Examples¶

Structural processing example¶

Data¶

The following example uses the FreeSurfer (freesurfer) and DWI data (dtiinit) of subject 0001 from the Open Diffusion Data Derivatives (O3D) repository, that can be downloaded after a quick sign-up. After unpacking and putting the FreeSurfer data in a folder FreeSurfer and the DWI data in a folder DWI, we have the following files:

Reconstruction using a configuration file¶

This example processes Subject 0001 using the preprocess_eddy.sh preprocessing script. This preprocessing script performs a.o. eddy current correction using eddy from FSL. Eddy needs as input the phase encoding direction of the scans which we provide using the variable revPhaseEncDim. The dataset informs us that this direction is Anterior -> Posterior and the DWI file is in RAS orientation, so the phase encoding dimension is the 2nd dimension ("revPhaseEncDim": 2).

The following configuration file provides the minimum parameters that need to be specified. Copy the text and save it in a file (e.g. /Volumes/Example/CATO.conf).

{
    "general":{
       "fslRootDir":"UPDATE_THIS",
       "freesurferRootDir":"UPDATE_THIS",
       "freesurferDir":"FreeSurfer",
       "templates": ["aparc", "lausanne120", "lausanne250"]
    },
    "structural_preprocessing":{
       "rawBvalsFile":"DWI/dwi.bvals",
       "rawBvecsFile":"DWI/dwi.bvecs",
       "dwiFile":"DWI/dwi.nii.gz",
       "preprocessingScript":"TOOLBOXDIR/structural_preprocessing/preprocess_eddy.sh",
       "revPhaseEncDim": 2
    }
 }

Now you can run the structural pipeline with this configuration file:

Executable

structural_pipeline -s /Volumes/Example/0001 \
    -m MCRDIR_UPDATE_THIS \
    --configurationFile=/Volumes/Example/CATO.conf

where MCRDIR_UPDATE_THIS is the MCR installation directory (e.g. /Applications/MCR/v93)

MATLAB

subjectDir = '/Volumes/Example/0001';
configurationFile = '/Volumes/Example/CATO.conf';
structural_pipeline(subjectDir, ...
    'configurationFile', configurationFile);

CATO with command-line parameters¶

Instead, or in addition to a configuration file, all parameters can also be specified on the command line:

Executable

structural_pipeline -s /Volumes/Example/0001 \
    -m MCRDIR_UPDATE_THIS \
    --general.fslRootDir='UPDATE_THIS' \
    --general.freesurferRootDir='UPDATE_THIS' \
    --general.templates='["aparc","lausanne120","lausanne250"]' \
    --structural_preprocessing.rawBvalsFile='DWI/dwi.bvals' \
    --structural_preprocessing.rawBvecsFile='DWI/dwi.bvecs' \
    --structural_preprocessing.dwiFile='DWI/dwi.nii.gz' \
    --general.freesurferDir='FreeSurfer' \
    --structural_preprocessing.preprocessingScript='TOOLBOXDIR/structural_preprocessing/preprocess_eddy.sh' \
    --structural_preprocessing.revPhaseEncDim='2'

MATLAB

subjectDir = '/Volumes/Example/0001';
structural_pipeline(subjectDir, ...
    'general.fslRootDir', 'UPDATE_THIS', ...
    'general.freesurferRootDir', 'UPDATE_THIS', ...
    'general.templates', {'aparc', 'lausanne120', 'lausanne250'}, ...
    'structural_preprocessing.rawBvalsFile', 'DWI/dwi.bvals', ...
    'structural_preprocessing.rawBvecsFile', 'DWI/dwi.bvecs', ...
    'structural_preprocessing.dwiFile', 'DWI/dwi.nii.gz', ...
    'general.freesurferDir', 'FreeSurfer', ...
    'structural_preprocessing.preprocessingScript', 'TOOLBOXDIR/structural_preprocessing/preprocess_eddy.sh', ...
    'structural_preprocessing.revPhaseEncDim', 2);

Functional processing example¶

This example processes EXAMPLESUBJECT using the preprocess_default.sh preprocessing script. This preprocessing script performs a.o. slice time correction, motion correction, and mapping of the T1 parcellation to the rs-fMRI image (see Preprocessing). The following configuration file provides the minimum parameters to run the functional pipeline (including applying a bandpass filter and scrubbing). Copy the text and save it in a file (e.g. /Volumes/Example/CATO_functional.conf).

