fmriprep.qmd

# fMRIPrep {#sec-fmriprep}

Before being analyzed, raw structural and functional neuroimaging data must undergo a core set of preprocessing steps. Without these steps, the raw MR signals are dominated by noise sources (e.g., participant head motion, scanner drift, magnetic field inhomogeneities) rather than the underlying neural activity. 

Preprocessing mitigates these artifacts. The need for these preprocessing steps is relatively uncontroversial across the field, and they include intensity non-uniformity correction (for structural scans), correction for motion across volumes (functional scans), and coregistration (aligning structural and functional images into the same physical space), among others.

These outputs are the result of a minimal preprocessing stream using [fMRIPrep](https://fmriprep.org/en/stable/).[^qsi] That is, these derivatives have not undergone many advanced cleaning steps that are common in downstream pipelines, such as denoising, nuisance regression, or scrubbing. If you need data that have already gone through advanced data cleaning, please see either @sec-functional-connectivity or @sec-neural-pain-signatures. The fMRIPrep derivatives are most useful for tasks like reviewing the quality of preprocessing, implementing your own custom cleaning pipeline, or working from HCP-style [CIFTI data](https://www.nitrc.org/projects/cifti/).

[^qsi]: For the equivalent minimal preprocessing pipeline for diffusion MRI, please see @sec-qsiprep.

## Starting Project

### Locate Data

{{< include _snippets/mri-location.qmd >}}

The fMRIPrep derivatives are underneath `derivatives/fmriprep`. Let's take a look.

```bash
$ ls mris/derivatives/fmriprep/ | head
dataset_description.json
desc-aparcaseg_dseg.tsv
desc-aseg_dseg.tsv
README
sub-10003
sub-10003_ses-V1.html
sub-10005
sub-10005_ses-V1.html
sub-10008
sub-10008_ses-V1.html
```

### Extract Data

Because fMRIPrep produces a large and complex directory structure containing many different types of preprocessed files (e.g., brain masks, normalized anatomical images, confound regressors, and surface data), users typically extract only what they need for their specific downstream analysis tools (such as AFNI, FSL, or SPM). 

For a detailed description of every file produced by fMRIPrep, please review [their official outputs documentation](https://fmriprep.org/en/stable/outputs.html).

## Considerations While Working on the Project

### Brain Masking {#sec-synthstrip}

As a part of release 2.x, a custom brain mask was on the raw structural scan with [SynthStrip](https://surfer.nmr.mgh.harvard.edu/docs/synthstrip/)\ [@hoopes_synthstrip_2022]. SynthStrip is a cutting edge tool that can efficiently and accurately extract brains in a wide variety of challenging situations. Our use of SynthStrip was inspired by [QSIprep](https://qsiprep.readthedocs.io/en/latest/). However, while conducting quality control on the spatial normalization templates, we discovered that SynthStrip interacts poorly with the normalization tool used by fMRIPrep (and QSIPrep). For details of the issue, see: https://github.com/PennLINC/qsiprep/issues/954. The basic issue is that, while SynthStrip is effective at stripping the skull from an image, its default configuration leaves CSF and dura intact, which interferes with normalization to a template that does not include those materials (that is, a template that is only a brain). While we expect that the issue is relatively minor and have not observed obvious issues in the downstream products, this will be addressed in a future release (expected: 3.0). If you would like to evaluate the masks produced by SynthStrip, they are in `mris/derivatives/synthstrip`.

### Variability Across Scanners

{{< include _snippets/mri-scanner-variability.qmd >}}

### Data Quality

{{< include _snippets/mri-qc.qmd >}}

### Data Generation (Methods)

These outputs were generated by the [fmriprep_app](https://github.com/a2cps/mri_imaging_pipeline/tree/master/fmriprep_app). 

*(Note: The following text is boilerplate provided by fMRIPrep and should be included verbatim in any publications using these derivatives.)*

Results included in this manuscript come from preprocessing performed using *fMRIPrep* 24.1.1 (@fmriprep1; @fmriprep2; RRID:SCR_016216), which is based on *Nipype* 1.8.6 (@nipype1; @nipype2; RRID:SCR_002502).

#### Preprocessing of B<sub>0</sub> inhomogeneity mappings

A *B<sub>0</sub>*-nonuniformity map (or *fieldmap*) was estimated based on two (or more) echo-planar imaging (EPI) references  with `topup` (@topup; FSL None).

#### Anatomical data preprocessing

The T1w image was corrected for intensity non-uniformity (INU) with `N4BiasFieldCorrection`\ [@n4], distributed with ANTs 2.5.3\ [@ants, RRID:SCR_004757], and used as T1w-reference throughout the workflow. A pre-computed brain mask was provided as input and used throughout the workflow\ [@sec-synthstrip]. Brain tissue segmentation of cerebrospinal fluid (CSF), white-matter (WM) and gray-matter (GM) was performed on the brain-extracted T1w using `fast`\ [FSL, RRID:SCR_002823, @fsl_fast]. Brain surfaces were reconstructed using `recon-all`\ [FreeSurfer 7.3.2, RRID:SCR_001847, @fs_reconall], and the brain mask estimated previously was refined with a custom variation of the method to reconcile ANTs-derived and FreeSurfer-derived segmentations of the cortical gray-matter of Mindboggle\ [RRID:SCR_002438, @mindboggle]. Volume-based spatial normalization to two standard spaces (MNI152NLin2009cAsym, MNI152NLin6Asym) was performed through nonlinear registration with `antsRegistration` (ANTs 2.5.3), using brain-extracted versions of both T1w reference and the T1w template. The following templates were were selected for spatial normalization and accessed with *TemplateFlow*\ [24.2.0, @templateflow]: *ICBM 152 Nonlinear Asymmetrical template version 2009c*\ [@mni152nlin2009casym, RRID:SCR_008796; TemplateFlow ID: MNI152NLin2009cAsym], *FSL's MNI ICBM 152 non-linear 6th Generation Asymmetric Average Brain Stereotaxic Registration Model*\ [@mni152nlin6asym, RRID:SCR_002823; TemplateFlow ID: MNI152NLin6Asym]. *Grayordinate* "dscalar" files containing 91k samples were resampled onto fsLR using the Connectome Workbench\ [@hcppipelines].

#### Functional data preprocessing

For each of the 4 BOLD runs found per subject (across all tasks and sessions), the following preprocessing was performed. First, a reference volume was generated, using a custom methodology of *fMRIPrep*, for use in head motion correction. Head-motion parameters with respect to the BOLD reference (transformation matrices, and six corresponding rotation and translation parameters) are estimated before any spatiotemporal filtering using `mcflirt`\ [FSL, @mcflirt]. The estimated *fieldmap* was then aligned with rigid-registration to the target EPI (echo-planar imaging) reference run. The field coefficients were mapped on to the reference EPI using the transform. The BOLD reference was then co-registered to the T1w reference using `bbregister` (FreeSurfer) which implements boundary-based registration\ [@bbr]. Co-registration was configured with six degrees of freedom. Several confounding time-series were calculated based on the *preprocessed BOLD*: framewise displacement (FD), DVARS and three region-wise global signals. FD was computed using two formulations following Power (absolute sum of relative motions, @power_fd_dvars) and Jenkinson (relative root mean square displacement between affines, @mcflirt). FD and DVARS are calculated for each functional run, both using their implementations in *Nipype*\ [following the definitions by @power_fd_dvars]. The three global signals are extracted within the CSF, the WM, and the whole-brain masks. Additionally, a set of physiological regressors were extracted to allow for component-based noise correction\ [*CompCor*, @compcor]. Principal components are estimated after high-pass filtering the *preprocessed BOLD* time-series (using a discrete cosine filter with 128s cut-off) for the two *CompCor* variants: temporal (tCompCor) and anatomical (aCompCor). tCompCor components are then calculated from the top 2 percent variable voxels within the brain mask. For aCompCor, three probabilistic masks (CSF, WM and combined CSF+WM) are generated in anatomical space. The implementation differs from that of Behzadi et al. in that instead of eroding the masks by 2 pixels on BOLD space, a mask of pixels that likely contain a volume fraction of GM is subtracted from the aCompCor masks. This mask is obtained by dilating a GM mask extracted from the FreeSurfer's *aseg* segmentation, and it ensures components are not extracted from voxels containing a minimal fraction of GM. Finally, these masks are resampled into BOLD space and binarized by thresholding at 0.99 (as in the original implementation). Components are also calculated separately within the WM and CSF masks. For each CompCor decomposition, the *k* components with the largest singular values are retained, such that the retained components' time series are sufficient to explain 50 percent of variance across the nuisance mask (CSF, WM, combined, or temporal). The remaining components are dropped from consideration.

The head-motion estimates calculated in the correction step were also placed within the corresponding confounds file. The confound time series derived from head motion estimates and global signals were expanded with the inclusion of temporal derivatives and quadratic terms for each\ [@confounds_satterthwaite_2013]. Frames that exceeded a threshold of 0.5 mm FD or 1.5 standardized DVARS were annotated as motion outliers. Additional nuisance timeseries are calculated by means of principal components analysis of the signal found within a thin band (*crown*) of voxels around the edge of the brain, as proposed by\ [@patriat_improved_2017]. The BOLD time-series were resampled onto the left/right-symmetric template "fsLR" using the Connectome Workbench\ [@hcppipelines]. *Grayordinates* files\ [@hcppipelines] containing 91k samples were also generated with surface data transformed directly to fsLR space and subcortical data transformed to 2 mm resolution MNI152NLin6Asym space. All resamplings can be performed with *a single interpolation step* by composing all the pertinent transformations (i.e. head-motion transform matrices, susceptibility distortion correction when available, and co-registrations to anatomical and output spaces). Gridded (volumetric) resamplings were performed using `nitransforms`, configured with cubic B-spline interpolation.

Many internal operations of *fMRIPrep* use *Nilearn* 0.10.4\ [@nilearn, RRID:SCR_001362], mostly within the functional processing workflow. For more details of the pipeline, see [the section corresponding to workflows in *fMRIPrep*'s documentation](https://fmriprep.readthedocs.io/en/latest/workflows.html "FMRIPrep's documentation").

### Citations

If you use these products in your analyses, please cite the relevant papers written by members [TReNDS](https://trendscenter.org/data/).

{{< include _snippets/a2cps_citations.qmd >}}

When using neuroimaging derivatives, please also cite @sadil_acute_2024.