rabies 0.3.1

RABIES: Rodent Automated Bold Improvement of EPI Sequences.

RABIES: Rodent Automated Bold Improvement of EPI Sequences.

Installation

The software is available on PyPi https://pypi.org/project/rabies/. You can install it on your local python environment with pip install rabies.

For general uses, we recommend instead using a containerized installation with Singularity (https://singularity.lbl.gov) or Docker (https://www.docker.com), which will contain all additional dependencies from dependencies.txt and ensure reproducible behavior. See https://hub.docker.com/repository/docker/gabdesgreg/rabies/general for available versions.

• Install Singularity .sif image singularity build rabies.sif docker://gabdesgreg/rabies:tagname
• Install Docker image: docker pull gabdesgreg/rabies:tagname

Command Line Interface (CLI)

The following section describes the --help outputs from the command line interface

General CLI

Click to expand

usage: rabies [-h] [-p {Linear,MultiProc,SGE,SGEGraph,PBS,LSF,SLURM,SLURMGraph}] [--local_threads LOCAL_THREADS] [--scale_min_memory SCALE_MIN_MEMORY] [--min_proc MIN_PROC] Processing step ...

RABIES performs processing of rodent fMRI images. Can either run on datasets that only contain EPI images, or both structural and EPI images.

optional arguments:
  -h, --help            show this help message and exit

Commands:
  The RABIES workflow is seperated into three different processing steps: preprocessing, confound regression and analysis. Outputs from the preprocessing provides the inputs for the subsequent
  confound regression, and finally analysis.

  Processing step       Description
    preprocess          Conducts preprocessing on an input dataset in BIDS format. Preprocessing includes realignment for motion, correction for susceptibility distortions through non-linear
                        registration, registration to a commonspace atlas and associated masks, evaluation of confounding timecourses, and includes various execution options (see --help).
    confound_regression
                        Flexible options for confound regression are available to apply directly on preprocessing outputs from RABIES. After linear detrending, only selected options are applied
                        sequentially in following the order: 1) ICA-AROMA, 2) highpass/lowpass filtering, 3) frame censoring (from FD/DVARS measures), 4) regression of confound timeseries, 5)
                        standardization of timeseries, and 6) spatial smoothing.
    analysis            A few built-in resting-state functional connectivity (FC) analysis options are provided to conduct rapid analysis on the cleaned timeseries. Options include seed-based FC, whole-
                        brain correlation FC matrix, group-ICA, dual regression and dual ICA.
    data_diagnosis      This workflow executes an automated set of scan-level followed by a group-level analyses which allow to establish the influence of confounding sources on FC measures. Scan-level
                        analysis outputs a spatio-temporal diagnosis allowing the combined visualization of key temporal and spatial features to identify artefacts corrupting neural sources of signal.
                        Group-level diagnosis consists of the cross-subject correlation between spatial features, to control persisting corruption of neural measures at the group level. We recommend to
                        conduct a data diagnosis from this workflow to complement FC analysis by evaluating the intrinsic corruption of the dataset as well as the effectiveness of the confound
                        correction strategies.

Options for managing the execution of the workflow.:
  -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 local MultiProc execution, set the maximum number of processors run in parallel, defaults to number of CPUs. This option only applies to the MultiProc execution plugin,
                        otherwise it is set to 1. (default: 12)
  --scale_min_memory SCALE_MIN_MEMORY
                        For a parallel execution with MultiProc, the minimal memory attributed to nodes can be scaled with this multiplier to avoid memory crashes. (default: 1.0)
  --min_proc MIN_PROC   For SGE parallel processing, specify the minimal number of nodes to be assigned to avoid memory crashes. (default: 1)

Preprocessing CLI

Click to expand

