SPM2: cbu_csv2_ui.m
This is a modified version of the principal SPM2 user interface module spm_spm_ui.m which adds an option of reading from a previously prepared text file called a 'design specification file' all the required information relating to the design of your study and the location of the images you want to analyse.
The functionality is exactly the same as the distributed version except that a new yes/no window pops-up immediately after you have selected or created your design.
Replying No leaves things to carry on as before except for the eventual creation of a file called 'design.csv' in your working directory. This is in a form suitable for re-use in the way that will now be described.
Replying Yes brings up a file selection window looking for files with suffix .csv.
The format for the input file (which has a default filename suffix '.csv') is
[various lines of preamble] + [various lines of factor/covariate/filename raw design stuff]
(That really is a '+' character on a line by itself separating the preamble from the raw stuff.)
PREAMBLE LINES are of the following formats:
EITHER
the line begins with a '%' and the whole line is treated as a comment
OR
the line begins with an '=' and the rest is treated as a line of MATLAB code. In principle this might be anything, but there are a few to which it will pay special attention:
=cbu_title = <string>; =cbu_factors = <string>; =cbu_cov_columns = <integer>; =cbu_cov_partition = <cell array of cell arrays of integer vectors>; =cbu_cov_labels = <cell array of cell arrays of strings>;
Here is what they look like and what they do:
=cbu_title=<string>;
e.g.
=cbu_title='Experiment 5 with subject 3 dropped';
The default value for cbu_title is the empty string .
where <string> is made up from the letters 'G', 'S' , 'C' and 'R'. This indicates the Group, Subject, Condition and Replication indices that are present in the design dataset, and the order in which they occur. The Replications index is optional: the program assigns the correct replication count as it goes along. e.g. indicates that each line of the design dataset will start with comma-separated integers for the Replication and Condition appropriate to that scan. As no 'G' or 'S' is listed it is assumed that there is 1 'group' consisting of 1 'subject'. Any of the designs available through SPM menus requires an obvious minimum amount of G, S, C information to be specified. The default value for cbu_factors is the empty string =cbu_factors=<string>
=cbu_factors='RC';
=cbu_cov_columns=<integer>;
This defines the number of covariates listed in the design dataset. Note that these do not have to be used in subsequent analyses, but the program needs to know how many to skip over and/or preserve. Their designation for inclusion in the subsequent analysis, and whether they are to be treated as 'of interest' or as 'nuisance' is determined by the next option.
E.g.
=cbu_cov_columns=7;
and
=cbu_cov_columns=[7];
both indicate that there are 7 covariates present in the file.
The default value for cbu_cov_columns is 0.
=cbu_cov_partition=<cell array of cell arrays of integer vectors>
This defines the block structure of the covariates and their partition in covariates of interest and of nuisance.
For reasons which are not expanded on here, SPM2 (and SPM99 before it) allow you to organise covariate vectors into 'blocks'. In SPM97 the nuisance covariates were called 'confounds' and the covariates of interest were just called plain 'covariates'. Each type of covariate was entered separately as a single column. SPM2 allows you to treat a set of (related) covariates as a block with a name of your choice and assigns the corresponding parameters an indexed sequence of names.
Using the natural correspondence between the covariates and the numbers from 1 up to cbu_cov_columns, each block is represented by a sequence of column numbers enclosed in square brackets, e.g. [3,4,5]. A covariate to be treated singly is represented as a single column number, e.g. 6, or equivalently [6].
The blocks corresponding to covariates of interest are put in a list enclosed in curly brackets, e.g. {[3,4,5],6}; the blocks corresponding to nuisance covariates are similarly listed inside curly brackets, e.g. {1,[2,7]}, and then these two list are themselves enclosed in curly brackets, e.g. . The commas are optional, and spaces can be included to increase legibility. If there are no nuisance covariates the second (empty) pair of curly brackets can be omitted.
Note also that there is no need for the covariate in the cbu_cov_partition formula to include all the covariates corresponding to the input data. In this way you can either include or exclude a particular set of covariates by a single line in this design specification file.
Here are some examples, supposing that cbu_cov_columns=7 (or more):
=cbu_cov_partition={{[1], [7], [3, 4, 5]}}
or equivalently
=cbu_cov_partition={{1, 7, [3, 4, 5]}}
indicates that the covariates of interest 1 and 7 will be handled singly and variates 3, 4 and 5 are treated as a 3-column block of interest.
While
=cbu_cov_partition={{1,2},{[3,4,5]}}
indicates that covariate 1 and 2 are separately of interest and that a block formed from covariates 3, 4 and 5 is to be treated as nuisance.
=cbu_cov_partition={ {},[3,4,5]}}
indicates that there are no covariates of interest but a block formed from covariates 3, 4, and 5 is to be treated as nuisance.
The default value of cbu_cov_partition is {}: i.e. none.
=cbu_cov_block_labels=<cell array of cell arrays of integer strings>
is used to label to covariates in the analysis. The cell structure must match that given for the cov_partition e.g.
{{'Mean RT','Stimulus Rat'},{'Movement parameters'}}
would match
{{[1],[2]},{[3,4,5]}} which has the same 2+1 structure, but not {{[1],[7],[3,4,5]}} which has a 3+0 structure.
DESIGN DATASET LINES are of the form:
EITHER
it starts with a '%' and is treated as a comment; this can be useful both for reminding you of aspects of your study or for 'commenting out' some datasets from the current analysis without actually need to drop the corresponding lines. In this way a subset of subjects, or conditions, or whatever can be conveniently reanalysed.
OR
the line starts with a '#' which sets up a global absolute path;
OR
the line starts with a '@' which sets a relative subdirectory;
OR
the line contains length(cbu_factors)+cbu_cov_covariates comma-separated columns containing the designated factor indices and covariate values, followed by the name of the corresponding .img dataset. If the final 'filename' field starts with a '/' it is treated as an absolute pathname regardless of current settings via '#' or '@'. If the filename does not start with a '/' then it is prefixed by the concatenated values of '#' and '@'. Typically you would use a single '#' to set up the directory in which the data for your imaging study are located, and then use a series of '@' commands, but either of '#' or '@' may be unused and empty, or set once only.
White space after commas is optional but aids legibility.
Blank lines are ignored.
EXAMPLE of 2 subject, 4 conditions, 3 separate nuisance covariates
=cbu_title='dummy';
% your comments on this line
=cbu_factors='SC';
=cbu_cov_columns=[3];
=cbu_cov_partition={{},{[1],[2, 3]}};
=cbu_cov_block_labels={{},{'A','B and C'}};
+
#/cbu/imagers/data/brain.imager/Stroop_Pilot/
% the main directory for the current study ...
@970110/p00/00/spm/
% subdirectory for subject 1
1, 1, 2.1, 1.5, 4.6, snemiss_000_tra.img
1, 1, 2.2, 3.2, 4.0, snemiss_004_tra.img
1, 1, 2.3, 2.7, 4.1, snemiss_011_tra.img
1, 2, 2.4, 3.0, 4.9, snemiss_001_tra.img
1, 2, 2.8, 3.4, 4.5, snemiss_005_tra.img
%1, 2, 2.6, 3.2, 4.7, snemiss_008_tra.img
1, 2, 2.6, 3.2, 4.7, /cbu/imagers/data/brain.imager/subj2/average_1_5.img
% dodgy data replace by average
1, 3, 2.6, 5.1, 4.8, snemiss_002_tra.img
1, 3, 2.7, 5.7, 4.6, snemiss_007_tra.img
1, 3, 2.7, 4.2, 4.2, snemiss_009_tra.img
1, 4, 2.8, 3.4, 4.3, snemiss_003_tra.img
1, 4, 2.9, 4.7, 4.0, snemiss_006_tra.img
1, 4, 2.6, 3.9, 4.3, snemiss_010_tra.img
@970111/p00/00/spm/
% subdirectory for subject 2
2, 1, 2.1, 1.5, 4.6, snemiss_000_tra.img
2, 1, 2.2, 3.2, 4.0, snemiss_004_tra.img
2, 1, 2.3, 2.7, 4.1, snemiss_011_tra.img
2, 2, 2.4, 3.0, 4.9, snemiss_001_tra.img
2, 2, 2.5, 3.4, 4.8, snemiss_005_tra.img
2, 2, 2.6, 3.9, 4.3, snemiss_010_tra.img
2, 3, 2.6, 5.1, 4.8, snemiss_002_tra.img
2, 3, 2.7, 5.7, 4.6, snemiss_007_tra.img
2, 3, 2.7, 4.2, 4.2, snemiss_009_tra.img
2, 4, 2.8, 3.4, 4.3, snemiss_003_tra.img
2, 4, 2.9, 4.7, 4.0, snemiss_006_tra.img
.... etc.
Mapping 'GSCR' onto the Basic and Standard Designs
Since I find the the 'GSCR' mnemonics useful in understanding designs I have stuck to using them to enter all designs. If you are using one of the basic, standard or SPM96 designs here is how 'GSCR' map onto the SPM's labels for these design factors:
%=======================================================================
% - Basic Stats Design definitions
%=======================================================================
'One sample t-test',
R='obs',C='',S='',G='',
'Two sample t-test',
R='obs',C='group',S='',G='',
'Paired t-test',
R='',C='cond',S='pair',G='',
'One way Anova',
R='repl',C='group',S='',G='',
'Simple regression (correlation)',
R='repl',C='',S='',G='',
'Multiple regression',
R='repl',C='',S='',G='',
'AnCova',
R='repl',C='group',S='',G='',
%=======================================================================
% - Standard (SPM99) PET/SPECT Design definitions
%=======================================================================
'Single-subject: conditions & covariates',
R='repl',C='condition',S='',G='',
'Single-subject: covariates only',
R='repl',C='',S='',G='',
'Multi-subj: conditions & covariates',
R='repl',C='condition',S='subject',G='',
'Multi-subj: cond x subj interaction & covariates',
R='repl',C='condition',S='subject',G='',
'Multi-subj: covariates only',
R='repl',C='',S='subject',G='',
'Multi-group: conditions & covariates',
R='repl',C='condition',S='subject',G='group',
'Multi-group: covariates only',
R='repl',C='',S='subject',G='group',
'Population main effect: 2 conds, 1 scan/cond (paired t-test)',
R='',C='condition',S='subject',G='',
'Dodgy population main effect: >2 conds, 1 scan/cond',
R='',C='condition',S='subject',G='',
'Compare-populations: 1 scan/subject (two sample t-test)',
R='subject',C='group',S='',G='',
'The Full Monty ',
R='repl',C='cond',S='subj',G='group',
%=======================================================================
% - SPM96 PET/SPECT Design definitions
%=======================================================================
'SPM96:Single-subject: replicated conditions',
R='repl',C='condition',S='',G='',
'SPM96:Single-subject: replicated conditions & covariates',
R='repl',C='condition',S='',G='',
'SPM96:Single-subject: covariates only',
R='repl',C='',S='',G='',
'SPM96:Multi-subject: different conditions',
R='',C='condition',S='subject',G='',
'SPM96:Multi-subject: replicated conditions',
R='repl',C='condition',S='subject',G='',
'SPM96:Multi-subject: different conditions & covariates',
R='',C='condition',S='subject',G='',
'SPM96:Multi-subject: replicated conditions & covariates',
R='repl',C='condition',S='subject',G='',
'SPM96:Multi-subject: covariates only',
R='repl',C='',S='subject',G='',
'SPM96:Multi-study: different conditions',
R='',C='cond',S='subj',G='study',
'SPM96:Multi-study: replicated conditions',
R='repl',C='cond',S='subj',G='study',
'SPM96:Multi-study: different conditions & covariates',
R='',C='cond',S='subj',G='study',
'SPM96:Multi-study: replicated conditions & covariates',
R='',C='cond',S='subj',G='study',
'SPM96:Multi-study: covariates only',
R='repl',C='',S='subj',G='study',
'SPM96:Compare-groups: 1 scan per subject',
R='subject',C='group',S='',G='',