ENH: separate anatomical and functional reports per session for dense…

…ly sampled dataset (#3191)

enh: beyond a certain number of session for a single subject (4), we
separate the anatomical report from the functional and we separate the
functional reports per session. For fewer sessions than 4, we keep the
original behavior of aggregating all sessions and the anatomical in one
report.

enh: find the suitable bootstrapfile within generate_reports rather than
before

enh: add session_list argument to generate_reports

Builds on top of #3177

Closes #3080

---------

Co-authored-by: Oscar Esteban <code@oscaresteban.es>
Co-authored-by: Chris Markiewicz <markiewicz@stanford.edu>

fmriprep/cli/parser.py

@@ -446,6 +446,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 @@ def main():
             _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,15 @@ def main():
         from fmriprep.reports.core import generate_reports
 
         # Generate reports phase
+        session_list = (
+            config.execution.get().get('bids_filters', {}).get("bold", {}).get("session")
+        )
+
         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 @@ def build_workflow(config_file, retval):
     # 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.get("bold", {}).get("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/__init__.py

@@ -10,6 +10,7 @@
 
 .. autoclass:: Loader
 """
+
 from __future__ import annotations
 
 import atexit

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