KULeuven functions to automate SPM96 (fMRI)
1. Obligatory part of the automation script
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Obligatory first part of the automation
script
%
%***************************************************************************
% fmriTEST = 1 to run the simulation
mode
%
= 0 to run the actual post-processing
% fmriDIR = the directory
in which all your data is situated
%---------------------------------------------------------------------------
global fmriTEST fmriDIR;
%set global variables
fmriTEST = 1;
fmriDIR = '/images_odin1/sunaert/spm96_kul_data';
fmri96_CWD('LOG');
%make the LOG and RESULTS directory
This sets a few global variables to make the functions work.
The fmriTEST variable, if set to 1, makes the automation script run
in a test or simulation mode: the script, if executed, will now simulate
all steps of postprocessing and report errors (e.g. missing image files).
You will want to run the script in simulation mode to detect such errors.
If everything seems OK, you will change the fmriTEST value to 0. Then,
if executed, the real thing happens...
The fmriDIR string is the name of the directory that holds your subdirectories
with images.
Let's look how this part actually works: start a matlab, and start SPM
as usual. Suppose you have copied the above script into a file called kul96example.m.
Type in 'kul96example' into the matlab window. This window will now look
like this:
2. Function for realignment
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%fmri96_realign(T,DIR,EXP,flags,rmflag)
%
%***************************************************************************
% T
- 'all' - to realign several timeseries to
the first image of
%
the first timeseries;
%
'signle' - to realign several timeseries seperately (each
%
timeserie to its first image)
% DIR - [matrix
of the directories in which the images are located]
% EXP - [matrix
of a wildcard used to select the images in the DIR directories]
% flags - 'e'
Coregister only option
%
use a 'E' for more iterations during coregistering
%
'r' Reslice Only option
%
'er' Coregister & Reslice at once
%
%
'' tell the algorithm to use Bilinear Interpolation
%
'sS' tell the algorithm to use Sinc Interpolation
%
%
'i' tell the algorithm to output All Images + Mean
Image
%
'k' tell the algorithm to Mask the images
%
%
'' No adjustment
(TR>4s n<30)
%
'c' 1st order adjustment
(TR>4s 30<n<40)
%
'cp' 2nd order adjustment (TR>4s
n>40)
%
'ch' 1st order + Spin history (TR<4s n>40)
%
'cph' 2nd order + Spin history (TR<2s n>60)
% YOU HAVE TO PUT THE
OPTIONS ABOVE TOGETHER e.g.
% 'ersS'
to coregister and reslice the images using sinc interpolation
% 'rkcp'
to reslice only using masking and 1st order + Spin history
%---OPTIONALLY--------------------------------------------------------------
% rmflags - you can specify
'REALIGN.OK' as last parameter to delete the
%
unrealigned images after completion - USE WITH CAUTION
%---------------------------------------------------------------------------
fmri96_realign('all',...
['ts01';'ts02'],...
['i*.img';'i*.img'],...
'esS',...
'')
So, this example coregisters (without reslicing) both timeseries to
the first image of ts01, using sinc interpolation.
The spm.ps output from SPM96 is stored in the LOG directory. Parameters
are also logged in a file in the LOG directory.
The output of the simulation mode (fmriTEST=1) in the matlab window
looks like this:
3. Function for normalisation
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% fmri96_sn3d(T,Po,DIR,EXP,Tmpl,NT,NAP,NLI,NBF,SE,IM,BB,VS,rmflag)
%
%***************************************************************************
% T - 1 = Determine Parameters Only
% 2 = Write Normalised
Only
% 3 = Determine
Parameters & Write Normalised
% Po - '/dir/dir/tmpr.img' Image to determine
parameters from, OR
% IN CASE
OF RESLICE ONLY, Image for which parameters already exist
% DIR - [matrix of directories containing
the images]
% EXP - [matrix of wildcard used to select
the images in the DIR directories]
% Tmpl - '/home_saga/fmri/matlab/spm96/templates/T1.img'
Template image to use
% NT - 1 = Custom Affine Only
% 2 = Custom
Affine & Nonlinear
% NAP - number of affine parameters
%
2 params (X & Y Translations)
%
3 params (Translations)
%
5 params (Translations + Pitch & Roll)
%
6 params (Rigid Body)
%
8 params (Rigid Body + X & Y Zoom)
%
9 params (Rigid Body + Zooms)
%
11 params (Rigid Body, Zooms + X & Y Affine)
%
12 params (Rigid Body, Zooms & Affine)
% NLI - number of Nonlinear Iterations
%
0,1, 3, 5,8, 12 or 16 nonlinear iterations
% NBF - Nonlinear Basis Functions
%
1 = 'none' | 2 = '2x2x2'| 3 = '2x3x2'| 4 = '3x3x3'| 5 = '3x4x3'|
%
6 = '4x4x4'| 7 = '4x5x4'| 8 = '5x5x5'| 9 = '5x6x5'| 10= '6x6x6'|
%
11= '6x7x6'| 12= '7x7x7'| 13= '7x8x7'| 14= '8x8x8'
% SE - Affine Starting Estimate
%
0 = Neurological Convention (R is R)
%
1 = Radiological Convention (L is R)
% IM - Interpolation Method
%
0 = Nearest Neighbour
%
1 = Bilinear Interpolation
%
5 = Sinc Interpolation
% BB - Bounding Box
%
1 = -78:78 -112:76 -50:85 (MNI)
%
2 = -64:64 -104:68 -28:72 (SPM95)
%
3 = -90 91 -126 91 -72 109 (Template)
% VS - Voxel Sizes
%
1 = 1 1 1 | 2 = 1.5 1.5 1.5 | 3 = 2
2 2 | 4 = 3 3 3 |...
%
5 = 4 4 4 | 6 = 1 1 2
| 7 = 2 2 4
%---OPTIONALLY--------------------------------------------------------------
% rmflags - you can specify
'NORMALIZE.OK' as last parameter to delete the
%
unnormalised images after completion - USE WITH CAUTION
%---------------------------------------------------------------------------
fmri96_sn3d(3,...
'anat/tmpr.img',...
['anat'],...
['tmpr.img'],...
'/home_saga/fmri/matlab/spm96/templates/T1.img',...
2,12,8,5,1,...
5,1,1,'')
fmri96_sn3d(2,...
'anat/tmpr.img',...
['ts01';'ts02'],...
['i*.img';'i*.img'],...
'/home_saga/fmri/matlab/spm96/templates/T1.img',...
2,12,8,5,1,...
5,1,3,'')
The first fmri96_sn3d example will define the normalisation parameters
between image tmpr.img in the anat directory and the template image,
using a 12 parameter affine and a 3x4x3 nonlinear basis functions (8 iterations)
elastic registration. It will additionally, reslice the tmpr.img
image in a ntmpr.img image with sinc-interpolation using the MNI
bounding box, and voxel size of 1x1x1 mm.
The second fmri96_sn3d example will reslice the realigned images into
MNI space using the parameters determined on image tmpr.img using
the sinc-interpolation and voxel size of 2x2x2 mm.
The pages with output from SPM96 are added to the spm.ps file in the
LOG directory. The parameters are logged in the LOG directory.
The output of this script in simulation mode (fmriTEST=1) in the matlab
window looks like this:
4. Function for smoothing
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%fmri96_smooth(SP,DIR,EXP,rmflag)
%
%*******************************************************************************
% SP - smoothing kernel
parameters [x y z] in mm
% DIR - [matrix of directories
containing the images]
% EXP - [matrix of wildcard
used to select the images in the DIR directories]
%---OPTIONALLY---------------------------------------------------------------
% rmflags - you can specify
'SMOOTH.OK' as last parameter to delete the
%
unsmoothed images after completion - USE WITH CAUTION
%---------------------------------------------------------------------------
fmri96_smooth([7 7 7],...
['ts01';'ts02'],...
['n*.img';'n*.img'],...
'')
The fmri97_smooth function smoothens the data. The FWHM of the smoothing
kernel can be specified separately for x,y and z direction, or as one value
if identical for x,y and z.
Note that we perform smoothing now on the normalised images, thus the
wildcard is set to 'n*.img'. Parameters are logged in a file in the LOG
directory.
The output of this script in simulation mode (fmriTEST=1) in the matlab
window looks like this:
5. Function for statistics
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%fmri96_stat(RT,NS,NT,DIR,EXP,RES,Cov,td,ooe,spe,ncn,cni,hpf,glb,glt,...
%
%
nco,sco,con,ts,rmflag)
%
%***************************************************************************
% RT - repetition time
% NT - number of subjects
or sessions
% NS - number of timepoints
per subject
% DIR - [matrix of directories containing
the images]
% EXP - [matrix of wildcard used
to select the images in the DIR directories]
% RES - name of directory to write
results into
% Cov - Type of response
%
1 = user specified
%
2 = 2 temporal basis functions
%
3 = half sine-wave
%
4 = delayed box-car
% td - add temporal derivative?
%
1 = yes
%
0 = no
% ooe - matrix [order of epochs
eg 1 2 1 2;... session 1
%
order of epochs eg 1 2 1 2] session 2 - etc...
% spe - matrix [scans/epoch eg 10
10 10 10 or 8 6 8;... session 1
%
scans/epoch eg 10 10 10 10 or 8 6 8] session 2 - etc...
% ncn - matrix [number of covariates
of no interest;... session 1
%
number of covariates of no interest] session 2 - etc...
% cni - matrix [covariate of no
interest;... session 1
%
covariate of no interest] session 2 - etc...
% hpf - high pass filter: cut-off
period in seconds (0 = NO HPF)
% glb - global normalisation (1
= yes, 2 = no)
% glt - global normalisation TYPE
%
'AnCova' of 'Scaling'
% nco - number of contrasts
% sco - string of names of covariates
or conditions
% con - matrix of [contrasts] (sessions
* contrasts)
% ts - temporal smoothing
(1 = yes, 2 = no)
%----------------------------------------------------------------------------
fmri96_stat(4.35,...
2,[120;120],...
['ts01';'ts02'],...
['sn*.img';'sn*.img'],...
'LanguageNetwork',...
4,0,...
[ 1 2 1 2 1 2 1 2 1
2 1 2;...
1 2 1 2 1 2 1 2 1
2 1 2],...
[ 10 10 10 10 10 10 10 10 10 10 10 10;...
10 10 10 10 10 10 10 10 10 10 10 10],...
[0;0],[],...
43.5*4,...
1,'AnCova',...
2,...
['Task Rest'],...
[ 1 -1;...
-1 1],...
1)
This example of the fmri96_stat function executes statistics on the
smoothed and normalised images ('sn*.img') of both timeseries. The *.mat
and spm.ps files are written in the directory 'RESULTS/LanguageNetwork'.
Parameters are logged in a file in the LOG directory.
The output in the matlab window looks like this:
6. Additional tools
In addition to the above basis scripts we have written several other tools
that might come in handy when you have to analyze a lot of data sets. This
part includes scripts that have incorporated the extra tools of spm97,
a script that constructs a mozaic of anatomical slices through the brain
overlayed with the activation foci, and a last one that performs the preparation
steps before using the Random Effects Kit. These scripts were written more
recently and therefore less well tested, but they seem to be free of bugs.
If you would find any, please report them to us.
You can find these scripts in the subdirectory 'spm96_kul/beta' after
downloading spm96_kul.tar.gz.
Additional info and an example
of these scripts are available here!
Webpage last updated on 6/8/1999. Authors: Stefan
Sunaert & Erik Beatse.