Batch Processing with the Tutorial Data by hcj

VIEWS: 24 PAGES: 19

									Batch Processing With the Tutorial Data
11/14/2003

Index
BATCH PROCESSING WITH THE TUTORIAL DATA INDEX INTRODUCTION
Matlab Basics Other Definitions

1 1 2
3 4

DOWNLOADS BATCH PREPROCESSING PREPROCESSING SCRIPT
Variable Setup Example Realignment Argument Slots Defined (9) Example Coregistration Argument Slots Defined (8) Example Slice Timing Argument Slots Defined (7) Example Normalization Argument Slots Defined (18) Example Smoothing Argument Slots Defined (4) Example

4 5 5
5 5 6 6 6 10 10 11 7 7 7 8 8 9 10 10 10

BATCH MODEL SPECIFICATION AND ESTIMATION
Calculation Of Timing Parameters Onsets Useful Tool Length Varab Additional Parameters General Stats Argument Slots Defined (6) Example Stochastic Design Argument Slots Defined (5) Example Non-Stochastic Design Argument Slots Defined (5) Example Response Modulation Argument Slots Defined (7) Example Basis Functions Arguments Defined (12) Example Construction Of Design Matrix Model Estimation Argument Slots Defined (11) Example

11
12 12 12 13 14 14 15 15 15 15 15 15 15 16 16 16 16 16 17 17 17 18 18 18 18

Introduction
Batch processing spm data is extremely useful but difficult to implement initially. This document attempts to lay out the details of batch processing using the Belgian files from http://www.kuleuven.ac.be/radiology/Research/fMRI/kulSPM/. These routines are fast and (relatively) easy to understand, nevertheless, you will need to spend some time with them (It is worth your time if you intend to use SPM seriously). Running SPM processes in batch files will save you a lot of time, make repetition easy and leave a detailed record behind. The researchers at Kuleuven have created Matlab functions that take arguments at the Matlab command line (or from a matlab m-file like those I go on to explain). These functions hook into the underlying spm routines and allow you to avoid entering data in the GUI (Graphical User Interface).

To use Batch processing, you will need some basic familiarity with Matlab and SPM. You may be interested in the spm page: http://w3.arizona.edu/~cnl/spm.htm and the Matlab page: http://w3.arizona.edu/~cnl/matlab.htm (there is an additional Matlab tutorial which probably includes more than you need, but would not hurt). At minimum, read the Matlab page so you know about setting the path, m-files and mat files. You will need to modify the m-file that calls all the others. An example of the preprocessing m-file and the stats m-file are explicated below. You can download the real m-files and make modifications for your data.

Matlab Basics
 Comments First, any line beginning with % is a comment which means it is for human beings to read and NOT for Matlab to read. You can use the % sign on the same line as a Matlab command, and Matlab will simply ignore all the characters after the %. Variables In the script below, we set variables. This is useful because you can define something once at the top of the script (variable = variable value). Then if you need to change it, you only need to change it once at the top of the script. e.g., TR = 2.000; Variables may be of different data types. Data Types Matlab gets very upset if it expects one datatype and gets another. It knows what a datatype is supposed to be from the punctuation that you use. o Number: Now anywhere the TR is needed, I can just insert the word TR and Matlab will understand that to be 2.000 (unless I change it). If a variable is a number, Matlab handles that just fine. String: If the variable is a word or phrase, Matlab needs to have single quotes around the variable value. These are called strings, e.g., fmriDIR = 'C:\Study1'; Matrix: A matrix is a list of variables enclosed in square brackets []: A = [1 2 3 4] Cell Array: This is similar to a matrix but more versatile. It uses some different bracketing: A{1} = [1 2 3 4]





o o o o



Functions and Arguments The preprocessing script calls several functions (a.k.a. “programs” or “m-files”) that live in your spm99_kul directory (or whatever you called it). These are functions like realignment, coregistration, slice timing, normalization and smoothing. If you don‟t want to include one of those functions, you can simply remove it. Or you can put the functions in a different order. You can find and display each function to learn more about it (actually, one m-file can contain multiple functions and calls to other functions, but the above description is close enough for what you need to know). Each function is called with a bunch of arguments that specify things like TR, directory names, whether or not you want to mask the images etc. The list of arguments starts with “(“ and ends with “)”. Generally, a function will require a specific number of arguments, though some functions are smart enough to assume certain values given others (e.g., if you say „no‟, it won‟t ask you for any more arguments). A simple example of a function: function silly (number1, number2) number1 + number2



