Standalone Version of CAT26

Use of the standalone version of CAT26

The advantage of the standalone version is that no Matlab license is required. Only the (free) Matlab Runtime has to be downloaded. However, there are some limitations (e.g. no parallelization and no interactive help in the GUI version) and the standalone version is mainly intended to run without GUI on Unix systems.

Installation of the standalone version of CAT26

1. Download the CAT26.0 standalone version for MacOS (ARM64, Silicon), MacOS (Intel), Linux or Windows.
2. Unzip the file. This creates the folder "cat_standalone", which you can rename and move to your preferred location (e.g. "/software/CAT26.0_MCR").
3. Download the Matlab Runtime R2023b for MacOS (ARM64, Silicon), MacOS (Intel), Linux or Windows and install it preferably in the same folder. The installer creates the subfolder "R2023b". On Linux, you can also install it without GUI:

   
   unzip MATLAB_Runtime_R2023b_Update_10_glnxa64.zip -d mcr_installer
   sudo mcr_installer/install -agreeToLicense yes -destinationFolder /software/CAT26.0_MCR
                   

Use of the standalone version of CAT26

If you prefer to use the standalone version of CAT via the GUI, you can call the GUI version with the following command:

/software/CAT26.0_MCR/run_spm.sh /software/CAT26.0_MCR/R2023b
                

Please note that the start script is now always named "run_spm.sh" (instead of "run_spm25.sh" in CAT12.9). On Windows, start the GUI version with "spm.exe". The shell scripts in the following examples require Linux or MacOS.

In order to use the GUI version, please see the instructions for the standard version.

For the following examples, we assume that the CAT standalone version was installed in "/software/CAT26.0_MCR" and the Matlab Runtime in "/software/CAT26.0_MCR/R2023b" and your T1-data are located in "/data/enigma-data/raw" and are named "sub*.nii.gz".
See the help text of standalone/cat_standalone.sh for more examples and a description of additional options.

DICOM Import

/software/CAT26.0_MCR/standalone/cat_standalone.sh -m /software/CAT26.0_MCR/R2023b \
  -b /software/CAT26.0_MCR/standalone/cat_standalone_dicom2nii.m /data/enigma-data/dicom/*.dcm \
  -a1 "'patid_date'" -a2 "{'raw'}"
                

Import DICOM files *.dcm and save converted nifti files in directory "raw" with structure <PatientID>/<StudyDate-StudyTime>/<ProtocollName>

Other options for directory structure are:

Please note the multiple quotes for parameter a1.

Preprocessing

/software/CAT26.0_MCR/standalone/cat_standalone.sh -m /software/CAT26.0_MCR/R2023b \
  -b /software/CAT26.0_MCR/standalone/cat_standalone_segment_enigma.m \
  /data/enigma-data/raw/sub*.nii.gz
                

Unzip and preprocess (segment) the files sub*.nii.gz using the ENIGMA CAT preprocessing batch. The preprocessed data is stored in a folder named after the CAT version (i.e. CAT26.0) and in separate subfolders (mri, surf, label and report) located in this folder. Data that contain non-brain areas (e.g. bias-corrected images in native space) are de-faced after preprocessing and saved with the prefix "anon_".

If your data are organized in BIDS format, the folder CAT26.0 is created in the BIDS root folder and the results are saved in CAT26.0/sub-*/[ses-*/]anat. In this case, please adapt the paths in the following examples.

Preprocessing without surface estimation

/software/CAT26.0_MCR/standalone/cat_standalone.sh -m /software/CAT26.0_MCR/R2023b \
  -b /software/CAT26.0_MCR/standalone/cat_standalone_segment_enigma.m \
  -a "matlabbatch{1}.spm.tools.cat.estwrite.output.surface = 0;" /data/enigma-data/raw/sub*.nii.gz
                

Same as above, but skip surface extraction.

Smoothing of Volume Data

This step is optional if you intend to statistically analyze your VBM data.

/software/CAT26.0_MCR/standalone/cat_standalone.sh -m /software/CAT26.0_MCR/R2023b \
  -b /software/CAT26.0_MCR/standalone/cat_standalone_smooth.m \
  /data/enigma-data/raw/CAT26.0/mri/mwp1sub*.nii -a1 "[6 6 6]" -a2 "'s6'"
                

Smooth the modulated and warped segmentations for gray matter with 6mm and prepend the string "s6" to the smoothed files. Optionally also smooth the white matter segmentations (i.e. mwp2*) and the warped segmentations without modulation (i.e. wp1* and wp2*) and also consider different smoothing sizes.

The recommended smoothing size for analyzing the volume data is 6mm. In order to use the data for machine learning with NeuroMiner no smoothing is necessary.
Please note the multiple quotes for parameter a2.

Resample and Smooth Surface Data

/software/CAT26.0_MCR/standalone/cat_standalone.sh -m /software/CAT26.0_MCR/R2023b \
  -b /software/CAT26.0_MCR/standalone/cat_standalone_resample.m \
  /data/enigma-data/raw/CAT26.0/surf/lh.thickness.sub* -a1 "12" -a2 "1"
                

