ENH: separate anatomical and functional reports per session for densely sampled dataset

fmriprep/cli/parser.py

@@ -401,6 +401,15 @@ def _slice_time_ref(value, parser):
         help="Output individual echo time series with slice, motion and susceptibility "
         "correction. Useful for further Tedana processing post-fMRIPrep.",
     )
+    g_outputs.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_outputs.add_argument(
         "--medial-surface-nan",
         required=False,

fmriprep/cli/run.py

@@ -202,8 +202,6 @@
             _copy_any(dseg_tsv, str(config.execution.fmriprep_dir / "desc-aparcaseg_dseg.tsv"))
         errno = 0
     finally:
-        from .. import data
-
         # Code Carbon
         if config.execution.track_carbon:
             emissions: float = tracker.stop()
@@ -214,11 +212,13 @@
         from fmriprep.reports.core import generate_reports
 
         # Generate reports phase
+        session_list = config.execution.bids_filters.get("bold", {}).get("session", None)
+
         failed_reports = generate_reports(
             config.execution.participant_label,
             config.execution.fmriprep_dir,
             config.execution.run_uuid,
-            config=data.load("reports-spec.yml"),
+            session_list=session_list,
         )
         write_derivative_description(config.execution.bids_dir, config.execution.fmriprep_dir)
         write_bidsignore(config.execution.fmriprep_dir)

fmriprep/cli/workflow.py

@@ -86,11 +86,17 @@
     # Called with reports only
     if config.execution.reports_only:
         build_log.log(25, "Running --reports-only on participants %s", ", ".join(subject_list))
+        session_list = (
+            config.execution.bids_filters["bold"]["session"]
+            if config.execution.bids_filters
+            else None
+        )
+
         failed_reports = generate_reports(
             config.execution.participant_label,
             config.execution.fmriprep_dir,
             config.execution.run_uuid,
-            config=data.load("reports-spec.yml"),
+            session_list=session_list,
         )
         if failed_reports:
             config.loggers.cli.error(

fmriprep/config.py

@@ -417,6 +417,8 @@ class execution(_Config):
     """Folder where derivatives will be stored."""
     me_output_echos = False
     """Output individual echo time series with slice, motion and susceptibility correction"""
+    aggr_ses_reports = None
+    """Maximum number of sessions aggregated in one subject's visual report."""
     output_layout = None
     """Layout of derivatives within output_dir."""
     output_spaces = None

fmriprep/data/reports-spec-anat.yml

@@ -0,0 +1,47 @@
+package: fmriprep
+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: ['fmriprep', '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

fmriprep/data/reports-spec-func.yml

@@ -0,0 +1,157 @@
+package: fmriprep
+sections:
+- name: Summary
+  reportlets:
+  - bids: {datatype: figures, desc: summary, suffix: T1w}
+- 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: Functional
+  ordering: session,task,acquisition,ceagent,reconstruction,direction,run,echo
+  reportlets:
+  - bids: {datatype: figures, desc: summary, suffix: bold}
+  - bids: {datatype: figures, desc: validation, suffix: bold}
+  - bids: {datatype: figures, desc: fmapCoreg, suffix: bold}
+    caption: The estimated fieldmap was aligned to the corresponding EPI reference
+      with a rigid-registration process of the fieldmap reference image,
+      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
+  - bids: {datatype: figures, desc: fieldmap, suffix: bold}
+    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: bold}
+    caption: Results of performing susceptibility distortion correction (SDC) on the
+      BOLD reference image. The "distorted" image is the image that would be used to
+      align to the anatomical reference if SDC were not applied. The "corrected"
+      image is the image that was used.
+    static: false
+    subtitle: Susceptibility distortion correction
+  - bids: {datatype: figures, desc: forcedsyn, suffix: bold}
+    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: t2scomp, suffix: bold}
+    caption: A T2* map was calculated from the echos. Here, we show the comparison
+      of the T2* map and the BOLD reference map used for BOLD-T1w coregistration.
+      The red contour shows the anatomical gray-matter mask resampled into BOLD space.
+    static: false
+    subtitle: T2* map
+  - bids: {datatype: figures, desc: t2starhist, suffix: bold}
+    caption: A histogram of estimated T2* values within the anatomically-derived gray-matter mask
+      shown in the previous plot. Note that values are clipped at 100ms, so any extreme outliers will
+      appear in the 100ms bin.
+    static: false
+    subtitle: T2* gray-matter values
+  - bids: {datatype: figures, desc: coreg, suffix: bold}
+    caption: This panel shows the alignment of the reference EPI (BOLD) image to the
+      anatomical (T1-weighted) image.
+      The reference EPI has been contrast enhanced and susceptibility-distortion
+      corrected (if applicable) for improved anatomical fidelity.
+      The anatomical image has been resampled into EPI space, as well as the
+      anatomical white matter mask, which appears as a red contour.
+    static: false
+    subtitle: Alignment of functional and anatomical MRI data (coregistration)
+  - bids: {datatype: figures, desc: rois, suffix: bold}
+    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: bold
+  - bids: {datatype: figures, desc: 'compcorvar', suffix: bold}
+    caption: The cumulative variance explained by the first k components of the
+      <em>t/aCompCor</em> decomposition, plotted for all values of <em>k</em>.
+      The number of components that must be included in the model in order to
+      explain some fraction of variance in the decomposition mask can be used
+      as a feature selection criterion for confound regression.
+    subtitle: Variance explained by t/aCompCor components
+  - bids: {datatype: figures, desc: carpetplot, suffix: bold}
+    caption: Summary statistics are plotted, which may reveal trends or artifacts
+      in the BOLD data. Global signals calculated within the whole-brain (GS), within
+      the white-matter (WM) and within cerebro-spinal fluid (CSF) show the mean BOLD
+      signal in their corresponding masks. DVARS and FD show the standardized DVARS
+      and framewise-displacement measures for each time point.<br />
+      A carpet plot shows the time series for all voxels within the brain mask,
+      or if <code>--cifti-output</code> was enabled, all grayordinates.
+      See the figure legend for specific color mappings.
+      "Ctx" = cortex, "Cb" = cerebellum, "WM" = white matter, "CSF" = cerebrospinal fluid.
+      "d" and "s" prefixes indicate "deep" and "shallow" relative to the cortex.
+      "Edge" indicates regions just outside the brain.
+    subtitle: BOLD Summary
+  - bids: {datatype: figures, desc: 'confoundcorr', suffix: bold}
+    caption: |
+      Left: Heatmap summarizing the correlation structure among confound variables.
+      (Cosine bases and PCA-derived CompCor components are inherently orthogonal.)
+      Right: magnitude of the correlation between each confound time series and the
+      mean global signal. Strong correlations might be indicative of partial volume
+      effects and can inform decisions about feature orthogonalization prior to
+      confound regression.
+    subtitle: Correlations among nuisance regressors
+- name: About
+  reportlets:
+  - bids: {datatype: figures, desc: about, suffix: T1w}

fmriprep/data/reports-spec.yml

@@ -176,5 +176,23 @@ sections:
       confound regression.
     subtitle: Correlations among nuisance regressors
 - name: About
+  nested: true
   reportlets:
   - bids: {datatype: figures, desc: about, suffix: T1w}
+  - custom: boilerplate
+    path: '{out_dir}/logs'
+    bibfile: ['fmriprep', '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