The above function takes 2 arguments and adds them together. At the command line (or in a separate m-file), you would be expected to enter something like silly(3 5). The function silly would return 8 with these two arguments. The functions we will be discussing take more arguments and do fancier things with them, but it is the same idea. The Path: Matlab has its own path. It‟ll look for m-files and mat files in the path in an orderly way (based on the order of paths specified). Stay alert, if you have something in the path (like an SPM_fMRIDesMtx.mat in the Matlab/work directory) it‟ll happily pick that up, and you may find results from another study being displayed…very confusing.



Other Definitions
 Session: Each functional “run” is a session. For the preprocessing I have assumed two sessions, run01 and run02 (they are exactly the same data but it seemed useful to have an example with multiple sessions). The consequence of having multiple sessions is that throughout preproc_study1.m there are matrices where you have to enter multiple values (2 values if there are two sessions). If there was only one session, you‟d only need one value in each of these matrices. Trial Type or Condition: For the Model Definition and Estimation you will need to define how many conditions there are in your experiment. In our data, we have a one condition analysis (birds) and a 3 condition analysis (easy, control and hard).



Downloads
 Go here http://www.kuleuven.ac.be/radiology/Research/fMRI/kulSPM/ And download spm99_kul.tar.gz. You‟ll need to unzip and untar this directory and put it in your Matlab path. You might look at their remarks and explanations as well. I won‟t reproduce those here. Go here: http://w3.arizona.edu/~cnl/spm.htm#batch and download: 1) The SPM99WorkbookStudy1.doc. If you are not familiar with SPM, then follow the instructions in this tutorial and process the data (links to the data are in the tutorial) thoroughly before you go on. If you are familiar with SPM, then you will still want the workbook for reference to run batch processing on the tutorial data. 2) The tutorial data (converted to spm img and hdr files, flipped into the correct orientation and neatly embedded in the correct directory structure): Study1_batch_Data.tar.gz. 3) The script files (which you should also put in the matlab path) for processing the tutorial data: preproc_study1.m, stat_study1_simple.m and stat_study1_fancy.m.



