package: fmriprep
title: Visual report for participant '{subject}' - 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: <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-sdc</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
  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