{
    "general":{
        "fslRootDir":"UPDATE_THIS",
        "freesurferRootDir": "UPDATE_THIS",
        "freesurferDir": "T1/SUBJECT_FS",
        "templates": ["aparc", "lausanne120", "lausanne250"]
    },
    "functional_preprocessing":{
        "fmriFile": "fMRI/SUBJECT_fmri.nii.gz",
        "preprocessingScript": "TOOLBOXDIR/functional_preprocessing/preprocess_default.sh",
        "sliceTimingCorrection": true,
        "sliceTimerOptions": ""
    },
    "reconstruction_functional_network":{
        "methodDescription": "scrubbed_0.01-0.1",
        "regression":{
            "regressionMask": [2, 41, 24],
            "globalMeanRegression": false
        },
        "bandpass_filter":{
            "filter": true,
            "frequencies": [0.01, 0.1]
        },
        "scrubbing":{
            "scrubbing": true,
            "maxFD": 0.25,
            "maxDVARS": 1.5,
            "minViolations": 2,
            "backwardNeighbors": 1,
            "forwardNeighbors": 0
        }
    }
}

To run the functional pipeline with this configuration file:

Executable

functional_pipeline -s /Volumes/Example/0001 \
    -m MCRDIR_UPDATE_THIS \
    --configurationFile=/Volumes/Example/CATO_functional.conf

where MCRDIR_UPDATE_THIS is the MCR installation directory (e.g. /Applications/MCR/v93)

MATLAB

subjectDir = '/Volumes/Example/0001';
configurationFile = '/Volumes/Example/CATO_functional.conf';
functional_pipeline(subjectDir, ...
    'configurationFile', configurationFile);

BIDS formatted data¶

Brain imaging data structured according to the BIDS format is organized consistently, making it easy to process such datasets with CATO. Datasets will differ in their acquisition and scanner parameters, so makes it always important to adjust the configuration file to the dataset used. Parameters that are often the same for BIDS datasets are listed below. In this example, FreeSurfer reconstructions are expected in the derivatives subfolder of the dataset and the output of CATO will go into this derivatives folder as well.

Structural pipeline

{
    "general":{
        "derivativesDir":"../derivatives",
        "freesurferDir": "DERIVATIVESDIR/freesurfer/SUBJECT",
        "outputDir": "DERIVATIVESDIR/cato_structural/SUBJECT"
    },
    "structural_preprocessing": {
        "rawBvalsFile": "ses-1/dwi/SUBJECT_ses-1_dwi.bval",
        "rawBvecsFile": "ses-1/dwi/SUBJECT_ses-1_dwi.bvec",
        "dwiFile": "ses-1/dwi/SUBJECT_ses-1_dwi.nii.gz"
    }
}

Functional pipeline

 {
     "general":{
         "derivativesDir":"../derivatives",
         "freesurferDir": "DERIVATIVESDIR/freesurfer/SUBJECT",
         "outputDir": "DERIVATIVESDIR/cato_functional/SUBJECT"
     },
    "functional_preprocessing": {
        "fmriFile": "SUBJECT/ses-1/func/SUBJECT_ses-1_task-rest_bold.nii.gz"
    }
}

fMRI preprocessing with Melodic + Fix¶

Artifacts can be removed from the fMRI data using using an independent component analysis (ICA) approach in which the fMRI signal is decomposed into ICA components and “noise” components (including motion, non-neural physiological and scanner artifacts) are removed. An example preprocessing script for this approach using FSL Fix and FSL Melodic is provided on the GitHub repository. This example preprocessing script is currently in development and can be discussed in the associated pull request.

Cortical reconstruction with FreeSurfer¶

The CATO toolbox requires cortical reconstructions from preprocessed T1 data. This preprocessing can be achieved using FreeSurfer, a widely used software package for analyzing neuroimaging data. The following steps can be used to add cortical reconstruction using FreeSurfer to the preprocessing step in CATO:

Copy a template preprocessing script (e.g. preprocess_minimal.sh) and name it preprocess_FreeSurfer.sh.
Make sure that the new preprocessing script is executable by running the following command in the terminal:

chmod 700 "preprocess_FreeSurfer.sh"

Add the following code to the input argument parser in the preprocessing script:

--t1File=*)
t1File=${1#*=}
shift
;;

Add the following code to the begining of the preprocessing script (after the line “parse_input "$@"”):

# run FreeSurfer
oldDir=$(pwd)
cd $(dirname $freesurferDir)
recon-all -i "${oldDir}/${t1File}" -s $(basename ${freesurferDir}) -autorecon-all
cd "$oldDir"

An overview of the edits is provided in the following figure:

⠀

Add a parameter t1File to the structural_preprocessing or functional_preprocessing section of the configuration file and update the preprocessing script.

 {
     "structural_preprocessing":{
         "t1File":"T1/SUBJECT_T1.nii.gz",
         "preprocessingScript":"TOOLBOXDIR/functional_preprocessing/preprocess_FreeSurfer.sh"
     }
}

CATO will now run FreeSurfer in the preprocessing step!

Note: For computational reasons, it is often beneficial to run FreeSurfer and CATO seperately.