Resample and smooth the thickness files lh.thickness.sub* with 12mm and save the resampled meshes as 32k mesh (HCP conform meshes). Only the left surface file has to be defined. The right hemisphere is processed automatically.

The recommended smoothing size for analyzing the surface data is 12mm. In order to use the data for machine learning with NeuroMiner no smoothing is necessary and the filter size should be set to "0".

Estimate and Save Quality Measures for Volume Data

/software/CAT26.0_MCR/standalone/cat_standalone.sh -m /software/CAT26.0_MCR/R2023b \
  -b /software/CAT26.0_MCR/standalone/cat_standalone_get_quality.m \
  /data/enigma-data/raw/CAT26.0/mri/mwp1sub*.nii -a1 "'Quality_measures_volumes.csv'" -a2 "1"
                

Estimate sample homogeneity (after preprocessing) using mean z-scores with global scaling with TIV for the modulated and warped segmentations for gray matter and save quality measures in the file Quality_measures_volumes.csv for external analysis.

Please note the multiple quotes for parameter a1.

Estimate and Save Quality Measures for Surface Data

/software/CAT26.0_MCR/standalone/cat_standalone.sh -m /software/CAT26.0_MCR/R2023b \
  -b /software/CAT26.0_MCR/standalone/cat_standalone_get_quality.m \
  /data/enigma-data/raw/CAT26.0/surf/s12.mesh.thickness.resampled_32k.sub* \
  -a1 "'Quality_measures_surfaces.csv'"
                

Estimate sample homogeneity (after preprocessing) using mean z-scores for resampled and smoothed thickness values and save quality measures in Quality_measures_surfaces.csv for external analysis.

Please note the multiple quotes for parameter a1.

Estimate and Save Weighted Overall Image Quality

/software/CAT26.0_MCR/standalone/cat_standalone.sh -m /software/CAT26.0_MCR/R2023b \
  -b /software/CAT26.0_MCR/standalone/cat_standalone_get_IQR.m \
  /data/enigma-data/raw/CAT26.0/report/cat_*.xml \
  -a1 "'SIQR.txt'"
                

Estimate weighted overall image quality (before preprocessing) using xml-files in report folder and save the structural image quality ratings (SIQR) in SIQR.txt for external analysis. Please note that SIQR replaces the former IQR of CAT12.9 and both measures are not directly comparable.

Please note the multiple quotes for parameter a1.

Estimate Total Intra-cranial Volume (TIV)

/software/CAT26.0_MCR/standalone/cat_standalone.sh -m /software/CAT26.0_MCR/R2023b \
  -b /software/CAT26.0_MCR/standalone/cat_standalone_get_TIV.m \
  /data/enigma-data/raw/CAT26.0/report/cat_*.xml -a1 "'TIV.txt'" -a2 "1" -a3 "0"
                

Save TIV values for all selected data in TIV.txt. Please note the multiple quotes to define the output name with a1.
The parameter a2 allows you to save only the TIV (1) or additionally to save also the global volumes for GM, WM, CSF, and WM hyperintensities (0). With parameter a3 you can add file names to the 1st column: 0 - save values only; 1 - add file name; 2 - add folder and file names.

Please note that you must also define parameter a2 if you use parameter a3.

Estimate mean volumes and mean surface values inside ROI

This step is optional (as an alternative to the ENIGMA Freesurfer protocol).

/software/CAT26.0_MCR/standalone/cat_standalone.sh -m /software/CAT26.0_MCR/R2023b \
  -b /software/CAT26.0_MCR/standalone/cat_standalone_get_ROI_values.m \
  /data/enigma-data/raw/CAT26.0/label/catROI*.xml -a1 "'ROI'"
                

Save mean surface values (e.g. cortical thickness) and mean volumes (in ml) for all selected data in a csv-file. The csv-file is named "ROI_" followed by the atlas name and the name of the measure (e.g. thickness or Vgm).

Please note the multiple quotes to define the ROI name.

Parallelization of the standalone version

In contrast to the Matlab standard version of CAT, the standalone version only supports serial preprocessing of multiple files. In order to speed up preprocessing and to distribute your jobs or batches to several processors or cores, you can use the script standalone/cat_parallelize.sh:

/software/CAT26.0_MCR/standalone/cat_parallelize.sh -p 8 -l /tmp \
  -c "-m /software/CAT26.0_MCR/R2023b \
  -b /software/CAT26.0_MCR/standalone/cat_standalone_segment_enigma.m" \
  /data/enigma-data/raw/sub*.nii
                

Parallelize CAT ENIGMA preprocessing by splitting all sub*.nii files into 8 jobs (processes) and save log file in /tmp folder.

Matlab Standard Version of CAT26

Use of the standard version of CAT26

You need a Matlab license to run the standard version of CAT.

Installation of CAT26

1. Download CAT26.0. If you need other versions select them here.
2. Unzip and copy the CAT folder to the spm/toolbox directory. Please note that the toolbox folder is now named "CAT" instead of "cat12". Please remove all older versions of CAT12 before installation. When CAT is started for the first time, it also offers to remove an old cat12 folder.