Batch Preprocessing
 Assuming you have the directory of Kuleuven tools and the script files in your Matlab path, and you have the data, you are ready to begin. Below I supply additional explanation for the preproc_study1.m script. You will need to understand and modify that script to run batch processing. An annotated version of the script appears below. You can learn even more by looking at the m-file for each function: f99_realign, f99_coregister etc. Watch out for syntax errors. There do seem to be some minor but annoying differences between the behavior of matlab on different operating systems. The number of arguments must be correct (except if you use 'no' in parts 2, 3 and 4, then this one parameter will be sufficient) All entered strings (i.e., the names of subdirectories or of conditions) should have the same length). Main directory names (e.g. C:\Study1 or the path to the spm template directory) don‟t have to be the same length. Matlab does not like to have different length strings all entered in the same variable as this violates rules about matrices. This example is set up to run on the tutorial data copied into subdirectories under Study1: run01 and run02 (each containing the same flipped P*img files (and the hdr and mat files)). The anatomy files, brain and brain3d (img, hdr, and mat) are also flipped and in the anato subdirectory. This naming and organizational scheme (run01, run02, anato) is suggested by the script writers (All directory names under the main directory must have the same number of characters. In this tutorial data, each directory, “run01”, “run02” and “anato” have 5 characters. See also http://www.kuleuven.ac.be/radiology/Research/fMRI/kulSPM/ I have tried to make preprocessing choices that are equivalent to the SPM99WorkbookStudy1.doc choices, with a couple of exceptions which I explain below.

  



Preprocessing Script
Variable Setup
Obligatory first part of the automation script. Defines some general variables and whether you are running in simulation mode or doing actual processing.

Example
global fmriTEST fmriDIR; % Set global variables fmriTEST = 1; % 1=SIMULATION mode; 0=ACTUAL processing fmriDIR = 'C:\Study1'; % The directory in which all your data is situated (don‟t put % an extra \ at the end of the pathname) f99_CWD('LOG'); % Make the LOG and RESULTS directory % Additional variables to be defined once: TR = 2.000; % Enter TR in seconds NAS = 17; % Enter # of anatomical slices here RUNS = ['run01';'run02']; % A matrix of 2 strings, each containing the % name of one of our sessions. Note that strings % in a matrix are separated by a semicolon. TEMPLATE = 'C:\matlab\spm99\templates\EPI.img'; % This is simply the path to the spm templates % directory to be used in the normalization step.

TEMPLATE2 = 'C:\matlab\spm99\templates\T1.img';

Realignment
To realign in batch mode, you use the realignment function (It is best to have run the “Obligatory first Part‟” and to define the “additional variables” first.) The realignment function is in an m-file called f99_realign.m which you can open and examine in any text editor. As you can see, f99_realign (below) expects 9 arguments, in order (do_what, DIR, EXP, etc.). The values that you can put in these argument slots are defined below, and exemplified below that. Because there are 9 argument slots, you will need 9 arguments. You can use an empty string „‟ or empty matrix [] for an argument you don‟t want to define (Remember, to use the expected datatype)…examples occur below. f99_realign(do_what,DIR,EXP,reslice_type,create_what,mask_images,adj_se, real_qual,rmflag)

Argument Slots Defined (9)
1. do_what? a. 1 = coregister only b. 2 = reslice only c. 3 = coregister and reslice 2. DIR [matrix containing directories of experiments] 3. EXP [matrix containing image file names (with wildcards)]. An image file name must be added for each session. The multiple sessions will then be aligned to the first image in the first session. 4. reslice_type? 1= Trilinear -9 = Sinc Inf = Fourier (only if isotropic voxels) 5. create_what? 1 = All Images (1..n) 2 = Images 2..n 3 = All Images + Mean Image 4 = Mean Image Only' 6. mask_images? 1 = yes, 0 = no 7. adj_sampling_errors? 1 = yes, 0 = no 8. registration quality? 1.00 to 0.001 (0.50 is the SPM default) 'Quality 1.00 (slowest/most accurate) |Quality 0.90|' ... 'Quality 0.75 |Quality 0.50|Quality 0.25|Quality 0.10|' ... 'Quality 0.05 |Quality 0.01|' ... 'Quality 0.005|Quality 0.001 (fastest/poorest)' ---OPTIONALLY-------------------------------------------------------------9. rmflags - you can specify 'REALIGN.OK' as last parameter to delete the original images after completion of realignment - USE WITH CAUTION

Example

f99_realign(3,... RUNS,... ['P*.img';'P*.img'],... -9,... 3,... 1,... 1,... 0.50,... '')

% 1. Do what % 2. DIR, the variable RUNS defined above % 3. EXP: Both sessions will be aligned together % 4. reslice_type? % 5. create_what? % 6. mask_images? % 7. adj_sampling_errors? % 8. Registration quality, 0.5 is spm default, % 9. rmflag: „‟ an empty string, we don‟t want to remove anything, but we must put something in the argument slot.

Slice Timing
f99_slice_timing(DIR,EXP,Seq,sl_order,refslice,TR,TA)

1) DIR [matrix containing experimentdirectory names] 2) EXP [matrix containing image names] 3) Seq slice acquisition order (1,2,3 = asc, desc, interl, user specified) 4) sl_order chronological order of slice acquisition (if Seq = 4) 5) refslice slice for time 0 6) TR repetition time 7) TA acquisition time (time between start of acq of first slice and the end of acq of the last slice). TA = TR-(TR/#slices) Note: I have had more trouble with slice timing than any other step of the preprocessing. If you have trouble running in simulation mode, try changing the filenames to match whatever is actually available in the data run directory (e.g., In the example below, I assume that files will have a prepended “r”. If your real current files don‟t have the “r” yet, simulation mode may blow up. Change the file names to P* and run in simulation mode again.). Another alternative is to comment out the slice timing step, at least you can make sure everything else runs. TA=TR-(TR/NAS) % Define variable TA based on TR and # of slices f99_slice_timing(... RUNS,... ['rP*.img';'rP*.img'],... 2,... [],... 1,... TR,... TA);

Argument Slots Defined (7)

Example

% % % % % % %

1. 2. 3. 4. 5. 6. 7.

'DIR' RUNS defined at the top 'EXP' (note prefix change post-realignment) Seq 'sl_order' (empty matrix since Seq ≠ 4) 'refslice' TR TA

Normalization
SPATIAL NORMALIZATION f99_sn3d (option, objima, mask_object, maskima, DIR,EXP,templima,mask_templ,spec_brainmask,affinet,ase,nbf,nli,nlr,intplt,bbt,voxt, rmflag)

Argument Slots Defined (18)
1) option - 'Do What?' 1= 'Determine Parameters Only' 2= 'Write Normalised Only' 3= 'Determine Parameters & Write Normalised' 2) objima - 'Image to determine parameters from (objectimage), OR in case of write normalised only, image for which parameters exist e.g. 'anat/anatomy.img' 3) mask_object - 'Mask the object?' 1 = yes, 0 = no 4) maskima - 'image that contains the mask for the objectimage' e.g. 'anat/noskull.img' 5) DIR - '[matrix of dirs]' 6) EXP - '[matrix of experiments]' 7) templima - '[one or more templates]'The image will be fitted (in the least squares sense) to the optimum linear combination of these templates. 8) mask_templ 0 = 'no masking' 1 = 'mask the template image with the mask in SPM/apriori directory' 2 = 'mask with the spec_brainmask (user defined)' 9) spec_brainmask - 'user specified brainmask for template' 10) affinet - 'Affine Normalisation Type?' 'rigid1' - rigid body normalization 'rigid2' 'rigid3' 'affine1' 'affine2' 'affine3' - this is default SPM99 11) ase - 'Affine Starting Estimates?' 'Neurological Convention (R is R)'The starting estimates do not include a left right flip.[0 0 0 0 0 0 1 1 1 0 0 0]. 'Radiological Convention (L is R)'[0 0 0 0 0 0 -1 1 1 0 0 0]. 12) nbf - '# Basis Functions (x y z)' 1=none - USE THIS IF AFFINE ONLY NORMALISATION WANTED 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 13) nli - '# Nonlinear Iterations?'can be set to : 1, 3, 5, 8, 12 or 16 14) nlr - 'Nonlinear Regularization' Can be set to : 1, 0.1, 0.01, 0.001 or 0.0001 from 'Extremely Heavy regularization' to 'Very Light regularization' 0.01 is SPM99 default. Use Heavy if distorted. 15) intplt - 'Interpolation Method?' 0=Nearest Neighbour 1=Bilinear Interpolation -9=Sinc Interpolation (9x9x9) 16) bbt - 'Bounding Box?‟ [-x x -y y -z z] in mm e.g. [-78 78 -112 76 -50 85] (Default SPM99) 17) voxt - 'Voxel Sizes 'The voxel sizes (x, y & z, in mm) of the written normalised images (output).[x y z] in mm e.g. [2 2 2] ---OPTIONALLY----------------------------------------------------18) rmflags - status file in the LOG that controls if files can be safely deleted Note: Apparently Matlab 6.5 (at least on the PC) does not handle the nbf (Basis Function) correctly. I currently (7/11/2003) have no solution for this (except, use a different version of matlab).

