SPM8 batch wrapper

  • Print
Details
Last Updated on Sunday, 06 May 2012 08:34
Written by P.F.C. Groot

SPM wrapper batch iconspmwrapperlib is a small Matlab toolbox which assists in running multi-subject or multi-session batches using SPM8. Main functionality of the toolbox is to use batch templates that are created by the SPM batch editor and execute those templates on a structured dataset. A flexible mechanism is used to define parameters and directory structures (using user-defined symbols). Symbols sets are used to provide a mechanism to iterate over subjects, sessions and parameters. Note that the toolbox is not specific for running SPM-jobs, but can act as general purpose job-iterator with other scripts as well.

Installation

Download spmwrapperlib.zip, unzip the file on your computer and add the toolbox location to the Matlab path. That's it! Also make sure you already have SPM8 installed properly.

Script structure

Initialisation

Most scripts start with a few initialisation lines. The initialisation lines in the example scripts are used to make sure all required toolboxes can be found by Matlab. If one of these lines fail, you probably forgot to add the toolbox to the Matlab path. You should at least add the smpwrapperlib toolbox to the Matlab path. If you are creating an SPM-job, SPM itself should also be installed properly off course. The function CheckSPM('FMRI') will make sure SPM is available and configured. CheckSPM also returns the location (and version) of SPM, so it is rather easy to get the paths of files that are located in the templates and apriori subfolders of SPM. (You need these if you would like to make your script independent of the location of the SPM folder.) The rest of the initialisation code is just plain Matlab code, and can be customized if needed.

Job data structure

The most important part of the wrapper script is the definition of a data structure that holds all the input information that is required to run the job. Typically this structure contains definitions for input files, subject identifiers, output folders and other parameters. The information that can be stored in this data structure is very flexible and can be changed or expanded, depending on your requirements. In the example scripts this structure is called 'db'. The db data structure has the following fields:

  • db.jobfn
    This field is used to define which function should be called at each iteration when running the script. Note that Matlab requires the @-character in front of a function name to refer to a function. (Also see the Job Function section below.)
  • db.job
    This field contains the filepath of the SPM job template. (See also the SPM batch template section below.)
  • db.diaryfile
    Optional. This item can be defined to create a log or diary file at the specified location. Just enter a full path of the diary file that should be created. Note that all diary information will be appended to the specified file.
  • db.symbols
    User defined parameters. The symbols substructure can be used to specify one or more parameters, simply by adding new fields to the symbols structure (for example: db.symbols.JOBFILE = 'myjob.mat';). You can add as many parameters as you require in the job function. Typical symbols are the location of the input files, the name of the image files, the name of the job file, etc. An important property of a symbol definition is that symbols can be re-used as part of a string value of another symbol. You can do this by placing <>-brackets around the symbol name (for example 'db.job = '<JOBDIR>/<JOBFILE>'').
  • db.sets
    User defined parameter sets. Parameter sets are similar to symbol definitions, except that a single set can contain more that one value. Just use a matlab cell-array to define a set. For example: db.sets.SUBJECT = { 'SUBJ001', 'SUBJ003', 'SUBJ009' }. When a script is executed, spmwrapperlib will pick a value from each set and use that value as regular symbol definition (for example db.SUBJECT = 'SUBJ001' for the first iteration, db.SUBJECT = 'SUBJ003' for the second iteration, etc.) Also, spmwrapperlib will use all possible permutations when there are two or more sets.
  • db.stopaftererrors
    This optional parameter can be defined to specify how many errors are allowed before job-iteration will be stopped. A value of zero will abort the batch after the very first error. The batch will never stop on errors if Matlab's positive infinite value is used:  Inf

 

Running the job

Finally, an spmwrapper script should call the LoopDB function to execute all individual job iterations that can be constructed with the defined symbol sets. The easiest way to call this function is to pass the job data structure as argument: LoopDB(db)

The job function

The job function is a user-defined matlab function which is called for each iteration, and where all the SPM-calculations are be performed. In general, this is the place where the symbols are used to prepare the arguments that are required by the spm_jobman function. The SPM batch template determines which arguments should be assembled. The job function itself also requires a few arguments: The first argument holds the filename of the batch template (as defined in db.job). The second argument is a copy of the db.symbols structure, but with 'real' values (i.e. <>-symbols are replaced with real values.) The job function should also return true (on success) or false (on failure).

 

Example script: running a single subject or session

This example demonstrates the use of the spmwrapperlib toolbox by running a straightforward SPM job that uses only one dataset. First download the example dataset of the face repetition priming experiment from the SPM website:

EPIs: rawepi.zip 
Structural: structural.zip

When running this script, it is assumed that both files are unzipped in the following directory: C:\spm_example_data\face_rep, and that the images are placed in their original subdirectory (RawEPI and Structural). However, you can put the data anywhere as long as the directory definition in the batch file matches. Then, download spmwrapperlib.zip, unzip the file on your computer and add the toolbox location to the Matlab path. Also make sure you already have SPM8 installed properly. The job-file face_rep_spm8_batch_job.m defines the steps required for the spatial pre-processing. The file was created using the SPM batch editor and saved as m-file. Note that 5 parameters are still undefined (i.e. have an undefined value '<-X') and a few other parameters are defined as dependency (a new feature in SPM8). The job-file is used by the master script: face_rep_spm8_batch.m. So, if all directories are setup properly you should be able to run the master batch as-is. Both m-files can be downloaded as zip file: face_rep_spm8_batch.zip

 

Example script: running multiple subjects or sessions

It is really easy to change the single-subject example and use it for a more complex dataset. Adding subjects or sessions is just a matter of adding symbols. It is also possible to split a complex batch-template into several smaller steps and run them as a sequence of batches. For example, the segmentation step could be executed as separate sub-job in an experiment where several fMRI tasks were performed during a single session. Example script coming soon...

SPM8 batch templates

At the core of each spmwrapper script you will have at least one job function (JobFunction in the first example) that eventually runs SPM using the function spm_jobman. The easiest way to use this function is to create batch-jobs using the batch editor provided by SPM. It's up to you to create the jobs required for your analysis, but there are a few things to keep in mind.

1) The new batch manager introduced in SPM8, provides a new mechanism to define relations between outputs and inputs within the same batch: Dependencies. These dependencies can be used to select the output of a previous module as input for a later module. The advantage of this, is that you don't have to keep track of all the filenames that are created when the batch is executed. You can simply refer to a previous result by using a symbolic dependency. (Although it takes some time to get used to the names listed in the dependency list)

2) The SPM job manager supports undefined parameters. In the SPM batch editor, you can now simply leave a parameter uninitialized. (You can also clear a parameter that already has a value by using the menu.) An undefined parameter is displayed with a special symbol: '<-X'. In the job-file, undefined parameters are assigned with a special text: '<UNDEFINED>'. The job manager (spm_jobman) handles undefined parameters in a special way. When spm_jobman was started in 'serial' mode, additional arguments are accepted and used to initialise undefined parameters. This provides a simple mechanism to supply new values to the undefined parameters at runtime without detailed knowledge of the underlying job structure. The main thing to keep in mind is that the order of the additional arguments must match the order of the undefined parameters in the job file.

 

Non-SPM usage

The use of symbol sets and the accompanying iteration function (LoopDb) is not specific for SPM. The spmwrapperlib toolbox provides a generic mechanism that can be used in combination with your own scripts to iterate a job function over any combination of parameter sets. The functionality can be considered as a structured and flexible alternative for programming a bunch of nested for-loops. SPM itself also contains a few functions that can be very useful by themselves. For instance, spm_select (used by GetImageList3D and GetImageList4D), is a very handy function for performing recursive file searches. Support for regular expressions makes it a very flexible lookup-function.

Downloads

matlab toolbox: spmwrapperlib.zip (updated 2012-05-06; rev 123)

spmwrapperlib example script: face_rep_spm8_batch.zip

Update history

  • rev 123: Added stopaftererrors parameter.

 

 

Free Software Disclaimer

The free software programs provided by 3TMRI.nl may be freely distributed, provided that no charge above the cost of distribution is levied, and that the disclaimer below is always attached to it.
The programs are provided as is without any guarantees or warranty. Although the author has attempted to find and correct any bugs in the free software programs, the author is not responsible for any damage or losses of any kind caused by the use or misuse of the programs.
The author is under no obligation to provide support, service, corrections, or upgrades to the free software programs. For more information, please send and email to the  This email address is being protected from spambots. You need JavaScript enabled to view it. support mailbox.