SPM2 batch engine

Summary

This SPM2 batch engine provides a way to automize analyses with the popular SPM software package (version 2), a toolbox with large set of MATLAB functions intended for medical image analysis (http://www.fil.ion.ucl.ac.uk/spm/). It is used mainly for analysis of MRI, fMRI and PET data. SPM is an abbreviation of "Statistical Parametrical Mapping", the guiding principle underlying the software package. The SPM toolbox is written in Matlab code, and computationally expensive operations are passed to compiled C-routines. The methods in this package are well documented in a set of peer-reviewed papers in international scientific journals (see SPM web pages). SPM's matlab and performance-optimized C source code is underlying the GNU GPL license and is freely available for download.

SPM2's elaborate Graphical User Interface (GUI) is complete, but doesn't allow a high degree of automization for large data sets derived from multiple patients/subjects. Furthermore, the GUI is written in a 'feedforward' manner, each of the many choices/settings are provided in a subsequent step, without an option to return to previous settings. Finally, when making an error, the GUI bails out with an error message and the process will have to be started all over again.
The latter makes the GUI quite cumbersome in clinical practice or research.

When using this batch engine, which is also written in Matlab, one can fill in a large structure containing most of the options and information one would otherwise provide to the SPM2 GUI. This structure can be passed to our SPM2 batch engine that will then execute all the necessary functions in the official SPM2 toolbox, identical to when the official SPM2 GUI is used. Importantly, we do not intend to alter the actual steps in the analysis, but merely provide a way to automize the analysis of large datasets from multiple subjects. This engine is not complete yet, but covers the most important analyses by now and will be updated frequently.

Disclaimer

Although it is already used succesfully in our labs, we consider this a Beta version, so use it at your own risk. We hereby denounce any responsibility for all the harm or physical injuries this code will undoubtedlty cause to the innocent user. It is intended for users with at least some basic knowledge of the Matlab programming language.

Features

By now, the batch engine (implemented in spm_batch.m) supports the following features:

Spatial preprocessing:

- arbitrary affine transformation (as in 'display' from the GUI)
- coregsitration
- realignment
- slice timing correction
- spatial normalization
- smoothing

Statistical analysis:
- model specification (should work for multiple sessions). Implemented so far:
- event related analysis
- epoch analysis
- parametric analysis
- contrast setup and statistical map formation (T and F)
- group analysis. Implemented so far:
- T-tests
- ANOVAs (F-tests)
- Error trapping: Some general checks on the inner consistency of the
structure will be performed, and an understandable error
message will be given. Many checks will be added soon.

Implementation

With the batch engine (spm_batch.m, the function to which the structure with choices and settings will be passed), an example of how an analysis can be setup is available at the project download page (test_batch.m).

The batch engine's source code is already commented on many lines, alhough we intend to provide more comments as the project matures. An extensive syntax description of the usage of the function is provided in the beginning of the function body (or can be viewed here). When typing 'help spm_batch' in the Matlab prompt, this information will be displayed.

The engine can be used on any OS running the commercial Matlab package, some OS compatibilty checks are performed by the code. It was tested on Matlab running under Linux (Red Hat 7) and Windows XP.

The batch engine was developed by S.F.W. Neggers, at the department of Psychonomics, Utrecht University, with some help from the Division of Brain Research, Utrecht University Medical Center. Collaborators are invited to help implement more features in this batch engine.

Downloading, installing and usage.

From the link below you can download the file spm2-batch.tar.gz. Unzip this archive ('tar xzvf spm2-batch.tar.gz' in linux, use winzip or equivalent on windows), you should now have the following 4 .m files:

spm_batch.m

setup_group_bch.m

init_groupana.m

test_batch.m

Now simply copy the m-files to a directory that is in your matlab search path. Start spm2 (IMPORTANT: spm2 has to be running when using this engine!). Create a structure with all the settings (such as SPMBATCH in the example in test_batch.m), and pass it to the batch engine by typing 'spm_batch(SPMBATCH)'.

Some notes:

try and run your script creating the structure with settings (such as test_batch.m), to see if any errors arise at that level.
Make sure the directories in the fields 'work_dir' and 'workdirparent', to which the results of all the analyses will be written, exist before passing the structure to spm_batch.m. The engine won't create them for you.
A good way to obtain lists of file names (usually vertically concatenated strings) to fill in in the strcuture is the spm function spm_get. Type 'help spm_get' for more information.
Be patient, it is likely you make some errors in the analysis structure initially causing spm_batch to bail out with an obscure error message. We are currently trying to expand the minimal error trapping procedure in spm_batch that detects logical errors in this structure, and inform the user in a comprehensive manner.

Donate for spm2-batch development

If you wish, you can support the development of r2agui and other open source MR analysis tools by donating money. We will always freely distribute the tools you sponsored with your donation under an open source license, for the benefit of the scientific community.

Download files