usage: rabies preprocess [-h] [-e] [--bold_bias_cor_method {otsu_reg,thresh_reg,mouse-preprocessing-v5.sh,disable}] [--anat_bias_cor_method {otsu_reg,thresh_reg,mouse-preprocessing-v5.sh,disable}]
                         [--apply_despiking] [--HMC_option {intraSubjectBOLD,0,1,2,3}] [--apply_slice_mc] [--detect_dummy] [--data_type {int16,int32,float32,float64}] [--debug]
                         [--coreg_script COREG_SCRIPT] [--template_reg_script TEMPLATE_REG_SCRIPT] [--fast_commonspace] [--nativespace_resampling NATIVESPACE_RESAMPLING]
                         [--commonspace_resampling COMMONSPACE_RESAMPLING] [--anatomical_resampling ANATOMICAL_RESAMPLING] [--cluster_type {local,sge,pbs,slurm}] [--walltime WALLTIME] [--TR TR]
                         [--no_STC] [--tpattern {alt,seq}] [--anat_template ANAT_TEMPLATE] [--brain_mask BRAIN_MASK] [--WM_mask WM_MASK] [--CSF_mask CSF_MASK] [--vascular_mask VASCULAR_MASK]
                         [--labels LABELS]
                         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
  -e, --bold_only       Apply preprocessing with only EPI scans. Commonspace registration is executed directly using the denoised EPI 3D reference images. The commonspace registration simultaneously
                        applies distortion correction, so only commonspace outputs are provided with this option. (default: False)
  --bold_bias_cor_method {otsu_reg,thresh_reg,mouse-preprocessing-v5.sh,disable}
                        Choose the algorithm for bias field correction of the EPI before registration. Each algorithm consists of 1) initial denoising, 2) registration to the masked anatomical reference
                        3) use the mask to enhance bias field correction to provide the final corrected image. 'mouse-preprocessing-v5.sh' from https://github.com/CoBrALab/minc-toolkit-extras has been
                        extensively validated on anatomical images across spaces, and uses an Affine registration. 'otsu_reg' uses a otsu masking approach to support bias field correction together with
                        a Rigid registration. 'thresh_reg' uses a simple threshold masking approach to support bias field correction together with a Rigid registration. (default: mouse-
                        preprocessing-v5.sh)
  --anat_bias_cor_method {otsu_reg,thresh_reg,mouse-preprocessing-v5.sh,disable}
                        Same as --bold_bias_cor_method but for the anatomical image. (default: mouse-preprocessing-v5.sh)
  --apply_despiking     Applies AFNI's 3dDespike https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dDespike.html. (default: False)
  --HMC_option {intraSubjectBOLD,0,1,2,3}
                        Select an option for head motion realignment among the pre-built options from https://github.com/ANTsX/ANTsR/blob/master/R/ants_motion_estimation.R. (default: intraSubjectBOLD)
  --apply_slice_mc      Whether to apply a slice-specific motion correction after initial volumetric HMC. This can correct for interslice misalignment resulting from within-TR motion. With this option,
                        motion corrections and the subsequent resampling from registration are applied sequentially, since the 2D slice registrations cannot be concatenate with 3D transforms. (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)
  --data_type {int16,int32,float32,float64}
                        Specify data format outputs to control for file size. (default: float32)
  --debug               Run in debug mode. (default: False)

        Options for the registration steps.
        Built-in options include 'Rigid', 'Affine', 'SyN' (non-linear), 'light_SyN', 'heavy_SyN' and 'multiRAT'.
        A custom registration script can be provided instead following the template script structure
        from other registration scripts (see RABIES/scripts/preprocess_scripts/ for template).
        :
  --coreg_script COREG_SCRIPT
                        Specify EPI to anat coregistration script. (default: SyN)
  --template_reg_script TEMPLATE_REG_SCRIPT
                        Registration script that will be used for registration of the generated dataset template to the provided commonspace atlas for masking and labeling. (default: SyN)
  --fast_commonspace    This option will skip the generation of a dataset template from https://github.com/CoBrALab/twolevel_ants_dbm. Instead each anatomical scan will be individually registered to the
                        commonspace template using the --template_reg_script. Note that this option, although faster, is expected to reduce the quality of commonspace registration. (default: False)

        Options for the resampling of the EPI.
        Axis resampling specifications must follow the format 'dim1xdim2xdim3' (in mm) with the RAS axis
        convention (dim1=Right-Left, dim2=Anterior-Posterior, dim3=Superior-Inferior).
        The original dimensions are conserved if 'inputs_defined' is specified.
        :
  --nativespace_resampling NATIVESPACE_RESAMPLING
                        Can specify a resampling dimension for the nativespace outputs. (default: inputs_defined)
  --commonspace_resampling COMMONSPACE_RESAMPLING
                        Can specify a resampling dimension for the commonspace outputs. (default: inputs_defined)
  --anatomical_resampling ANATOMICAL_RESAMPLING
                        To optimize the efficiency of registration, the provided anatomical template is resampled based on the provided input images. The smallest dimension among the anatomical images
                        (EPI images instead if --bold_only is True) defines the isotropic resolution for resampling. Alternatively, resampling dimension can be specified. (default: inputs_defined)

        Cluster options for running twolevel_dbm.py.
        :
  --cluster_type {local,sge,pbs,slurm}
                        Choose the type of cluster system to submit jobs to (default: local)
  --walltime WALLTIME   Option for job submission specifying requested time per pairwise registration. (default: 20:00:00)

        Specify Slice Timing Correction info that is fed to AFNI 3dTshift
        (https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dTshift.html). The STC is applied in the
        anterior-posterior orientation, assuming slices were acquired in this direction.
        :
  --TR TR               Specify repetition time (TR) in seconds. (default: 1.0s)
  --no_STC              Select this option to ignore the STC step. (default: False)
  --tpattern {alt,seq}  Specify if interleaved or sequential acquisition. 'alt' for interleaved, 'seq' for sequential. (default: alt)

        Specify commonspace template and associated mask/label files.
        A mouse atlas is provided as default https://wiki.mouseimaging.ca/display/MICePub/Mouse+Brain+Atlases.
        :
  --anat_template ANAT_TEMPLATE
                        Anatomical file for the commonspace template. (default: /home/gabriel/.local/share/rabies/DSURQE_40micron_average.nii.gz)
  --brain_mask BRAIN_MASK
                        Brain mask for the template. (default: /home/gabriel/.local/share/rabies/DSURQE_40micron_mask.nii.gz)
  --WM_mask WM_MASK     White matter mask for the template. (default: /home/gabriel/.local/share/rabies/DSURQE_40micron_eroded_WM_mask.nii.gz)
  --CSF_mask CSF_MASK   CSF mask for the template. (default: /home/gabriel/.local/share/rabies/DSURQE_40micron_eroded_CSF_mask.nii.gz)
  --vascular_mask VASCULAR_MASK
                        Can provide a mask of major blood vessels for computing confound timeseries. The default mask was generated by applying MELODIC ICA and selecting the resulting component mapping
                        onto major veins. (default: /home/gabriel/.local/share/rabies/vascular_mask.nii.gz)
  --labels LABELS       Atlas file with anatomical labels. (default: /home/gabriel/.local/share/rabies/DSURQE_40micron_labels.nii.gz)