Calling CAT from the shell and running in headless mode without display

If you do not want to use the CAT and SPM graphical user interface, you can use the cat_standalone.sh script located in the CAT standalone folder to call batch files. You can use any of the supplied batches in the standalone folder, but you can also create your own batches using the batch manager in SPM. Please note that the supplied standalone batches must be called in CAT expert mode.

The cat_standalone.sh script can be used with few changes with the same flags as for the standalone version. You just need to add the flags "-ns" to turn off standalone mode and "-e" to call CAT in expert mode. Also, the flag "-m" now defines the Matlab command and "-s" the SPM folder, but can be skipped if they are found automatically. For example, to preprocess (segment) files, you can call:

your_spm_folder/toolbox/CAT/standalone/cat_standalone.sh -ns -e -m /usr/local/bin/matlab \
  -b your_spm_folder/toolbox/CAT/standalone/cat_standalone_segment_enigma.m \
  -s your_spm_folder /data/enigma-data/raw/sub*.nii.gz
                

See the standalone version for more examples.

Use of CAT

See the Quick Start Guide for step-by-step instructions for using CAT and also check the CAT Manual.

Important

CAT should be used in "expert mode" either by calling "CAT('expert')" from the Matlab command line or by using "Switch to Expert Mode" in the CAT GUI.

DICOM Import

Use "DICOM Import" from the SPM GUI.

Preprocessing

Load "standalone/cat_standalone_segment_enigma.m" in SPM batch manager and select your files and run preprocessing.

Smoothing of Volume Data

Use "Smooth" from the SPM GUI and select the warped segmentations in the "mri" folder: "mwp1*" and "wp1*" for gray matter (modulated warped/warped) and "mwp2*" and "wp2*" for white matter (modulated warped/warped).
The recommended smoothing size for analyzing the data is 6mm. In order to use the data for machine learning with NeuroMiner no smoothing is necessary.

Resample and Smooth Surface Data

Use "Resamp. & Smooth Surf." from the CAT GUI and select the thickness files of the left hemisphere (lh.thickness.*) in the "surf" folder. The right hemisphere is processed automatically.
The recommended smoothing size for analyzing the surface data is 12mm. In order to use the data for machine learning with NeuroMiner no smoothing is necessary and the filter size should be set to "0".

Estimate and Save Quality Measures for Volume and Surface Data

Use "Tools -> Save sample homogeneity for very large samples" from the CAT batch menu (SPM -> Tools -> CAT).

Estimate and Save Weighted Overall Image Quality

Use "Data Quality -> Get Weighted Overall Image Quality" from the CAT GUI.

Estimate Total Intra-cranial Volume (TIV)

Use "Get TIV" from the CAT GUI.

Optional (with graphical output):

Check Sample Homogeneity for Volume and Surface Data

Use "Data Quality -> Check Sample Homogeneity" from the CAT GUI.

Optional (as an alternative to the ENIGMA Freesurfer protocol):

Estimate mean volumes and mean surface values inside ROI

Use "ROI Tools -> Estimate Mean Value Inside ROI for External Analysis" from the CAT GUI and select the catROI*xml files in the label folder.

Optional (for general use with other machine learning tools):

Save Volume or Surface Data as mat File

Use "Volume Tools -> Save (resampled) Volume Data as mat-File" from the CAT GUI and select smoothed gray/white matter segmentations (modulated normalized or affine registered DARTEL export).
Use "Surface Tools -> Save Surface Data as mat-File" from the CAT GUI and select resampled and smoothed surface data.

Parallelization of the standard version

In order to speed up preprocessing and to distribute your jobs or batches to several processors or cores, there are two different options:

1. You can use the script standalone/cat_parallelize.sh. However, you also need to use the flag "-fg" with cat_standalone.sh to prevent the internal parallelization from being used:

your_spm_folder/toolbox/CAT/standalone/cat_parallelize.sh -p 8 -l /tmp \
  -c "your_spm_folder/toolbox/CAT/standalone/cat_standalone.sh -fg -ns -e -m /usr/local/bin/matlab \
  -b your_spm_folder/toolbox/CAT/standalone/cat_standalone_segment_enigma.m" \
  /data/enigma-data/raw/sub*.nii
                

Parallelize CAT ENIGMA preprocessing by splitting all sub*.nii files into 8 jobs (processes) and save the log file into the /tmp folder.

2. Call cat_standalone.sh and the parallelization will be handled automatically. By default, CAT uses half of the available processors. You can adjust the number of processors in cat_defaults (e.g. "cat.extopts.nproc = 4;"):

your_spm_folder/toolbox/CAT/standalone/cat_standalone.sh -ns -e -m /usr/local/bin/matlab \
  -b your_spm_folder/toolbox/CAT/standalone/cat_standalone_segment_enigma.m \
  -s your_spm_folder /data/enigma-data/raw/sub*.nii.gz
                

Parallelize CAT ENIGMA preprocessing by splitting all sub*.nii.gz files into the number of available or defined jobs (processes).