Example
f99_sn3d(3,... 'run01/meanP15872em1.img',... 0,... '',... RUNS,... ['arP*.img';'arP*.img'],... TEMPLATE,... 0,... [],... 'affine3',... [0 0 0 0 0 0 -1 1 1 0 0 0],... 13,... 16,... 0.01,... 1,... [-78 78 -122 76 -50 85],... [2 2 2],... ''); % 1. option % 2. objima % 3. mask_object % 4. maskima: „‟ empty string % 5. 'DIR' Uses RUNS defined above % 6. EXP The names have changed again. % 7. 'templima' This is defined above % 8. mask_templ % 9. spec_brainmask (none, []) % 10. affinet 'Affine Normalisation Type?' % 11. ase (Radiological) % 12. nbf % 13. nli 'Nonlinear Iterations?' % 14. nlr 'Nonlinear Regularization' % 15. intplt 'Interpolation Method?' % 16. bbt (Default SPM99) % 17. voxt (x, y & z, in mm) % 18. rmflags We don‟t want to remove anything, use an empty string‟‟

NORMALIZATION OF T1 f99_sn3d(1,... 'anato\brain.img',... 0,... '',...

(Normalizing the spgr is the same principle and even the same T1 template)

['anato'],... % 'DIR' - [matrix of dirs] ['brain.img'],... TEMPLATE2,... 0,... [],... 'affine3',... 13,... 16,... 0.01,... -9,... [-78 78 -122 76 -50 85],... [3.4375 3.4375 3.5],... '')

Smoothing
f99_smooth(SP,DIR,EXP,rmflag)

Argument Slots Defined (4)
1) SP - FWHM of smoothing kernel 2) DIR - [matrix of dirs] 3) EXP - [matrix of experiments] ---OPTIONALLY---------------------------------------------------------------4) rmflags - status file in the LOG that controls if files can be safely deleted

Example
f99_smooth ([7],... % 1. SP RUNS,... % 2. DIR (Use RUNS defined above) ['narP*.img';'narP*.img'],... % 3. EXP (Names have changed again) '') % 4. rmflags, an empty string „‟