Confound Regression CLI

Click to expand

usage: rabies confound_regression [-h] [--output_name OUTPUT_NAME] [--commonspace_bold] [--TR TR] [--highpass HIGHPASS] [--lowpass LOWPASS] [--smoothing_filter SMOOTHING_FILTER] [--run_aroma]
                                  [--aroma_dim AROMA_DIM] [--conf_list [{WM_signal,CSF_signal,vascular_signal,global_signal,aCompCor,mot_6,mot_24,mean_FD} ...]] [--FD_censoring]
                                  [--FD_threshold FD_THRESHOLD] [--DVARS_censoring] [--minimum_timepoint MINIMUM_TIMEPOINT] [--standardize] [--timeseries_interval TIMESERIES_INTERVAL]
                                  preprocess_out output_dir

positional arguments:
  preprocess_out        path to RABIES preprocessing output directory with the datasinks.
  output_dir            path to drop confound regression output datasink.

optional arguments:
  -h, --help            show this help message and exit
  --output_name OUTPUT_NAME
                        Creates a new output folder to store the workflow of this CR run, to avoid potential overlaps with previous runs (can be useful if investigating multiple strategies). (default:
                        confound_regression_wf)
  --commonspace_bold    If should run confound regression on the commonspace bold output. (default: False)
  --TR TR               Specify repetition time (TR) in seconds. (default: 1.0s)
  --highpass HIGHPASS   Specify highpass filter frequency. (default: None)
  --lowpass LOWPASS     Specify lowpass filter frequency. (default: None)
  --smoothing_filter SMOOTHING_FILTER
                        Specify spatial smoothing filter size in mm. Uses nilearn's function https://nilearn.github.io/modules/generated/nilearn.image.smooth_img.html (default: None)
  --run_aroma           Whether to run ICA-AROMA or not. The classifier implemented within RABIES is a slightly modified version from the original (Pruim et al. 2015), with parameters and masks adapted
                        for rodent images. (default: False)
  --aroma_dim AROMA_DIM
                        Can specify a fixed number of dimension for the MELODIC run before ICA-AROMA. (default: 0)
  --conf_list [{WM_signal,CSF_signal,vascular_signal,global_signal,aCompCor,mot_6,mot_24,mean_FD} ...]
                        List of nuisance regressors that will be applied on voxel timeseries. WM/CSF/vascular/global_signal: correspond to mean signal from WM/CSF/vascular/brain masks. mot_6: 6 rigid
                        HMC parameters. mot_24: mot_6 + their temporal derivative, and all 12 parameters squared (Friston et al. 1996). aCompCor: corresponds to the timeseries of components from a PCA
                        conducted on the combined WM and CSF masks voxel timeseries, including all components that together explain 50/100 of the variance, as in Muschelli et al. 2014. mean_FD: the mean
                        framewise displacement timecourse (default: [])
  --FD_censoring        Whether to remove timepoints that exceed a framewise displacement threshold. The frames that exceed the given threshold together with 1 back and 4 forward frames will be masked
                        out (based on Power et al. 2012). (default: False)
  --FD_threshold FD_THRESHOLD
                        Scrubbing threshold for the mean framewise displacement in mm (averaged across the brain mask) to select corrupted volumes. (default: 0.05)
  --DVARS_censoring     Whether to remove timepoints that present outlier values on the DVARS metric (temporal derivative of global signal). This will censor out timepoints until a distribution of DVARS
                        values is obtained without outliers values above or below 2.5 standard deviations. (default: False)
  --minimum_timepoint MINIMUM_TIMEPOINT
                        Can select a threshold number of timepoint to remain after censoring, and return empty files for scans that don't pass threshold. (default: 3)
  --standardize         Whether to standardize timeseries to unit variance. (default: False)
  --timeseries_interval TIMESERIES_INTERVAL
                        Specify a time interval in the timeseries to keep. e.g. "0,80". By default all timeseries are kept. (default: all)

