Computational Anatomy Toolbox for Standardized Processing of ENIGMA Data

These protocols use CAT12 to process voxel- and surface-based morphometry for MRI data in a standardized way for ENIGMA data, but also enable region-based measures for volume and surface data. CAT12 includes various quality control options and covers the entire analysis workflow, from cross-sectional or longitudinal data processing, to the statistical analysis, and visualization of results. The current version is CAT12.8.1.


You can either use the standalone version or the standard version of CAT12. The advantage of the standalone version is that no Matlab license is needed. Only the (free) Matlab Runtime R2017b (v93) has to be downloaded.


For any questions or suggestions please contact me.

Christian Gaser, Jena University Hospital

Standalone Version of CAT12

Use of the standalone version of CAT12

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 CAT12

  1. Download the CAT12 standalone version for macOS or Linux (copy the link to your browser if the download does not start automatically or load the latest file for your system with the name cat12_latest_R2017b_MCR* here).
  2. Open the MCR_v93.webloc link in the installed folder, which automatically downloads the Matlab Runtime for R2017b.
  3. Install the Matlab Runtime with the "v93" folder preferably in the same folder.

Use of the standalone version of CAT12

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


/software/CAT12.8.1_MCR/run_spm12.sh /software/CAT12.8.1_MCR/v93
                

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

For the following examples, we assume that the CAT12 standalone version was installed in "/software/CAT12.8.1_MCR" and the Matlab Runtime in "/software/CAT12.8.1_MCR/v93" 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/CAT12.8.1_MCR/standalone/cat_standalone.sh -m /software/CAT12.8.1_MCR/v93 \
  -b /software/CAT12.8.1_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:

flat No directory hierarchy
series <ProtocollName>
patid_date <PatientID>/<StudyDate-StudyTime>/<ProtocollName>
patid <PatientID>/<ProtocollName>
date_time <StudyDate-StudyTime>/<ProtocollName>

Please note the multiple quotes for parameter a1.

Preprocessing

/software/CAT12.8.1_MCR/standalone/cat_standalone.sh -m /software/CAT12.8.1_MCR/v93 \
  -b /software/CAT12.8.1_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 CAT12 preprocessing batch. The preprocessed data is stored in a folder named after the CAT12 version (e.g. CAT12.8.1) 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_".

Preprocessing without surface estimation

/software/CAT12.8.1_MCR/standalone/cat_standalone.sh -m /software/CAT12.8.1_MCR/v93 \
  -b /software/CAT12.8.1_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/CAT12.8.1_MCR/standalone/cat_standalone.sh -m /software/CAT12.8.1_MCR/v93 \
  -b /software/CAT12.8.1_MCR/standalone/cat_standalone_smooth.m \
  /data/enigma-data/raw/CAT12.8.1/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/CAT12.8.1_MCR/standalone/cat_standalone.sh -m /software/CAT12.8.1_MCR/v93 \
  -b /software/CAT12.8.1_MCR/standalone/cat_standalone_resample.m \
  /data/enigma-data/raw/CAT12.8.1/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 a the filter size should be set to "0".

Estimate and Save Quality Measures for Volume Data

/software/CAT12.8.1_MCR/standalone/cat_standalone.sh -m /software/CAT12.8.1_MCR/v93 \
  -b /software/CAT12.8.1_MCR/standalone/cat_standalone_get_quality.m \
  /data/enigma-data/raw/CAT12.8.1/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/CAT12.8.1_MCR/standalone/cat_standalone.sh -m /software/CAT12.8.1_MCR/v93 \
  -b /software/CAT12.8.1_MCR/standalone/cat_standalone_get_quality.m \
  /data/enigma-data/raw/CAT12.8.1/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_mesures_surfaces.csv for external analysis.

Please note the multiple quotes for parameter a1.

Estimate and Save Weighted Overall Image Quality

/software/CAT12.8.1_MCR/standalone/cat_standalone.sh -m /software/CAT12.8.1_MCR/v93 \
  -b /software/CAT12.8.1_MCR/standalone/cat_standalone_get_IQR.m \
  /data/enigma-data/raw/CAT12.8.1/report/cat_*.xml \
  -a1 "'IQR.txt'"
                

Estimate weighted overall image quality (before preprocessing) using xml-files in report folder and save quality measures in IQR.txt for external analysis.

Please note the multiple quotes for parameter a1.

Estimate Total Intra-cranial Volume (TIV)

/software/CAT12.8.1_MCR/standalone/cat_standalone.sh -m /software/CAT12.8.1_MCR/v93 \
  -b /software/CAT12.8.1_MCR/standalone/cat_standalone_get_TIV.m \
  /data/enigma-data/raw/CAT12.8.1/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 parameter a3 is available only from version r1987 and you must add the parameter a2 in addition.

Estimate mean volumes and mean surface values inside ROI

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


/software/CAT12.8.1_MCR/standalone/cat_standalone.sh -m /software/CAT12.8.1_MCR/v93 \
  -b /software/CAT12.8.1_MCR/standalone/cat_standalone_get_ROI_values.m \
  /data/enigma-data/raw/CAT12.8.1/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 CAT12, 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_parallize.sh:


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

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

Matlab Standard Version of CAT12

Use of the standard version of CAT12

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

Installation of CAT12

  1. Download the latest CAT12 version. If you need older versions select them here.
  2. Unzip and copy the cat12 folder to the spm12/toolbox directory. Please remove all older versions of CAT12 before installation.

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

If you do not want to use the CAT12 and SPM12 graphical user interface, you can use the cat_standalone.sh script located in the cat12 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 SPM12. Please note that the supplied standalone batches must be called in CAT12 expert mode and this script only works with newer CAT12 versions from r1984 onwards.

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 CAT12 in expert mode. Also, the flag "-m" now defines the Matlab command and "-s" the SPM12 folder, but can be skipped if they are found automatically. For example, to preprocess (segment) files, you can call:


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

See the standalone version for more examples.

Use of CAT12

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

Important

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

DICOM Import

Use "DICOM Import" from the SPM12 GUI.

Preprocessing

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

Smoothing of Volume Data
Use "Smooth" from the SPM12 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 "Smooth" from the SPM12 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 surface data is 12mm. In order to use the data for machine learning with NeuroMiner no smoothing is necessary and a the filter size should be set to "0".

Estimate and Save Quality Measures for Volume and Surface Data

Use "Data Quality -> Check Sample Homogeneity for Very Large Samples Using Mean z-Score" from the CAT12 GUI.

Estimate and Save Weighted Overall Image Quality

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

Estimate Total Intra-cranial Volume (TIV)

Use "Get TIV" from the CAT12 GUI.

Optional (with graphical output):
Check Sample Homogeneity for Volume and Surface Data

Use "Data Quality -> Check Data Homogeneity" from the CAT12 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 CAT12 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 CAT12 GUI and select smoothed gray/white matter segmentations (modulated normalized or affine registered DARTEL export).
Use "Surface Tools -> Save Volume Data as mat-File" from the CAT12 GUI and select resampled and smoothed surface data.

Contact