Coregistration
f99_coregister(option, Use_MutInf, target_mod, targetima, object_mod, objectima, DIR, EXP)

Argument Slots Defined (8)
1) option 'do what?' 1 coregister only; 2 reslice only; 3 coregister & reslice 2) Use_MutInf 'Use Mutual Information?' 1 = yes ; 0 = no 3) target_mod 'modality of target image' 1 = PET 2 = T1 MRI 3 = T2 MRI

4) 5)

6) 7) 8)

4 = PD MRI 5= EPI 6 = Transm targetima 'run01\meanP15872em1.img',... % DIR 'target image' object_mod 'modality of object image' 1 = PET 2 = T1 MRI 3 = T2 MRI 4 = PD MRI 5= EPI 6 = Transm objima 'anato\brain.img',... % EXP 'object image' DIR If there are other images to reslice, [matrix containing directories of experiments] EXP If there are other images to reslice, [matrix containing directories of image names using wildcards]

Example
f99_coregister(3,... % 1. 'do what?' 1 - coregister and reslice 0,... % 2. 'Use Mutual Information?' 0 = no 5,... % 3. 'modality of target image' 5= EPI 'run01\nmeanP15872em1.img',... % 4. DIR 2,... % 5. 'modality of object image' 2 = T1 MRI 'anato\nbrain.img',... % 6. EXP 'object image' [],... % 7. DIR none, hence empty matrix []) % 8. EXP “other” images (with wildcards); none Coregistration of the spgr follows the same strategies for the same reasons.

Batch Model Specification And Estimation
Model specification and estimation can also be handled with batch mode. Although these processes aren‟t that slow to run, the parameters are very annoying to enter in the gui (one slip and you have to start all over again). This is faster, and if you have a lot of similar analyses to run, easier. Again, it takes a little while to get the hang of it, but it is worth it. This sample script analyzes the CNL study1 data in the "Fancy" analysis style described in the SPM Study1 Tutorial. http://merlin.psych.arizona.edu/~dpat/Public/Imaging/SPM/Study1Dataset/SPM99Workboo kStudy1.doc It works on only one run. Obligatory first part of the automation script global fmriTEST fmriDIR; % set global variables fmriTEST = 1; % 1=simulation fmriDIR = 'C:\Study1'; % main data directory f99_CWD('LOG'); % Make the LOG and RESULTS directory

Calculation Of Timing Parameters
These deserve several examples to clarify. Below I borrow copiously from the very useful “remarks” on the Kuleuven site. I have added some additional examples and explanations to try to further clarify how these cell arrays should be created and understood. See http://w3.arizona.edu/~cnl/glossary.htm#cellarray for a description of cell arrays.

Onsets

For each session, specify the onset times of each condition in separate rows of a single matrix. Each row of the matrix must be the same length as the other rows. Fill in blanks with -1. This is an example for one run with three conditions. The first condition, “easy”, occurs only twice, beginning at the 0 th TR and then at the 40th TR. The second condition, “cont” starts at TR 10, 30, 50 and 70. The third condition, “hard” starts at TRs 20 60. Each condition gets a row (crucially separated by a ; and for readability separated out onto different lines). The row lengths have been matched by padding with -1. In this case you are creating cell 1 in the cell array “onset”. If other runs were exact replications of this one, then this single onset{1} would be sufficient: onset{1} = [0 40 -1 -1;... 10 30 50 70;... 20 60 -1 -1]; If you had a second session/run which differed from the first (we don‟t have this in our tutorial dataset), you would create an additional cell in the onset cell array to hold the matrix for that second run, for example, here is a session where timing and the number of trials per condition differ from our real case: onset{2} = [0 30 40 -1;... 10 20 50 -1;... 60 -1 -1 -1]; Another example (from the example_script_stat) Here they have 2 runs, each with 3 conditions, the first condition occurs 6 times (and then the row is padded with -1‟s), the second and third conditions each occur 12 times. The two runs differ: onset{1} = [0 20 40 60 80 100 -1 -1 -1 -1 -1 -1;... 2 6 14 44 50 58 66 70 76 83 99 106;... 4 10 20 30 38 47 62 68 78 88 102 112]; onset{2} = [10 30 40 70 90 105 -1 -1 -1 -1 -1 -1;... 4 8 19 42 55 56 66 70 78 85 100 108;... 6 12 22 31 38 40 60 66 76 84 104 112];

Useful Tool
If you have a lot of trials and you don‟t want to do the “-1” padding manually, use f99_equalencov.m as follows: The first step is to make matrices (one for each session) in which each row represents the onset times of a trial type. Here are two matrices:

