KULeuven functions to automate SPM (fMRI)

1. Introduction & Purpose

SPM is a functional imaging analysis tool developed at the FIL. It is one of the best and most widely used fMRI post processing packages.
The package is developed as a collection of matlab (version 4 for spm96, version 5 for spm99) scripts. To the user these scripts are not visible, because SPM has an excellent user interface from which these scripts are called when pressing the buttons.
FMRI data post processing consists of several image processing/analysis steps performed sequentially on the acquired data. A standard data post processing consists of realigning the acquired images to compensate for head motion occurred during scanning, normalization of the images to a standard space, spatial smoothing and finally voxel wise statistical analysis.
In our fMRI experience, having acquired lots of data, the post processing is a lengthy and computationally heavy application. For instance, in our setup, it takes a few hours to compute the realignment of more than 1000 sequentially acquired images from one subject. So in practice, one has to sit at his workstation to start the realignment and again after an hour or so, one has to start the next step. In the meantime your workstation is so heavily loaded, that visualizing results, reading mail, surfing the web, doing other useful work becomes quite slow...
Wouldn't it be nice to have the different steps of the post processing automated?
The purpose of our functions is to automate the fmri data post processing so that we could start the post processing when leaving the lab at night, and have our results (hopefully) the next morning when we come in again. Additionally, we wanted the script to comply with the following requirements:

automate the SPM post processing for the realignment, normalization, smoothing, statistics
do this without loosing any of the imaging processing functionalities of SPM
have the possibility to perform different statistical analyses with results being written in different directories
log all actions (e.g. kind of normalization used, kernel used for smoothing, contrasts used to compute SPM(Z)maps, etc...) to a file
have a simulation mode of the automated post processing to detect common errors (e.g. missing images) before starting the real post processing

2. Methods

The general idea was to turn the SPM user interface scripts into functions that accept arguments. You write down the functions and the arguments for your fMRI experiment into a text file. Executing this text file in matlab performs all post processing steps sequentially using your arguments without you having to interact with the user interface.
Note that all the SPM code that does the post processing itself has been left unchanged as developed at the FIL.
If you want a more detailed description of the methods click here.

3. Usage

For the impatient user: read the disclaimer, download the software, install everything and run the example. Learn by example but don't forget to (e)mail us a postcard.
Or, carry on reading:

3.1. Your data (images) must be organized in a certain way
The functions are dependent on a typical organization of the images!
Let's explain this by a fmri experiment performed in one subject.
This is what we acquired sequentially.

a high resolution anatomical image

a timeseries of 120 timepoints of EPIs during e.g. semantic decision versus rest

a timeseries of 120 timepoints of EPIs during e.g. verb to noun generation versus rest

This is a good example of a bad experiment ('rest' as baseline...), but it will do nicely as example data for these functions...
The functions expect that the 2 timeseries of 120 EPI images are in separate directories. The names of these directories should be of the same length e.g. 'ts01' and 'ts02'. The anatomical images are best stored into a separate directory, and again the length of the directory name should be of the same length as the name of the EPI image directories, e.g. 'ts01' is 4 digits long so 'anat' would be a good name.
Finally, the functions will generate directories in which the results (different SPM*.mat and spm.ps files) and logs of what has been done will be written.
Thus your directory structure should look like this:

2 directories of equal 'name-length' in which the images of the corresponding timeseries are stored

1 directory of the same 'name-length' in which the anatomical image(s) are stored

Additionally the scripts will generate:

a directory 'LOG' with log files

a directory 'RESULTS' in which sub directories will hold the results of statistics

3.2. Automatisation scripts
Are described below the links:

SPM96 automation functions

SPM99 automation functions last updated on 23/aug/2000.

adapted version of spm99b functions to the final release

possibility to implement a user defined hrf function

tool for overlay of activation on tra, sag and cor slices

4. Installation of the KULeuven scripts

4.1. The first step is to download the package:

4.1.1. SPM96 scripts
spm96_kul.tar.gz, containing the matlab functions is 46763 bytes large.
spm96_kul_data.tar.gz, containing the sample data is 46197269 bytes large (45 MB!).

4.1.2. SPM99 scripts
download spm99_kul.tar.gz containing the matlab functions to automate SPM99 (final release) and some example scripts!!

4.2. The second step is to install the scripts onto your workstation:
The installation for the spm96 or spm99 sripts are almost identical. The examples below are for spm96. If you want to install scripts for spm99 just replace '96' with '99'...
On your workstation, go to the directory where the spm directory resides, e.g.
cd /usr/local/SPM (replace with your real directory names)
Extract the files by typing
gunzip -c spm96_kul.tar.gz | tar -xvf -
This will create a subdirectory 'spm96_kul' in which the scripts are stored.
Make a subdirectory, e.g. in your home directory, to store the automation scripts that you will create for your studies.
Optionally, to run the example script:
On your workstation, go to a directory that you use to store MRI data & extract the data: e.g.
cd /my_100Giga_disk/always_full/ (replace with your real directory names)
gunzip -c spm96_kul_data.tar.gz | tar -xvf -
This will create a subdirectory 'spm96_kul_data' with the example data in subdirectories.
4.3. The third step is to tell matlab where the functions are located on your workstation:
This is done by adding the directory in which the functions reside into the MATLABPATH. This is usually done in your .login file in your home directory. Ask the person who installed SPM. So, continuing with the example above you will have to add /usr/local/SPM/spm96_kul to the MATLABPATH.
Also add the directory containing the automation scripts for your studies (see 5.2) in the MATLABPATH.
4.4. The fourth step is to (e)mail us a nice postcard!
If you do so, we will keep you informed if new things happen or if bugs are reported and fixed.
And it makes us feel good... you should know that our lab is located 2 levels below ground, without windows... so mail us and make our day!

5. Stability, Bugs & Support

Although we did our best effort, the scripts probably still contain bugs.
Over the past few years we have used the scripts daily in our department, making them quite stable. Of course we tested them with our familiar fMRI setup. Your design could be quite different from ours, and thus the change that you will encounter bugs is real.
I would advise doing everything in parallel first: to start, do the post-processing manually, then repeat it with these automation functions: it MUST be identical.

One known bug: some of the comments in the code are in Dutch, our native language (This might be a feature (joke)).

As a very small fMRI group of two to three people, we CANNOT promise to answer your questions, why this or that is not working, or not implemented. However, if you find a bug (and preferably also a solution), please let us know.
Please, don't disturb the people of the FIL with questions about the (mal)functioning of our scripts.

6. About the authors & the history of the scripts

We are a research group of a University Hospital Radiology department devoted to the clinical and neuroscience applicability of fMRI. These scripts were implemented by a MD, a physicist, and a bio engineer (so, not real IT people). When we started with these scripts already in 1995 (and SPM95), we never thought that these scripts were ever going to be used by anybody else then the 3 or 4 people in our research group. Nevertheless, these scripts have become over time a quite stable and useful tool, and thus we want to share them with whoever is interested.

7. Disclaimer

The scripts are provided as is, with no guarantee whatsoever. If they kill your computer and/or your data (which of course you didn't backup) is not our responsibility.

Webpage last updated on 23/8/00. Authors: Stefan Sunaert & Erik Beatse.