Note

This page is a reference documentation. It only explains the function signature, and not how to use it. Please refer to the user guide for the big picture.

brainprep.workflow.brainprep_fmriprep

brainprep.workflow.brainprep_fmriprep(t1_file, func_files, freesurfer_dir, output_dir, keep_intermediate=False, **kwargs)

Subject level functional MRI pre-processing.

Applies fmriprep tool [1] with the following setting:

1. T1-weighted volume was corrected for INU (intensity non-uniformity) using N4BiasFieldCorrection and skull-stripped using antsBrainExtraction.sh (using the OASIS template).

2. 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.

3. Spatial normalization to the ICBM 152 Nonlinear Asymmetrical template version 2009c was performed through nonlinear registration with the antsRegistration tool of ANTs, using brain-extracted versions of both T1w volume and template.

4. Brain tissue segmentation of cerebrospinal fluid (CSF), white-matter (WM) and gray-matter (GM) was performed on the brain-extracted T1w using FSL fast.

5. Functional data was motion corrected using FSL mcflirt.

6. This was followed by co-registration to the corresponding T1w using boundary-based registration with six degrees of freedom, using FreeSurfer bbregister.

7. Motion correcting transformations, BOLD-to-T1w transformation and T1w-to-template (MNI) warp were concatenated and applied in a single step using ANTs antsApplyTransforms using Lanczos interpolation.

8. Physiological noise regressors were extracted applying CompCor. Principal components were estimated for the two CompCor variants: temporal (tCompCor) and anatomical (aCompCor).A mask to exclude signal with cortical origin was obtained by eroding the brain mask, ensuring it only contained subcortical structures. Six tCompCor components were then calculated including only the top 5% variable voxels within that subcortical mask. For aCompCor, six components were calculated within the intersection of the subcortical mask and the union of CSF and WM masks calculated in T1w space, after their projection to the native space of each functional run.

9. Frame-wise displacement was calculated for each functional run using Nipype.

Then, compute functional ROI-based functional connectivity from pre-processed volumetric fMRI data based on the Schaefer 200 ROI atlas. Connectivity is computed using Pearson correlation.

Parameters:

t1_fileFile

Path to the input T1w image file.

func_fileslist[File]

Path to the input functional image files of one subject.

freesurfer_dirDirectory

Path to an existing FreeSurfer subjects directory in which the recon-all commands have already been executed.

output_dirDirectory

Directory where the prep-processing related outputs will be saved (i.e., the root of your dataset).

keep_intermediatebool

If True, retains intermediate results (i.e., the workspace); useful for debugging. Default False.

**kwargsdict

entities: dict

Dictionary of parsed BIDS entities.

Returns:

Bunch

A dictionary-like object containing:

• fmri_rest_image_files: list[File] - pre-processed rfMRI NIFTI volumes: 2mm MNI152NLin6Asym and MNI152NLin2009cAsym.

• fmri_rest_surf_files: File - pre-processed rfMRI CIFTI surfaces: fsLR23k.

• qc_file: File - the HTML visual report for the subject’s data.

• connectivity_files: list[File] - TSV files containing the ROI-to-ROI connectivity matrix for each resting-state fMRI pre-processed image.

Raises:

ValueError

If the input T1w file is not BIDS-compliant.

Notes

This workflow assumes the T1w image is organized in BIDS.

References

[1]

Oscar Esteban, Christopher J Markiewicz, Ross W Blair, Craig A Moodie, A Ilkay Isik, Asier Erramuzpe, James D Kent, Mathias Goncalves, Elizabeth DuPre, Madeleine Snyder, Hiroyuki Oya, Satrajit S Ghosh, Jessey Wright, Joke Durnez, Russell A Poldrack, and Krzysztof J Gorgolewski. fMRIPrep: a robust preprocessing pipeline for functional MRI. Nat. Methods, 16(1):111–116, January 2019.

Examples

>>> from brainprep.config import Config
>>> from brainprep.reporting import RSTReport
>>> from brainprep.workflow import brainprep_fmriprep
>>>
>>> with Config(dryrun=True, verbose=False):
...     report = RSTReport()
...     outputs = brainprep_fmriprep(
...         t1_file=(
...             "/tmp/dataset/rawdata/sub-01/ses-01/anat/"
...             "sub-01_ses-01_run-01_T1w.nii.gz"
...         ),
...         func_files=[
...             "/tmp/dataset/rawdata/sub-01/ses-01/func/"
...             "sub-01_ses-01_task-rest_run-01_bold.nii.gz",
...         ],
...         freesurfer_dir=(
...             "/tmp/dataset/derivatives/brain_parcellation/subjects"
...         ),
...         output_dir="/tmp/dataset/derivatives",
...     ) 
>>> outputs 
Bunch(
    fmri_rest_image_files=[PosixPath('...')],
    fmri_rest_surf_files=[PosixPath('...')],
    qc_file=PosixPath('...'),
    connectivity_files=[PosixPath('...')],
)

Examples using brainprep.workflow.brainprep_fmriprep

fMRI

fMRI