Adopt nireports fully.

aslprep/cli/parser.py

@@ -544,6 +544,17 @@ def _bids_filter(value, parser):
     )
 
     g_other = parser.add_argument_group("Other options")
+    g_other.add_argument(
+        "--aggregate-session-reports",
+        dest="aggr_ses_reports",
+        action="store",
+        type=PositiveInt,
+        default=4,
+        help=(
+            "Maximum number of sessions aggregated in one subject's visual report. "
+            "If exceeded, visual reports are split by session."
+        ),
+    )
     g_other.add_argument("--version", action="version", version=verstr)
     g_other.add_argument(
         "-v",

aslprep/cli/run.py

@@ -174,27 +174,33 @@ def main():
             _copy_any(dseg_tsv, str(config.execution.aslprep_dir / "desc-aparcaseg_dseg.tsv"))
         errno = 0
     finally:
-        from fmriprep.reports.core import generate_reports
+        from aslprep.reports.core import generate_reports
 
-        from aslprep import data
+        # Generate reports phase
+        session_list = (
+            config.execution.get().get("bids_filters", {}).get("bold", {}).get("session")
+        )
 
         # Generate reports phase
         failed_reports = generate_reports(
             config.execution.participant_label,
             config.execution.aslprep_dir,
             config.execution.run_uuid,
-            config=data.load("reports-spec.yml"),
-            packagename="aslprep",
+            session_list=session_list,
         )
         write_derivative_description(config.execution.bids_dir, config.execution.aslprep_dir)
         write_bidsignore(config.execution.aslprep_dir)
 
-        if sentry_sdk is not None and failed_reports:
-            sentry_sdk.capture_message(
-                f"Report generation failed for {failed_reports} subjects",
-                level="error",
+        if failed_reports:
+            msg = (
+                "Report generation was not successful for the following participants "
+                f': {", ".join(failed_reports)}.'
             )
-        sys.exit(int((errno + failed_reports) > 0))
+            config.loggers.cli.error(msg)
+            if sentry_sdk is not None:
+                sentry_sdk.capture_message(msg, level="error")
+
+        sys.exit(int((errno + len(failed_reports)) > 0))
 
 
 if __name__ == "__main__":

aslprep/cli/workflow.py

@@ -12,12 +12,12 @@
 
 def build_workflow(config_file, retval):
     """Create the Nipype Workflow that supports the whole execution graph."""
-    from fmriprep.reports.core import generate_reports
     from fmriprep.utils.bids import check_pipeline_version
     from niworkflows.utils.bids import collect_participants
     from niworkflows.utils.misc import check_valid_fs_license
 
     from aslprep import config, data
+    from aslprep.reports.core import generate_reports
     from aslprep.utils.misc import check_deps
     from aslprep.workflows.base import init_aslprep_wf
 

aslprep/config.py

@@ -388,6 +388,8 @@ class execution(_Config):
     """Debug mode(s)."""
     aslprep_dir = None
     """Root of ASLPrep BIDS Derivatives dataset."""
+    aggr_ses_reports = None
+    """Maximum number of sessions aggregated in one subject's visual report."""
     fs_license_file = _fs_license
     """An existing file containing a FreeSurfer license."""
     fs_subjects_dir = None

aslprep/data/reports-spec-anat.yml

@@ -0,0 +1,47 @@
+package: aslprep
+sections:
+- name: Summary
+  reportlets:
+  - bids: {datatype: figures, desc: summary, suffix: T1w}
+- name: Anatomical
+  reportlets:
+  - bids:
+      datatype: figures
+      desc: conform
+      extension: [.html]
+      suffix: T1w
+  - bids: {datatype: figures, suffix: dseg}
+    caption: This panel shows the final, preprocessed T1-weighted image,
+      with contours delineating the detected brain mask and brain tissue segmentations.
+    subtitle: Brain mask and brain tissue segmentation of the T1w
+  - bids: {datatype: figures, space: .*, suffix: T1w, regex_search: True}
+    caption: Spatial normalization of the T1w image to the <code>{space}</code> template.
+    description: Results of nonlinear alignment of the T1w reference one or more template
+      space(s). Hover on the panels with the mouse pointer to transition between both
+      spaces.
+    static: false
+    subtitle: Spatial normalization of the anatomical T1w reference
+  - bids: {datatype: figures, desc: reconall, suffix: T1w}
+    caption: Surfaces (white and pial) reconstructed with FreeSurfer (<code>recon-all</code>)
+      overlaid on the participant's T1w template.
+    subtitle: Surface reconstruction
+- name: About
+  reportlets:
+  - bids: {datatype: figures, desc: about, suffix: T1w}
+  - custom: boilerplate
+    path: '{out_dir}/logs'
+    bibfile: ['aslprep', 'data/boilerplate.bib']
+    caption: |
+      <p>We kindly ask to report results preprocessed with this tool using the following boilerplate.</p>
+      <p class="alert alert-info" role="alert">
+      <strong>Copyright Waiver</strong>.
+      The boilerplate text was automatically generated by <em>NiReports</em> with the
+      express intention that users should copy and paste this text into their manuscripts <em>unchanged</em>.
+      It is released under the
+      <a href="https://creativecommons.org/publicdomain/zero/1.0/" target="_blank">CC0 license</a>.
+      </p>
+    title: Methods
+  - custom: errors
+    path: '{out_dir}/sub-{subject}/log/{run_uuid}'
+    captions: <em>NiReports</em> may have recorded failure conditions.
+    title: Errors

aslprep/data/reports-spec-perf.yml

@@ -0,0 +1,212 @@
+package: aslprep
+sections:
+- name: <em>B<sub>0</sub></em> field mapping
+  ordering: session,acquisition,run,fmapid
+  reportlets:
+  - bids: {datatype: figures, desc: mapped, suffix: fieldmap}
+    caption: Inhomogeneities of the <em>B<sub>0</sub></em> field introduce (oftentimes severe) spatial distortions
+      along the phase-encoding direction of the image. Some scanners produce a <em>B<sub>0</sub></em>
+      mapping of the field, using Spiral Echo Imaging (SEI) or postprocessing a "phase-difference"
+      acquisition. The plot below shows an anatomical "magnitude" reference and the corresponding
+      fieldmap.
+    description: Hover over the panels with the mouse pointer to also visualize the intensity of the
+      field inhomogeneity in Hertz.
+    static: false
+    subtitle: "Preprocessed <em>B<sub>0</sub></em> mapping acquisition"
+  - bids: {datatype: figures, desc: phasediff, suffix: fieldmap}
+    caption: Inhomogeneities of the <em>B<sub>0</sub></em> field introduce (oftentimes severe) spatial distortions
+      along the phase-encoding direction of the image. A Gradient-Recalled Echo (GRE) scheme was included for the
+      mapping of the <em>B<sub>0</sub></em> inhomogeneities by subtracting the phase maps obtained at
+      two subsequent echoes. The plot below shows an anatomical "magnitude" reference and the corresponding
+      fieldmap.
+    description: Hover over the panels with the mouse pointer to also visualize the intensity of the
+      field inhomogeneity in Hertz.
+    static: false
+    subtitle: "Preprocessed mapping of phase-difference acquisition"
+  - bids: {datatype: figures, desc: pepolar, suffix: fieldmap}
+    caption: Inhomogeneities of the <em>B<sub>0</sub></em> field introduce (oftentimes severe) spatial distortions
+      along the phase-encoding direction of the image. Utilizing two or more images with different
+      phase-encoding polarities (PEPolar) or directions, it is possible to estimate the inhomogeneity
+      of the field. The plot below shows a reference EPI (echo-planar imaging) volume generated
+      using two or more EPI images with varying phase-encoding blips.
+    description: Hover on the panels with the mouse pointer to also visualize the intensity of the
+      inhomogeneity of the field in Hertz.
+    static: false
+    subtitle: "Preprocessed estimation with varying Phase-Encoding (PE) blips"
+  - bids: {datatype: figures, desc: anat, suffix: fieldmap}
+    caption: Inhomogeneities of the <em>B<sub>0</sub></em> field introduce (oftentimes severe) spatial distortions
+      along the phase-encoding direction of the image. Utilizing an <em>anatomically-correct</em> acquisition
+      (for instance, T1w or T2w), it is possible to estimate the inhomogeneity of the field by means of nonlinear
+      registration. The plot below shows a reference EPI (echo-planar imaging) volume generated
+      using two or more EPI images with the same PE encoding, after alignment to the anatomical scan.
+    description: Hover on the panels with the mouse pointer to also visualize the intensity of the
+      inhomogeneity of the field in Hertz.
+    static: false
+    subtitle: "Preprocessed estimation by nonlinear registration to an anatomical scan (&ldquo;<em>fieldmap-less</em>&rdquo;)"
+
+- name: Arterial Spin Labeling
+  ordering: session,task,acquisition,ceagent,reconstruction,direction,run,echo
+  reportlets:
+  - bids: {datatype: figures, desc: summary, suffix: asl}
+  - bids: {datatype: figures, desc: validation, suffix: asl}
+  - bids: {datatype: figures, desc: fmapCoreg, suffix: asl}
+    caption: |
+      The estimated fieldmap was aligned to the corresponding EPI reference
+      with a rigid-registration process of the anatomical reference of the fieldmap,
+      using <code>antsRegistration</code>.
+      Overlaid on top of the co-registration results, the final BOLD mask is represented
+      with a red contour for reference.
+    static: false
+    subtitle: Alignment between the anatomical reference of the fieldmap and the target EPI (debug mode)
+  - bids: {datatype: figures, desc: fieldmap, suffix: asl}
+    caption: |
+      Estimated fieldmap, as reconstructed on the target BOLD run space to allow
+      the assessment of its alignment with the distorted data.
+      The anatomical reference is the fieldmap's reference moved into the target EPI's grid through
+      the estimated transformation.
+      In other words, this plot should be equivalent to that of the
+      <em>Preprocessed estimation with varying Phase-Encoding (PE) blips</em> shown above in the
+      fieldmap section.
+      Therefore, the fieldmap should be positioned relative to the anatomical reference exactly
+      as it is positioned in the reportlet above.
+    static: false
+    subtitle: "Reconstructed <em>B<sub>0</sub></em> map in the corresponding run's space (debug mode)"
+  - bids: {datatype: figures, desc: sdc, suffix: asl}
+    caption: |
+      Results of performing susceptibility distortion correction (SDC) on the EPI
+    static: false
+    subtitle: Susceptibility distortion correction
+  - bids: {datatype: figures, desc: forcedsyn, suffix: asl}
+    caption: |
+      The dataset contained some fieldmap information, but the argument <code>--force-syn</code>
+      was used. The higher-priority SDC method was used. Here, we show the results
+      of performing SyN-based SDC on the EPI for comparison.
+    static: false
+    subtitle: Experimental fieldmap-less susceptibility distortion correction
+  - bids: {datatype: figures, desc: flirtnobbr, suffix: asl}
+    caption: |
+      <code>mri_coreg</code> (FreeSurfer) was used to generate transformations
+      from EPI space to T1 Space - BBR refinement using FSL <code>flirt</code> rejected.
+      Note that Nearest Neighbor interpolation is used in the reportlets in order to
+      highlight potential spin-history and other artifacts, whereas final images are
+      resampled using Lanczos interpolation.
+    static: false
+    subtitle: Alignment of functional and anatomical MRI data (volume based)
+  - bids: {datatype: figures, desc: coreg, suffix: asl}
+    caption: |
+      <code>mri_coreg</code> (FreeSurfer) was used to generate transformations
+      from EPI space to T1 Space - <code>bbregister</code> refinement rejected. Note
+      that Nearest Neighbor interpolation is used in the reportlets in order to highlight
+      potential spin-history and other artifacts, whereas final images are resampled
+      using Lanczos interpolation.
+    static: false
+    subtitle: Alignment of functional and anatomical MRI data (volume based)
+  - bids: {datatype: figures, desc: flirtbbr, suffix: asl}
+    caption: |
+      FSL <code>flirt</code> was used to generate transformations from EPI-space
+      to T1w-space - The white matter mask calculated with FSL <code>fast</code> (brain
+      tissue segmentation) was used for BBR. Note that Nearest Neighbor interpolation
+      is used in the reportlets in order to highlight potential spin-history and other
+      artifacts, whereas final images are resampled using Lanczos interpolation.
+    static: false
+    subtitle: Alignment of functional and anatomical MRI data (surface driven)
+  - bids: {datatype: figures, desc: bbregister, suffix: asl}
+    caption: |
+      <code>bbregister</code> was used to generate transformations from EPI-space
+      to T1w-space. Note that Nearest Neighbor interpolation is used in the reportlets
+      in order to highlight potential spin-history and other artifacts, whereas final
+      images are resampled using Lanczos interpolation.
+    static: false
+    subtitle: Alignment of functional and anatomical MRI data (surface driven)
+  - bids: {datatype: figures, desc: rois, suffix: asl}
+    caption: |
+      Brain mask calculated on the BOLD signal (red contour), along with the
+      regions of interest (ROIs) used for the estimation of physiological and movement
+      confounding components that can be then used as nuisance regressors in analysis.<br />
+      The <em>anatomical CompCor</em> ROI (magenta contour) is a mask combining
+      CSF and WM (white-matter), where voxels containing a minimal partial volume
+      of GM have been removed.<br />
+      The <em>temporal CompCor</em> ROI (blue contour) contains the top 2% most
+      variable voxels within the brain mask.<br />
+      The <em>brain edge</em> (or <em>crown</em>) ROI (green contour) picks signals
+      outside but close to the brain, which are decomposed into 24 principal components.
+    subtitle: Brain mask and (anatomical/temporal) CompCor ROIs
+  - bids:
+      datatype: figures
+      desc: '[at]compcor'
+      extension: [.html]
+      suffix: asl
+  - bids: {datatype: figures, desc: carpetplot, suffix: asl}
+    caption: |
+      Summary statistics are plotted, which may reveal trends or artifacts in the ASL data.
+      DVARS and FD show the standardized DVARS and framewise-displacement measures for each time point.
+      A carpet plot shows the time series for all voxels within the brain mask.
+      Voxels are grouped into cortical (blue), and subcortical (orange) gray matter, cerebellum (green)
+      and white matter and CSF (red), indicated by the color map on the left-hand side.
+    subtitle: ASL Summary
+  - bids: {datatype: figures, desc: carpetplot, suffix: cbf}
+    caption: |
+      This carpet plot shows the time series for all voxels within the brain mask for CBF.
+      Voxels are grouped into cortical (blue), and subcortical (orange) gray matter,
+      cerebellum (green), white matter and CSF (red), indicated by the color map on the left-hand side.
+      The SCORE index with values greater than zero indicates which volume(s) are removed by SCORE.
+    subtitle: CBF Summary
+  - bids: {datatype: figures, desc: cbf, suffix: cbf}
+    caption: |
+      The maps plot cerebral blood flow (CBF) for basic CBF.
+      The unit is mL/100 g/min.
+    subtitle: CBF
+  - bids: {datatype: figures, desc: cbfByTissueType, suffix: cbf}
+    caption: |
+      The maps plot the distribution of cerebral blood flow (CBF) values for the basic output,
+      separated by tissue type.
+      The unit is mL/100 g/min.
+    subtitle: Mean CBF by Tissue Type
+  - bids: {datatype: figures, desc: score, suffix: cbf}
+    caption: |
+      The maps plot cerebral blood flow (CBF) for SCORE-corrected CBF.
+      The unit is mL/100 g/min.
+    subtitle: SCORE CBF
+  - bids: {datatype: figures, desc: scoreByTissueType, suffix: cbf}
+    caption: |
+      The maps plot the distribution of cerebral blood flow (CBF) values for the SCORE output,
+      separated by tissue type.
+      The unit is mL/100 g/min.
+    subtitle: SCORE CBF by Tissue Type
+  - bids: {datatype: figures, desc: scrub, suffix: cbf}
+    caption: |
+      The maps plot cerebral blood flow (CBF) for SCRUB-corrected CBF.
+      The unit is mL/100 g/min.
+    subtitle: SCRUB CBF
+  - bids: {datatype: figures, desc: scrubByTissueType, suffix: cbf}
+    caption: |
+      The maps plot the distribution of cerebral blood flow (CBF) values for the SCRUB output,
+      separated by tissue type.
+      The unit is mL/100 g/min.
+    subtitle: SCRUB CBF by Tissue Type
+  - bids: {datatype: figures, desc: basil, suffix: cbf}
+    caption: |
+      The maps plot cerebral blood flow (CBF) for BASIL-estimated CBF.
+      The unit is mL/100 g/min.
+    subtitle: BASIL CBF
+  - bids: {datatype: figures, desc: basilByTissueType, suffix: cbf}
+    caption: |
+      The maps plot the distribution of cerebral blood flow (CBF) values for the BASIL output,
+      separated by tissue type.
+      The unit is mL/100 g/min.
+    subtitle: BASIL CBF by Tissue Type
+  - bids: {datatype: figures, desc: basilGM, suffix: cbf}
+    caption: |
+      The maps plot cerebral blood flow (CBF) for gray matter partial volume-corrected CBF.
+      The unit is mL/100 g/min.
+    subtitle: BASIL GM-PVC CBF
+  - bids: {datatype: figures, desc: basilGMByTissueType, suffix: cbf}
+    caption: |
+      The maps plot the distribution of cerebral blood flow (CBF) values for the
+      BASIL gray matter partial volume-corrected output, separated by tissue type.
+      The unit is mL/100 g/min.
+    subtitle: BASIL GM-PVC CBF by Tissue Type
+
+- name: About
+  reportlets:
+  - bids: {datatype: figures, desc: about, suffix: T1w}