SPM2 batch files

Introduction

This page describes batch files we use to analyze data from functional neuroimaging experiments. SPM2 is a popular neuroimaging tool that runs from Matlab. SPM2 is flexible and powerful, but also requires a lot of user input. These matlab script files allow you to process an entire dataset quickly. Furthermore, you can keep the script file with your original data, so you can go back and check what options you used for analysis. There are three main scripts and two utility scripts:

  1. cr_preproc_anat: This script is designed to conduct spatial processing on anatomical scans. It can correct for field inhomogeneity and normalize your T1 scans.
  2. cr_preproc_func: This script spatial preprocesses functional data. It can realign (motion correct), EPI unwarp, slice time correct, normalize and smooth your functional dataset.
  3. cr_stats_fixed: A script for statistical analysis of data. This script assumed that the data is already spatially preprocessed (i.e. run cr_preproc_func prior to statistical analysis).
  4. cr_delete: Do not edit this file: This utility simply deletes a series of images. This script is called by cr_preproc_func to clean up your hard disk.
  5. cr_filedir_exists: Do not edit this file: A utility for making sure that a specific file exists. This m file is used by other scripts to warn the user if they attempt to process data that does not exist.

These scripts are heavily modified versions of the scripts distributed with the SPM2 sample datasets. Changes were made by Bianca De Haan and Chris Rorden. Our changes allow the user to process data from multiple subjects across multiple sessions. We have also added warning messages that attempt to tell the user in plain English why a script has failed.

Warning: Used appropriately, these scripts have saved us a lot of time. However, used foolishly they can lead to misleading results. We have tried to test these scripts extensively, but not all options may be implemented. Use at your own risk.

Download

To download the latest version of our scripts and a very small sample dataset, click here. You need to place the .m files in your Matlab path (typically the same folder as SPM).

Data: Filenames and File Paths

These scripts expect your images to be given specific names and stored in particular folders. Thus, the names and paths of files are rigidly defined. While this might seem like a nuisance, it is also a nice way to keep your data organized. You can edit the first few lines of each script to describe the names of the folders where your data will be stored. For example, consider cr_preproc_func (the text after the % are comments, and are ignored by Matlab):

cwd = 'C:\sensefx'; %base path
nsub = 2; %number of subjects
subname = {'CR','HAM'}; %foldername for each subject CASE SENSITIVE
nses = 2; %numer of sessions per subject
sesname = {'sesA','sesB'}; %name for each session, separate with commas CASE SENSITIVE

This code will process data from two subjects, with each individual having data from two sessions. The corresponding images for this setup is illustrated on the figure on the right, or below as text:

C:\sensefx\CR\sesA\CRsesA001.img...CRsesAxxx.img
C:\sensefx\CR\sesB\CRsesB001.img...CRsesBxxx.img
C:\sensefx\HAM\sesA\HAMsesA001.img...HAMsesAxxx.img
C:\sensefx\HAM\sesB\HAMsesB001.img...HAMsesBxxx.img

Choosing the correct settings

