spm_batch, documentation

What is spm_batch ?

spm_batch is a collection of matlab-scripts that make the spm-batch feature accessible to non-programmers. This allows you to perform the whole pre-processing of several subjects with a single command: preprocess.
Of course before you start the (batch) job, you have to specify how the pre-processing should be performed. When using spm_batch, this is done by editing some configuration-file accordingly.

When can I use spm_batch ?

1. For the moment spm_batch runs only under Windows. This Limitation is due to some system calls providing file manipulations (moving, delete and copy) I've used because of their much better performance compared to the matlab buidin commands. Here, a port to UNIX should be no problem for the experienced matlab user.
2. your first (or with minor modifications the last) functional volume scan and the anatomical scan (MPRage or FLASH) must be naturally coregistered i.e. the subjects must not moved their head between the two subsequently recorded scans (see visionToSPM). In addition you must ensure that not only the bitmaps but also position and orientation of the scans are transformed to SPM world. If you are recording at a SIEMENS magnetom vision scanner you can use visionToSPM for this purpose.

Installation

Unzip the package into your matlab working directory. Three directories will be generated (spm_batch, spm99_Modifications and myStudy-Part1). If you have download the package without example Data the last directory is empty and provides an template for the directory-structure required by spm_batch (see below).

1. make a backup of the five files in your spm directory, named like those files in the directory spm99_Modifications. Now copy the files in spm99_Modifications to your spm directory.

2. add the directory spm_batch to the path in matlab.

3. move the directory myStudy-Part1 to where ever your fmri-dataspace is.

Running the example

Because error tracing of a miss-configured batch-job is extremely bothersome I strongly recommend you to get some experience with batch-processing by running the example first.

The first step after installation (as in real life) is to convert the raw image-files to SPM. Again: bitmaps and orientation/position of the scans must converted to SPM world (you can use visionToSPM for this).
The example data contains the directory-structure for two subjects. However only the structure of subject1 contains anatomical and functional data. The anatomical raw images (*.ima) are contained in subject1/Anatom/Mpr/. The functional data for two sessions in this example is contained in subject1/Session1/ima and subject1/Session2/ima respectively.
The structure for subject2 is empty and provides you with an template of the directory-structure required by spm_batch. You should use this template when you prepare your own data for batch processing. Running the batch job on a subject not organized in this directory structure without respective adjustments in the batch-scripts will break down the batch-job !

1. Convert the raw image files to SPM world. Output files must be located in the same directories as the files from which they are generated. The prefix of the functional *.mat files (the *.mat files only) must be ra !

2. Open the file process.m in the directory spm_batch with the matlab editor and:

a: change the variable diskdir = { 'F:\myStudy-part1', 'I:\myStudy-part2' }; to wherever you have moved the directory myStudy-part1. The second entry allows you to access the data of subjects distributed over multiple Partitions (Windows does not know anything about mounting ...).

b: check the entries in dInd = [ 1 1 ]; For each Subject (the first, the second and so on) you have to specify here under which entry in diskdir the directory of the respective subject is located. In the example this is 1 1.

c:adjust the paths given in templateDir and batchDir to wherever your SPM99 templates and the spm_batch scripts are.

d: the array uind specifies on which subjects given by the uind^th value of userdir the bach-job should be performed. Here in the example we work only on the first subject: uInd = [ 1];. To work on Subject1 and Subject2 for example uind should be: uInd = [ 1 2];.

e: to specify the session to work on set sesDir appropriately.

f: set mprImg to match the name of the anatomical scan in analyze format: mprImg = [ WR_SEP_USER_DIR '\Anatom\Mpr\myAnatomicalScan.img'];

3. You are ready to start the example. Type preprocess at the matlab command line. If everything works fine, after the batch has finished you will find the raw image files *.img and *.hdr in the directory Subject1/Session1,2/img/raw, the realigned images in .../realignd and the smoothed final images in ..../smoothed. The normalized anatomical scan will be in Subject1/Anatom/Mpr.

Troubleshooting: if it works not fine, check all the entries in preprocess.m carefully. Check whether the anatomical file name is given/located correctly.

Before restarting the batch, ensure that for all sessions and subjects the directories .../realignd .../normalized and .../smoothed are empty (you have to clean them manually). In .../raw only the raw *.img and *.hdr are allowed. Other files from preprocessing (a*.img, ra*.img *.txt) located in this directory when preprocess is started will break down the batch-job ! The ra*.mat files generated by the conversion tool (for example visionToSPM) must reside in Subject1/Session1,2/ima when the batch is started (they will always be there if you do not move them).

What is the normalization procedure applied in the example ?

Not all the preprocessing strategies can be made completely automatic. In particular coregistration and normalization can require some user interaction. This is a general limitation to batch processing, of course.

The major prerequisite for normalization in batch mode is a natural coregistration of anatomical and functional images as described above. In the example the anatomical scan is normalized to the T1 template. The resulting transformation (see the Thesis of John Ashburner) is applied subsequently to the functional data. This strategy does not correct the susceptibility-bias of the EPI-technique, however I believe this proceeding ensures an optimal overlap of functional brain-regions between different subjects which is important for an analysis over the whole group.
Besides by a few modifications a normalization of the functional images onto functional template also can performed in batch-mode.

Adjusting the scripts in spm_batch

The best way to configure your own the batch most probably is to modify the example in a iterative step and try procedure to fit your requirements.

First at all: you always should test your configuration using the example data before you start the batch on the whole group of subjects. Otherwise you will not save time using batch processing but you will waste a lot of time, believe me ! This can be easily done by adding a testSubject to you the main study-directory (in the example called: myStudy-part1). Before you start the whole process, set uind to point on the testSubject only (uind = [n], n == index of the testSubject in userdir) and run the batch.

In the beginning you may only modify the file preprocess.m to fit your demands. To change more general aspects of the preprocessing such as the normalization strategy you need to have some programming skills. The modifications will have to be made in the files given below.

All the parameters you specify using SPM in interactive mode can be specified in batch mode too. In batch-mode they are specified in: