function SPMbatch_results=spm_batch(BatchSpecs); % % function SPMbatch_results=spm_batch(BatchSpecs); % % SPM2 batch engine, devoloped at UU and UMCU % (Utrecht University, University Medical Center Utrecht). % % Allows users to bypass the SPM2 Graphical Interface and batch preprocessing and statistics jobs for many subjects at once % For more info on SPM2 see http://www.fil.ion.ucl.ac.uk/spm/spm2.html % The details of the analyses will be passed to the native spm2 functions, i.e. this batch engine does not influence the spm2 functionality, but merely % automizes it. % % A structure (for example, BatchSpecs) with the following fields can be passed to this function: % % BatchSpecs.preproc % BatchSpecs.model % BatchSpecs.conditions % BatchSpecs.parametrics % BatchSpecs.bf_ev % BatchSpecs.regressors % BatchSpecs.parametrics % BatchSpecs.dirs % BatchSpecs.contrasts % BatchSpecs.groupstats % BatchSpecs.workdirparent % BatchSpecs.Todo % % See below for a detailed description of the various fields. % % Preprocessing: % The fields of BatchSpecs.preproc determine how and which preprocessing steps will be taken, and in what order. % Currently supported are: fixed affine transformations (as in 'display'), coregstration, realignment, % slice time correction, normalization, smoothing % % Statistics: % Various fields of BatchSpecs contain the specifications for the models to be estimated. % It is possible to specifiy a matrix of models at once, for multiple % sessions and subjects. Below the fields are specified in detail % The proper SPM. ... structures will be constructed here, and estimated with % spm_spm(SPM) for all models specified % % ------------------------------------------------------------------------------------ % In the descriptions below, N = number of subjects, S=number of sessions per subject % % Other jargon: % Integer: number without decimal places (i.e. 1, 7, 12) % Float: number with decimal places (i.e. 1.4, 7.2, 12.8) % Vector: list of numbers, as coded in Matlab. (i.e. [1 4 9 12]) % String: vector of characters, a word (i.e. 'justaname') % String matrix: vertically concatenated strings (actually a matrix of characters) (i.e. ['file1.img';file2.img', ...,'fileN.img']) % Cell array: complex matlab variable type, like vector but with members between brackets (i.e. {[1 3 5],[5 2 7 2 3.2]}) % members can be anything, or have different lengts % Structure: complex matlab variable type, containing fields (indicated with a '.' after the variable name). % (i.e. structvar.number=1;structvar.name='me') % Structure array: vector of structures (i.e. structvar(1), structvar(2), all with fields) % ------------------------------------------------------------------------------------ % PREPROCESSING % % BatchSpecs.preproc(1...N) % - Structure array for data preprocessing jobs of N data sets (i.e. subjects). % - Available fields: % order = Vector of Integers, indicating order of operations. Default: [1 2 3 4 5 6] % codes: AFFINE TRANSFORMATION=1; COREGISTER=2; SLICE TIMING = 3; REALIGN=4; NORMALIZE=5; SMOOTH=6 % % affinetrans = Structure holding parameters for an affine transformation (creating a 'matfile' by hand) % similar to options available after pressing 'display' in the GUI) (per 'subject'). % - Available fields: % P = files on which the transformation has to be applied % prev = Integer (0/1); if 1, use output images of previous step for (P can be empty), % if 0, P will have to specify file names % transv = the 1x12 element transformation vector (as P in spm_matrix) [ . . . ] % P(1) - x translation % P(2) - y translation % P(3) - z translation % P(4) - x rotation about - {pitch} (radians) % P(5) - y rotation about - {roll} (radians) % P(6) - z rotation about - {yaw} (radians) % P(7) - x scaling % P(8) - y scaling % P(9) - z scaling % P(10) - x shear % P(11) - y shear % P(12) - z shear % % % coregister = Structure holding coregistration parameters (per 'subject'). % - Available fields: % % estimate = structure holding info for estimating coregistration parameters % - Available fields: % target = String; image to coregister to (transformed source images will match target image, % target image is untouched) % source = String; image to coregister (image that will be transformed to match the target) % PLUS: any of the other fields also present in defaults.coreg.estimate (see spm_defaults.m) % % write = structure holding info for writing coregistered images % - Available fields: % PLUS: any of the fields also present in defaults.coreg.write (see spm_defaults.m) % % P = String Matrix, holding other files to coregister to target (with same parameters as source) % (spm_get is a good way to create this matrix) % prev = Integer (0/1); if 1, use output images of previous step for (P can be empty), % if 0, P will have to specify file names % option = Integer; indicating realignment options. % 1: coregister only; 2: reslice only; 3: coregister & reslice % % slice = Structure holding slice timing correct parameters (per 'subject'). Good for EPI (or % other 'sliced' acquisitions) only % - Available fields: % P = String Matrix, holding files to slice time correct. spm_get is a good way to create this matrix % prev = Integer (0/1); if 1, use output images of previous step for (P can be empty), % if 0, P will have to specify file names % slice_order = Vector of Integers (i.e.[s1 s1 ... sN] where N = number of slices); indices indication order of slice % acquisition, i.e. something like [1 3 5 7 .. 2 4 6 ..] for interleaved sequences. Ask your MR physicist % for details regarding your pulse sequence. % TA = Float; acquisition time: total time of actual slice acquisition in seconds % TR = Float; repetition time: time in which one volume is measured in seconds (might differ from TA when % there is 'dead' time between image volumes) % ref_slice = Integer; reference slice number (slice for time 0) % option = Integer; indicating slice timing correction options. % % realign = Structure holding realignment parameters (per 'subject'). % - Available fields: % P = String Matrix, holding files to realign (to first image). spm_get is a good way to create this matrix % prev = Integer (0/1); if 1, use output images of previous step for (P can be empty), % if 0, P will have to specify file names % option = Integer; indicating realignment options. % 1: coregister only; 2: reslice only; 3: coregister & reslice % % normalise = Structure holding holding normalisation parameters. % - Available fields: % object = String ; image file name to determine parameters from (i.e. structural image of subject) % template = String ; image file name to use as normalization template % P = String Matrix; rows in this matrix are images file names to apply the % normalization to (i.e. time series images) % voxel_size_default = Integer (0/1); if 1, write images in the default voxel size (as specified in spm_defaults.m) % if 0, use value from 'voxel_size' field (see below); % voxel_size = Vector of Floats, 1x3 (i.e. [vx vy vz]); images will be written with corresponding voxel sizes (when % voxel_size_default =0) % bounding_box_default = Integer (0/1); if 1, write images using the default bounding box (as specified in spm_defaults.m) % if 0, use value from 'bounding_box' field (see below); % bounding_box = Matrix of Integers, 3x2 (i.e. [bx1 bx2; by1 by2;bz1 bz2]); images will be written with % corresponding voxel sizes (when bounding_box_default =0).bx1=lower x limit,bx2=upper x limit, etc ... % prev = Integer (0/1); if 1, use output images of previous step for 'P' ('P' field can % then be empty). % option = Integer (1/2/3); 1: determine parameters only; 2: write normalised; % 3: determine parameters and write normalised % % % % smooth = Structure holding smoothing parameters % -Available Fields: % FWHM = Float; full width at half maximum % P = String Matrix; rows in this matrix are images file names to smooth (i.e. time series images) % prev = if 1, use output images of previous step for images (P can be empty). Otherwise, images % needs to be specified % % ------------------------------------- % STATISTICS % BatchSpecs.model(1...N) % - structure array; describing the model that has to be estimated, per subject. Some fields refer to other fields from BatchSpecs % N equals the number of subjects % - available fields: % global_effects = String: 'Scaling/None' % HF_fil = String: 'specify/None' % HF_cut = Integer % Drift = String: 'none/linear' % int_corr = String: 'AR(1)/none' % RT = Float (repetition time of a single scan in seconds) % replicated = Integer, i.e. 1/0 (yes/no) (are modelled sessions (if any) mere replications, or can each % session be different?) % nsess, = Integer (Number of sessions to model) % nscans = Vector of integers [n1,n2 ... nS] (S=number of sessions). number of scans per session % conditions_nb = Vector of integers [n1,n2 ... nS] (S=number of sessions). Number of conditions per session % parametrics_type= String: 'none/time/other' (when 'other', parameters are given in BatchSpecs.parametrics(subjectnumer,:) ) % files = String matrix: ['file1';'file2';...;'fileN'] % regressors_nb = Vector of integers [n1,n2 ... nS] (S=number of sessions). Number of extra regressors per session % See BatchSpecs.regressors below. % % BatchSpecs.conditions(1...N,1...S) % - structure array; describing the conditions to be put in the model. % - available fields: % names = Cell array of strings, i.e. {'conditionA','conditionB','conditionC'} % types = Cell array of strings, i.e. {'events','events','events'} % bf_ev_i = Integer, refers to BatchSpecs.bf_ev(1...NE), indicates event types to use (as specified in BatchSpecs.bf_ev) % volterra = Integer, calculate volterra kernels (yes/no = 1/0) % onsets = Cell array with vectors of Floats: containing event onsets, i.e. {onsetsA,onsetsB,onsetsC}, % where onsetsA=Vector of Floats indicating onsets such as [12.2 45.0 ...] % variable_dur = Integer, i.e. 1/n (yes/no) indicating if all events/epochs/other things are of the same duration? % dur = Cell array with Vectors of Floats (or single Float when variable_dur=0), a vector indicates % duration of each individual event in a condition (vector must be of same size as corresponding onset vector) % , i.e. {durationsA,durationsB,durationsC}, where durationsA=array of Floats indicating % durations, i.e. [10 15 10 ...] % % BatchSpecs.bf_ev(1...NumEventTypes) % - Structure array; Indicating possible event type to use for modelling. Indicated by index in BatchSpecs.conditions(...).bf_ev_i % - available fields: % ev_type = Integer indicating basis function (1:hrf,2:hrf (with time derivative), % 3:hrf (with time and dispersion derivatives), 4: Fourier set, 5: Fourier set (Hanning), 6: Gamma functions, % % 7:Finite Impulse Response) % win_len = Integer, indicating length in seconds (not always relevant, if not, use []) % % BatchSpecs.Parametrics(1..N,1...S) % % - Structure array; when model(subjectnr).parametrics_type= 'other', the parametric modulation of responses will be read from % BatchSpecs.Parametrics(subjectnr, ..) % - available fields: % name = String (name of parametric modulator) % order = [1,1] (polynomial order of modulation, for each condition (trial) % trials = [1:2] (for what condition (trial) a parametric modulation has to be added) % parameters = Cell array with vectors of floats, holding the actual modulation parameters for each of the conditions in the % 'trials' field above. i.e. {Par1,Par2} where par1,par2 are vectors of floats holding the actual parameters for % that condition, (each vector element corresponds to one event onset (as indicated by % BatchSpecs.conditions(..,..).onsets ) % % % % BatchSpecs.dirs{1...N}; % -cell array with work directories for N subjects. Results from model % estimation will be saved here, or read from here if needed for other % steps (contrast estimation, group analyses) % % BatchSpecs.regressors(1..N,1...S); % - Structure array containing extra regressors manually (usually nuisance regressors). % - Available fields: % names = Cell array with strings; names of regressors (i.e. {'Reg1','Reg2',Reg3'},... % values = NumScans x NumReg Matrix of Floats, where NumScans is the number of scans for this session, % and NumReg is the number of extra regressors (as specified in model(..).regressors_nb(session)) % % BatchSpecs.contrasts{1..N}(1...NumContrast) % - Cell array holding Structure array with statistical contrasts to be calculated (con*.img images) for each subject % - Available fields: % name = String; name of contrast (will show up when using 'contrast manager' from GUI) % type = String ('T'/'F'); type of contrast to calculate, T- or F-contrast % values = Vector of Integers; contrast vector or matrix (when using F-contrast) (example: [1 1 1 0 0 0 0 0 0 0]); % % BatchSpecs.groupstats(1...N) % - Structure array holding N different group statistics (2nd level RFX for all subjects specified in BatchSpecs.model, % or for all data in BatchSpecs.dirs when no model is specified) can be specified here. % One can refer to the Beta* or Con* image generated in the 1st level model and estimation or contrast generation section % - Available Fields: % model = String; at present this can only be 'T-test' (one sided T-test) or 'ANOVA' (ANOVA without a constant term ) % input_imgs = String;'con'/'beta'/'contrast' (refers to images to use: also see below at 'indices' field) % % indices = Vector of Integers; meaning depends on the value of 'input_imgs' field % When 'input_imgs' = 'contrast': Vector with indices of 1st level contrasts % (as specified in BatchSpecs.contrasts) for which 2nd level % T-test or ANOVA statistics should be calculated. Results will be % saved in a folder with the 1st level contrasts name. % % When 'input' = 'con' or 'beta': Indices refer to actual contrast IMAGES con*.img % or regression coefficient 'beta' images (beta*.img) from 1st level model estimation. % Use this when no contrasts (BatchSpecs.contrasts) were defined, and images will have to be used directly. % The con*.img and beta*.img will be looked for in the BatchSpecs.dirs workdirectories, and % will need to be present. % name = Name of folder were 2nd level stats results will be saved. % If this field is present and not empty, it overrides the % names specified in BatchSpecs.contrasts that would % otherwise be used. When 'input_imgs' ='contrast', this field is % irrelevant, and names of BatchSpecs.contrasts will be used instead % % % BatchSpecs.workdirparent % - String representing the directory where the results of the group analysis will be saved. % % % BatchSpecs.Todo % - Vector of Integers; List of what to do. Vector with 1s for relevant operations: % [ANALYSIS CONTRASTS PREPROCESSING GROUPANALYSIS] (i.e. [1 0 0 0] for 1st level stats only) % % ___________________________________________________________________ % @(#)spm_batch.m Bas Neggers (Utrecht University) % Martijn van den Heuvel (University Medical Center Utrecht) % v.0.5 Erno Hermans (Utrecht University)