Analysis CLI

Click to expand

usage: rabies analysis [-h] [--output_name OUTPUT_NAME] [--scan_list [SCAN_LIST ...]] [--seed_list [SEED_LIST ...]] [--FC_matrix] [--ROI_type {parcellated,voxelwise}] [--group_ICA] [--TR TR] [--dim DIM]
                       [--DR_ICA] [--IC_file IC_FILE] [--dual_ICA DUAL_ICA] [--prior_maps PRIOR_MAPS] [--prior_bold_idx [PRIOR_BOLD_IDX ...]]
                       confound_regression_out output_dir

positional arguments:
  confound_regression_out
                        path to RABIES confound regression output directory with the datasink.
  output_dir            path to drop analysis outputs.

optional arguments:
  -h, --help            show this help message and exit
  --output_name OUTPUT_NAME
                        Creates a new output folder to store the workflow of this analysis run, to avoid potential overlaps with previous runs. (default: analysis_wf)
  --scan_list [SCAN_LIST ...]
                        This option offers to run the analysis on a subset of the scans. The scans selected are specified by providing the full path to each EPI file from the input BIDS folder. The list
                        of scan can be specified manually as a list of file name '--scan_list scan1.nii.gz scan2.nii.gz ...' or the files can be imbedded into a .txt file with one filename per row. By
                        default, 'all' will use all the scans previously processed. (default: ['all'])
  --seed_list [SEED_LIST ...]
                        Can provide a list of seed .nii images that will be used to evaluate seed-based correlation maps based on Pearson's r. Each seed must consist of a binary mask representing the
                        ROI in commonspace. (default: [])

        Options for performing a whole-brain timeseries correlation matrix analysis.
        :
  --FC_matrix           Choose this option to derive a whole-brain functional connectivity matrix, based on the Pearson's r correlation of regional timeseries for each subject cleaned timeseries.
                        (default: False)
  --ROI_type {parcellated,voxelwise}
                        Define the types of ROI to extract regional timeseries for correlation matrix analysis. Options are 'parcellated', in which case the atlas labels provided for preprocessing are
                        used as ROIs, or 'voxelwise', in which case all voxel timeseries are cross-correlated. (default: parcellated)

        Options for performing group-ICA using FSL's MELODIC on the whole dataset cleaned timeseries.
        Note that confound regression must have been conducted on commonspace outputs.
        :
  --group_ICA           Choose this option to conduct group-ICA. (default: False)
  --TR TR               Specify repetition time (TR) in seconds. (default: 1.0s)
  --dim DIM             You can specify the number of ICA components to be derived. The default uses an automatic estimation. (default: 0)

        Options for performing a dual regression analysis based on a previous group-ICA run from FSL's MELODIC.
        Note that confound regression must have been conducted on commonspace outputs.
        :
  --DR_ICA              Choose this option to conduct dual regression on each subject timeseries. This analysis will output the spatial maps corresponding to the linear coefficients from the second
                        linear regression. See rabies.analysis_pkg.analysis_functions.dual_regression for the specific code. (default: False)
  --IC_file IC_FILE     Option to provide a melodic_IC.nii.gz file with the ICA components from a previous group-ICA run. If none is provided, a group-ICA will be run with the dataset cleaned
                        timeseries. (default: None)

        Options for performing a Dual ICA.
        Need to provide the prior maps to fit --prior_maps, and the associated indices for the target components
        in --prior_bold_idx
        :
  --dual_ICA DUAL_ICA   Specify how many subject-specific sources to compute using dual ICA. (default: 0)
  --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). Default: Corresponds to a MELODIC run
                        on a combined group of anesthetized- ventilated and awake mice. Confound regression 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/gabriel/.local/share/rabies/melodic_IC.nii.gz)
  --prior_bold_idx [PRIOR_BOLD_IDX ...]
                        Specify the indices for the priors to fit from --prior_maps. (default: [5, 12, 19])