The scripts allow you to decide what steps you want to use for your data. The first few lines of the .m files allow you to describe both the location of the data and what optional processing you want to conduct. Here are some comments for the different scripts.

  1. cr_preproc_anat: This script is designed to conduct spatial processing on anatomical scans. It can correct for field inhomogeneity and normalize your T1 scans.
    1. computebiascorr: use this to homogeneity correct your data. Set this to 1 if the brightness of white matter varies across different regions, set to 0 if the image birghtness is fairly uniform. Typically, use bias correction for data from 3.0 Tesla MRI systems and ignore for scans from 1.5 Tesla systems. However, different scanners and protocols will have different levels of inhomogeneity.
    2. dnrm.estimate.cutoff: Leave this value at 25 unless you want to switch off non-linear normalization. Setting this value to 'Inf' (Infinity) will lead to a linear-only normalization. Set to 'Inf' if you are processing data from brain injured individuals or if your images have large regions of signal dropout that does not match the templates.
    3. norm_template: Image used as a template to match. Keep this as 'T1.mnc' for standard T1-weighted anatomical scans. Change to 'T2.mnc' for T2-weighted images.
  2. cr_preproc_func: This script spatial preprocesses functional data. It can realign (motion correct), EPI unwarp, slice time correct, normalize and smooth your functional dataset.
    1. flip_images: Decide if you want to left-right flip your images. It is always worth processing datasets where you know the left/right orientation of your data (e.g. use a fiducial marker to mark one side of the head during scanning).
    2. Unwarp: This turns EPI unwarping off (0) or on (1). EPI unwarping generally helps reduce motion related image distortion, but is very slow. I suggest leaving this switched on (1).
    3. reslicevoxelsize: I typically request images be resliced to an isotropic 3mm ([3 3 3]), if your original fMRI data has high spatial resolution (e.g. 128x128 acquisition matrix) you may prefer to choose a higher resolution, (e.g. 2mm isotropic, [2 2 2]).
    4. SmoothFWHMmm: The smoothing full width half maximum is typically set to about three times your reslicevoxelsize, e.g. I use an 8mm (8) FWHM. Note that this smoothing function is a tuning filter: if you are looking for a large region you may want to use a larger FWHM.
    5. cutoff_norm: Normalization cutoff. Leave this value at 25 unless you want to switch off non-linear normalization. Setting this value to 'Inf' (Infinity) will lead to a linear-only normalization. Set to 'Inf' if you are processing data from brain injured individuals or if your images have large regions of signal dropout that does not match the templates.
    6. Slice_Time_Correct: Turn slice timing correction on (1) or off (0). I suggest switching this off for block designs and situations where your interscan interval is very short (<1.5sec) or very long (>5 seconds). This can improve your statistical power for event related designs, particularly for the 1st and final slices of each volume. If you turn on Slice_Time_Correct, you also need to specify the interscan interval (TR) and number of slices per volume (num_slices).
  3. cr_stats_fixed: A script for statistical analysis of data. This script assumed that the data is already spatially preprocessed (i.e. run cr_preproc_func prior to statistical analysis).
    1. HighPassFilterSec: For event related designs, set this to 128 seconds. Set this to two times the length of an on-off cycle (e.g. if you did a 12 second on, 12-second off block paradigm you would want to set this value to 48).
    2. TR: make sure you accurately specify the true interscan interval.
    3. global_normalization: Use 'None' to use the raw intensity values. Use 'Scaling' to make the overall brightness of a volume constant. Scaling can improve signal when the scanner signal drifts, however if there is widespread brain activity in one condition, the true extent of this activity is supressed (as the overall signal is reduced).
    4. ncon: set the number of conditions in your comparison.
    5. ncontrast: Number of statistical t-test contrasts you want to conduct.
    6. contrast_content{x}: specify each each contrast you want to conduct, for example [1 0 0 0 0 0] would show activity that was greater in the first condition than other periods, while [1 0 -1 0 0 0] would identify regions that showed great activity in condition 1 than condition 2.
      • Warning: Note that [1 -1 0 0 0] would not contrast the first condition with the second condition (it compares the first condition activation with the temporal derivative for the 1st condition).
      • Warning: You must explicitly decribe each column, e.g. [1 0 -1] will fail (the script does not zero-pad contrasts).
      • Warning: Adding/deleting conditions and sessions will change the number of columns. For example, is you have two conditions (C1 and C2) with their temporal derivatives (tC1 and tC2 repectively) with three sessions (s1, s2 and s3), the order of the columns will be [C1 tC1 C2 tC2 s1 s2 s3]. Adding a third condition (C3) would change the way you define contrasts [C1 tC1 C2 tC2 C3 tC3 s1 s2 s3].
    7. nVol: Number of volumes collected for each participant and for each session. For example, if 80 scans were collected in the first session and 93 scans were collected in the second session you would want to set this to [80 93]
    8. consets{x}: set the condition onsets for each condition. For example, if condition 1's stimuli occurred 25, 32 and 37 seconds after the start of the first scan you would write consets{1} = [25, 32, 37]
    9. condur{x}: set the condition duration for each stimuli. Use zero for events, and number of seconds for block designs. E.G. if condition 1 had 3 blocks that lasted 3, 4 and 9 seconds respectively, you would write [3, 4, 9]. Note: the number of condur{x} must match the number of consets{x}.

 

Notes

Other sources for SPM2 scripts include