nireports.assembler.report module

Core objects representing reports.

class nireports.assembler.report.Report(out_dir, run_uuid, bootstrap_file=None, out_filename='report.html', reportlets_dir=None, plugins=None, plugin_meta=None, metadata=None, **bids_filters)

Bases: object

The full report object. This object maintains a BIDSLayout to index all reportlets.

Examples

Output naming can be automated or customized:

>>> summary_meta = {
...     "Summary": {
...         "Structural images": 1,
...         "FreeSurfer reconstruction": "Pre-existing directory",
...         "Output spaces":
...             "<code>MNI152NLin2009cAsym</code>, <code>fsaverage5</code>",
...     }
... }
>>> robj = Report(
...     output_dir,
...     'madeoutuuid',
...     bootstrap_file=test_data_path / "tests" / "minimal.yml"
... )
>>> str(robj.out_filename)  
'.../report.html'

>>> robj = Report(
...     output_dir,
...     'madeoutuuid',
...     bootstrap_file=test_data_path / "tests" / "minimal.yml",
...     out_filename="override.html"
... )
>>> str(robj.out_filename) == str(output_dir / "override.html")
True

When bids_filters are available, the report will take up all the entities for naming. Therefore, the user must be careful to only include the necessary entities:

>>> robj = Report(
...     output_dir,
...     'madeoutuuid',
...     bootstrap_file=test_data_path / "tests" / "minimal.yml",
...     metadata={"summary-meta": summary_meta},
...     subject="17",
...     acquisition="mprage",
...     suffix="T1w",
... )
>>> str(robj.out_filename)
'.../sub-17_acq-mprage_T1w.html'

Report generation, first with a bootstrap file that contains special reportlets (namely, “errors” and “boilerplate”). The first generated test does not have errors, and the CITATION files are missing (failing the boilerplate generation):

>>> robj = Report(
...     output_dir / 'nireports',
...     'madeoutuuid',
...     reportlets_dir=testdir / 'work' / 'reportlets' / 'nireports',
...     plugins=[],
...     metadata={"summary-meta": summary_meta},
...     subject='01',
... )
>>> robj.generate_report()
0

Test including a crashfile, but no CITATION files (therefore, failing boilerplate generation):

>>> robj = Report(
...     output_dir / 'nireports',
...     'madeoutuuid02',
...     reportlets_dir=testdir / 'work' / 'reportlets' / 'nireports',
...     plugins=[],
...     metadata={"summary-meta": summary_meta},
...     subject='02',
... )
>>> robj.generate_report()
0

Test including CITATION files (i.e., boilerplate generation is successful) and no crashfiles (no errors reported):

>>> robj = Report(
...     output_dir / 'nireports',
...     'madeoutuuid03',
...     reportlets_dir=testdir / 'work' / 'reportlets' / 'nireports',
...     plugins=[],
...     metadata={"summary-meta": summary_meta},
...     subject='03',
... )
>>> robj.generate_report()
0

>>> robj = Report(
...     output_dir / 'nireports',
...     'madeoutuuid03',
...     reportlets_dir=testdir / 'work' / 'reportlets' / 'nireports',
...     plugins=[{
...         "module": "nireports.assembler",
...         "path": "data/rating-widget/bootstrap.yml",
...     }],
...     metadata={"summary-meta": summary_meta},
...     subject='03',
...     task="faketaskwithruns",
...     suffix="bold",
... )
>>> robj.generate_report()
0

Check contents (roughly, by length of the generated HTML file):

>>> len((
...     output_dir / 'nireports' / 'sub-01.html'
... ).read_text()) - REPORT_BASELINE_LENGTH
0
>>> len((
...     output_dir / 'nireports' / 'sub-02.html'
... ).read_text()) - (REPORT_BASELINE_LENGTH + 3254)
0
>>> len((
...     output_dir / 'nireports' / 'sub-03.html'
... ).read_text()) - (REPORT_BASELINE_LENGTH + 51892)
0

>>> len((
...     output_dir / 'nireports' / 'sub-03_task-faketaskwithruns_bold.html'
... ).read_text()) - RATING_WIDGET_LENGTH
0

footer

plugins can modify the default HTML elements of the report

generate_report()

Once the Report has been indexed, the final HTML can be generated

header

plugins can modify the default HTML elements of the report

index(config)

Traverse the reports config definition and instantiate reportlets.

This method also places figures in their final location.

navbar

plugins can modify the default HTML elements of the report

out_filename

output path where report will be stored

process_plugins(config, metadata=None)

Add components to header/navbar/footer to extend the default report.

sections

a header for the content included in the subreport

template_path

location of a JINJA2 template for the output HTML

title

the title that will be shown in the browser

class nireports.assembler.report.SubReport(name, isnested=False, reportlets=None, title='')

Bases: object

SubReports are sections within a Report.

isnested

True if this subreport is a reportlet to another subreport

name

a unique subreport name

reportlets

the collection of reportlets in this subreport

title

a header for the content included in the subreport