Workflow reference
RABIES pipelines are built as Nipype workflows: each node is a processing step, and the required inputs and outputs define the links between nodes.
The docstrings below are included directly from the RABIES source, so they describe the version of the code these docs were built from. For what each workflow is for and why it exists, see The preprocessing workflow and The confound correction workflow.
Preprocessing
rabies.preprocess_pkg.bold_ref.init_bold_reference_wf
"""
The 4D raw EPI file is used to generate a representative volumetric 3D EPI. This volume later becomes the target for
motion realignment and the estimation of susceptibility distortions through registration to the structural image.
Two iterations of motion realignment to an initial median of the volumes are conducted, then a trimmed mean is
computed on the realignment volumes, ignoring 5% extreme, and this average becomes the reference image. The final
image is then corrected using non-local means denoising (Manjón et al., 2010).
References:
Manjón, J. V., Coupé, P., Martí-Bonmatí, L., Collins, D. L., & Robles, M. (2010). Adaptive non-local means
denoising of MR images with spatially varying noise levels. Journal of Magnetic Resonance Imaging:
JMRI, 31(1), 192–203.
Command line interface parameters:
--detect_dummy Detect and remove initial dummy volumes from the EPI, and generate a reference EPI based on
these volumes if detected. Dummy volumes will be removed from the output preprocessed EPI.
(default: False)
Workflow:
parameters
opts: command line interface parameters
inputs
bold_file: Nifti file with EPI timeseries
outputs
ref_image: the reference EPI volume
"""
rabies.preprocess_pkg.hmc.init_bold_hmc_wf
"""
This workflow estimates motion during fMRI acquisition. To do so, each EPI frame is registered to a volumetric
target reference image with a rigid registration.
This results in the measurement of 3 Euler angles in radians and 3 translations in mm (from ITK's
Euler3DTransform https://itk.org/Doxygen/html/classitk_1_1Euler3DTransform.html) at each time frame, which are
then stored into an output CSV file.
Command line interface parameters:
--HMC_level {1,2,3,4}
Select a level of stringence for the framewise registration (the higher the level, the
more stringent it is).
(default: 2)
Workflow:
parameters
opts: command line interface parameters
inputs
bold_file: Nifti file with EPI timeseries to realign
ref_image: the 3D image target for realignment
outputs
motcorr_params: CSV file which contains all translation and rotation parameters
"""
rabies.preprocess_pkg.hmc.EstimateMotionParams
"""
This interface generates estimations of framewise displacement, together with
the expansion of the 6 motion parameters to include derivatives and squared parameters (Friston 24).
Framewise displacement are computed within as follows:
1. For each timepoint, the 3 Euler rotations and translations are converted to an affine matrix
2. For each voxel within a brain mask representing the referential space post-motion realignment,
the inverse transform is applied to generate a point pre-motion realignment.
3. For framewise displacement, the distance is measured between the pre-correction points generated
from the current and the previous timeframe. Distance is measured in mm with the Euclidean distance.
"""
rabies.preprocess_pkg.inho_correction.init_inho_correction_wf
"""
Corrects an input 3D image for intensity inhomogeneities. The image is denoised with non-local mean
denoising (Manjón et al., 2010) (for EPIs, denoising was carried beforehand during 3D EPI generation)
followed by iterative correction for intensity inhomogeneities (Sled et al., 1998). Initial masking
is achieved via intensity thresholding, giving an initial correction of the image, and a registration is
then conducted to register a brain mask for a final round of correction.
References:
Manjón, J. V., Coupé, P., Martí-Bonmatí, L., Collins, D. L., & Robles, M. (2010). Adaptive non-local means
denoising of MR images with spatially varying noise levels. Journal of Magnetic Resonance Imaging:
JMRI, 31(1), 192–203.
Sled, J. G., Zijdenbos, A. P., & Evans, A. C. (1998). A nonparametric method for automatic correction of
intensity nonuniformity in MRI data. IEEE Transactions on Medical Imaging, 17(1), 87–97.
Command line interface parameters:
--anat_inho_cor ANAT_INHO_COR
Select options for the inhomogeneity correction of the structural image.
* method: specify which registration strategy is employed for providing a brain mask.
*** Rigid: conducts only rigid registration.
*** Affine: conducts Rigid then Affine registration.
*** SyN: conducts Rigid, Affine then non-linear registration.
*** no_reg: skip registration.
*** N4_reg: previous correction script prior to version 0.3.1.
*** disable: disables the inhomogeneity correction.
* otsu_thresh: The inhomogeneity correction script necessitates an initial correction with a
Otsu masking strategy (prior to registration of an anatomical mask). This option sets the
Otsu threshold level to capture the right intensity distribution.
*** Specify an integer among [0,1,2,3,4].
* multiotsu: Select this option to perform a staged inhomogeneity correction, where only
lower intensities are initially corrected, then higher intensities are iteratively
included to eventually correct the whole image. This technique may help with images with
particularly strong inhomogeneity gradients and very low intensities.
*** Specify 'true' or 'false'.
(default: method=SyN,otsu_thresh=2,multiotsu=false)
--anat_robust_inho_cor ANAT_ROBUST_INHO_COR
When selecting this option, inhomogeneity correction is executed twice to optimize
outcomes. After completing an initial inhomogeneity correction step, the corrected outputs
are co-registered to generate an unbiased template, using the same method as the commonspace
registration. This template is then masked, and is used as a new target for masking during a
second iteration of inhomogeneity correction. Using this dataset-specific template should
improve the robustness of masking for inhomogeneity correction.
* apply: select 'true' to apply this option.
*** Specify 'true' or 'false'.
* masking: Combine masks derived from the inhomogeneity correction step to support
registration during the generation of the unbiased template, and then during template
registration.
*** Specify 'true' or 'false'.
* brain_extraction: conducts brain extraction prior to template registration based on the
combined masks from inhomogeneity correction. This will enhance brain edge-matching, but
requires good quality masks. This should be selected along the 'masking' option.
*** Specify 'true' or 'false'.
* keep_mask_after_extract: If using brain_extraction, use the mask to compute the registration metric
within the mask only. Choose to prevent stretching of the images beyond the limit of the brain mask
(e.g. if the moving and target images don't have the same brain coverage).
*** Specify 'true' or 'false'.
* template_registration: Specify a registration script for the alignment of the
dataset-generated unbiased template to a reference template for masking.
*** Rigid: conducts only rigid registration.
*** Affine: conducts Rigid then Affine registration.
*** SyN: conducts Rigid, Affine then non-linear registration.
*** no_reg: skip registration.
(default: apply=false,masking=false,brain_extraction=false,keep_mask_after_extract=false,template_registration=SyN)
--bold_inho_cor BOLD_INHO_COR
Same as --anat_inho_cor, but for the EPI images.
(default: method=Rigid,otsu_thresh=2,multiotsu=false)
--bold_robust_inho_cor BOLD_ROBUST_INHO_COR
Same as --anat_robust_inho_cor, but for the EPI images.
(default: apply=false,masking=false,brain_extraction=false,keep_mask_after_extract=false,template_registration=SyN)
Workflow:
parameters
opts: command line interface parameters
image_type: between 'EPI' and 'structural'. Defines which script to run depending on
image type
output_folder: specify a folder to execute the unbiased template generation and store important outputs
nthreads_modelbuild: set the maximum number of parallel threads to launch
inputs
target_img: the image to correct
anat_ref: the registration target with a brain mask
anat_mask: the brain mask of the registration target
name_source: reference file for naming purpose
template_anat: the structural template in for robust inhomogeneity correction
template_mask: the brain mask for robust inhomogeneity correction
outputs
corrected: the output image after the final correction
denoise_mask: the brain mask resampled on the corrected image
init_denoise: the image after a first round of correction
"""
rabies.preprocess_pkg.commonspace_reg.init_commonspace_reg_wf
"""
This workflow handles the alignment of all MRI sessions to a common space. This is conducted first by generating
a dataset-specific unbiased template from the input structural images, thereby aligning the different MRI
sessions. Through a set of iterations, images are registered to a consensus average generated from the overlap
of all scans at the previous iteration. Registrations are increasingly stringent, executing 2 iterations each
for a rigid, then affine and finally non-linear template generation. The final iteration provides the individual
transforms to align each scan to the unbiased template. This template generation process creates a robust target
for the alignment of MRI sessions sharing the same acquisition properties, which will minimize registration
inconsistencies between sessions, as opposed to the direct registration to an external template. The algorithm is
implemented in https://github.com/CoBrALab/optimized_antsMultivariateTemplateConstruction.
After generating the unbiased template, the template itself is registered with a non-linear registration to the
reference atlas in common space, providing transforms to common space and the associated brain parcellations.
References:
Avants, B. B., Tustison, N. J., Song, G., Cook, P. A., Klein, A., & Gee, J. C. (2011). A reproducible evaluation
of ANTs similarity metric performance in brain image registration. NeuroImage, 54(3), 2033–2044.
Command line interface parameters:
--commonspace_reg COMMONSPACE_REG
Specify registration options for the commonspace registration.
* masking: Combine masks derived from the inhomogeneity correction step to support
registration during the generation of the unbiased template, and then during template
registration.
*** Specify 'true' or 'false'.
* brain_extraction: conducts brain extraction prior to template registration based on the
combined masks from inhomogeneity correction. This will enhance brain edge-matching, but
requires good quality masks. This should be selected along the 'masking' option.
*** Specify 'true' or 'false'.
* keep_mask_after_extract: If using brain_extraction, use the mask to compute the registration metric
within the mask only. Choose to prevent stretching of the images beyond the limit of the brain mask
(e.g. if the moving and target images don't have the same brain coverage).
*** Specify 'true' or 'false'.
* template_registration: Specify a registration script for the alignment of the
dataset-generated unbiased template to the commonspace atlas.
*** Rigid: conducts only rigid registration.
*** Affine: conducts Rigid then Affine registration.
*** SyN: conducts Rigid, Affine then non-linear registration.
*** no_reg: skip registration.
* fast_commonspace: Skip the generation of a dataset-generated unbiased template, and
instead, register each scan independently directly onto the commonspace atlas, using the
template_registration. This option can be faster, but may decrease the quality of
alignment between subjects.
*** Specify 'true' or 'false'.
(default: masking=false,brain_extraction=false,keep_mask_after_extract=false,template_registration=SyN,fast_commonspace=false)
Workflow:
parameters
opts: command line interface parameters (technically all the parser args, including winsorization and brain_extraction etc are included here)
commonspace_reg_opts: the opts that are specific to this run of commonspace_reg (there can be different parameters, for instance for the robust_inho_cor workflows)
output_folder: specify a folder to execute the workflow and store important outputs
transforms_datasink: datasink node where the transforms are stored
nthreads_modelbuild: set the maximum number of parallel threads to launch
output_datasinks: whether to generate a datasink from the outputs of the workflow
joinsource_list: names for the iterable nodes to join before unbiased template generation
inputs
moving_image_list: list of files corresponding to the images from different MRI sessions
moving_mask_list: mask files overlapping with the moving images, inherited from the inhomogeneity
correction step. These masks are used for --commonspace_masking and --brain_extraction
template_anat: the target structural template to register the unbiased template
template_mask: the brain mask of the structural template
outputs
unbiased_template: the generated unbiased template
unbiased_mask: brain mask resampled over the unbiased template
anatspace_mask: the atlas brain mask resampled to an associated MRI session in anat space
to_atlas_affine: affine transform for registration to the atlas
to_atlas_warp: non-linear transform for registration to the atlas
to_atlas_inverse_warp: inverse of the non-linear transform for registration to the atlas
anat_to_unbiased_affine: affine transform from anat space to the unbiased template
anat_to_unbiased_warp: non-linear transform from anat space to the unbiased template
anat_to_unbiased_inverse_warp: inverse of the non-linear transform from anat space to the unbiased template
anat_to_commonspace_transform_list: ordered list of the transforms to apply to move from the
anat space to the common space
anat_to_commonspace_inverse_list: list defining whether the inverse of affine transforms should
be applied for anat_to_commonspace_transform_list
commonspace_to_anat_transform_list: ordered list of the transforms to apply to move from the
common space to the anat space
commonspace_to_anat_inverse_list: list defining whether the inverse of affine transforms should
be applied for commonspace_to_anat_transform_list
"""
rabies.preprocess_pkg.registration.init_cross_modal_reg_wf
"""
The input volumetric EPI image is registered non-linearly to an associated structural MRI image.
The non-linear transform estimates the correction for EPI susceptibility distortions (Wang et al., 2017).
References:
Wang, S., Peterson, D. J., Gatenby, J. C., Li, W., Grabowski, T. J., & Madhyastha, T. M. (2017).
Evaluation of Field Map and Nonlinear Registration Methods for Correction of Susceptibility Artifacts
in Diffusion MRI. Frontiers in Neuroinformatics, 11, 17.
Command line interface parameters:
--bold2anat_coreg BOLD2ANAT_COREG
Specify the registration script for cross-modal alignment between the EPI and structural
images. This operation is responsible for correcting EPI susceptibility distortions.
* masking: With this option, the brain masks obtained from the EPI inhomogeneity correction
step are used to support registration.
*** Specify 'true' or 'false'.
* brain_extraction: conducts brain extraction prior to registration using the EPI masks from
inhomogeneity correction. This will enhance brain edge-matching, but requires good quality
masks. This should be selected along the 'masking' option.
*** Specify 'true' or 'false'.
* winsorize_lower_bound: the lower bound for the antsRegistration winsorize-image-intensities option, useful for fUS images with intensity outliers.
*** Specify a value between 0 and 1.
* winsorize_upper_bound: the upper bound for the antsRegistration winsorize-image-intensities option, useful for fUS images with intensity outliers.
*** Specify a value between 0 and 1.
* keep_mask_after_extract: If using brain_extraction, use the mask to compute the registration metric
within the mask only. Choose to prevent stretching of the images beyond the limit of the brain mask
(e.g. if the moving and target images don't have the same brain coverage).
*** Specify 'true' or 'false'.
* registration: Specify a registration script.
*** Rigid: conducts only rigid registration.
*** Affine: conducts Rigid then Affine registration.
*** SyN: conducts Rigid, Affine then non-linear registration.
*** no_reg: skip registration.
(default: masking=false,brain_extraction=false,winsorize_lower_bound=0.0,winsorize_upper_bound=1.0,keep_mask_after_extract=false,registration=SyN)
Workflow:
parameters
opts: command line interface parameters
inputs
ref_bold_brain: volumetric EPI image to register
anat_ref: the target structural image
anat_mask: the brain mask of the structural image
moving_mask: a EPI mask inherited from inhomogeneity correction
outputs
bold_to_anat_affine: affine transform from the EPI to the anatomical image
bold_to_anat_warp: non-linear transform from the EPI to the anatomical image
bold_to_anat_inverse_warp: inverse non-linear transform from the EPI to the anatomical image
output_warped_bold: the EPI image warped onto the structural image
"""
rabies.preprocess_pkg.resampling.init_bold_preproc_trans_wf
"""
This workflow carries out the resampling of the original EPI timeseries into preprocessed timeseries.
This is accomplished by applying at each frame a combined transform which accounts for previously estimated
motion correction and susceptibility distortion correction, together with the alignment to common space (the
exact combination of transforms depends on which anatomical preprocessed timeseries are resampled into).
All transforms are concatenated into a single resampling operation to mitigate interpolation effects from
repeated resampling.
Command line interface parameters:
Resampling Options:
The following options allow to resample the voxel dimensions for the preprocessed EPIs
or for the anatomical images during registration.
The resampling syntax must be 'dim1xdim2xdim3' (in mm), follwing the RAS axis convention
(dim1=Right-Left, dim2=Anterior-Posterior, dim3=Superior-Inferior). If 'inputs_defined'
is provided instead of axis dimensions, the original dimensions are preserved.
--nativespace_resampling NATIVESPACE_RESAMPLING
Can specify a resampling dimension for the nativespace fMRI outputs.
(default: inputs_defined)
--commonspace_resampling COMMONSPACE_RESAMPLING
Can specify a resampling dimension for the commonspace fMRI outputs.
(default: inputs_defined)
Workflow:
parameters
opts: command line interface parameters
resampling_dim: specify the desired output voxel dimensions after resampling
inputs
name_source: a reference file for naming the output
bold_file: the EPI timeseries to resample
motcorr_params: the motion correction parameters
transforms_list: a list of transforms to apply onto EPI timeseries, including
susceptibility distortion correction and resampling to common space
inverses: a list specifying whether the inverse affine transforms should be
applied in transforms_list
ref_file: a reference image in the targetted space for resampling. Should be the structural
image from the same session if outputs are in native space, or the atlas template for
outputs in common space
outputs
bold: the preprocessed EPI timeseries
bold_ref: a volumetric 3D EPI generated from the preprocessed timeseries
"""
rabies.preprocess_pkg.resampling.init_mask_preproc_trans_wf
"""
This workflow carries the resampling of brain masks from the reference
commonspace onto the preprocessed EPI timeseries.
Workflow:
parameters
opts: command line interface parameters
inputs
name_source: a reference file for naming the output
ref_file: a reference image in the targetted space for resampling. Should be the structural
image from the same session if outputs are in native space, or the atlas template for
outputs in common space
mask_transforms_list: the list of transforms to apply onto the atlas parcellations
to overlap with the EPI
mask_inverses: a list specifying whether the inverse affine transforms should be
applied in mask_transforms_list
outputs
brain_mask: the brain mask resampled onto preprocessed EPI timeseries
WM_mask: the WM mask resampled onto preprocessed EPI timeseries
CSF_mask: the CSF mask resampled onto preprocessed EPI timeseries
vascular_mask: the vascular mask resampled onto preprocessed EPI timeseries
"""
Confound correction
rabies.confound_correction_pkg.confound_correction.init_confound_correction_wf
"""
This workflow applies the RABIES confound correction pipeline to preprocessed EPI timeseries. The correction steps are
orchestrated in line with recommendations from human litterature:
#1 - Compute and apply frame censoring mask (from FD and/or DVARS thresholds)
#2 - If --match_number_timepoints is selected, each scan is matched to the defined minimum_timepoint number of frames.
#4 - Linear/Quadratic detrending of fMRI timeseries and nuisance regressors
#4 - Apply ICA-AROMA.
#5 - If frequency filtering and frame censoring are applied, simulate data in censored timepoints using the Lomb-Scargle periodogram,
as suggested in Power et al. (2014, Neuroimage), for both the fMRI timeseries and nuisance regressors prior to filtering.
#6 - As recommended in Lindquist et al. (2019, Human brain mapping), make the nuisance regressors orthogonal
to the temporal frequency filter.
#7 - Apply highpass and/or lowpass filtering on the fMRI timeseries (with simulated timepoints).
#8 - Re-apply the frame censoring mask onto filtered fMRI timeseries and nuisance regressors, taking out the
simulated timepoints. Edge artefacts from frequency filtering can also be removed as recommended in Power et al. (2014, Neuroimage).
#9 - Apply confound regression using the selected nuisance regressors.
#10 - Scaling of timeseries variance.
#11 - Apply Gaussian spatial smoothing.
References:
Power, J. D., Barnes, K. A., Snyder, A. Z., Schlaggar, B. L., & Petersen, S. E. (2012). Spurious but systematic
correlations in functional connectivity MRI networks arise from subject motion. Neuroimage, 59(3), 2142-2154.
Power, J. D., Mitra, A., Laumann, T. O., Snyder, A. Z., Schlaggar, B. L., & Petersen, S. E. (2014). Methods to detect,
characterize, and remove motion artifact in resting state fMRI. Neuroimage, 84, 320-341.
Lindquist, M. A., Geuter, S., Wager, T. D., & Caffo, B. S. (2019). Modular preprocessing pipelines can reintroduce
artifacts into fMRI data. Human brain mapping, 40(8), 2358-2376.
Workflow:
parameters
cr_opts: command line interface parameters from confound_correction
inputs
bold_file: preprocessed EPI timeseries
brain_mask: brain mask overlapping with EPI timeseries
csf_mask: CSF mask overlapping with EPI timeseries
motion_params_csv: CSV file with motion regressors
FD_file: CSV file with the framewise displacement
outputs
cleaned_path: the cleaned EPI timeseries
aroma_out: folder with outputs from ICA-AROMA
VE_file: variance explained (R^2) from confound regression at each voxel
STD_file: standard deviation on the cleaned EPI timeseries
CR_STD_file: standard deviation on the confound timeseries modelled during confound regression
random_CR_STD_file_path: variance fitted by random regressors during confound regression
corrected_CR_STD_file_path: CR_STD_file after substracting the variance fitted by random
regressors.
frame_mask_file: CSV file which records which frame were censored
CR_data_dict: dictionary object storing extra data computed during confound correction
"""
See also
How to contribute to RABIES covers writing a new Nipype interface and connecting it into one of these workflows.