Getting started¶
Read how to use the CATO toolbox.
How to use CATO¶
After installation, the structural and functional pipelines can be run from the command line (as executable) or in MATLAB (as MATLAB Toolbox). The executable is fast and easy to deploy on high-performance computing clusters and the set of MATLAB functions is easy to customize.
Executable
structural_pipeline -s SUBJECTDIR -m MCRDIR [--PARAM1=VAL1] [--PARAM2=VAL2]...
functional_pipeline -s SUBJECTDIR -m MCRDIR [--PARAM1=VAL1] [--PARAM2=VAL2]...
To run specific pipeline steps, include the requested pipeline steps as first input arguments:
structural_pipeline [STEP]... -s SUBJECTDIR -m MCRDIR [--PARAM1=VAL1] [--PARAM2=VAL2]...
functional_pipeline [STEP]... -s SUBJECTDIR -m MCRDIR [--PARAM1=VAL1] [--PARAM2=VAL2]...
MATLAB
structural_pipeline(SUBJECTDIR, 'PARAM1', VAL1, 'PARAM2', VAL2, ...)
functional_pipeline(SUBJECTDIR, 'PARAM1', VAL1, 'PARAM2', VAL2, ...)
With the following parameters:
- SUBJECTDIR
- example
/Volumes/DATA/subject001
- description
Directory with the subject’s FreeSurfer, rs-fMRI and/or DWI data.
- MCRDIR
- example
/Applications/MATLAB/MATLAB_Runtime/v93
- description
Installation directory of MATLAB runtime version R2017b (9.3).
- STEP
- example
structural_preprocessing
- description
Specific pipeline steps that will be executed.
- PARAM1 VAL1 name-value pair arguments
- terminal
--general.freesurferDir='T1/SUBJECT_FS'
- MATLAB
'general.freesurferDir', 'T1/SUBJECT_FS'
- description
Configuration parameters that overwrite the default values and values specified in the configuration file.
Docker¶
The CATO toolbox can be run from a Docker container by following these steps:
First, download and install Docker from https://www.docker.com.
Download the most recent CATO Docker image. The latest Docker image can be found on Docker hub and can be downloaded from this website or from the command line by running the following command:
docker pull dutchconnectomelab/cato:v3.2.1
Run the following command to start the Docker container and link it to subject data located in the
/Volumes/Example
directory:docker run --rm -t -i \ --mount type=bind,source="/Volumes/Example/",target=/mnt/Example \ cato:v3.2.1
To process a subject
0001
run the following commands:structural_pipeline -s /mnt/Example/0001 \ -m /opt/MCR-2017b/v93 \ --configurationFile=/mnt/Example/CATO.conf
Running a subject again¶
At default, the pipelines gives an error when it notices that a subject has already been (partly) processed. Use the runType
parameter to determine the behavior when re-running a subject:
Executable
structural_pipeline -s SUBJECTDIR -m MCRDIR --runType=overwrite
MATLAB
structural_pipeline(SUBJECTDIR, 'runType', 'overwrite');
Parameter value |
Description |
---|---|
|
(Default) Execute pipeline only when no logFile is present in the output directory. |
|
Execute steps that have not been started earlier or halted due to an error. Does not execute steps that finished successfully. |
|
Execute all steps including steps that finished successfully earlier. |
Parameters¶
Parameters for the structural and functional pipeline can be specified on the command line or in a configuration file in JSON-format. Parameters in the user-provided configuration file override the default parameters and parameters specified on the command line override both.
Special parameters¶
Parameter values can also contain “special variables”, which are in uppercase and replaced by a specific string when running CATO.
- Examples:
The name of a parameter in capital letters (e.g. MINFA, DWIFILE or OUTPUTDIR). This special variable is replaced by the value of the referenced parameter. The following example shows how MINFA and OUTPUTDIR are used as special variables, resulting in a reconstructed fiber cloud file named
DWI_processed/fibers_0.1.trk
:"reconstruction_fibers":{ "minFA": 0.1, "fiberFile": "OUTPUTDIR/fibers_MINFA.trk" }
SUBJECT: replaced by the subject name (the name of the directory containing the data).
TOOLBOXDIR: replaced by the location of the toolbox directory.
CONFIGDIR: replaced by the location of the directory containing the configuration file.
METHOD: In the structural pipeline, METHOD is replaced by the used reconstruction method, e.g. ‘csd’. In the functional pipeline, METHOD is replaced by the methodDescription of the used reconstruction method, e.g. ‘scrubbed_0.01-0.1’.
TEMPLATE: replaced by the used template, e.g. ‘lausanne120’.
MEASURE: replaced by the used diffusion measure, e.g. ‘fractional anisotropy’ (this special variable is only used when exporting diffusion measures to NifTi in the Reconstruction diffusion step).
Note: Two special variables must be seperated by a character (e.g. ‘a’, ‘0’ or ‘_’) that is not a capital letter.