Data Diagnosis CLI

Click to expand

usage: rabies data_diagnosis [-h] [--output_name OUTPUT_NAME] [--scan_list [SCAN_LIST ...]] [--dual_ICA DUAL_ICA] [--prior_maps PRIOR_MAPS] [--prior_bold_idx [PRIOR_BOLD_IDX ...]]
                             [--prior_confound_idx [PRIOR_CONFOUND_IDX ...]] [--DSURQE_regions]
                             confound_regression_out output_dir

positional arguments:
  confound_regression_out
                        path to RABIES confound regression output directory with the datasink.
  output_dir            path to drop data_diagnosis outputs.

optional arguments:
  -h, --help            show this help message and exit
  --output_name OUTPUT_NAME
                        Creates a new output folder to store the workflow of this analysis run, to avoid potential overlaps with previous runs. (default: data_diagnosis_wf)
  --scan_list [SCAN_LIST ...]
                        This option offers to run the analysis on a subset of the scans. The scans selected are specified by providing the full path to each EPI file from the input BIDS folder. The list
                        of scan can be specified manually as a list of file name '--scan_list scan1.nii.gz scan2.nii.gz ...' or the files can be imbedded into a .txt file with one filename per row. By
                        default, 'all' will use all the scans previously processed. (default: ['all'])
  --dual_ICA DUAL_ICA   Specify how many subject-specific sources to compute using dual ICA. (default: 0)
  --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). Default: Corresponds to a MELODIC run
                        on a combined group of anesthetized- ventilated and awake mice. Confound regression 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/gabriel/.local/share/rabies/melodic_IC.nii.gz)
  --prior_bold_idx [PRIOR_BOLD_IDX ...]
                        Specify the indices for the BOLD components from --prior_maps. (default: [5, 12, 19])
  --prior_confound_idx [PRIOR_CONFOUND_IDX ...]
                        Specify the indices for the confound components from --prior_maps. (default: [0, 1, 2, 6, 7, 8, 9, 10, 11, 13, 14, 21, 22, 24, 26, 28, 29])
  --DSURQE_regions      If using the default mouse DSURQE atlas, will organize the grayplot to have regional labels. (default: False)

Step 1: Organize Input Data