>>A= [1 2 4] >>B= [3 5 6 7 8 9] If the number of trials for each type differs (e.g. when epochs and events are mixed), you can fill up the empty part with the number "-1", which will be ignored during the analysis. For that you can use the script 'f99_equallencov.m". Here you combine them into a matrix padded with “-1‟s” (in this example A will be padded with -1 -1 -1) >>cot = f99_equallencov(-1,A,B) The above step creates a matrix for use in the batch processing. >>save cot cot This will save your hard won matrix into a mat file on the disk (in your current directory). It is probably a really good idea to save it. f99_equallencov takes as its first argument the value you want to pad with (-1 in this case) and then allows up to 20 matrices as additional arguments. The results can be stuck into a giant matrix, or, as in this case, a cell array (since that is what we need anyhow). If you are using Fixed onset times the approach is similar, but here for the onset times and the soa's: You should specify n matrices (# of sessions) of length m (# of trial types). Then these matrices are pasted into a cell. Identically, if sessions are replicated or in case of only 1 session, a cell containing only 1 matrix is sufficient. For example, in stat_study1_simple we have one session (run01) and one condition (birds). Since the onset times are fixed, all we need is the first onset of a birds condition (beginning at TR=0) and then the soa [20] that tells us what the fixed repetition time is: onset{1} = [0]; soa{1} = [20];

Length
Length of the trial types: similar approach A cell containing one matrix per session must be constructed. Each matrix contains the lengths of all trial types (= 0 in case of 'events', since event durations will be defined in the varab). The length cell array is thus small compared to the giant onset and varab cell arrays, you only need to specify one number for each trial type: Example 1: For our fancy analysis we have three conditions easy, cont and hard and one session/run. Each condition lasts 10 TRs, so here we specify all three: length{1} = [10 10 10];

Example 2: For our simple analysis we have one condition, birds, and it always has a length of 10 TRs. Again, we have one session: length{1} = [10]; Example 3: In the example script, they have 3 conditions and two runs. The first condition is an epoch and the second and third are events: length{1} = [10 0 0]; length{2} = [15 0 0];

Varab
Variable durations: this cell array has the same dimensions as the variable 'onset'. However, values should only be entered for those conditions with variable durations, for all other conditions a '0' should be entered for each onset of this condition. Remember that a blocked condition with variable onset times should be entered as a "event-like" trial with variable durations and length '0'!!! Example 1: all rows in varab are matched in length to onset. They are filled with 0‟s because they are epoch trials with a length already specified. If they were events, they would have lengths specified. dur{1} = [0 40 -1 -1;... 10 30 50 70;... 20 60 -1 -1]; length{1} = [10 10 10]; varab{1} = [0 0 0 0;... 0 0 0 0;... 0 0 0 0]; Easy creation of the varab variable named “dur” for the batch processing: >>dur = zeros(3,4) This creates a matrix called dur with 3 rows and 4 columns (i.e., it is the same as varab illustrated above, except varab is a cell array to be directly assigned in the batch file while dur is a matrix that is saved as a mat file, loaded at the beginning of the batch process and then dumped into a cell array during the batch processing). Example 2: in stat_study1_simple.m the condition “birds” begins predictably starting with 0 and then every 20 TRs. The varab variable does not need to be defined.

Additional Parameters
names = ['Easy';'Cont';'Hard']; % trial names (must all be same # of characters) Out = 'Stat1' % Subdirectory of Results directory to put results in % % these

General Stats
function f99_stat_general(RT,nscan,rep,n_cond,cond_name,LULRES1)

Argument Slots Defined (6)
1) RT repetition time (TR, in seconds) 2) nscan number of scans per session (nfs) = number of img files in a run. You need a number for each session/run (e.g., [80 80] two sessions with 80 reps each; [80 80 80] three sessions with 80 reps each, etc. 3) rep Are sessions replicated exactly? (1=yes / 0=no) 4) n_cond Number of conditions or trials 5) cond_name Matrix with names of conditions/trials (all names equal length) 6) LULRES1 directory Where results get written

Example
f99_stat_general(... 2.0,... [80],... 1,... 3,... Out); % 1. TR (aka, RT): repetition time (in seconds) % 2. nscan: number of scans/reps per session % 3. rep % 4. n_cond % 5. LULRES1: defined as "Out" variable.

Stochastic Design
All parameters should be entered for each session individually. f99_stat_stoch(s_STOC,nulev,soa_stoc,oc_prob,prob_type)

