API¶
Workflows¶
fMRIprep base processing workflows¶
-
fmriprep.workflows.base.
init_fmriprep_wf
(subject_list, task_id, run_uuid, ignore, debug, low_mem, anat_only, longitudinal, t2s_coreg, omp_nthreads, skull_strip_template, work_dir, output_dir, bids_dir, freesurfer, output_spaces, template, medial_surface_nan, hires, use_bbr, bold2t1w_dof, fmap_bspline, fmap_demean, use_syn, force_syn, use_aroma, ignore_aroma_err, output_grid_ref)[source]¶ This workflow organizes the execution of FMRIPREP, with a sub-workflow for each subject.
If FreeSurfer’s recon-all is to be run, a FreeSurfer derivatives folder is created and populated with any needed template subjects.
Parameters
- subject_list : list
- List of subject labels
- task_id : str or None
- Task ID of BOLD series to preprocess, or
None
to preprocess all - run_uuid : str
- Unique identifier for execution instance
- ignore : list
- Preprocessing steps to skip (may include “slicetiming”, “fieldmaps”)
- debug : bool
- Enable debugging outputs
- low_mem : bool
- Write uncompressed .nii files in some cases to reduce memory usage
- anat_only : bool
- Disable functional workflows
- longitudinal : bool
- Treat multiple sessions as longitudinal (may increase runtime) See sub-workflows for specific differences
- t2s_coreg : bool
- Use multiple BOLD echos to create T2*-map for T2*-driven coregistration
- omp_nthreads : int
- Maximum number of threads an individual process may use
- skull_strip_template : str
- Name of ANTs skull-stripping template (‘OASIS’ or ‘NKI’)
- work_dir : str
- Directory in which to store workflow execution state and temporary files
- output_dir : str
- Directory in which to save derivatives
- bids_dir : str
- Root directory of BIDS dataset
- freesurfer : bool
- Enable FreeSurfer surface reconstruction (may increase runtime)
- output_spaces : list
List of output spaces functional images are to be resampled to. Some parts of pipeline will only be instantiated for some output spaces.
Valid spaces:
- T1w
- template
- fsnative
- fsaverage (or other pre-existing FreeSurfer templates)
- template : str
- Name of template targeted by ‘template’ output space
- medial_surface_nan : bool
- Replace medial wall values with NaNs on functional GIFTI files
- hires : bool
- Enable sub-millimeter preprocessing in FreeSurfer
- use_bbr : bool or None
- Enable/disable boundary-based registration refinement.
If
None
, test BBR result for distortion before accepting. - bold2t1w_dof : 6, 9 or 12
- Degrees-of-freedom for BOLD-T1w registration
- fmap_bspline : bool
- Experimental: Fit B-Spline field using least-squares
- fmap_demean : bool
- Demean voxel-shift map during unwarp
- use_syn : bool
- Experimental: Enable ANTs SyN-based susceptibility distortion correction (SDC). If fieldmaps are present and enabled, this is not run, by default.
- force_syn : bool
- Temporary: Always run SyN-based SDC
- use_aroma : bool
- Perform ICA-AROMA on MNI-resampled functional series
- ignore_aroma_err : bool
- Do not fail on ICA-AROMA errors
- output_grid_ref : str or None
- Path of custom reference image for normalization
-
fmriprep.workflows.base.
init_single_subject_wf
(subject_id, task_id, name, ignore, debug, low_mem, anat_only, longitudinal, t2s_coreg, omp_nthreads, skull_strip_template, reportlets_dir, output_dir, bids_dir, freesurfer, output_spaces, template, medial_surface_nan, hires, use_bbr, bold2t1w_dof, fmap_bspline, fmap_demean, use_syn, force_syn, output_grid_ref, use_aroma, ignore_aroma_err)[source]¶ This workflow organizes the preprocessing pipeline for a single subject. It collects and reports information about the subject, and prepares sub-workflows to perform anatomical and functional preprocessing.
Anatomical preprocessing is performed in a single workflow, regardless of the number of sessions. Functional preprocessing is performed using a separate workflow for each individual BOLD series.
(Source code, png, svg, pdf)
Parameters
- subject_id : str
- List of subject labels
- task_id : str or None
- Task ID of BOLD series to preprocess, or
None
to preprocess all - name : str
- Name of workflow
- ignore : list
- Preprocessing steps to skip (may include “slicetiming”, “fieldmaps”)
- debug : bool
- Enable debugging outputs
- low_mem : bool
- Write uncompressed .nii files in some cases to reduce memory usage
- anat_only : bool
- Disable functional workflows
- longitudinal : bool
- Treat multiple sessions as longitudinal (may increase runtime) See sub-workflows for specific differences
- t2s_coreg : bool
- Use multiple BOLDS echos to create T2*-map for T2*-driven coregistration
- omp_nthreads : int
- Maximum number of threads an individual process may use
- skull_strip_template : str
- Name of ANTs skull-stripping template (‘OASIS’ or ‘NKI’)
- reportlets_dir : str
- Directory in which to save reportlets
- output_dir : str
- Directory in which to save derivatives
- bids_dir : str
- Root directory of BIDS dataset
- freesurfer : bool
- Enable FreeSurfer surface reconstruction (may increase runtime)
- output_spaces : list
List of output spaces functional images are to be resampled to. Some parts of pipeline will only be instantiated for some output spaces.
Valid spaces:
- T1w
- template
- fsnative
- fsaverage (or other pre-existing FreeSurfer templates)
- template : str
- Name of template targeted by ‘template’ output space
- medial_surface_nan : bool
- Replace medial wall values with NaNs on functional GIFTI files
- hires : bool
- Enable sub-millimeter preprocessing in FreeSurfer
- use_bbr : bool or None
- Enable/disable boundary-based registration refinement.
If
None
, test BBR result for distortion before accepting. - bold2t1w_dof : 6, 9 or 12
- Degrees-of-freedom for BOLD-T1w registration
- fmap_bspline : bool
- Experimental: Fit B-Spline field using least-squares
- fmap_demean : bool
- Demean voxel-shift map during unwarp
- use_syn : bool
- Experimental: Enable ANTs SyN-based susceptibility distortion correction (SDC). If fieldmaps are present and enabled, this is not run, by default.
- force_syn : bool
- Temporary: Always run SyN-based SDC
- output_grid_ref : str or None
- Path of custom reference image for normalization
- use_aroma : bool
- Perform ICA-AROMA on MNI-resampled functional series
- ignore_aroma_err : bool
- Do not fail on ICA-AROMA errors
Inputs
- subjects_dir
- FreeSurfer SUBJECTS_DIR
Anatomical reference preprocessing workflows¶
-
fmriprep.workflows.anatomical.
init_anat_preproc_wf
(skull_strip_template, output_spaces, template, debug, freesurfer, longitudinal, omp_nthreads, hires, reportlets_dir, output_dir, num_t1w, name='anat_preproc_wf')[source]¶ This workflow controls the anatomical preprocessing stages of FMRIPREP.
This includes:
- Creation of a structural template
- Skull-stripping and bias correction
- Tissue segmentation
- Normalization
- Surface reconstruction with FreeSurfer
(Source code, png, svg, pdf)
Parameters
- skull_strip_template : str
- Name of ANTs skull-stripping template (‘OASIS’ or ‘NKI’)
- output_spaces : list
List of output spaces functional images are to be resampled to.
Some pipeline components will only be instantiated for some output spaces.
Valid spaces:
- T1w
- template
- fsnative
- fsaverage (or other pre-existing FreeSurfer templates)
- template : str
- Name of template targeted by ‘template’ output space
- debug : bool
- Enable debugging outputs
- freesurfer : bool
- Enable FreeSurfer surface reconstruction (may increase runtime)
- longitudinal : bool
- Create unbiased structural template, regardless of number of inputs (may increase runtime)
- omp_nthreads : int
- Maximum number of threads an individual process may use
- hires : bool
- Enable sub-millimeter preprocessing in FreeSurfer
- reportlets_dir : str
- Directory in which to save reportlets
- output_dir : str
- Directory in which to save derivatives
- name : str, optional
- Workflow name (default: anat_preproc_wf)
Inputs
- t1w
- List of T1-weighted structural images
- t2w
- List of T2-weighted structural images
- subjects_dir
- FreeSurfer SUBJECTS_DIR
Outputs
- t1_preproc
- Bias-corrected structural template, defining T1w space
- t1_brain
- Skull-stripped
t1_preproc
- t1_mask
- Mask of the skull-stripped template image
- t1_seg
- Segmentation of preprocessed structural image, including gray-matter (GM), white-matter (WM) and cerebrospinal fluid (CSF)
- t1_tpms
- List of tissue probability maps in T1w space
- t1_2_mni
- T1w template, normalized to MNI space
- t1_2_mni_forward_transform
- ANTs-compatible affine-and-warp transform file
- t1_2_mni_reverse_transform
- ANTs-compatible affine-and-warp transform file (inverse)
- mni_mask
- Mask of skull-stripped template, in MNI space
- mni_seg
- Segmentation, resampled into MNI space
- mni_tpms
- List of tissue probability maps in MNI space
- subjects_dir
- FreeSurfer SUBJECTS_DIR
- subject_id
- FreeSurfer subject ID
- t1_2_fsnative_forward_transform
- LTA-style affine matrix translating from T1w to FreeSurfer-conformed subject space
- t1_2_fsnative_reverse_transform
- LTA-style affine matrix translating from FreeSurfer-conformed subject space to T1w
- surfaces
- GIFTI surfaces (gray/white boundary, midthickness, pial, inflated)
Subworkflows
-
fmriprep.workflows.anatomical.
init_skullstrip_ants_wf
(skull_strip_template, debug, omp_nthreads, name='skullstrip_ants_wf')[source]¶ This workflow performs skull-stripping using ANTs’
BrainExtraction.sh
(Source code, png, svg, pdf)
Parameters
- skull_strip_template : str
- Name of ANTs skull-stripping template (‘OASIS’ or ‘NKI’)
- debug : bool
- Enable debugging outputs
- omp_nthreads : int
- Maximum number of threads an individual process may use
Inputs
- in_file
- T1-weighted structural image to skull-strip
Outputs
- bias_corrected
- Bias-corrected
in_file
, before skull-stripping - out_file
- Skull-stripped
in_file
- out_mask
- Binary mask of the skull-stripped
in_file
- out_report
- Reportlet visualizing quality of skull-stripping
-
fmriprep.workflows.anatomical.
init_refine_brainmask_wf
(name='refine_brainmask')[source]¶ This workflow refines the brainmask implicit in the FreeSurfer’s
aseg.mgz
brain tissue segmentation to reconcile ANTs’ and FreeSurfer’s brain masks.First, the
aseg.mgz
mask from FreeSurfer is refined in two steps, using binary morphological operations:- With a binary closing operation the sulci are included into the mask. This results in a smoother brain mask that does not exclude deep, wide sulci.
- Fill any holes (typically, there could be a hole next to the pineal gland and the corpora quadrigemina if the great cerebral brain is segmented out).
Second, the brain mask is grown, including pixels that have a high likelihood to the GM tissue distribution:
- Dilate and substract the brain mask, defining the region to search for candidate pixels that likely belong to cortical GM.
- Pixels found in the search region that are labeled as GM by ANTs
(during
antsBrainExtraction.sh
) are directly added to the new mask. - Otherwise, estimate GM tissue parameters locally in patches of
ww
size, and test the likelihood of the pixel to belong in the GM distribution.
This procedure is inspired on mindboggle’s solution to the problem: https://github.com/nipy/mindboggle/blob/master/mindboggle/guts/segment.py#L1660
(Source code, png, svg, pdf)
Inputs
- in_file
- Anatomical, merged T1w image after INU correction
- ants_segs
- Brain tissue segmentation from ANTS
antsBrainExtraction.sh
- subjects_dir
- FreeSurfer SUBJECTS_DIR
- subject_id
- FreeSurfer subject ID
Outputs
- out_file
- New, refined brain mask
Surface preprocessing¶
fmriprep
uses FreeSurfer to reconstruct surfaces from T1w/T2w
structural images.
-
fmriprep.workflows.anatomical.
init_surface_recon_wf
(omp_nthreads, hires, name='surface_recon_wf')[source]¶ This workflow reconstructs anatomical surfaces using FreeSurfer’s
recon-all
.Reconstruction is performed in three phases. The first phase initializes the subject with T1w and T2w (if available) structural images and performs basic reconstruction (
autorecon1
) with the exception of skull-stripping. For example, a subject with only one session with T1w and T2w images would be processed by the following command:$ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \ -i <bids-root>/sub-<subject_label>/anat/sub-<subject_label>_T1w.nii.gz \ -T2 <bids-root>/sub-<subject_label>/anat/sub-<subject_label>_T2w.nii.gz \ -autorecon1 \ -noskullstrip
The second phase imports an externally computed skull-stripping mask. The final phase resumes reconstruction, using the T2w image to assist in finding the pial surface, if available. See
init_autorecon_resume_wf()
for details.Memory annotations for FreeSurfer are based off their documentation. They specify an allocation of 4GB per subject. Here we define 5GB to have a certain margin.
(Source code, png, svg, pdf)
Parameters
- omp_nthreads : int
- Maximum number of threads an individual process may use
- hires : bool
- Enable sub-millimeter preprocessing in FreeSurfer
Inputs
- t1w
- List of T1-weighted structural images
- t2w
- List of T2-weighted structural images (only first used)
- skullstripped_t1
- Skull-stripped T1-weighted image (or mask of image)
- ants_segs
- Brain tissue segmentation from ANTS
antsBrainExtraction.sh
- corrected_t1
- INU-corrected, merged T1-weighted image
- subjects_dir
- FreeSurfer SUBJECTS_DIR
- subject_id
- FreeSurfer subject ID
Outputs
- subjects_dir
- FreeSurfer SUBJECTS_DIR
- subject_id
- FreeSurfer subject ID
- t1_2_fsnative_forward_transform
- LTA-style affine matrix translating from T1w to FreeSurfer-conformed subject space
- t1_2_fsnative_reverse_transform
- LTA-style affine matrix translating from FreeSurfer-conformed subject space to T1w
- surfaces
- GIFTI surfaces for gray/white matter boundary, pial surface, midthickness (or graymid) surface, and inflated surfaces
- out_brainmask
- Refined brainmask, derived from FreeSurfer’s
aseg
volume - out_report
- Reportlet visualizing quality of surface alignment
Subworkflows
-
fmriprep.workflows.anatomical.
init_autorecon_resume_wf
(omp_nthreads, name='autorecon_resume_wf')[source]¶ This workflow resumes recon-all execution, assuming the -autorecon1 stage has been completed.
In order to utilize resources efficiently, this is broken down into five sub-stages; after the first stage, the second and third stages may be run simultaneously, and the fourth and fifth stages may be run simultaneously, if resources permit:
$ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \ -autorecon2-volonly $ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \ -autorecon-hemi lh \ -noparcstats -nocortparc2 -noparcstats2 -nocortparc3 \ -noparcstats3 -nopctsurfcon -nohyporelabel -noaparc2aseg \ -noapas2aseg -nosegstats -nowmparc -nobalabels $ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \ -autorecon-hemi rh \ -noparcstats -nocortparc2 -noparcstats2 -nocortparc3 \ -noparcstats3 -nopctsurfcon -nohyporelabel -noaparc2aseg \ -noapas2aseg -nosegstats -nowmparc -nobalabels $ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \ -autorecon3 -hemi lh -T2pial $ recon-all -sd <output dir>/freesurfer -subjid sub-<subject_label> \ -autorecon3 -hemi rh -T2pial
The excluded steps in the second and third stages (
-no<option>
) are not fully hemisphere independent, and are therefore postponed to the final two stages.(Source code, png, svg, pdf)
Inputs
- subjects_dir
- FreeSurfer SUBJECTS_DIR
- subject_id
- FreeSurfer subject ID
- use_T2
- Refine pial surface using T2w images
Outputs
- subjects_dir
- FreeSurfer SUBJECTS_DIR
- subject_id
- FreeSurfer subject ID
- out_report
- Reportlet visualizing quality of surface alignment
-
fmriprep.workflows.anatomical.
init_gifti_surface_wf
(name='gifti_surface_wf')[source]¶ This workflow prepares GIFTI surfaces from a FreeSurfer subjects directory
If midthickness (or graymid) surfaces do not exist, they are generated and saved to the subject directory as
lh/rh.midthickness
. These, along with the gray/white matter boundary (lh/rh.smoothwm
), pial sufaces (lh/rh.pial
) and inflated surfaces (lh/rh.inflated
) are converted to GIFTI files. Additionally, the vertex coordinates arerecentered
to align with native T1w space.(Source code, png, svg, pdf)
Inputs
- subjects_dir
- FreeSurfer SUBJECTS_DIR
- subject_id
- FreeSurfer subject ID
- t1_2_fsnative_reverse_transform
- LTA formatted affine transform file (inverse)
Outputs
- surfaces
- GIFTI surfaces for gray/white matter boundary, pial surface, midthickness (or graymid) surface, and inflated surfaces
Pre-processing fMRI - BOLD signal workflows¶
Orchestrating the BOLD-preprocessing workflow¶
-
fmriprep.workflows.bold.base.
init_func_preproc_wf
(bold_file, ignore, freesurfer, use_bbr, t2s_coreg, bold2t1w_dof, reportlets_dir, output_spaces, template, output_dir, omp_nthreads, fmap_bspline, fmap_demean, use_syn, force_syn, use_aroma, ignore_aroma_err, medial_surface_nan, debug, low_mem, output_grid_ref, layout=None)[source]¶ This workflow controls the functional preprocessing stages of FMRIPREP.
(Source code, png, svg, pdf)
Parameters
- bold_file : str
- BOLD series NIfTI file
- ignore : list
- Preprocessing steps to skip (may include “slicetiming”, “fieldmaps”)
- freesurfer : bool
- Enable FreeSurfer functional registration (bbregister) and resampling BOLD series to FreeSurfer surface meshes.
- use_bbr : bool or None
- Enable/disable boundary-based registration refinement.
If
None
, test BBR result for distortion before accepting. - t2s_coreg : bool
- Use multiple BOLD echos to create T2*-map for T2*-driven coregistration
- bold2t1w_dof : 6, 9 or 12
- Degrees-of-freedom for BOLD-T1w registration
- reportlets_dir : str
- Directory in which to save reportlets
- output_spaces : list
List of output spaces functional images are to be resampled to. Some parts of pipeline will only be instantiated for some output spaces.
Valid spaces:
- T1w
- template
- fsnative
- fsaverage (or other pre-existing FreeSurfer templates)
- template : str
- Name of template targeted by ‘template’ output space
- output_dir : str
- Directory in which to save derivatives
- omp_nthreads : int
- Maximum number of threads an individual process may use
- fmap_bspline : bool
- Experimental: Fit B-Spline field using least-squares
- fmap_demean : bool
- Demean voxel-shift map during unwarp
- use_syn : bool
- Experimental: Enable ANTs SyN-based susceptibility distortion correction (SDC). If fieldmaps are present and enabled, this is not run, by default.
- force_syn : bool
- Temporary: Always run SyN-based SDC
- use_aroma : bool
- Perform ICA-AROMA on MNI-resampled functional series
- ignore_aroma_err : bool
- Do not fail on ICA-AROMA errors
- medial_surface_nan : bool
- Replace medial wall values with NaNs on functional GIFTI files
- debug : bool
- Enable debugging outputs
- low_mem : bool
- Write uncompressed .nii files in some cases to reduce memory usage
- output_grid_ref : str or None
- Path of custom reference image for normalization
- layout : BIDSLayout
- BIDSLayout structure to enable metadata retrieval
Inputs
- bold_file
- BOLD series NIfTI file
- t1_preproc
- Bias-corrected structural template image
- t1_brain
- Skull-stripped
t1_preproc
- t1_mask
- Mask of the skull-stripped template image
- t1_seg
- Segmentation of preprocessed structural image, including gray-matter (GM), white-matter (WM) and cerebrospinal fluid (CSF)
- t1_tpms
- List of tissue probability maps in T1w space
- t1_2_mni_forward_transform
- ANTs-compatible affine-and-warp transform file
- t1_2_mni_reverse_transform
- ANTs-compatible affine-and-warp transform file (inverse)
- subjects_dir
- FreeSurfer SUBJECTS_DIR
- subject_id
- FreeSurfer subject ID
- t1_2_fsnative_forward_transform
- LTA-style affine matrix translating from T1w to FreeSurfer-conformed subject space
- t1_2_fsnative_reverse_transform
- LTA-style affine matrix translating from FreeSurfer-conformed subject space to T1w
Outputs
- bold_t1
- BOLD series, resampled to T1w space
- bold_mask_t1
- BOLD series mask in T1w space
- bold_mni
- BOLD series, resampled to template space
- bold_mask_mni
- BOLD series mask in template space
- confounds
- TSV of confounds
- surfaces
- BOLD series, resampled to FreeSurfer surfaces
- aroma_noise_ics
- Noise components identified by ICA-AROMA
- melodic_mix
- FSL MELODIC mixing matrix
Subworkflows
init_bold_reference_wf()
init_bold_stc_wf()
init_bold_hmc_wf()
init_bold_t2s_wf()
init_bold_reg_wf()
init_bold_confounds_wf()
init_bold_mni_trans_wf()
init_bold_preproc_trans_wf()
init_bold_surf_wf()
init_pepolar_unwarp_wf()
init_fmap_estimator_wf()
init_sdc_unwarp_wf()
init_nonlinear_sdc_wf()
Utility workflows¶
-
fmriprep.workflows.bold.util.
init_bold_reference_wf
(omp_nthreads, bold_file=None, name='bold_reference_wf')[source]¶ This workflow generates reference BOLD images for a series
The raw reference image is the target of HMC, and a contrast-enhanced reference is the subject of distortion correction, as well as boundary-based registration to T1w and template spaces.
(Source code, png, svg, pdf)
Parameters
- bold_file : str
- BOLD series NIfTI file
- omp_nthreads : int
- Maximum number of threads an individual process may use
- name : str
- Name of workflow (default:
bold_reference_wf
)
Inputs
- bold_file
- BOLD series NIfTI file
Outputs
- bold_file
- Validated BOLD series NIfTI file
- raw_ref_image
- Reference image to which BOLD series is motion corrected
- skip_vols
- Number of non-steady-state volumes detected at beginning of
bold_file
- ref_image
- Contrast-enhanced reference image
- ref_image_brain
- Skull-stripped reference image
- bold_mask
- Skull-stripping mask of reference image
- validation_report
- HTML reportlet indicating whether
bold_file
had a valid affine
Subworkflows
init_enhance_and_skullstrip_wf()
-
fmriprep.workflows.bold.util.
init_enhance_and_skullstrip_bold_wf
(name='enhance_and_skullstrip_bold_wf', omp_nthreads=1)[source]¶ This workflow takes in a BOLD fMRI average/summary (e.g. a reference image averaging non-steady-state timepoints), and sharpens the histogram with the application of the N4 algorithm for removing the INU bias field and calculates a signal mask.
Steps of this workflow are:
- Calculate a conservative mask using Nilearn’s
create_epi_mask
. - Run ANTs’
N4BiasFieldCorrection
on the input BOLD average, using the mask generated in 1) instead of the internal Otsu thresholding. - Calculate a loose mask using FSL’s
bet
, with one mathematical morphology dilation of one iteration and a sphere of 6mm as structuring element. - Mask the INU-corrected image
with the latest mask calculated in 3), then use AFNI’s
3dUnifize
to standardize the T2* contrast distribution. - Calculate a mask using AFNI’s
3dAutomask
after the contrast enhancement of 4). - Calculate a final mask as the intersection of 3) and 5).
- Apply final mask on the enhanced reference.
(Source code, png, svg, pdf)
Inputs
- in_file
- BOLD image (single volume)
Outputs
- bias_corrected_file
- the
in_file
after N4BiasFieldCorrection - skull_stripped_file
- the
bias_corrected_file
after skull-stripping - mask_file
- mask of the skull-stripped input file
- out_report
- reportlet for the skull-stripping
- Calculate a conservative mask using Nilearn’s
-
fmriprep.workflows.bold.util.
init_skullstrip_bold_wf
(name='skullstrip_bold_wf')[source]¶ This workflow applies skull-stripping to a BOLD image.
It is intended to be used on an image that has previously been bias-corrected with
init_enhance_and_skullstrip_bold_wf()
(Source code, png, svg, pdf)
Inputs
- in_file
- BOLD image (single volume)
Outputs
- skull_stripped_file
- the
in_file
after skull-stripping - mask_file
- mask of the skull-stripped input file
- out_report
- reportlet for the skull-stripping
Head-Motion Estimation and Correction (HMC) of BOLD images¶
-
fmriprep.workflows.bold.hmc.
init_bold_hmc_wf
(mem_gb, omp_nthreads, name='bold_hmc_wf')[source]¶ This workflow estimates the motion parameters to perform HMC over the input BOLD image.
(Source code, png, svg, pdf)
Parameters
- mem_gb : float
- Size of BOLD file in GB
- omp_nthreads : int
- Maximum number of threads an individual process may use
- name : str
- Name of workflow (default:
bold_hmc_wf
)
Inputs
- bold_file
- BOLD series NIfTI file
- raw_ref_image
- Reference image to which BOLD series is motion corrected
Outputs
- xforms
- ITKTransform file aligning each volume to
ref_image
- movpar_file
- MCFLIRT motion parameters, normalized to SPM format (X, Y, Z, Rx, Ry, Rz)
Slice-Timing Correction (STC) of BOLD images¶
-
fmriprep.workflows.bold.stc.
init_bold_stc_wf
(metadata, name='bold_stc_wf')[source]¶ This workflow performs STC over the input BOLD image.
(Source code, png, svg, pdf)
Parameters
- metadata : dict
- BIDS metadata for BOLD file
- name : str
- Name of workflow (default:
bold_stc_wf
)
Inputs
- bold_file
- BOLD series NIfTI file
- skip_vols
- Number of non-steady-state volumes detected at beginning of
bold_file
Outputs
- stc_file
- Slice-timing corrected BOLD series NIfTI file
Generate T2* map from multi-echo BOLD images¶
-
fmriprep.workflows.bold.t2s.
init_bold_t2s_wf
(echo_times, mem_gb, omp_nthreads, name='bold_t2s_wf')[source]¶ This workflow performs HMC on individual echo_files, uses T2SMap to generate a T2* image for coregistration instead of mean BOLD EPI.
(Source code, png, svg, pdf)
Parameters
- echo_times
- list of TEs associated with each echo
- mem_gb : float
- Size of BOLD file in GB
- omp_nthreads : int
- Maximum number of threads an individual process may use
- name : str
- Name of workflow (default:
bold_t2s_wf
)
Inputs
- xforms
- ITKTransform file aligning each volume to
ref_image
- echo_split
- 3D volumes of multi-echo BOLD EPI
Outputs
- t2s_map
- the T2* map for the EPI run
Registration workflows¶
-
fmriprep.workflows.bold.registration.
init_bold_reg_wf
(freesurfer, use_bbr, bold2t1w_dof, mem_gb, omp_nthreads, name='bold_reg_wf', use_compression=True, use_fieldwarp=False)[source]¶ This workflow registers the reference BOLD image to T1-space, using a boundary-based registration (BBR) cost function.
If FreeSurfer-based preprocessing is enabled, the
bbregister
utility is used to align the BOLD images to the reconstructed subject, and the resulting transform is adjusted to target the T1 space. If FreeSurfer-based preprocessing is disabled, FSL FLIRT is used with the BBR cost function to directly target the T1 space.(Source code, png, svg, pdf)
Parameters
- freesurfer : bool
- Enable FreeSurfer functional registration (bbregister)
- use_bbr : bool or None
- Enable/disable boundary-based registration refinement.
If
None
, test BBR result for distortion before accepting. - bold2t1w_dof : 6, 9 or 12
- Degrees-of-freedom for BOLD-T1w registration
- mem_gb : float
- Size of BOLD file in GB
- omp_nthreads : int
- Maximum number of threads an individual process may use
- name : str
- Name of workflow (default:
bold_reg_wf
) - use_compression : bool
- Save registered BOLD series as
.nii.gz
- use_fieldwarp : bool
- Include SDC warp in single-shot transform from BOLD to T1
Inputs
- name_source
- BOLD series NIfTI file Used to recover original information lost during processing
- ref_bold_brain
- Reference image to which BOLD series is aligned
If
fieldwarp == True
,ref_bold_brain
should be unwarped - ref_bold_mask
- Skull-stripping mask of reference image
- t1_preproc
- Bias-corrected structural template image
- t1_brain
- Skull-stripped
t1_preproc
- t1_mask
- Mask of the skull-stripped template image
- t1_seg
- Segmentation of preprocessed structural image, including gray-matter (GM), white-matter (WM) and cerebrospinal fluid (CSF)
- bold_split
- Individual 3D BOLD volumes, not motion corrected
- hmc_xforms
- List of affine transforms aligning each volume to
ref_image
in ITK format - subjects_dir
- FreeSurfer SUBJECTS_DIR
- subject_id
- FreeSurfer subject ID
- t1_2_fsnative_reverse_transform
- LTA-style affine matrix translating from FreeSurfer-conformed subject space to T1w
- fieldwarp
- a DFM in ITK format
Outputs
- itk_bold_to_t1
- Affine transform from
ref_bold_brain
to T1 space (ITK format) - itk_t1_to_bold
- Affine transform from T1 space to BOLD space (ITK format)
- bold_t1
- Motion-corrected BOLD series in T1 space
- bold_mask_t1
- BOLD mask in T1 space
- out_report
- Reportlet visualizing quality of registration
- fallback
- Boolean indicating whether BBR was rejected (mri_coreg registration returned)
Subworkflows
init_bbreg_wf()
init_fsl_bbr_wf()
-
fmriprep.workflows.bold.registration.
init_bbreg_wf
(use_bbr, bold2t1w_dof, omp_nthreads, name='bbreg_wf')[source]¶ This workflow uses FreeSurfer’s
bbregister
to register a BOLD image to a T1-weighted structural image.It is a counterpart to
init_fsl_bbr_wf()
, which performs the same task using FSL’s FLIRT with a BBR cost function.The
use_bbr
option permits a high degree of control over registration. IfFalse
, standard, affine coregistration will be performed using FreeSurfer’smri_coreg
tool. IfTrue
,bbregister
will be seeded with the initial transform found bymri_coreg
(equivalent to runningbbregister --init-coreg
). IfNone
, afterbbregister
is run, the resulting affine transform will be compared to the initial transform found bymri_coreg
. Excessive deviation will result in rejecting the BBR refinement and accepting the original, affine registration.(Source code, png, svg, pdf)
Parameters
- use_bbr : bool or None
- Enable/disable boundary-based registration refinement.
If
None
, test BBR result for distortion before accepting. - bold2t1w_dof : 6, 9 or 12
- Degrees-of-freedom for BOLD-T1w registration
- name : str, optional
- Workflow name (default: bbreg_wf)
Inputs
- in_file
- Reference BOLD image to be registered
- t1_2_fsnative_reverse_transform
- FSL-style affine matrix translating from FreeSurfer T1.mgz to T1w
- subjects_dir
- FreeSurfer SUBJECTS_DIR
- subject_id
- FreeSurfer subject ID (must have folder in SUBJECTS_DIR)
- t1_brain
- Unused (see
init_fsl_bbr_wf()
) - t1_seg
- Unused (see
init_fsl_bbr_wf()
)
Outputs
- itk_bold_to_t1
- Affine transform from
ref_bold_brain
to T1 space (ITK format) - itk_t1_to_bold
- Affine transform from T1 space to BOLD space (ITK format)
- out_report
- Reportlet for assessing registration quality
- fallback
- Boolean indicating whether BBR was rejected (mri_coreg registration returned)
-
fmriprep.workflows.bold.registration.
init_fsl_bbr_wf
(use_bbr, bold2t1w_dof, name='fsl_bbr_wf')[source]¶ This workflow uses FSL FLIRT to register a BOLD image to a T1-weighted structural image, using a boundary-based registration (BBR) cost function.
It is a counterpart to
init_bbreg_wf()
, which performs the same task using FreeSurfer’sbbregister
.The
use_bbr
option permits a high degree of control over registration. IfFalse
, standard, rigid coregistration will be performed by FLIRT. IfTrue
, FLIRT-BBR will be seeded with the initial transform found by the rigid coregistration. IfNone
, after FLIRT-BBR is run, the resulting affine transform will be compared to the initial transform found by FLIRT. Excessive deviation will result in rejecting the BBR refinement and accepting the original, affine registration.Parameters
- use_bbr : bool or None
- Enable/disable boundary-based registration refinement.
If
None
, test BBR result for distortion before accepting. - bold2t1w_dof : 6, 9 or 12
- Degrees-of-freedom for BOLD-T1w registration
- name : str, optional
- Workflow name (default: fsl_bbr_wf)
Inputs
- in_file
- Reference BOLD image to be registered
- t1_brain
- Skull-stripped T1-weighted structural image
- t1_seg
- FAST segmentation of
t1_brain
- t1_2_fsnative_reverse_transform
- Unused (see
init_bbreg_wf()
) - subjects_dir
- Unused (see
init_bbreg_wf()
) - subject_id
- Unused (see
init_bbreg_wf()
)
Outputs
- itk_bold_to_t1
- Affine transform from
ref_bold_brain
to T1 space (ITK format) - itk_t1_to_bold
- Affine transform from T1 space to BOLD space (ITK format)
- out_report
- Reportlet for assessing registration quality
- fallback
- Boolean indicating whether BBR was rejected (rigid FLIRT registration returned)
Resampling workflows¶
-
fmriprep.workflows.bold.resampling.
init_bold_surf_wf
(mem_gb, output_spaces, medial_surface_nan, name='bold_surf_wf')[source]¶ This workflow samples functional images to FreeSurfer surfaces
For each vertex, the cortical ribbon is sampled at six points (spaced 20% of thickness apart) and averaged.
Outputs are in GIFTI format.
(Source code, png, svg, pdf)
Parameters
- output_spaces : list
- List of output spaces functional images are to be resampled to
Target spaces beginning with
fs
will be selected for resampling, such asfsaverage
or related template spaces If the list containsfsnative
, images will be resampled to the individual subject’s native surface - medial_surface_nan : bool
- Replace medial wall values with NaNs on functional GIFTI files
Inputs
- source_file
- Motion-corrected BOLD series in T1 space
- t1_preproc
- Bias-corrected structural template image
- subjects_dir
- FreeSurfer SUBJECTS_DIR
- subject_id
- FreeSurfer subject ID
- t1_2_fsnative_forward_transform
- LTA-style affine matrix translating from T1w to FreeSurfer-conformed subject space
Outputs
- surfaces
- BOLD series, resampled to FreeSurfer surfaces
-
fmriprep.workflows.bold.resampling.
init_bold_mni_trans_wf
(template, mem_gb, omp_nthreads, name='bold_mni_trans_wf', output_grid_ref=None, use_compression=True, use_fieldwarp=False)[source]¶ This workflow samples functional images to the MNI template in a “single shot” from the original BOLD series.
(Source code, png, svg, pdf)
Parameters
- template : str
- Name of template targeted by ‘template’ output space
- mem_gb : float
- Size of BOLD file in GB
- omp_nthreads : int
- Maximum number of threads an individual process may use
- name : str
- Name of workflow (default:
bold_mni_trans_wf
) - output_grid_ref : str or None
- Path of custom reference image for normalization
- use_compression : bool
- Save registered BOLD series as
.nii.gz
- use_fieldwarp : bool
- Include SDC warp in single-shot transform from BOLD to MNI
Inputs
- itk_bold_to_t1
- Affine transform from
ref_bold_brain
to T1 space (ITK format) - t1_2_mni_forward_transform
- ANTs-compatible affine-and-warp transform file
- bold_split
- Individual 3D volumes, not motion corrected
- bold_mask
- Skull-stripping mask of reference image
- name_source
- BOLD series NIfTI file Used to recover original information lost during processing
- hmc_xforms
- List of affine transforms aligning each volume to
ref_image
in ITK format - fieldwarp
- a DFM in ITK format
Outputs
- bold_mni
- BOLD series, resampled to template space
- bold_mask_mni
- BOLD series mask in template space
-
fmriprep.workflows.bold.resampling.
init_bold_preproc_trans_wf
(mem_gb, omp_nthreads, name='bold_preproc_trans_wf', use_compression=True, use_fieldwarp=False)[source]¶ This workflow resamples the input fMRI in its native (original) space in a “single shot” from the original BOLD series.
(Source code, png, svg, pdf)
Parameters
- mem_gb : float
- Size of BOLD file in GB
- omp_nthreads : int
- Maximum number of threads an individual process may use
- name : str
- Name of workflow (default:
bold_mni_trans_wf
) - use_compression : bool
- Save registered BOLD series as
.nii.gz
- use_fieldwarp : bool
- Include SDC warp in single-shot transform from BOLD to MNI
Inputs
- bold_split
- Individual 3D volumes, not motion corrected
- bold_mask
- Skull-stripping mask of reference image
- name_source
- BOLD series NIfTI file Used to recover original information lost during processing
- hmc_xforms
- List of affine transforms aligning each volume to
ref_image
in ITK format - fieldwarp
- a DFM in ITK format
Outputs
- bold
- BOLD series, resampled in native space, including all preprocessing
- bold_mask
- BOLD series mask calculated with the new time-series
- bold_ref
- BOLD reference image: an average-like 3D image of the time-series
- bold_ref_brain
- Same as
bold_ref
, but once the brain mask has been applied
Calculate BOLD confounds¶
-
fmriprep.workflows.bold.confounds.
init_bold_confs_wf
(mem_gb, use_aroma, ignore_aroma_err, metadata, name='bold_confs_wf')[source]¶ This workflow calculates confounds for a BOLD series, and aggregates them into a TSV file, for use as nuisance regressors in a GLM.
The following confounds are calculated, with column headings in parentheses:
- Region-wise average signal (
CSF
,WhiteMatter
,GlobalSignal
) - DVARS - standard, nonstandard, and voxel-wise standard variants
(
stdDVARS
,non-stdDVARS
,vx-wisestdDVARS
) - Framewise displacement, based on MCFLIRT motion parameters
(
FramewiseDisplacement
) - Temporal CompCor (
tCompCorXX
) - Anatomical CompCor (
aCompCorXX
) - Cosine basis set for high-pass filtering w/ 0.008 Hz cut-off
(
CosineXX
) - Non-steady-state volumes (
NonSteadyStateXX
) - Estimated head-motion parameters, in mm and rad
(
X
,Y
,Z
,RotX
,RotY
,RotZ
) - ICA-AROMA-identified noise components, if enabled
(
AROMAAggrCompXX
)
Prior to estimating aCompCor and tCompCor, non-steady-state volumes are censored and high-pass filtered using a DCT basis. The cosine basis, as well as one regressor per censored volume, are included for convenience.
(Source code, png, svg, pdf)
Parameters
- mem_gb : float
- Size of BOLD file in GB - please note that this size should be calculated after resamplings that may extend the FoV
- use_aroma : bool
- Perform ICA-AROMA on MNI-resampled functional series
- ignore_aroma_err : bool
- Do not fail on ICA-AROMA errors
- metadata : dict
- BIDS metadata for BOLD file
Inputs
- bold
- BOLD image, after the prescribed corrections (STC, HMC and SDC) when available.
- bold_mask
- BOLD series mask
- movpar_file
- SPM-formatted motion parameters file
- t1_mask
- Mask of the skull-stripped template image
- t1_tpms
- List of tissue probability maps in T1w space
- t1_bold_xform
- Affine matrix that maps the T1w space into alignment with the native BOLD space
- bold_mni
- BOLD image resampled in MNI space (only if
use_aroma
enabled) - bold_mask_mni
- Brain mask corresponding to the BOLD image resampled in MNI space
(only if
use_aroma
enabled)
Outputs
- confounds_file
- TSV of all aggregated confounds
- confounds_list
- List of calculated confounds for reporting
- acompcor_report
- Reportlet visualizing white-matter/CSF mask used for aCompCor
- tcompcor_report
- Reportlet visualizing ROI identified in tCompCor
- ica_aroma_report
- Reportlet visualizing MELODIC ICs, with ICA-AROMA signal/noise labels
- aroma_noise_ics
- CSV of noise components identified by ICA-AROMA
- melodic_mix
- FSL MELODIC mixing matrix
- nonaggr_denoised_file
- BOLD series with non-aggressive ICA-AROMA denoising applied
Subworkflows
- Region-wise average signal (
-
fmriprep.workflows.bold.confounds.
init_ica_aroma_wf
(name='ica_aroma_wf', ignore_aroma_err=False)[source]¶ This workflow wraps ICA-AROMA to identify and remove motion-related independent components from a BOLD time series.
The following steps are performed:
- Smooth data using SUSAN
- Run MELODIC outside of ICA-AROMA to generate the report
- Run ICA-AROMA
- Aggregate identified motion components (aggressive) to TSV
- Return classified_motion_ICs and melodic_mix for user to complete
- non-aggressive denoising in T1w space
Additionally, non-aggressive denoising is performed on the BOLD series resampled into MNI space.
(Source code, png, svg, pdf)
Parameters
- ignore_aroma_err : bool
- Do not fail on ICA-AROMA errors
Inputs
- bold_mni
- BOLD series, resampled to template space
- movpar_file
- SPM-formatted motion parameters file
- bold_mask_mni
- BOLD series mask in template space
Outputs
- aroma_confounds
- TSV of confounds identified as noise by ICA-AROMA
- aroma_noise_ics
- CSV of noise components identified by ICA-AROMA
- melodic_mix
- FSL MELODIC mixing matrix
- nonaggr_denoised_file
- BOLD series with non-aggressive ICA-AROMA denoising applied
- out_report
- Reportlet visualizing MELODIC ICs, with ICA-AROMA signal/noise labels
Fieldmap estimation and unwarping workflows¶
Automatic selection of the appropriate SDC method¶
If the dataset metadata indicate tha more than one field map acquisition is
IntendedFor
(see BIDS Specification section 8.9) the following priority will
be used:
Table of behavior (fieldmap use-cases):
Fieldmaps found | use_syn |
force_syn |
Action |
---|---|---|---|
True | True | Fieldmaps + SyN | |
True | False | Fieldmaps | |
False | True | SyN | |
False | True | False | SyN |
False | False | False | HMC only |
-
fmriprep.workflows.fieldmap.base.
init_fmap_estimator_wf
(fmap_bids, reportlets_dir, omp_nthreads, fmap_bspline)[source]¶ This workflow selects the fieldmap estimation data available for the subject and returns the estimated fieldmap in mm.
Outputs:
- fmap
- The estimated fieldmap itself IN UNITS OF Hz.
- fmap_ref
- the anatomical reference for the fieldmap (magnitude image, corrected SEm, etc.)
- fmap_mask
- a brain mask for the fieldmap
Direct B0 mapping sequences¶
When the fieldmap is directly measured with a prescribed sequence (such as SE), we only need to calculate the corresponding B-Spline coefficients to adapt the fieldmap to the TOPUP tool. This procedure is described with more detail here.
This corresponds to the section 8.9.3 –fieldmap image (and one magnitude image)– of the BIDS specification.
-
fmriprep.workflows.fieldmap.fmap.
init_fmap_wf
(reportlets_dir, omp_nthreads, fmap_bspline, name='fmap_wf')[source]¶ Fieldmap workflow - when we have a sequence that directly measures the fieldmap we just need to mask it (using the corresponding magnitude image) to remove the noise in the surrounding air region, and ensure that units are Hz.
(Source code, png, svg, pdf)
Phase-difference B0 estimation¶
The field inhomogeneity inside the scanner (fieldmap) is proportional to the phase drift between two subsequent GRE sequence.
Fieldmap preprocessing workflow for fieldmap data structure 8.9.1 in BIDS 1.0.0: one phase diff and at least one magnitude image
-
fmriprep.workflows.fieldmap.phdiff.
init_phdiff_wf
(reportlets_dir, omp_nthreads, name='phdiff_wf')[source]¶ Estimates the fieldmap using a phase-difference image and one or more magnitude images corresponding to two or more GRE acquisitions. The original code was taken from nipype.
(Source code, png, svg, pdf)
Outputs:
outputnode.fmap_ref - The average magnitude image, skull-stripped outputnode.fmap_mask - The brain mask applied to the fieldmap outputnode.fmap - The estimated fieldmap in Hz
-
fmriprep.workflows.fieldmap.phdiff.
phdiff2fmap
(in_file, delta_te, out_file=None)[source]¶ Converts the input phase-difference map into a fieldmap in Hz, using the eq. (1) of [Hutton2002]:
\[\Delta B_0 (\text{T}^{-1}) = \frac{\Delta \Theta}{2\pi\gamma \Delta\text{TE}}\]In this case, we do not take into account the gyromagnetic ratio of the proton (\(\gamma\)), since it will be applied inside TOPUP:
\[\Delta B_0 (\text{Hz}) = \frac{\Delta \Theta}{2\pi \Delta\text{TE}}\]
Phase Encoding POLARity (PEPOLAR) techniques¶
-
fmriprep.workflows.fieldmap.pepolar.
init_pepolar_unwarp_wf
(fmaps, bold_file, omp_nthreads, layout=None, fmaps_pes=None, bold_file_pe=None, name='pepolar_unwarp_wf')[source]¶ This workflow takes in a set of EPI files with opposite phase encoding direction than the target file and calculates a displacements field (in other words, an ANTs-compatible warp file).
This procedure works if there is only one ‘_epi’ file is present (as long as it has the opposite phase encoding direction to the target file). The target file will be used to estimate the field distortion. However, if there is another ‘_epi’ file present with a matching phase encoding direction to the target it will be used instead.
Currently, different phase encoding dimension in the target file and the ‘_epi’ file(s) (for example ‘i’ and ‘j’) is not supported.
The warp field correcting for the distortions is estimated using AFNI’s 3dQwarp, with displacement estimation limited to the target file phase encoding direction.
It also calculates a new mask for the input dataset that takes into account the distortions.
(Source code, png, svg, pdf)
Inputs
- in_reference
- the reference image
- in_reference_brain
- the reference image skullstripped
- in_mask
- a brain mask corresponding to
in_reference
- name_source
- not used, kept for signature compatibility with
init_sdc_unwarp_wf
Outputs
- out_reference
- the
in_reference
after unwarping - out_reference_brain
- the
in_reference
after unwarping and skullstripping - out_warp
- the corresponding DFM compatible with ANTs
- out_mask
- mask of the unwarped input file
-
fmriprep.workflows.fieldmap.pepolar.
init_prepare_epi_wf
(omp_nthreads, name='prepare_epi_wf')[source]¶ This workflow takes in a set of EPI files with with the same phase encoding direction and returns a single 3D volume ready to be used in field distortion estimation.
The procedure involves: estimating a robust template using FreeSurfer’s ‘mri_robust_template’, bias field correction using ANTs N4BiasFieldCorrection and AFNI 3dUnifize, skullstripping using FSL BET and AFNI 3dAutomask, and rigid coregistration to the reference using ANTs.
(Source code, png, svg, pdf)
Inputs
- fmaps
- list of 3D or 4D NIfTI images
- ref_brain
- coregistration reference (skullstripped and bias field corrected)
Outputs
- out_file
- single 3D NIfTI file
Fieldmap-less estimation (experimental)¶
In the absence of direct measurements of fieldmap data, we provide an (experimental)
option to estimate the susceptibility distortion based on the ANTs symmetric
normalization (SyN) technique.
This feature may be enabled, using the --use-syn-sdc
flag, and will only be
applied if fieldmaps are unavailable.
During the evaluation phase, the --force-syn
flag will cause this estimation to
be performed in addition to fieldmap-based estimation, to permit the direct
comparison of the results of each technique.
Note that, even if --force-syn
is given, the functional outputs of FMRIPREP will
be corrected using the fieldmap-based estimates.
Feedback will be enthusiastically received.
-
fmriprep.workflows.fieldmap.syn.
init_nonlinear_sdc_wf
(bold_file, freesurfer, bold2t1w_dof, template, omp_nthreads, bold_pe='j', atlas_threshold=3, name='nonlinear_sdc_wf')[source]¶ This workflow takes a skull-stripped T1w image and reference BOLD image and estimates a susceptibility distortion correction warp, using ANTs symmetric normalization (SyN) and the average fieldmap atlas described in [Treiber2016].
SyN deformation is restricted to the phase-encoding (PE) direction. If no PE direction is specified, anterior-posterior PE is assumed.
SyN deformation is also restricted to regions that are expected to have a >3mm (approximately 1 voxel) warp, based on the fieldmap atlas.
This technique is a variation on those developed in [Huntenburg2014] and [Wang2017].
(Source code, png, svg, pdf)
Inputs
- t1_brain
- skull-stripped, bias-corrected structural image
- bold_ref
- skull-stripped reference image
- t1_seg
- FAST segmentation white and gray matter, in native T1w space
- t1_2_mni_reverse_transform
- inverse registration transform of T1w image to MNI template
Outputs
- out_reference_brain
- the
bold_ref
image after unwarping - out_warp
- the corresponding DFM compatible with ANTs
- out_mask
- mask of the unwarped input file
Unwarping¶
Abbreviations
- fmap
- fieldmap
- VSM
- voxel-shift map – a 3D nifti where displacements are in pixels (not mm)
- DFM
- displacements field map – a nifti warp file compatible with ANTs (mm)
-
fmriprep.workflows.fieldmap.unwarp.
init_fmap_unwarp_report_wf
(reportlets_dir, name='fmap_unwarp_report_wf')[source]¶ This workflow generates and saves a reportlet showing the effect of fieldmap unwarping a BOLD image.
(Source code, png, svg, pdf)
Parameters
- reportlets_dir : str
- Directory in which to save reportlets
- name : str, optional
- Workflow name (default: fmap_unwarp_report_wf)
Inputs
- in_pre
- Reference image, before unwarping
- in_post
- Reference image, after unwarping
- in_seg
- Segmentation of preprocessed structural image, including gray-matter (GM), white-matter (WM) and cerebrospinal fluid (CSF)
- in_xfm
- Affine transform from T1 space to BOLD space (ITK format)
- name_source
- BOLD series NIfTI file Used to recover original information lost during processing
-
fmriprep.workflows.fieldmap.unwarp.
init_sdc_unwarp_wf
(reportlets_dir, omp_nthreads, fmap_bspline, fmap_demean, debug, name='sdc_unwarp_wf')[source]¶ This workflow takes in a displacements fieldmap and calculates the corresponding displacements field (in other words, an ANTs-compatible warp file).
It also calculates a new mask for the input dataset that takes into account the distortions. The mask is restricted to the field of view of the fieldmap since outside of it corrections could not be performed.
(Source code, png, svg, pdf)
Inputs
- in_reference
- the reference image
- in_mask
- a brain mask corresponding to
in_reference
- name_source
- path to the original _bold file being unwarped
- fmap
- the fieldmap in Hz
- fmap_ref
- the reference (anatomical) image corresponding to
fmap
- fmap_mask
- a brain mask corresponding to
fmap
Outputs
- out_reference
- the
in_reference
after unwarping - out_reference_brain
- the
in_reference
after unwarping and skullstripping - out_warp
- the corresponding DFM compatible with ANTs
- out_jacobian
- the jacobian of the field (for drop-out alleviation)
- out_mask
- mask of the unwarped input file