Input folder must follow the BIDS structure (https://bids.neuroimaging.io/). RABIES will iterate through subjects and search for all available functional scans with suffix 'bold' or 'cbv'. If anatomical scans are used for preprocessing (--bold_only False), each functional scan will be matched to one corresponding anatomical scan with suffix 'T1w' or 'T2w' of the same subject/session.

Mandatory BIDS specifications are:

• 'sub-{subject ID}' and 'ses-{session ID}' for both functional and anatomical images
• 'bold' or 'cbv' suffix for functional images
• 'T1w' or 'T2w' for anatomical images
• 'run-{run #}' is necessary for functional images if there are multiple scans per session

Directory tree of the example dataset

• http://doi.org/10.5281/zenodo.3937697 has the following BIDS structure:

test_dataset
├── sub-MFC067
│   └── ses-1
│       ├── anat
│       │   └── sub-MFC067_ses-1_acq-FLASH_T1w.nii.gz
│       └── func
│           └── sub-MFC067_ses-1_task-rest_acq-EPI_run-1_bold.nii.gz
└── sub-MFC068
    └── ses-1
        ├── anat
        │   └── sub-MFC068_ses-1_acq-FLASH_T1w.nii.gz
        └── func
            └── sub-MFC068_ses-1_task-rest_acq-EPI_run-1_bold.nii.gz

8 directories, 4 files

---

tree v1.7.0 © 1996 - 2014 by Steve Baker and Thomas Moore
HTML output hacked and copyleft © 1998 by Francesc Rocher
JSON output hacked and copyleft © 2014 by Florian Sesser
Charsets / OS/2 support © 2001 by Kyosuke Tokoro

Step 2: Execute RABIES

The following section describes the basic syntax to run RABIES with an example dataset available here http://doi.org/10.5281/zenodo.3937697

Option A: How to run with local installation

Click to expand

preprocess

rabies -p MultiProc preprocess test_dataset/ preprocess_outputs/ --TR 1.0s --no_STC

First, this will run the minimal preprocessing step on the test dataset and store outputs into preprocess_outputs/ folder. The option -p MultiProc specifies to run the pipeline in parallel according to available local threads.

confound_regression

rabies -p MultiProc confound_regression preprocess_outputs/ confound_regression_outputs/ --TR 1.0s --commonspace_bold --smoothing_filter 0.3 --conf_list WM_signal CSF_signal vascular_signal mot_6

Next, to conduct the modeling and regression of confounding sources, the confound_regression step can be run with custom options for denoising. In this case, we apply a highpass filtering at 0.01Hz, together with the voxelwise regression of the 6 rigid realignment parameters and the mean WM,CSF and vascular signal which are derived from masks provided along with the anatomical template. Finally, a smoothing filter 0.3mm is applied. We are running this on the commonspace outputs from preprocess (--commonspace_bold), since we will run analysis in commonspace in the next step.

analysis

rabies -p MultiProc analysis confound_regression_outputs analysis_outputs/ --TR 1.0s --group_ICA --DR_ICA

Finally, RABIES has a few standard analysis options provided, which are specified in the Analysis documentation. In this example, we are going to run group independent component analysis (--group_ICA), using FSL's MELODIC function, followed by a dual regression (--DR_ICA) to back propagate the group components onto individual subjects.

Option B: How to run with a container (Singularity and Docker)

Click to expand

Containers are independent computing environments which have their own dependencies installed to ensure consistent and reliable execution of the software regardless of the user. Singularity containers can be exported to remote high-performance computing platforms (e.g. computecanada).
The main difference for the execution of a container consists in relating the paths for all relevant directories from the local computer to the container's internal folders. This is done using -B for Singularity and -v for Docker. See below for examples:

Singularity execution

preprocess

singularity run -B $PWD/test_dataset:/test_dataset:ro \
-B $PWD/preprocess_outputs:/preprocess_outputs/ \
/path_to_singularity_image/rabies.sif -p MultiProc preprocess /test_dataset/ /preprocess_outputs/ --TR 1.0s --no_STC

confound_regression

singularity run -B $PWD/test_dataset:/test_dataset:ro \
-B $PWD/preprocess_outputs:/preprocess_outputs/ \
-B $PWD/confound_regression_outputs:/confound_regression_outputs/ \
/path_to_singularity_image/rabies.sif -p MultiProc confound_regression /preprocess_outputs/ /confound_regression_outputs/ --TR 1.0s --highpass 0.01 --commonspace_bold --smoothing_filter 0.3 --conf_list WM_signal CSF_signal vascular_signal mot_6

Note here that the path to the dataset is still linked to the container with -B, even though it is not explicitely part of the inputs in the confound regression call. This is necessary since the paths used in the preprocess steps are still accessed in the background, and there will be an error if the paths are not kept consistent across processing steps.

analysis

singularity run -B $PWD/test_dataset:/test_dataset:ro \
-B $PWD/preprocess_outputs:/preprocess_outputs/ \
-B $PWD/confound_regression_outputs:/confound_regression_outputs/ \
-B $PWD/analysis_outputs:/analysis_outputs/ \
/path_to_singularity_image/rabies.sif -p MultiProc analysis /confound_regression_outputs /analysis_outputs/ --TR 1.0s --group_ICA --DR_ICA

Docker execution

docker run -it --rm \
-v /local_input_folder_path:/nii_inputs:ro \
-v /local_output_folder_path:/outputs \
rabies preprocess /nii_inputs /outputs --further_execution_specifications

The docker execution has very similar syntax to the singularity execution, except that -B is replaced by -v, and some further specifications may be needed (e.g. -it, --rm).

Step 3: Understand your outputs

In this section, there is a description for all the output files provided at each processing steps, together with recommandations for quality control.

Preprocessing Outputs

Click to expand

Important outputs will be found in the datasink folders. All the different preprocessing outputs are found below:

• anat_datasink: Includes outputs specific to the anatomical preprocessing workflow

  • anat_preproc: preprocessed anatomical scans that are used for further registrations
  • anat_mask: brain mask in the anatomical native space
  • WM_mask: WM mask in the anatomical native space
  • CSF_mask: CSF mask in the anatomical native space
  • anat_labels: atlas labels in the anatomical native space

• bold_datasink: Includes corrected EPI timeseries (corrected_bold/ for native space and commonspace_bold/ for registered to commonspace), EPI masks and other key EPI outputs from the preprocessing workflow

  • input_bold: original raw EPI images used as inputs into the pipeline
  • corrected_bold: EPI timeseries after preprocessing in native space
  • corrected_bold_ref: reference 3D EPI image (temporal median) after correction
  • bold_brain_mask: brain mask in the corrected_bold space
  • bold_WM_mask: WM mask in the corrected_bold space
  • bold_CSF_mask: CSF mask in the corrected_bold space
  • bold_labels: atlas labels in the corrected_bold space
  • commonspace_bold: EPI timeseries after preprocessing in common space
  • commonspace_bold_mask: brain mask in the commonspace_bold space
  • commonspace_bold_WM_mask: WM mask in the commonspace_bold space
  • commonspace_bold_CSF_mask: CSF mask in the commonspace_bold space
  • commonspace_vascular_mask: vascular mask in the commonspace_bold space
  • commonspace_bold_labels: atlas labels in the commonspace_bold space
  • initial_bold_ref: initial reference 3D EPI image that was subsequently used for bias-field correction
  • bias_cor_bold: reference 3D EPI after bias-field correction which is then used for co-registration
  • bias_cor_bold_warped2anat: bias_cor_bold warped to the co-registration target anatomical image

• commonspace_datasink: Outputs from the common space registration

  • ants_dbm_template: the dataset template generated from the registration of anatomical images, using two-level ants dbm (https://github.com/CoBrALab/twolevel_ants_dbm), can be found here
  • warped_template: ants_dbm_template warped to the provided common space template after registration
  • ants_dbm_outputs: a complete output from the two-level ants dbm run for the generation of a dataset anatomical template

• transforms_datasink: Contains all transforms

  • affine_bold2anat: affine transforms from the EPI co-registration to the anatomical image
  • warp_bold2anat: non-linear transforms from the EPI co-registration to the anatomical image
  • inverse_warp_bold2anat: inverse of the non-linear transforms from the EPI co-registration to the anatomical image
  • anat_to_template_affine: affine transforms from the registration of the anatomical image to ants_dbm_template registration
  • anat_to_template_warp: non-linear transforms from the registration of the anatomical image to ants_dbm_template registration
  • anat_to_template_inverse_warp: inverse of the non-linear transforms from the registration of the anatomical image to ants_dbm_template
  • template_to_common_affine: affine transforms from the registration of the ants_dbm_template to the commonspace template
  • template_to_common_warp: non-linear transforms from the registration of the ants_dbm_template to the commonspace template
  • template_to_common_inverse_warp: inverse of the non-linear transforms from the registration of the ants_dbm_template to the commonspace template

• confounds_datasink: contains confounding features from the EPI that are relevant for subsequent confound regression

  • confounds_csv: a .csv file with the diverse potential confound timecourses. Includes up to 24 motion parameters (6 rigid parameters, their temporal derivative, and all 12 parameters squared; Friston et al. 1996), the global signal, the WM mask signal, the CSF mask signal, the vascular mask signal and aCompCor timecourses (Muschelli et al. 2014).
  • FD_csv: a .csv file with the timecourse of the voxelwise mean and maximal framewise displacement (FD) estimations
  • FD_voxelwise: a .nii image which contains FD timecourses for all single voxel
  • pos_voxelwise: a .nii image which contains the relative positioning timecourses for all single voxel

Recommendations for Quality Control (QC)

Visual QC outputs in .png format are generate for several processing milestones. These can be found in the rabies_out/QC_report folder. The milestones include:

• template_files: displays the overlap of the provided anatomical template with it's associated masks and labels.
• anat_denoising: represents the processing steps for the denoising of the anatomical image before main registration steps. It includes 1-the raw image, 2-the initial correction, 3-the overlap of the registered mask used for final correction, 4-final corrected output.
• bold_denoising: same as anat_denoising, but for the functional image.
• EPI2Anat: registration of the EPI to the anatomical image within subject
• Anat2Template: registration of the anatomical image to the dataset-generated template
• Template2Commonspace: registration of the dataset template to the provided commonspace template
• temporal_denoising: includes the timecourse of the head motion realignment parameters and associated framewise displacement. Also include spatial maps for temporal variability and tSNR. The following image presents an example of the overlap for the EPI2Anat registration:

Confound Regression Outputs

Click to expand

Important outputs from confound regression will be found in the confound_regression_datasink present in the provided output folder:

• confound_regression_datasink: Includes outputs specific to the anatomical preprocessing workflow
  • cleaned_timeseries: Resulting timeseries after the application of confound regression
  • VE_file: .pkl file which contains a dictionary vectors, where each vector corresponds to the voxelwise the variance explained (VE) from each regressor in the regression model
  • aroma_out: if --run_aroma is selected, the outputs from running ICA-AROMA will be saved, which includes the MELODIC ICA outputs and the component classification results
  • subject_melodic_ICA: if --diagnosis_output is activated, will contain the outputs from MELODIC ICA run on each individual scan
  • tSNR_map: if --diagnosis_output is activated, this will contain the tSNR map for each scan before confound regression

Analysis Outputs

Click to expand

Important outputs from analysis will be found in the analysis_datasink present in the provided output folder:

• analysis_datasink: Includes outputs specific to the anatomical preprocessing workflow
  • group_ICA_dir: complete output from MELODIC ICA, which includes a HTML report for visualization
  • group_IC_file: MELODIC ICA output file with the ICA components
  • DR_data_file: dual regression outputs in the form of a .pkl file which contains a 2D numpy array of component number by voxel number
  • DR_nii_file: dual regression outputs in the form of a .nii file which contains all component 3D maps concatenated into a single .nii file, where the component numbers correspond to the provided template ICA file
  • matrix_data_file: .pkl file which contains a 2D numpy array representing the whole-brain correlation matrix. If using parcellation, the row/column ROI indices are in increasing number of the atlas label number
  • matrix_fig: .png file offered for visualization which represent the correlation matrix
  • seed_correlation_maps: nifti files with voxelwise correlation maps for all provided seeds for seed-based FC

Acknowledgments

Acknowledging RABIES: We currently ask users to acknowledge the usage of this software by citing the Github page.

Presentations

• Gabriel Desrosiers-Gregoire, Gabriel A. Devenyi, Francesca Mandino, Joanes Grandjean, M. Mallar Chakravarty. The Convergence of Different fMRI Analysis Streams. Organization for Human Brain Mapping 2020, Virtual Conference (06/2020)
• Gabriel Desrosiers-Gregoire, Gabriel A. Devenyi, Joanes Grandjean, M. Mallar Chakravarty. Recurrent functional connectivity gradients identified along specific frequency bands of oscillatory coherence and across anesthesia protocols for mouse fMRI. Presented at Society for Neuroscience 2019, Chicago, IL
• Gabriel Desrosiers-Gregoire, Gabriel A. Devenyi, Joanes Grandjean, M. Mallar Chakravarty. (2019) Dynamic functional connectivity properties are differentially affected by anesthesia protocols and compare across species. Presented at Organization for Human Brain Mapping 2019, Rome, Italy
• Gabriel Desrosiers-Gregoire, Daniel Gallino, Gabriel A. Devenyi, M. Mallar Chakravarty. (2019) Comparison of the BOLD-evoked response to hypercapnic challenge in mice anesthetized under isoflurane and dexmedetomidine. Presented at International Society for Magnetic Resonance in Medicine 2019, Montreal, QC

References and Influential Material

• fMRIPrep - https://github.com/poldracklab/fmriprep - Esteban, O., Markiewicz, C. J., Blair, R. W., Moodie, C. A., Isik, A. I., Erramuzpe, A., ... & Oya, H. (2019). fMRIPrep: a robust preprocessing pipeline for functional MRI. Nature methods, 16(1), 111-116.
• Two-level DBM - https://github.com/CoBrALab/twolevel_ants_dbm
• ICA-AROMA - https://github.com/maartenmennes/ICA-AROMA - Pruim, R. H., Mennes, M., van Rooij, D., Llera, A., Buitelaar, J. K., & Beckmann, C. F. (2015). ICA-AROMA: A robust ICA-based strategy for removing motion artifacts from fMRI data. Neuroimage, 112, 267-277.
• Grandjean, J., Canella, C., Anckaerts, C., Ayrancı, G., Bougacha, S., Bienert, T., ... & Garin, C. M. (2020). Common functional networks in the mouse brain revealed by multi-centre resting-state fMRI analysis. Neuroimage, 205, 116278.
• FSL MELODIC - https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/MELODIC - Beckmann, C. F., Mackay, C. E., Filippini, N., & Smith, S. M. (2009). Group comparison of resting-state FMRI data using multi-subject ICA and dual regression. Neuroimage, 47(Suppl 1), S148.
• ANTs - https://github.com/ANTsX/ANTs
• AFNI - https://afni.nimh.nih.gov/
• Friston, K. J., Williams, S., Howard, R., Frackowiak, R. S., & Turner, R. (1996). Movement‐related effects in fMRI time‐series. Magnetic resonance in medicine, 35(3), 346-355.
• Muschelli, J., Nebel, M. B., Caffo, B. S., Barber, A. D., Pekar, J. J., & Mostofsky, S. H. (2014). Reduction of motion-related artifacts in resting state fMRI using aCompCor. Neuroimage, 96, 22-35.
• Hong, X., To, X. V., Teh, I., Soh, J. R., & Chuang, K. H. (2015). Evaluation of EPI distortion correction methods for quantitative MRI of the brain at high magnetic field. Magnetic resonance imaging, 33(9), 1098-1105.