Argument Slots Defined (5)
1) s_STOC DO YOU WANT A STOCHASTIC DESIGN ('yes'/'no') if you answer yes here, answer no in the next part. If you answer “no” here, you don‟t have to put any other arguments in at all (this is a very clever function) 2) nulev include null event? (1=yes / 0=no ; for each session) 3) soa_stoc soa for each trial type 4) oc_prob matrix with occurrence probabilities for each trial type 5) prob_type stationary (1) or modulated (0) occurrence probabilities

Example
f99_stat_stoch(... %1. We don‟t want a stochastic design, so this “no” is all we need

Non-Stochastic Design
f99_stat_nonstoch(N_STOC,Sstr,onset,durat,soa_n_stoc)

1) N_STOC: DO YOU WANT A DETERMINISTIC DESIGN ('yes'/'no'). Answer yes here only if you said no in the previous (stochastic design) part. 2) Sstr - type of SOA ('fixed' or 'variable') 3) onset - time to first trial (scans) a. if 'Fixed' : onset of first trial presentation b. if 'Variable' : onset times of all trials only one session or sessions are replicated i. onset = [n_trials*n_trial_types] several sessions, not replicated ii. onset{1} = [n_trials*n_trial_types] iii. onset{2} = [n_trials*n_trial_types] iv. ... v. onset{n_sess} = [n_trials*n_trial_types] 4) durat variable durations for all sessions and conditions i. (ncond x # onsets for each cond) for each session 5) soa_n_stoc soa for each trial type (only if 'Fixed')

Argument Slots Defined (5)

Example
f99_stat_nonstoch(... 'yes',... % 1. N_STOC 'Variable',... % 2. Sstr type of SOA ('Fixed' or 'Variable') onset,... % 3. onset (uses giant cell array defined at the top) varab,... % 4.durat: (uses a giant cell array defined at the top) []); % 5. soa for each trial type, only if 'fixed'

Response Modulation
f99_stat_modul(Ptype,Pstr,Etype,h_exp,h_pol,sel,p_mod) 1) Ptype parametric modulation? ('none','time','other'). If you enter “none” then you don‟t need any other arguments 2) Pstr name of parameter (in case of 'other') 3) Etype expansion type ('linear','exponen','polynom') 4) h_exp time constant (in case of 'exponen') 5) h_pol order of polynomial expansion (in case of 'polynom') 6) sel which trials to modulate 7) p matrix with parameters for each selected covariate [#starting points per covariate * #selected covariates]

Argument Slots Defined (7)

Example
f99_stat_modul(... %1. Ptype no response modulation (don‟t need other arguments)

Basis Functions
f99_stat_basisfunct(Rov,hrffunct,Cov,pst_ev,h,m,HRF,TD,W,VOLT,regr_us, regr_us_na) 1) Rov matrix with types of trials: event ('ev') or epoch ('ep') one string per trial (e.g. ['ep';'ep';'ep'] for 3 trials/conditions each of which is an epoch) 2) hrffunct - user specified hrf function of this subject i. length of this function can be checked using fmriTEST 3) Cov - model type for covariates of interest i. 1 = basis functions (Discrete Cosine Set) ii. 2 = basis functions (Mean & exponential decay) iii. 3 = fixed response (Half-sine) iv. 4 = fixed response (Box-car) - model type for event-related responses i. 5 = hrf (alone) ii. 6 = hrf (with time derivative) iii. 7 = hrf (with time and dispersion derivatives) iv. 8 = basis functions (Fourier set) v. 9 = basis functions (Windowed Fourier set) vi. 10 = basis functions (Gamma functions) vii. 11 = basis functions (Gamma functions with derivatives), e.g. [4 4 6] *event related arguments* 4) pst_ev - window length (for Cov=8 Cov=9) 5) h - order of Fourier set (for Cov=8 Cov=9) *epoch related arguments* 6) m - number of basis functions (if Cov=1) 7) HRF - convolve with HRF (1=yes / 0=no) 8) TD - add temporal differences (1=yes / 0=no) 9) W epoch length (scans) for each condition *additional arguments* 10) VOLT interactions among trials (Volterra series)? (1=yes / 0=no) 11) regr_us - matrix with user specified regressors 12) regr_us_na - matrix with strings of names of regr_us

Arguments Defined (12)

