Running The Software
Input data in BIDS standard
The input dataset must be organized according to the BIDS data structure[GAC+16]. RABIES will iterate through all subjects found to contain a functional file (see section on BIDS filters below), and will also iterate according to sessions and runs found within each subject if available. If anatomical scans are used for preprocessing (i.e. not using --bold_only), each functional scan will be matched to one corresponding anatomical scan of the same subject/session (using BIDS filters for the anatomical image, see below).
Directory structure for an example dataset
Our example dataset has the following BIDS structure:
├── sub-PHG001
│ └── ses-3
│ ├── anat
│ │ ├── sub-PHG001_ses-3_acq-RARE_T2w.json
│ │ └── sub-PHG001_ses-3_acq-RARE_T2w.nii.gz
│ └── func
│ ├── sub-PHG001_ses-3_task-rest_acq-EPI_run-1_bold.json
│ └── sub-PHG001_ses-3_task-rest_acq-EPI_run-1_bold.nii.gz
└── sub-PHG002
└── ses-3
├── anat
│ ├── sub-PHG002_ses-3_acq-RARE_T2w.json
│ └── sub-PHG002_ses-3_acq-RARE_T2w.nii.gz
└── func
├── sub-PHG002_ses-3_task-rest_acq-EPI_run-1_bold.json
└── sub-PHG002_ses-3_task-rest_acq-EPI_run-1_bold.nii.gz
8 directories, 8 files
BIDS filters to identify functional and structural images
By default, RABIES will use the ‘bold’ or ‘cbv’ suffix to identify functional scans and the ‘T1w’ or ‘T2w’ suffix for structural scans. Files which don’t match the BIDS filters are ignored. However, the BIDS filters can also be customized with the --bids_filter parameter during the preprocessing stage. This can be useful for instance if the default is not enough to find the right set of scans. The custom BIDS filter must be formated into a JSON file with the functional filter under ‘func’ and structural filter under ‘anat’ (see example below for the default parameters):
{
"func": {
"suffix":["bold","cbv"]
},
"anat": {
"suffix":["T1w","T2w"]
}
}
Command Line Interface
RABIES is executed using a command line interface, within a terminal. The software is divided into three main processing stages: preprocessing, confound correction and analysis. Accordingly, the command line interface allows for three different mode of execution, corresponding to the processing stages. So first, when executing the software, one of the processing stage must be selected. Below you can find the general –help message printed with rabies --help, which provides a summary of each processing stage together with options for parallel processing and memory management. Then, the –help associated to each processing stage, i.e. preprocess, confound_correction and analysis, describes in more detail the various parameters available to adapt image processing according to the user needs. Click on the corresponding –help to expand:
rabies --help
usage: rabies [-h] [--inclusion_ids [INCLUSION_IDS ...]]
[--exclusion_ids [EXCLUSION_IDS ...]]
[-p {Linear,MultiProc,SGE,SGEGraph,PBS,LSF,SLURM,SLURMGraph}]
[--local_threads LOCAL_THREADS]
[--num_ITK_threads NUM_ITK_THREADS]
[--scale_min_memory SCALE_MIN_MEMORY] [--min_proc MIN_PROC]
[--figure_format {png,svg}] [--verbose VERBOSE] [-f]
[--data_type {int16,int32,float32,float64}]
[--interpolation {Linear,BSpline3,LanczosSinc,CosineSinc}]
Processing stage ...
RABIES performs multiple stages of rodent fMRI image processing, including preprocessing,
confound correction, simple analyses and data quality assessment.
optional arguments:
-h, --help show this help message and exit
Processing options:
The RABIES workflow is seperated into three main processing stages: preprocessing,
confound correction and analysis. Outputs from the preprocessing provide the inputs for
the subsequent confound correction, and finally analysis.
Processing stage Description
preprocess
Conducts preprocessing on an input dataset in BIDS format. Preprocessing includes
motion realignment, susceptibility distortions correction through non-linear
registration, alignment to commonspace, anatomical parcellation and evaluation of
nuisance timecourses.
confound_correction
Flexible options for confound correction are applied directly on preprocessing outputs
from RABIES to derive cleaned timeseries. Various correction strategies, if selected, are
applied in the following order, following best practices 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.
#3 - 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 (see --nuisance_regressors
options).
#10 - Scaling of timeseries variance
#11 - Apply Gaussian spatial smoothing.
analysis
Conduct simple resting-state functional connectivity (FC) analysis, or data quality
diagnosis, on cleaned timeseries after confound correction. Analysis options include
seed-based FC, whole-brain FC matrix, group-ICA and dual regression. --data_diagnosis
computes features of data quality at the individual scan and group levels, as in
Desrosiers-Gregoire et al. 2024.
Execution Options:
Options for parallel execution and memory management.
--inclusion_ids [INCLUSION_IDS ...]
Define a list of BOLD scan to include, i.e. run the pipeline on a subset of the data.
To do so, provide the full path to the corresponding BOLD file in the input BIDS folder. The list
of scan can be specified manually as a list of file name '--inclusion_ids scan1.nii.gz
scan2.nii.gz ...' or the files can be imbedded into a .txt file with one filename per row.
By default, 'all' the scans found in the input BIDS directory or from the previous
processing step. This can be provided at any processing stage.
***NOTE: do not enter this parameter right before the processing stage (preprocess, etc...), this will cause
parsing errors. Instead, provide another parameter after --inclusion_ids (e.g. --verbose or -p).
(default: ['all'])
--exclusion_ids [EXCLUSION_IDS ...]
Instead of providing a list of scans to include, this argument provides a list of scans to exclude (while
keeping all other scans). This argument follows the same syntax rules as --includion_ids. --exclusion_ids
and --inclusion_ids cannot be used simultaneously.
(default: ['none'])
-p {Linear,MultiProc,SGE,SGEGraph,PBS,LSF,SLURM,SLURMGraph}, --plugin {Linear,MultiProc,SGE,SGEGraph,PBS,LSF,SLURM,SLURMGraph}
Specify the nipype plugin for workflow execution.
Consult https://nipype.readthedocs.io/en/0.11.0/users/plugins.html for details.
(default: Linear)
--local_threads LOCAL_THREADS
For --plugin MultiProc, set the maximum number of processors run in parallel.
Defaults to number of CPUs.
(default: 2)
--num_ITK_threads NUM_ITK_THREADS
Number of threads to provide for antsRegistration and antsMotionCorr commands.
The nipype parallelization will be impacted accordingly, i.e. nodes running these commands
will require this number of threads from --local_threads.
This can take the value of 'optimal', 'off' or an integer value:
optimal: The number of threads will be set to '# --local_threads/# of functional scans',
which will maximize the distribution of available threads across scans.
int: an integer can be provided to manually set the number of ITK threads.
off: This will turn off ITK threading management, and maximize parallelization (as in previous RABIES
versions), which will maximize computational efficiency but risks memory overloads and crashes.
(default: optimal)
--scale_min_memory SCALE_MIN_MEMORY
For --plugin MultiProc, set the memory scaling factor attributed to nodes during
execution. Increase the scaling if memory crashes are reported.
(default: 1.0)
--min_proc MIN_PROC For --plugin SGE/SGEGraph, scale the number of nodes attributed to jobs to
avoid memory crashes.
(default: 1)
--figure_format {png,svg}
Select the file format for figures generated by RABIES.
(default: png)
--verbose VERBOSE Set the verbose level. 0=WARNING, 1=INFO, 2 or above=DEBUG.
(default: 1)
-f, --force The pipeline will not stop if previous outputs are encountered.
Previous outputs will be overwritten.
(default: False)
--data_type {int16,int32,float32,float64}
Specify data format outputs to control for file size.
(default: float32)
--interpolation {Linear,BSpline3,LanczosSinc,CosineSinc}
Select the interpolator which will be used when resampling images across different spaces.
(default: Linear)
rabies preprocess --help
usage: rabies preprocess [-h] [--bids_filter BIDS_FILTER] [--bold_only]
[--anat_autobox] [--bold_autobox]
[--oblique2card {none,affine,3dWarp}]
[--apply_despiking] [--detect_dummy]
[--log_transform] [--anat_inho_cor ANAT_INHO_COR]
[--anat_robust_inho_cor ANAT_ROBUST_INHO_COR]
[--bold_inho_cor BOLD_INHO_COR]
[--bold_robust_inho_cor BOLD_ROBUST_INHO_COR]
[--commonspace_reg COMMONSPACE_REG]
[--inherit_unbiased_template INHERIT_UNBIASED_TEMPLATE]
[--bold2anat_coreg BOLD2ANAT_COREG] [--no_HMC]
[--HMC_level {1,2,3,4}]
[--hmc_qc_report HMC_QC_REPORT]
[--resampling_space {common_only,native_only,both}]
[--bold_nativespace]
[--nativespace_resampling NATIVESPACE_RESAMPLING]
[--commonspace_resampling COMMONSPACE_RESAMPLING]
[--anatomical_resampling ANATOMICAL_RESAMPLING]
[--apply_STC] [--TR TR]
[--args_3dTshift ARGS_3DTSHIFT] [--stc_axis {X,Y,Z}]
[--anat_template ANAT_TEMPLATE]
[--brain_mask BRAIN_MASK] [--WM_mask WM_MASK]
[--CSF_mask CSF_MASK] [--vascular_mask VASCULAR_MASK]
bids_dir output_dir
positional arguments:
bids_dir The root folder of the BIDS-formated input data directory.
output_dir the output path to drop outputs from major preprocessing steps.
optional arguments:
-h, --help show this help message and exit
--bids_filter BIDS_FILTER
Allows to provide additional BIDS specifications (found within the input BIDS directory)
for selected a subset of functional and/or anatomical images. Takes as input a JSON file
containing the set of parameters for functional image under 'func' and under 'anat' for the
anatomical image. See online documentation for an example.
(default: {'func': {'suffix': ['bold', 'cbv']}, 'anat': {'suffix': ['T1w', 'T2w']}})
--bold_only Apply preprocessing with only EPI scans. Commonspace registration is executed directly using
the corrected EPI 3D reference images. The commonspace registration simultaneously applies
distortion correction. Nativespace is always the original EPI space.
(default: False)
--anat_autobox Crops out extra space around the brain on the structural image using AFNI's 3dAutobox
https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dAutobox.html.
(default: False)
--bold_autobox Crops out extra space around the brain on the EPI image using AFNI's 3dAutobox
https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dAutobox.html.
(default: False)
--oblique2card {none,affine,3dWarp}
Correct for oblique coordinates on all structural and functional data.
WARNING: these corrections are suboptimal, and may alter the data. Only apply if necessary.
affine: only the affine matrix is changed to cardinal axes.
3dWarp: Applies AFNI's 3dWarp -oblique2card. This involves resampling the
data on a new isotropic grid.
(default: none)
--apply_despiking Applies AFNI's 3dDespike https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dDespike.html.
(default: False)
--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)
--log_transform The functional and structural image intensity will be log transformed before registration.
The preprocessed functional timeseries will retain the original intensity values.
This parameter can support registration of fUSI images.
(default: False)
Registration Options:
Customize registration operations and troubleshoot registration failures.
--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'.
* stages: Registration stages for generating the unbiased template.
*** Each stage must be among the following: 'rigid','similarity','affine' or 'nlin' (non-linear). The syntax must follows this example: rigid-affine-nlin.
* 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 must 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.
* winsorize_lower_bound: the lower bound for the antsRegistration winsorize-image-intensities option, useful for fUS images with intensity outliers.
* winsorize_upper_bound: the upper bound for the antsRegistration winsorize-image-intensities option, useful for fUS images with intensity outliers.
(default: apply=false,stages=rigid-affine-nlin,masking=false,brain_extraction=false,keep_mask_after_extract=false,template_registration=SyN,winsorize_lower_bound=0.0,winsorize_upper_bound=1.0)
--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,stages=rigid-affine-nlin,masking=false,brain_extraction=false,keep_mask_after_extract=false,template_registration=SyN,winsorize_lower_bound=0.0,winsorize_upper_bound=1.0)
--commonspace_reg COMMONSPACE_REG
Specify registration options for the commonspace registration.
* stages: Registration stages for generating the unbiased template.
*** Each stage must be among the following: 'rigid','similarity','affine' or 'nlin' (non-linear). The syntax must follows this example: rigid-affine-nlin.
* 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 must 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'.
* winsorize_lower_bound: the lower bound for the antsRegistration winsorize-image-intensities option, useful for fUS images with intensity outliers.
* winsorize_upper_bound: the upper bound for the antsRegistration winsorize-image-intensities option, useful for fUS images with intensity outliers.
(default: stages=rigid-affine-nlin,masking=false,brain_extraction=false,keep_mask_after_extract=false,template_registration=SyN,fast_commonspace=false,winsorize_lower_bound=0.0,winsorize_upper_bound=1.0)
--inherit_unbiased_template INHERIT_UNBIASED_TEMPLATE
Provide a path to a previous RABIES preprocessing output folder to inherit the unbiased template
generated in that previous run, as well as the registration to the external atlas. In place of
conducting unbiased template generation, each scan is registered to this pre-generated template
with registration parameters that are consistent with that of the previous run. The atlas registration
is also inherited, and won't be conducted again.
By selecting this option, the following preprocessing parameters will be overriden to enforce
consistency with the previous run: --anatomical_resampling, --commonspace_reg, --anat_template,
--brain_mask, --WM_mask, --CSF_mask, --vascular_mask
(default: none)
--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 must be selected along the 'masking' option.
*** Specify 'true' or 'false'.
* winsorize_lower_bound: the lower bound for the antsRegistration winsorize-image-intensities option.
* winsorize_upper_bound: the upper bound for the antsRegistration winsorize-image-intensities option.
* 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,keep_mask_after_extract=false,registration=SyN,winsorize_lower_bound=0.0,winsorize_upper_bound=1.0)
Head motion correction options:
Customize the framewise registration carried for head motion correction.
--no_HMC Select this option to turn off the application of head motion correction when generating resampled timeseries.
Head motion parameters are still computed, and remain available for further operations that rely on those parameters.
(default: False)
--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)
--hmc_qc_report HMC_QC_REPORT
This option manages the generation of a quality report on the head motion correction registration step.
The report includes registration error across frames, standard deviation and a video of the
timeseries each before and after applying the correction.
* apply: whether to generate the report or not.
*** Specify 'true' or 'false'.
* fps: frames per second for the video generated.
*** Provide an integer of 1 or above.
(default: apply=false,fps=10)
Resampling Options:
The following options handle resampling to common and/or nativespaces and the resolution for registration.
The resampling syntax for voxel dimensions 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.
--resampling_space {common_only,native_only,both}
Determine whether preprocessed timeseries should be generated in commonspace only ('common_only'),
nativespace only ('native_only'), or for both native and commonspaces ('both'). Generating timeseries
only in the desired space will save memory and computational time.
(default: common_only)
--bold_nativespace Select this option to define nativespace as the original space of the input functional scan, as opposed
to the anatomical space of the structural scan which is by default the nativespace.
The main difference is that distortion correction is no longer carried in the nativespace, which is
the result of registration to the structural scan, but the commonspace still includes distortion correction.
NOTE: --resampling_space must include native space as a desired output, otherwise this parameter has no effect.
Also, if using --bold_only, this parameter has no effect, since there is no anatomical scan in the workflow.
(default: False)
--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)
--anatomical_resampling ANATOMICAL_RESAMPLING
This specifies resampling dimensions for the anatomical registration targets. By
default, images are resampled to isotropic resolution based on the smallest dimension
among the provided anatomical images (EPI images instead if --bold_only is True).
Increasing voxel resampling size will increase registration speed at the cost of
accuracy.
(default: inputs_defined)
STC Options:
Specify Slice Timing Correction (STC) info that is fed to AFNI's 3dTshift
(https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dTshift.html). The STC is applied
in the anterior-posterior orientation, and thus RABIES assumes slices were acquired in
this direction.
--apply_STC Select this option to apply the STC step.
(default: False)
--TR TR Specify repetition time (TR) in seconds. (e.g. --TR 1.2). 'auto' will read the TR from
the nifti header.
(default: auto)
--args_3dTshift ARGS_3DTSHIFT
Specify a string of custom parameters that is fed directly into the 3dTshift CLI.
For correct usage, follow this syntax: --args_3dTshift='-Fourier -tpattern alt-z'.
If -TR is not provided, the TR is read from the Nifti header. Do not provide a -prefix,
as RABIES uses this parameter.
(default: -Fourier -tpattern alt-z)
--stc_axis {X,Y,Z} Can specify over which axis of the image the STC must be applied. Generally, the correction
should be over the Y axis, which corresponds to the anteroposterior axis in RAS convention.
(default: Y)
Commonspace Template Files:
Specify commonspace template and associated mask files. By default, RABIES
provides the mouse DSURQE atlas
https://wiki.mouseimaging.ca/display/MICePub/Mouse+Brain+Atlases.
--anat_template ANAT_TEMPLATE
Anatomical file for the commonspace atlas.
(default: /home/docs/.local/share/rabies/DSURQE_40micron_average.nii.gz)
--brain_mask BRAIN_MASK
Brain mask aligned with the template.
(default: /home/docs/.local/share/rabies/DSURQE_40micron_mask.nii.gz)
--WM_mask WM_MASK (OPTIONAL) White matter mask aligned with the template.
If no input is provided and the default --anat_template is not used,
the core pipeline will run, but downstream functions that rely on
this file will be disabled.
(default: /home/docs/.local/share/rabies/DSURQE_40micron_eroded_WM_mask.nii.gz)
--CSF_mask CSF_MASK (OPTIONAL) CSF mask aligned with the template.
If no input is provided and the default --anat_template is not used,
the core pipeline will run, but downstream functions that rely on
this file will be disabled.
(default: /home/docs/.local/share/rabies/DSURQE_40micron_eroded_CSF_mask.nii.gz)
--vascular_mask VASCULAR_MASK
(OPTIONAL) Can provide a mask of major blood vessels to compute associated nuisance timeseries.
The default mask was generated by applying MELODIC ICA and selecting the resulting
component mapping onto major brain vessels.
If no input is provided and the default --anat_template is not used,
the core pipeline will run, but downstream functions that rely on
this file will be disabled.
(default: /home/docs/.local/share/rabies/vascular_mask.nii.gz)
rabies confound_correction --help
usage: rabies confound_correction [-h] [--nativespace_analysis]
[--resample_to_commonspace]
[--image_scaling {None,global_variance,voxelwise_standardization,grand_mean_scaling,voxelwise_mean}]
[--scale_variance_voxelwise]
[--detrending DETRENDING]
[--nuisance_regressors [{WM_signal,CSF_signal,vascular_signal,global_signal,aCompCor_percent,aCompCor_5,mot_6,mot_24} ...]]
[--conf_list CONF_LIST]
[--frame_censoring FRAME_CENSORING]
[--TR TR] [--highpass HIGHPASS]
[--lowpass LOWPASS]
[--edge_cutoff EDGE_CUTOFF]
[--smoothing_filter SMOOTHING_FILTER]
[--match_number_timepoints]
[--ica_aroma ICA_AROMA] [--read_datasink]
[--timeseries_interval TIMESERIES_INTERVAL]
[--generate_CR_null]
[--slicewise_correction_direction {Off,RL,AP,SI}]
preprocess_out output_dir
positional arguments:
preprocess_out path to RABIES preprocessing output directory.
output_dir path for confound correction output directory.
optional arguments:
-h, --help show this help message and exit
--nativespace_analysis
Conduct confound correction and analysis in native space.
(default: False)
--resample_to_commonspace
If using --nativespace_analysis, use this parameter to also generate cleaned timeseries
resampled to commonspace after denoising is carried in nativespace.
Using this option is necessary to enable group ICA at the analysis stage after using --nativespace_analysis.
(default: False)
--image_scaling {None,global_variance,voxelwise_standardization,grand_mean_scaling,voxelwise_mean}
Select an option for scaling the image variance to match the intensity profile of
different scans and avoid biases in data variance and amplitude estimation during analysis.
The variance explained from confound regression is also scaled accordingly for later use with
--data_diagnosis.
*** None: No scaling is applied, only detrending.
*** global_variance: After applying confound correction, the cleaned timeseries are scaled
according to the total standard deviation of all voxels, to scale total variance to 1.
*** voxelwise_standardization: After applying confound correction, each voxel is separately
scaled to unit variance (z-scoring).
*** grand_mean_scaling: Timeseries are divided by the mean signal across voxel, and
multiplied by 100 to obtain percent BOLD fluctuations.
*** voxelwise_mean: each voxel is seperataly scaled according to its mean intensity,
a method suggested with AFNI https://afni.nimh.nih.gov/afni/community/board/read.php?1,161862,161864.
Timeseries are then multiplied by 100 to obtain percent BOLD fluctuations.
(default: grand_mean_scaling)
--scale_variance_voxelwise
If scaling was not applied voxelwise with voxelwise_standardization or voxelwise_mean, this option
standardize the variance at each voxel to be equal, while preserving to total variance of the
4D timeseries (i.e. voxels have same variance, but not unit variance).
(default: False)
--detrending DETRENDING
Detrend the voxel timeseries.
* order: Specify the polynomial order for detrending as a integer.
*** 0 for no detrending, 1 for linear detrending, 2 for quadratic etc.
* time_interval: the time interval over which the trend is computed.
Follow the syntax from --timeseries_interval to select a subset of frames.
Note the trend is always subtracted from the whole timeseries.
(default: order=1,time_interval=0-end)
--nuisance_regressors [{WM_signal,CSF_signal,vascular_signal,global_signal,aCompCor_percent,aCompCor_5,mot_6,mot_24} ...]
Select list of nuisance regressors that will be removed voxelwise.
*** WM/CSF/vascular/global_signal: correspond to mean signal from WM/CSF/vascular/brain
masks.
*** mot_6: 6 rigid head motion correction parameters.
*** mot_24: mot_6 + their temporal derivative, then all 12 parameters squared, as in
Friston et al. (1996, Magnetic Resonance in Medicine).
*** aCompCor_percent: method from Muschelli et al. (2014, Neuroimage), where component timeseries
are obtained using PCA, conducted on the combined WM and CSF masks voxel timeseries.
Components adding up to 50 percent of the variance are included.
*** aCompCor_5: aCompCor method, but taking 5 first principal components.
(default: [])
--conf_list CONF_LIST
DEPRECATED PARAMETER: This was replaced by --nuisance_regressors, throws an error if any input is provided.
--frame_censoring FRAME_CENSORING
Censor frames that are highly corrupted (i.e. 'scrubbing').
* FD_censoring: Apply frame censoring based on a framewise displacement threshold. The frames
that exceed the given threshold, together with 1 back and 2 forward frames will be masked
out, as in Power et al. (2012, Neuroimage).
*** Specify 'true' or 'false'.
* FD_threshold: the FD threshold in mm.
* DVARS_censoring: Will remove timepoints that present outlier values on the DVARS metric
(temporal derivative of global signal). This method will censor timepoints until the
distribution of DVARS values across time does not contain outliers values above or below 2.5
standard deviations.
*** Specify 'true' or 'false'.
* MSE_censoring: Apply censoring based on the mean square error (MSE) between each frame and
the average EPI (computed as the tri-mean across time voxelwise). Censoring is estimated
automatically through outlier detection as with DVARS_censoring .
This MSE metric is computed on the input preprocessed timeseries before any mean removal or
confound correction, meaning that metric represents changes in raw image contrast across time,
which is equivalent to the registration error computed post-head motion realignment with
--hmc_qc_report, or in other words, MSE captures residual motion or intensity spikes.
MSE can be a effective complement to FD to measure motion that was not well capture by registration.
*** Specify 'true' or 'false'.
* minimum_timepoint: Can set a minimum number of timepoints remaining after frame censoring.
If the threshold is not met, an empty file is generated and the scan is not considered in
further steps.
(default: FD_censoring=false,FD_threshold=0.05,DVARS_censoring=false,MSE_censoring=false,minimum_timepoint=3)
--TR TR Specify repetition time (TR) in seconds. (e.g. --TR 1.2). 'auto' will read the TR from
the nifti header.
(default: auto)
--highpass HIGHPASS Specify highpass filter frequency.
(default: None)
--lowpass LOWPASS Specify lowpass filter frequency.
(default: None)
--edge_cutoff EDGE_CUTOFF
Specify the number of seconds to cut at beginning and end of acquisition if applying a
frequency filter. Highpass filters generate edge effects at begining and end of the
timeseries. We recommend to cut those timepoints (around 30sec at both end for 0.01Hz
highpass.).
(default: 0)
--smoothing_filter SMOOTHING_FILTER
Specify filter size in mm for spatial smoothing. Will apply nilearn's function
https://nilearn.github.io/modules/generated/nilearn.image.smooth_img.html
(default: None)
--match_number_timepoints
With this option, only a subset of the timepoints are kept post-censoring to match the
--minimum_timepoint number for all scans. This can be conducted to avoid inconsistent
temporal degrees of freedom (tDOF) between scans during downstream analysis. We recommend
selecting this option if a significant confounding effect of tDOF is detected during --data_diagnosis.
The extra timepoints removed are randomly selected among the set available post-censoring.
(default: False)
--ica_aroma ICA_AROMA
Apply ICA-AROMA denoising (Pruim et al. 2015). The original classifier was modified to incorporate
rodent-adapted masks and classification hyperparameters.
* apply: apply the denoising.
*** Specify 'true' or 'false'.
* dim: Specify a pre-determined number of MELODIC components to derive. '0' will use an automatic
estimator.
* random_seed: For reproducibility, this option sets a fixed random seed for MELODIC.
(default: apply=false,dim=0,random_seed=1)
--read_datasink
Choose this option to read preprocessing outputs from datasinks instead of the saved
preprocessing workflow graph. This allows to run confound correction without having
available RABIES preprocessing folders, but the targetted datasink folders must follow the
structure of RABIES preprocessing.
(default: False)
--timeseries_interval TIMESERIES_INTERVAL
Before confound correction, can crop the timeseries within a specific interval.
e.g. '0-80' for timepoint 0 to 80. 0 is the first time frame, and 'end' stands for
the last time frame.
(default: 0-end)
--generate_CR_null Estimate overfitting from confound regression by generating phase randomised regressors,
following the method by Bright and Murphy (2015), NeuroImage. By selecting this option,
an additional figure will be generated to display the variance explained by the real
regressors VS the randomized regressors to assess overfitting.
(default: False)
--slicewise_correction_direction {Off,RL,AP,SI}
By inputing a slice direction with this parameters, the computation of nuisance signals,
nuisance regression, and smoothing, are all conducted on each 2D slice independently along
the provided slice direction.
This strategy can be useful in the presence of artefacts (e.g. intensity spikes) that are
not shared across slices due to time delays between slice acquisition, in which case a slicewise
nuisance regression may perform better. Otherwise, in the case of images with spatial gaps
between slices, smoothing should be applied slicewise using this parameter.
To apply slicewise correction, provide as input one of the RAS axial direction for slice
selection, i.e. this parameter takes as input one of: 'RL', 'AP' or 'SI'.
For accurate slice selection, the axial directions of the input nifti images must be properly
encoded. If no direction is provided, standard whole-brain correction is conducted.
(default: Off)
rabies analysis --help
usage: rabies analysis [-h] [--resample_to_commonspace]
[--prior_maps PRIOR_MAPS]
[--prior_bold_idx [PRIOR_BOLD_IDX ...]]
[--prior_confound_idx [PRIOR_CONFOUND_IDX ...]]
[--data_diagnosis] [--group_avg_prior]
[--scan_QC_thresholds SCAN_QC_THRESHOLDS]
[--outlier_threshold OUTLIER_THRESHOLD] [--extended_QC]
[--seed_list [SEED_LIST ...]]
[--seed_prior_list [SEED_PRIOR_LIST ...]]
[--plot_seed_frequencies PLOT_SEED_FREQUENCIES]
[--FC_matrix] [--ROI_labels_file ROI_LABELS_FILE]
[--ROI_type {parcellated,voxelwise}]
[--group_ica GROUP_ICA] [--DR_ICA]
[--NPR_temporal_comp NPR_TEMPORAL_COMP]
[--NPR_spatial_comp NPR_SPATIAL_COMP]
[--optimize_NPR OPTIMIZE_NPR]
[--network_weighting {absolute,relative}]
[--brainmap_percent_threshold BRAINMAP_PERCENT_THRESHOLD]
[--qc_smooth_maps]
confound_correction_out output_dir
positional arguments:
confound_correction_out
path to RABIES confound correction output directory.
output_dir path for analysis outputs.
optional arguments:
-h, --help show this help message and exit
--resample_to_commonspace
If the input cleaned timeseries are in nativespace, meaning that connectivity is computed in nativespace,
this option will resample analysis outputs into commonspace (both nativespace and commonspace versions
are thus generated).
(default: False)
--prior_maps PRIOR_MAPS
Provide a 4D nifti image with a series of spatial priors representing common sources of
signal (e.g. ICA components from a group-ICA run). This 4D prior map file will be used for
Dual regression, Dual ICA and --data_diagnosis. The RABIES default corresponds to a MELODIC
run on a combined group of anesthetized-ventilated and awake mice. Confound correction
consisted of highpass at 0.01 Hz, FD censoring at 0.03mm, DVARS censoring, and
mot_6,WM_signal,CSF_signal as regressors.
(default: /home/docs/.local/share/rabies/melodic_IC.nii.gz)
--prior_bold_idx [PRIOR_BOLD_IDX ...]
Specify the indices for the priors corresponding to BOLD sources of interest from --prior_maps.
This will determine the set of networks analyzed for --data_diagnosis.
IMPORTANT: index counting starts at 0 (i.e. the first component is selected with 0, not 1)
SYNTAX: Note that the syntax should follow the example of '--prior_bold_idx 5 12 19', and not
'--prior_bold_idx [5, 12, 19]'.
(default: [5, 12, 19])
--prior_confound_idx [PRIOR_CONFOUND_IDX ...]
Specify the indices for the confound components from --prior_maps. This is pertinent for
evaluating features in the --data_diagnosis outputs.
IMPORTANT: index counting starts at 0 (i.e. the first component is selected with 0, not 1)
SYNTAX: Note that the syntax should follow the example of '--prior_bold_idx 5 12 19', and not
'--prior_bold_idx [5, 12, 19]'.
(default: [0, 2, 6, 7, 8, 9, 10, 11, 13, 14, 21, 22, 24, 26, 28, 29])
--data_diagnosis Generates a set of data quality assessment reports as described in Desrosiers-Gregoire et al. 2024.
These reports aim to support interpreting connectivity results and account for data quality issues,
and include: 1) a scan-level qualitative diagnosis report, 2) a quantitative distribution report, 3) a
group-level statistical report for network analysis.
Note that all brain maps are displayed in commonspace, and analysis outputs in nativespace are thus
first resampled before plotting.
(default: False)
--group_avg_prior Select this option to use the group average (the median across subject) as a reference prior network map
instead of providing an external image. This option will circumvent --seed_prior_list, and the ICA
components selected with --prior_bold_idx won't be used for computing Dice overlap measures during QC.
(default: False)
--scan_QC_thresholds SCAN_QC_THRESHOLDS
Option to specify scan-level thresholds to remove scans from the dataset QC report.
This can be specified for a given set of network analyses among DR (dual regression), SBC (seed
connectivity), or NPR. For each analysis, the following QC parameters can be specified:
* Dice: Threshold for the minimum network detectability computed as Dice overlap with the prior.
*** Specify a list of thresholds between 0 and 1. The order of thresholds provided within the list
will be matched to the list of networks for the corresponding analysis (for DR/NPR, this
will be matched to the --prior_bold_idx list, and for SBC it will be matched to --seed_list).
If the list is empty, no thresholding is applied, otherwise, the length of the lists for the
thresholds and networks must match.
* Conf: Threshold for the maximum temporal correlation with DR confound timecourses.
*** Specify a list of thresholds between 0 and 1. The same rules as Dice are followed for specifying
the order of thresholds within the list.
* Amp: Whether to automatically remove outliers from the network amplitude measure.
*** Specify 'true' or 'false'.
The expression for the parameters must follow a dictionary syntax, as with this example:
'{DR:{Dice:[0.3],Conf:[0.25],Amp:false},SBC:{Dice:[0.3]}}'.
Note that the expression must be written within ' '.
(default: {})
--outlier_threshold OUTLIER_THRESHOLD
The modified Z-score threshold for detecting outliers during dataset QC when using
--data_diagnosis. The default of 3.5 is recommended in https://www.itl.nist.gov/div898/handbook/eda/section3/eda35h.htm.
(default: 3.5)
--extended_QC Select this option to output the network correlation with the original image intensity (calculated
during detrending) and the BOLDsd (signal variability). These two additional features allow to
further inspect potential issues of signal amplitude scaling between scans. However, it is unclear
whether signal of interest (i.e. neural metabolism) contribute to each measure, so these outputs should
be interpreted with caution.
(default: False)
--seed_list [SEED_LIST ...]
This parameter manages the list of anatomical seeds for seed-based connectivity (e.g. --seed_list seed1 seed2 ...).
A connectivity map is computed for each seed using pearson correlation with the mean seed timecourse across voxels.
The following list of pre-downloaded seeds can be selected with the following syntax: ACA_seed,
ECT_AI_seed, HY_seed, ORB_limbic_seed, SS_frontal_seed, AMYG_seed, RSP_seed, THAL_seed,
basal_ganglia_seed, HIP_seed, MO_seed, SS_dorsal_seed, VIS_seed.
These seeds are accessible online https://zenodo.org/records/18611133/files/DSURQE_seeds.zip,
were manually drawn on the left hemisphere of the DSURQE template and uses terminology from the
Allen brain parcellation (see info_seeds.txt).
Alternatively, it is possible to provide the path to an external Nifti file corresponding to a binary mask
highlighting a seed region, but this image must overlap with the template provided with --anat_template.
(default: [])
--seed_prior_list [SEED_PRIOR_LIST ...]
For analysis QC of seed-based FC during --data_diagnosis, prior network maps are required for
each seed provided in --seed_list. Provide the list of prior files in matching order of the
--seed_list arguments to match corresponding seed maps.
(default: [])
--plot_seed_frequencies PLOT_SEED_FREQUENCIES
With this option it is possible to plot the frequency spectrum of specific seed timecourses obtained from
--seed_list in the --data_diagnosis report.
The input must follow this example syntax SS=0,ACA=1, which defines a set of seed_name=seed_index (e.g. SS=0)
pairs, where the seed name will be used for plotting in the legend and the seed index (starting from 0) will
select the associated seed from --seed_list based on the order of seed provided.
(default: )
--FC_matrix Compute whole-brain connectivity matrices using Pearson's r between ROI timeseries.
(default: False)
--ROI_labels_file ROI_LABELS_FILE
Labels file providing the anatomical parcellation for --FC_matrix.
The nifti file must overlap with the --anat_template file from preprocessing.
By default, RABIES uses the DSURQE atlas if using the default template.
The parcellation includes 356 ROIs, and label annotations are documented in
https://github.com/CoBrALab/RABIES/releases/download/0.5.1/DSURQE_40micron_R_mapping.csv.
(default: /home/docs/.local/share/rabies/DSURQE_40micron_labels.nii.gz)
--ROI_type {parcellated,voxelwise}
Define ROIs for --FC_matrix between 'parcellated' from the provided atlas during preprocessing,
or 'voxelwise' to derive the correlations between every voxel.
(default: parcellated)
--group_ica GROUP_ICA
Perform group-ICA using FSL's MELODIC on the whole dataset's cleaned timeseries.
Note that confound correction must have been conducted on commonspace outputs.
* apply: compute group-ICA.
*** Specify 'true' or 'false'.
* dim: Specify a pre-determined number of MELODIC components to derive. '0' will use an automatic
estimator.
* random_seed: For reproducibility, this option sets a fixed random seed for MELODIC.
* disableMigp: Whether to disable the MIGP method for lowering the memory load of data concatenation.
(default: apply=false,dim=0,random_seed=1,disableMigp=false)
--DR_ICA Conduct dual regression on each subject timeseries, using the priors from --prior_maps. The
linear coefficients from both the first and second regressions will be provided as outputs.
Requires that confound correction was conducted on commonspace outputs.
(default: False)
--NPR_temporal_comp NPR_TEMPORAL_COMP
Option for performing Neural Prior Recovery (NPR). Specify with this option how many extra
subject-specific sources will be computed to account for non-prior confounds. This options
specifies the number of temporal components to compute. After computing
these sources, NPR will provide a fit for each prior in --prior_maps indexed by --prior_bold_idx.
Specify at least 0 extra sources to run NPR.
(default: -1)
--NPR_spatial_comp NPR_SPATIAL_COMP
Same as --NPR_temporal_comp, but specify how many spatial components to compute (which are
additioned to the temporal components).
(default: -1)
--optimize_NPR OPTIMIZE_NPR
This option handles the automated dimensionality estimation when carrying out NPR. NPR will be
carried out iteratively while incrementing the number of non-prior components fitted, until
convergence criteria are met (see below). A convergence report is generated to visualize the
results across iterations.
Convergence criterion 1: Iterations continue until the correlation between the fitted component
and the prior does not reach the specified minimum.
Convergence Criterion 2: At each iteration, the difference between the previous and new output
is evaluated (0=perfectly correlated; 1=uncorrelated). The forming set of successive iterations
(within a certain window length) is evaluated, and when a set respects the convergence threshold
for each iteration within the window, the iteration preceding that window is selected as optimal
output. We take the iteration preceding the window, as this corresponds to the last iteration
which generated changes above threshold. The sliding-window approach is employed to prevent
falling within a local minima, when further ameliorations may be possible with further iterations.
When multiple priors are fitted, they are all simultaneously subjected to the evaluation of
convergence, and as long as one prior fit does not meet the thresholds, iterations continue.
* apply: select 'true' to apply this option. If selected, this option overrides --NPR_spatial_comp
and --NPR_spatial_comp.
*** Specify 'true' or 'false'.
* window_size: Window size for criterion 2.
*** Must provide an integer.
* min_prior_corr: Threshold for criterion 1.
*** Must provide a float.
* diff_thresh: Threshold for criterion 2.
*** Must provide a float.
* max_iter: Maximum number of iterations.
*** Must provide an integer.
* compute_max: select 'true' to visualize all iterations until max_iter in the report.
*** Specify 'true' or 'false'.
(default: apply=false,window_size=5,min_prior_corr=0.5,diff_thresh=0.03,max_iter=20,compute_max=false)
--network_weighting {absolute,relative}
Whether to derive absolute or relative (variance-normalized) network maps, representing
respectively network amplitude + shape or network shape only. This option applies to both
dual regression (DR) and Neural Prior Recovery (NPR) analyses.
(default: absolute)
--brainmap_percent_threshold BRAINMAP_PERCENT_THRESHOLD
Specify the percentage of voxels with highest intensity included when thresholding brain maps
(e.g. an input of 10 means that the top 10 percent of voxels with highest values are included).
This is used within --data_diagnosis for plotting brain maps and computing Dice overlap coefficients.
(default: 10)
--qc_smooth_maps Whether to apply 0.3mm smoothing on each brain map prior to QC calculation (e.g. Dice overlap).
This may be useful for reducing the impact of background noise on estimates of network specificity,
and improve comparability across datasets from different scanning protocols/setups.
This was always ON for RABIES version <0.6.
(default: False)
Example execution syntax
The following section provides examples describing the basic syntax for running the RABIES command line interface.
preprocess
rabies -p MultiProc preprocess input_BIDS/ preprocess_outputs/ --apply_STC --TR 1.2 --commonspace_reg masking=true,brain_extraction=false,template_registration=SyN,fast_commonspace=false
First, we have to preprocess the dataset before it can be analyzed. In this example, we are running the RABIES preprocessing on the dataset found in the input_BIDS/ folder, formatted according to the BIDS standard, and the outputs from RABIES are stored in the preprocess_outputs/ folder. Additional execution parameters were specified:
-p MultiProcwill execute the pipeline in parallel using the local threads available. Notice that this parameter is specified before the processing stage, because it is one of theExecution Optionsaffiliated to therabies --help.--apply_STCis a boolean variable which, when selected, will apply slice timing correction during preprocessing, which is not applied by default in RABIES.--TR 1.2specifies the repetition time (TR) of the fMRI images that are processed, which must be defined to apply slice timing correction appropriately. Notice that this parameter must be provided with an argument, here1.2for TR = 1.2sec, and this is done by writing down the argument with a space dividing the associated parameter.--commonspace_reg masking=true,brain_extraction=false,template_registration=SyN,fast_commonspace=falsethis argument manages the options for the commonspace registration step. Some arguments, including--commonspace_reg, take multiple parameters as input, where each parameter-value pairs follow the syntax ofparameter=value. In this case, we are using the masking optino withmasking=true, which use available brain masks from inhomogeneity correction to drive the registration operations, and we specify a non-linear registration to the commonspace template withtemplate_registration=SyN.
confound_correction
rabies -p MultiProc confound_correction preprocess_outputs/ confound_correction_outputs/ --nuisance_regressors WM_signal CSF_signal vascular_signal mot_6 --smoothing_filter 0.3
Next, after completing preprocessing, in most cases the data should be corrected for potential confounds prior to analysis. This is done in the confound correction stage, where confounds are modelled and regressed from the data. In this example we correct the preprocessed data found in the preprocess_outputs/ folder and store the cleaned outputs in the confound_correction_outputs/ folder. Among the range of options available for confound correction, we define in this example three parameters:
--nuisance_regressorsis the option to regress nuisance timeseries from the data, i.e., confound regression. This parameter takes a list as input, where each argument in the list is seperated by a space as followWM_signal CSF_signal mot_6. This list defines which nuisance timeseries are going to model confounds during confound regression, in this case, the WM and CSF mean signals together with the 6 rigid realignment parameters from head motion realignment.--smoothing_filterwill additionally apply Gaussian spatial smoothing, where in this case, a filter size of0.3mm is specified.
analysis
rabies -p MultiProc analysis confound_correction_outputs analysis_outputs/ --group_ica apply=true,dim=30,random_seed=1
Finally, after conducting preprocessing and confound correction, certain analyses can be run within RABIES. In this case, the cleaned outputs found in confound_correction_outputs/ are going to be analyzed, with analysis outputs found in analysis_outputs/. We perform a group independent component analysis (ICA) with 30 components by providing --group_ica apply=true,dim=30,random_seed=1 to the command.
Execution syntax with containerized installation (Apptainer and Docker)
Containers are independent computing environments which have their own dependencies installed to ensure consistent and reliable
execution of the software across computing platforms. The main difference in execution syntax when running a container, as opposed to the examples above, is that the paths between the local environment where the data is stored must be ‘linked’ to the container’s internal paths. All relevant directories containing data that will be used by RABIES must be related to a container internal path, and this is done using -B for Apptainer and -v for Docker. See below for examples:
Apptainer execution
preprocess
apptainer run -B $PWD/input_BIDS:/input_BIDS:ro \
-B $PWD/preprocess_outputs:/preprocess_outputs/ \
/path_to_apptainer_image/rabies.sif -p MultiProc preprocess /input_BIDS/ /preprocess_outputs/ --apply_STC --TR 1.2 --commonspace_reg masking=true,brain_extraction=false,template_registration=SyN,fast_commonspace=false
Apptainer containers are stored in image files, for instance rabies.sif. apptainer run /path_to_apptainer_image/rabies.sif will execute the image, in this case the RABIES pipeline, and the same rules for the command line interface then apply as previously demonstrated. However, the container must gain access to the relevant folders for running RABIES, in this case an input folder and an output folder, and this is done with -B:
-B $PWD/input_BIDS:/input_BIDS:ro: this argument relates the BIDS input folder found in$PWD/input_BIDSto an internal path to the container, which we call/input_BIDS. The inputs are thus accessed according to this path in the RABIES arguments with/input_BIDS/. the:romeans that the container is only provided reading permissions at this location.-B $PWD/preprocess_outputs:/preprocess_outputs/: same as with the/input_BIDS/, but now we are relating a desired output directory$PWD/preprocess_outputsto/preprocess_outputs, and the container has writing permissions at this path since:rois not present.
confound_correction
apptainer run -B $PWD/input_BIDS:/input_BIDS:ro \
-B $PWD/preprocess_outputs:/preprocess_outputs/ \
-B $PWD/confound_correction_outputs:/confound_correction_outputs/ \
/path_to_apptainer_image/rabies.sif -p MultiProc confound_correction /preprocess_outputs/ /confound_correction_outputs/ --nuisance_regressors WM_signal CSF_signal vascular_signal mot_6 --smoothing_filter 0.3
The required paths are similarly provided for the confound correction stage. Note here that the path to $PWD/input_BIDS is still linked to the container, even though it is not explicitely part of the arguments during the confound correction call. This is necessary since the paths used in the preprocessing steps still need to be accessed at later stages, and there will be an error if the paths are not kept consistent across processing steps.
analysis
apptainer run -B $PWD/input_BIDS:/input_BIDS:ro \
-B $PWD/preprocess_outputs:/preprocess_outputs/ \
-B $PWD/confound_correction_outputs:/confound_correction_outputs/ \
-B $PWD/analysis_outputs:/analysis_outputs/ \
/path_to_apptainer_image/rabies.sif -p MultiProc analysis /confound_correction_outputs /analysis_outputs/ --group_ica apply=true,dim=30,random_seed=1
The same logic applies at the analysis stage.
Docker execution
docker run -it --rm --user $(id -u) \
-v $PWD/input_BIDS:/input_BIDS:ro \
-v $PWD/preprocess_outputs:/preprocess_outputs/ \
gabdesgreg/rabies:tagname -p MultiProc preprocess /input_BIDS/ /preprocess_outputs/ --apply_STC --TR 1.2 --commonspace_reg masking=true,brain_extraction=false,template_registration=SyN,fast_commonspace=false
The syntax in Docker is very similar to Apptainer, except that -B is replaced by -v, and further parameters may be needed (e.g. -it, --rm). --user $(id -u) can be added to mitigate writing permission issues when using Docker. Note that ‘tagname’ should be replaced by the proper RABIES version you are using (e.g. 0.4.8).
Additional Resources
Workshop and tutorial for RABIES:
Hands-on tutorial on RABIES (originally developed for and presented at the INCF Neuroinformatics Assembly 2023).
A workshop providing a complete software overview was recorded and posted online on February 2023.
Conversion from Bruker raw to Nifti formats can be handled with BrkRaw (consult associated documentation from the CoBrALab)
CoBrALab recommendations for using compute canada.