Skip to content

Module 7 CAT12 VBM

Jump to bottom
Jared Tanner edited this page Mar 6, 2026 · 24 revisions

What is a VBM analysis?

Voxel-based morphometry (VBM) allows you to assess group level behavioral relationships or group difference in gray matter structure (white matter can be done as well but typically isn't). It is based on estimations of brain matter density. Density is a proportion (think of it like the volume of a structure divided by head size).

As a side note: There’s some debate whether or not VBM measures volume or density. What it does depends on the tool and how the data are processed. Some processing of data for a VBM does what is called a modulation, which effectively transforms the density value into a volume (in effect, removes the adjustment for head size [this isn’t what’s going on but is close enough for our purposes]). However, there’s not clear consensus if the value is a volume or a density so I usually default to calling what you are comparing density, just to be safe.

In practice we are measuring gray matter volume differences or correlations with a VBM analysis; however, because there are additional factors to consider (e.g., whether or not to also include head size as a covariate: https://link.springer.com/article/10.1007/s11682-016-9656-9Links to an external site.), I’ll use density and volume interchangeably when talking about an VBM analysis and usually default to density.

Watch this video comparing FreeSurfer with VBM: https://www.youtube.com/watch?v=TT8FJUq-QKo

If you’re interested in learning more about VBM, this is an important paper to read: https://www.fil.ion.ucl.ac.uk/spm/doc/papers/am_vbmreview.pdf

“VBM can be thought of as comparing the relative concentration of gray or white matter structures in the spatially normalized images (i.e. the proportion of gray or white matter to all tissue types within a region). There are cases, however, when the objective of the study is to identify regional differences in the volume of a particular tissue (gray or white matter), which requires the information about absolute volumes to be preserved. Here a further processing step, which is usually referred to as “modulation”, can be incorporated to compensate for the effect of spatial normalisation…. In short, the multiplication of the spatially normalised gray matter (or other tissue class) by its relative volume before and after warping has critical implications for the interpretation of what VBM is actually testing for. Without this adjustment, VBM can be thought of as comparing the relative concentration of gray or white matter structures in the spatially normalized images. With the adjustment, VBM can be thought of as comparing the absolute volume of gray or white matter structures. The two approaches are known as “non-modulated” and “modulated” VBM, respectively.”

So what this means is just think of this as a volume and don’t worry about the density aspect.

Note that this will require about 4-8 hours of processing (you don't have to do anything during that time), but factor that into your schedule for working on this. Once that is done, the rest is relatively quick to do.

Once data are set up, running a VBM analysis is straightforward. The most challenging parts are quality assessment and setting up the GLM (General Linear Model). You do not need to worry about quality assessment for the class assignment. T1-weighted images are provided.

For the VBM analysis, organization of files depends on what type of analysis you are doing. If you are running a between-group analysis, the convention is to group or name all the "control" MRIs so they group together and all the "patient" MRIs so they group together. For example, prepend con_ for control and pat_ for patient. In CAT12 it's easiest to have all group MRI in one directory and another group in another directory. For the homework, this has already been done for you.

Data are stored in a directory called vbm, which is in /blue/psy4930/share/data/Module7

Copy that to your directory using the Terminal (or can use the file system in the browser in ood.ufl.edu): cp -fr /blue/psy4930/share/data/Module7/vbm /blue/psy4930/share/students/{gatorlink}/ Use a Matlab session for this (I've had good experiences with Matlab R2024b but you can try a different version; I had some problems with 2025b). Request 8 cores, about 32 GB of RAM, and to be safe, request at least 24 hours. You will need to use psy4930-b under QoS (refer to the video) and make sure Cluster partition has "default" selected.

My tutorial is mostly based on one created by Dr. Jahn. You can refer to these. We are using different data but his guide is a great resource.

Step 1: https://andysbrainbook.readthedocs.io/en/latest/CAT12/CAT12_03_Preprocessing.html

Step 2: https://andysbrainbook.readthedocs.io/en/latest/CAT12/CAT12_04_Analysis.html

Here is the walk-through video: https://youtu.be/02gFRDUjlhY

Again, the preprocessing can take 6+ hours, so plan accordingly.

Note: Sometimes not all the brains complete preprocessing. The Matlab window should tell you how many completed. Another way to check is to run a command like this from your vbm directory:

for d in {Con,Sz}/sub-*/; do sub=$(basename "$d"); [ ! -f "${d}anat/catreport_${sub}_T1w.pdf" ] && echo "Missing: $d"; done

That will tell you which brains need to be re-processed. Select any that failed and process them before moving to the VBM analysis.

Below is a guide based on the video walk-through. Please refer to the guide by Dr. Jahn if anything is unclear.

https://andysbrainbook.readthedocs.io/en/latest/CAT12/CAT12_03_Preprocessing.html

https://andysbrainbook.readthedocs.io/en/latest/CAT12/CAT12_04_Analysis.html

Beginner Tutorial: Running a VBM Analysis with CAT12, SPM12, and MATLAB

This tutorial explains how to run a voxel-based morphometry (VBM) analysis on structural MRI data using CAT12, SPM12, and MATLAB.

What VBM does

Voxel-based morphometry (VBM) is a method for testing whether local gray matter volume or concentration differs across the brain. In a typical study, you start with T1-weighted structural MRI scans, preprocess them, and then test for voxelwise differences between groups.

In the example shown in the video, the goal is to compare two groups:

  • controls
  • people with schizophrenia

The same general workflow also applies to many other two-group studies.

Overview of the workflow

You will complete the analysis in this order:

  1. Copy the VBM data into your own writable directory.
  2. Launch MATLAB on HiPerGator.
  3. Add SPM12 to the MATLAB path.
  4. Open CAT12 through SPM.
  5. Run segmentation/preprocessing on all structural scans.
  6. Confirm which subjects finished successfully.
  7. Reprocess any subjects that failed.
  8. Extract total intracranial volume (TIV).
  9. Set up the second-level statistical model.
  10. Estimate the model and define group contrasts.
  11. Review the results carefully.

Before you start

You should already have:

  • access to HiPerGator
  • access to MATLAB through an interactive session
  • access to an SPM12 installation that includes CAT12
  • a folder containing structural MRI files in .nii or .nii.gz format
  • two subject groups organized into separate folders

This tutorial assumes your data are already arranged in two folders, one per group, and that each subject has a structural scan inside that folder structure.

Step 1: Copy the data into your own directory

Do not work directly in a shared class or lab directory. Copy the full VBM folder into a location that you own and can write to.

You can copy the folder with either the file browser or the terminal.

Option A: Copy with the file browser

  1. Go to the shared data location.
  2. Find the VBM folder or Module7 folder.
  3. Copy it.
  4. Navigate to your own working directory.
  5. Paste it there.

Your goal is to create your own full copy of the analysis folder, not to edit the shared original.

Option B: Copy with the terminal

A recursive copy command was shown in the video. The exact paths will depend on your environment, but the general form is:

cp -fR /blue/psy4930/share/data/Module7 /blue/psy4930/$USER/

Important points:

  • -R means recursive, so the entire folder tree is copied.
  • the destination should be your folder
  • check that the copy finished before moving on

After copying, confirm that the folder structure looks correct and that both group folders are present.

Step 2: Launch MATLAB on HiPerGator

Launch MATLAB through an interactive session.

The video noted that MATLAB 2025b appeared unstable for this workflow, so use MATLAB 2024b unless you know a newer version works in your environment.

Suggested settings:

  • MATLAB version: 2024b
  • cores: 8
  • memory: 32 GB RAM
  • time: 24 hours
  • account: psy4930
  • QoS: psy4930-b

Preprocessing often takes several hours. A full run may take 6 hours or more, depending on the data and system load.

Step 3: Add SPM12 to the MATLAB path

Once MATLAB opens, make sure SPM12 is on the MATLAB path.

What to do

  1. In MATLAB, open Set Path.
  2. Add the folder containing SPM12.
  3. Save the path.

Example SPM12 location:

/blue/psy4930/share/data/neurotools/spm12

Common issue: MATLAB cannot save the default path

A common problem is that MATLAB cannot save changes to the default path because the installation directory is protected.

If that happens:

  1. choose to save the path somewhere else
  2. save it to a writable location
  3. use your home directory unless you have another personal directory you prefer

Do not save your path settings into a shared class or lab directory unless that directory belongs to you.

Quick test

In the MATLAB command window, type:

spm

If SPM opens without an error, the path is working.

Step 4: Open CAT12 through SPM

After SPM opens:

  1. click Toolbox
  2. choose CAT12

If CAT12 does not appear, one of two things is usually wrong:

  • you added the wrong SPM12 folder
  • that SPM installation does not include CAT12

Fix that before moving on.

Step 5: Run segmentation on all structural scans

This is the main preprocessing step for the VBM analysis.

Open the segmentation module

In CAT12:

  1. click Segment
  2. choose Volumes
  3. navigate to your copied VBM folder, not the shared original
  4. go to the top-level folder that contains both groups
  5. use a file filter such as nii.*
  6. use recursive selection so CAT12 searches through subfolders

What you should see

In the example dataset, CAT12 should find 40 files total:

  • 20 controls
  • 20 individuals with schizophrenia

The control scans appear first because the folders are arranged so the control group comes first alphabetically. Keeping that order consistent is helpful later when you define the group model.

If CAT12 does not find the expected number of files, stop and fix the problem before continuing. Usually this means one of the following:

  • some files did not copy
  • you selected the wrong folder
  • the file filter is wrong
  • recursive selection was not used

Run preprocessing

After all expected files are selected:

  1. click Done
  2. confirm the file list looks correct
  3. click Run

CAT12 will then process each subject.

Step 6: Wait for preprocessing to finish

CAT12 preprocessing takes time. Do not assume it is finished just because MATLAB is still open.

How to monitor progress

Watch the MATLAB command window and CAT12 job windows. You should see subjects being processed one by one. CAT12 also generates logs that can help you identify failures.

A practical approach is to come back later and check the MATLAB session directly rather than expecting an email notification.

Step 7: Check which subjects finished successfully

This is one of the most important parts of the workflow.

In the video example, only 27 of 40 subjects finished on the first attempt. The remaining 13 were incomplete or unknown. That means those subjects were not ready for group-level analysis.

How to tell whether a subject finished

For a completed subject, the subject's anat folder should usually contain:

  • many output files
  • roughly 27 files in the example workflow
  • a CAT report PDF

A completed subject typically has a file like this:

anat/catreport_sub-XXXX_T1w.pdf

If the CAT report is present, preprocessing likely completed successfully.

What failed output often looks like

A failed subject may have:

  • only a few files in the anat folder
  • no CAT report

Practical rule

Do not move on to group-level statistics until you know exactly which subjects finished and which did not.

Step 8: Reprocess any failed subjects

If all subjects completed successfully, skip this step.

If some subjects failed, identify the incomplete cases and rerun only those subjects.

How to identify missing subjects

You can do this in either of two ways:

  1. inspect subject folders one by one for missing CAT reports
  2. use a terminal command to list incomplete cases automatically

From your VBM directory, a command like this can help:

for d in {Con,Sz}/sub-*/; do
  sub=$(basename "$d")
  [ ! -f "${d}anat/catreport_${sub}_T1w.pdf" ] && echo "Missing: $d"
done

This command assumes:

  • your group folders are named Con and Sz
  • subject folders are named like sub-001
  • CAT reports are stored in each subject's anat folder

If your folder names differ, update the command accordingly.

Reprocessing workflow

To rerun failed cases:

  1. go back to CAT12 > Segment > Volumes
  2. select only the failed subject scans
  3. run segmentation again

Repeat until all intended subjects finish successfully.

Step 9: Extract total intracranial volume (TIV)

Once preprocessing is complete, extract total intracranial volume (TIV).

Why TIV matters

People differ in overall head and brain size. Even after spatial normalization, those differences can still influence the VBM results. Including TIV as a covariate helps account for those global size differences.

How to extract TIV in CAT12

From the CAT12 window:

  1. choose the option to get total intracranial volume
  2. point CAT12 to the processed subject output files
  3. save the extracted values

In the example dataset, CAT12 should find 40 text files containing intracranial volume information and then save a summary file such as:

TIV.txt

What to check

Open the TIV output file and confirm:

  • there is one TIV value per successfully processed subject
  • the number of rows matches the number of subjects you plan to analyze
  • the order of TIV values matches the order of subjects in your second-level model

That last point is critical. A correct TIV file in the wrong subject order is still wrong.

Step 10: Set up the second-level group model

After preprocessing and TIV extraction, you are ready for group-level statistics.

Create an output directory

Create a new folder for the second-level analysis, for example:

2ndLevel

You can create it:

  • from the MATLAB file browser
  • from the HiPerGator file browser
  • from a terminal

Example terminal command:

mkdir -p 2ndLevel

Define the factor

For a two-group analysis:

  1. create a factor called group
  2. set the number of levels to 2
  3. create two cells, one for each group

Assign scans to the correct cells

Be consistent about group ordering.

For example:

  • Cell 1 = controls
  • Cell 2 = schizophrenia

If controls came first during file selection and TIV extraction, keep that same ordering here.

Add covariates

Add TIV as a covariate.

Depending on your study, you may also add other covariates such as:

  • age
  • sex
  • site

Only include covariates if you understand how they are coded and they are aligned correctly with the subject order.

Estimate the model

Once the design matrix is set up, run the model estimation step.

Step 11: Define contrasts

After estimation, define the contrasts you want to test.

For a two-group design, the usual first contrasts are:

  • Group 1 > Group 2 with weights 1 -1 (in the video I called this Con-Sz)
  • Group 2 > Group 1 with weights -1 1 (in the video I called this Sz-Con)

If your model is ordered as controls first and schizophrenia second, that becomes:

  • Con > Sz = 1 -1
  • Sz > Con = -1 1

Interpret these carefully. The meaning of a positive result depends entirely on how you ordered the groups in the model.

Step 12: Review the results carefully

Once the model is estimated and contrasts are run, review the statistical maps and tables carefully.

At minimum, check the following

  • the design matrix looks reasonable
  • the subject count matches the subjects you intended to analyze
  • covariates were entered correctly
  • the contrast direction matches your coding
  • significant clusters are anatomically plausible

Important caution

A significant cluster is only meaningful if the preprocessing and model setup were correct. Subject-order mistakes, missing subjects, or mismatched TIV values can invalidate the analysis.

Recommended beginner checklist

Use this checklist before trusting your results.

Data setup

  • I copied the VBM folder into my own directory.
  • I am not working in the shared directory.
  • My two groups are in separate folders.

MATLAB / SPM / CAT12 setup

  • MATLAB launched successfully.
  • SPM12 opens when I type spm.
  • CAT12 appears in the SPM toolbox menu.

Segmentation

  • I selected the correct .nii or .nii.gz files recursively.
  • The total number of selected files matches what I expected.
  • CAT12 finished processing all intended subjects.
  • Each completed subject has a CAT report.

Reprocessing

  • Any failed subjects were identified.
  • Failed subjects were rerun until complete.

TIV and statistics

  • I extracted TIV values.
  • TIV order matches subject order.
  • My second-level factor has two levels.
  • I assigned the correct group scans to each cell.
  • My contrasts match my group coding.

Common problems and fixes

Problem 1: SPM does not open

Cause: SPM12 is not on the MATLAB path.

Fix: Add the correct SPM12 folder using Set Path and save the path to a writable location such as your home directory.

Problem 2: CAT12 is missing from the toolbox

Cause: The wrong SPM folder was added, or CAT12 is not included in that installation.

Fix: Recheck the SPM12 location and make sure CAT12 is present.

Problem 3: CAT12 does not find all expected MRI files

Cause: Wrong folder, wrong file filter, incomplete copy, or recursive selection was not used.

Fix: Go back to your copied VBM folder, use the correct filter, enable recursive selection, and confirm all files copied correctly.

Problem 4: Some subjects do not finish processing

Cause: CAT12 preprocessing failed for those cases.

Fix: Look for missing CAT reports, identify the failed subjects, and rerun segmentation on just those subjects.

Problem 5: MATLAB cannot save the path

Cause: You are trying to write to a protected location.

Fix: Save the path to your home directory or another writable location.

Problem 6: MATLAB 2025b crashes or behaves unpredictably

Cause: The video suggested a compatibility problem with that version.

Fix: Use MATLAB 2024b unless you know a newer version works in your setup.

Plain-language summary

A VBM analysis with CAT12 has two major stages.

First, you preprocess each subject's structural scan with CAT12. This produces tissue-segmented, normalized outputs for each brain. Before doing any statistics, you must confirm that every intended subject actually finished and rerun any failures.

Second, you build a second-level model using the processed scans, assign them to groups, and include covariates such as TIV. If your subject order and covariate order are correct, you can then test for group differences across the brain.

Final advice

The most common beginner mistakes in this workflow are usually organizational, not technical.

They include:

  • working in the wrong directory
  • selecting the wrong files
  • missing failed preprocessing cases
  • mismatching subject order between scans and covariates
  • forgetting which group was coded first

If you stay organized and verify each step before moving on, you avoid most of the serious problems.

What You Turn In

For this assignment, please upload a screenshot of the Matlab session showing some results.

Clone this wiki locally