Reports

How do reports work?

The reports mechanism can be tricky. Here is an outline of how it works.

Generating reports

The commandline entrypoint in qsiprep.cli.run runs the entire preprocessing workflow and then calls qsiprep.viz.reports.generate_reports(subject_list, output_dir, work_dir, run_uuid). This function takes care of generating a report for each subject that went through the pipeline.

Where do reports come from?

During the execution of the pipeline, the settings and outputs of some stages are connected to nodes containing qsiprep.interfaces.reports.SummaryInterface objects. Setting the "out_report" output of these objects is required. Sometimes the _generate_segment() has to be overridden to produce text in the html file.

These SummaryInterface nodes have to be connected to a DerivativesDataSink node. Whatever is written out by the report, be it an html or svg or gif, needs to be connected to the in_file input to the DerivativesDataSink. The node must have a name that matches "ds_report*" - this ensures that the correct attributes are set on each data sink (relevant section from qsiprep.workflows.dwi.base.init_qsiprep_dwi_preproc_wf):

    # Fill-in datasinks of reportlets seen so far
    for node in workflow.list_node_names():
        if node.split('.')[-1].startswith('ds_report'):
            workflow.get_node(node).inputs.base_directory = reportlets_dir
            workflow.get_node(node).inputs.source_file = source_file

Setting the base_directory attribute to reportlets_dir is required because the final report is created by looking through the reportlets_dir for things that can be added to the final html file.

Finally, the qsiprep.viz.reports.generate_reports function runs with a subject list and generates a report for each subject and counts the number of errors. The function that actually creates the html files.

Report contents

The contents of an html report are determined by

1. The files available in the reportlets directory (which arrive there because they're named 'ds_report*')
2. The contents of qsiprep/viz/config.json

The config.json file lists the sections of the final report along with their titles, text and the kind of image to expect. Here is part of that file:

    {
        "name": "Diffusion",
        "reportlets":
        [
            {
                "name": "epi/summary",
                "file_pattern": "dwi/.*_summary",
                "raw": true
            },
            {
                "name": "epi/validation",
                "file_pattern": "dwi/.*_validation\\.",
                "raw": true
            },
            {
                "name": "epi/sampling_scheme",
                "file_pattern": "dwi/.*sampling_scheme",
                "title": "DWI Sampling Scheme",
                "description": "Animation of the DWI sampling scheme. Each separate scan is its own color.",
                "imgtype": "gif"
            },