Example
f99_stat_basisfunct(... ['ep'; 'ep'; 'ep'],... % 1. Rov: 3 epoch trials (e.g., easy, cont, hard) [],... % 2. hrffunct: user specified hrf function of this subject [] means "none" [4 4 4],... % 3. Cov, model type for each of the trials (3 trials in this case) 0,... % 4. pst_ev: window length. 0 is just a place holder 0,... % 5. h: 'order of Fourier set'. 0 is a place holder 0,...% 6. m: number of basis functions. 0 is a place holder 1,... % 7. HRF 0,... % % 8. TD length,... % 9. W: epoch length (scans) for each condition (defined above) 0,... % 10. VOLT [],... % 11. regr_us [] empty matrix, (we have none) []); % 12. regr_us_na [] empty matrix, (we have none)

Construction Of Design Matrix
*Do Nothing to this* f99_make_DesMtx: This function doesn't seem to work properly. The following steps substitute and you don't need to alter them at all for your data. Previous steps create 5 mat files for you which are loaded here to create the design matrix. load KUL_stat_gen; load KUL_stat_stoch; load KUL_stat_nonstoch; load KUL_stat_modul; load KUL_stat_basisfunct; f99_spm_fmri_design_ma(RT,nscan,kulRES,STOC,rep,n_cond,cond_name,nulev,so a_stoc,oc_prob,prob_type,Sstr,soa_n_stoc,onset,Ptype,Pstr,Etype,h_exp,h_pol,sel ,p_mod,Rov,Cov,pst_ev,h,m,HRF,TD,W,VOLT,regr_us,regr_us_na,durat,hrffunct); Note: Failure of the script at this point could mean anything…since before this step, data are simply being saved up, only at this step are you really trying to run something.

Model Estimation
Argument Slots Defined (11)
f99_stat_calc(DIR,EXP,RES,glob,BM,cLF,HParam_in,cHF,LParam_in,cVi,bFcon) 1) DIR [matrix of directories] 2) EXP [matrix of experiment names] 3) RES directory where SPM_fMRIDesMtx will be written 4) glob global normalisation ('Scaling' or 'None') 5) BM burst mode? (1=yes, 0=no) 6) cLF apply High Pass Filter? ('none' or 'specify') 7) HParam_in user defined cut off period for each session (one per session: e.g., [160 160] for two sessions etc. 8) cHF Low Pass Filter? ('none', 'Gaussian' or 'hrf') 9) LParam_in user defined Gausssian FWHM (secs) 10) cVi intrinsic correlations ('none' or 'AR(1)') 11) bFcon Setup trial-specific F-contrasts? (1=yes, 0=no)

Example
f99_stat_calc(... ['run01'],... % ['sn*.img'],... % Out,... % 'Scaling',... % 0,... % 'specify',... % [160],... % 'hrf',... % [],... % 'none',... % 0); % 1. DIR [matrix of run directories] 2. EXP [matrix of image names] repeat for each session/run 3. RES corresponds to "Out" defined above 4. glob global normalisation ('Scaling') 5. BM burst mode? no 6. cLF apply High Pass Filter? 7. HParam_in cut off period for each session 8. cHF Low Pass Filter? 9. LParam_in user defined Gausssian FWHM (secs) 10. cVi 11. bFcon

Contrast Specification Script
To specify contrasts, you must be in the results directory (or subdirectory of the results) where your beta images (etc etc.) were created by the above stats script. There is no specification of the path or of simulation mode for the contrasts.

Get Contrasts
Argument Slots Defined (3)
f99_GetCont(names,ss,Ns) 1) names: matrix containing the string names of the contrasts 2) ss: matrix with the values for each defined contrast(one session) 3) Ns: the number of sessions (runs) for this subject

Example
This runs very quickly and simply adds the information to xCon.mat. Assuming the “fancy” stats…so we have 3 conditions to contrast: f99_GetCont_first(... ['a';'b';'c'],... % the names should all be the same length [ 1 -2 1;... % here are the contrasts for “a” -1 -1 2;... % here are the contrasts for “b” -1 0 1],... % here are the contrasts for “c” 1) % In the stats example we did one session, so here we must do one % session

Do Contrasts
f99_DoCont(act, contrast_num) This function computes contrast and statistical images (It generates spmT spmF ess and con files (at least)). There are 3 options for argument 1: -'all': all contrasts in xCon.mat will be computed (If you use “all”, no other arguments are needed. - OR 'selected': those contrasts defined in arg2 will be computed -OR the names of the contrasts defined in f99_GetCont_... should be used!!

Argument Slots Defined (1)

Example
f99_DoCont('all') %Yes, it can be as simple as this.


								
To top