1 =========================
   2 SPM 99 cbu_csv_ui:
   3 =========================
   4 
   5 This is a modified version of the principal SPM99 user interface
   6 module, spm_spm_ui.m which adds an option of reading from a
   7 previously prepared text file called a 'design specification file'
   8 all the required information relating to the design of your study
   9 and the location of the images you want to analyse.
  10 
  11 The functionality is exactly the same as the distributed version
  12 except that a new yes/no window pops-up immediately after you have
  13 selected or created your design.
  14 
  15 Replying 'No' leaves things to carry on as before except for the
  16 eventual creation of a file called 'design.csv' in you working
  17 directory. This is in a form suitable for re-use in the way that
  18 will now be described.
  19 
  20 Replying 'Yes' brings up a file selection window looking for files
  21 with suffix '.csv'.
  22 
  23 =============================================================================
  24 The format for the input file (which has a default filename suffix '.csv') is
  25 =============================================================================
  26 
  27 [various lines of preamble]
  28 +
  29 [various lines of factor/covariate/filename raw design stuff]
  30 
  31 
  32 (That really is a '+' character on a line by itself separating the
  33 preamble from the raw stuff.)
  34 
  35 ============================================
  36 PREAMBLE LINES are of the following formats:
  37 ============================================
  38 
  39 EITHER
  40 
  41 the line begins with a '%' and the whole line is treated as a comment
  42 
  43 OR
  44 
  45 the line begins with an '=' and the rest is treated as a line of
  46 MATLAB code. In principle this might be anything, but there are a
  47 few to which it will pay special attention:
  48 
  49 [1]  =cbu_title = <string>;
  50 
  51 [2]  =cbu_factors = <string>;
  52 
  53 [3]  =cbu_cov_columns = <integer>;
  54 
  55 [4]  =cbu_cov_partition = <cell array of cell arrays of integer vectors>;
  56 
  57 [5]  =cbu_cov_labels = <cell array of cell arrays of strings>;
  58 
  59 
  60 Here is what they look like and what they do:
  61 
  62 [1]  =cbu_title=<string>;
  63 
  64 e.g.
  65 
  66    =cbu_title='Experiment 5 with subject 3 dropped';
  67 
  68 The default value for cbu_title is the empty string ''.
  69 
  70 [2]  =cbu_factors=<string>
  71 
  72 where <string> is made up from the letters 'G', 'S' , 'C' and 'R'.
  73 This indicates the Group, Subject, Condition and Replication
  74 indices that are present in the design dataset, and the order in
  75 which they occur. The Replications index is optional: the program
  76 assigns the correct replication count as it goes along.
  77 
  78 e.g.
  79 
  80      =cbu_factors='RC';
  81 
  82 indicates that each line of the design dataset will start with
  83 comma-separated integers for the Replication and Condition
  84 appropriate to that scan. As no 'G' or 'S' is listed it is assumed
  85 that there is 1 'group' consisting of 1 'subject'.
  86 
  87 Any of the designs available through SPM menus requires an obvious
  88 minimum amount of G, S, C information to be specified.
  89 
  90 The default value for cbu_factors is the empty string ''.
  91 
  92 [3]  =cbu_cov_columns=<integer>;
  93 
  94 This defines the number of covariates listed in the design
  95 dataset. Note that these do not have to be used in subsequent
  96 analyses, but the program needs to know how many to skip over
  97 and/or preserve. Their designation for inclusion in the subsequent
  98 analysis, and whether they are to be treated as 'of interest' or
  99 as 'nuisance' is determined by the next option.
 100 
 101 E.g.
 102 
 103      =cbu_cov_columns=7;
 104 
 105 and
 106 
 107      =cbu_cov_columns=[7];
 108 
 109 both indicate that there are 7 covariates present in the file.
 110 
 111 The default value for cbu_cov_columns is 0.
 112 
 113 [4] =cbu_cov_partition=<cell array of cell arrays of integer vectors>
 114 
 115 This defines the block structure of the covariates and their
 116 partition in covariates of interest and of nuisance.
 117 
 118 For reasons which are not expanded on here, SPM99 allows you to
 119 organise covariate vectors into 'blocks'. In SPM97 the nuisance
 120 covariates were called 'confounds' and the covariates of interest
 121 were just called plain 'covariates'. Each type of covariate was
 122 entered separately as a single column. SPM99 allows you to treat a
 123 set of (related) covariates as a block with a name of your choice
 124 and assigns the corresponding parameters an indexed sequence of
 125 names.
 126 
 127 Using the natural correspondence between the covariates and the
 128 numbers from 1 up to cbu_cov_columns, each block is represented by
 129 a sequence of column numbers enclosed in square brackets, e.g.
 130 [3,4,5]. A covariate to be treated singly is represented as a
 131 single column number, e.g. 6, or equivalently [6].
 132 
 133 The blocks corresponding to covariates of interest are put in a
 134 list enclosed in curly brackets, e.g. {[3,4,5],6}; the blocks
 135 corresponding to nuisance covariates are similarly listed inside
 136 curly brackets, e.g. {1,[2,7]}, and then these two list are
 137 themselves enclosed in curly brackets, e.g.
 138 {{[3,4,5],6},{1,[2,7]}}. The commas are optional, and spaces can
 139 be included to increase legibility. If there are no nuisance
 140 covariates the second (empty) pair of curly brackets can be
 141 omitted.
 142 
 143 Note also that there is no need for the covariate in the
 144 cbu_cov_partition formula to include all the covariates
 145 corresponding to the input data. In this way you can either
 146 include or exclude a particular set of covariates by a single line
 147 in this design specification file.
 148 
 149 Here are some examples, supposing that cbu_cov_columns=7:
 150 
 151    =cbu_cov_partition={{[1], [7], [3, 4, 5]}}
 152 
 153 or equivalently
 154 
 155    =cbu_cov_partition={{1, 7, [3, 4, 5]}}
 156 
 157 indicates that the covariates of interest 1 and 7 will be handled
 158 singly and variates 3, 4 and 5 are treated as a 3-column block of
 159 interest.
 160 
 161 While
 162 
 163    =cbu_cov_partition={{1,2},{[3,4,5]}}
 164 
 165 indicates that covariate 1 and 2 are separately of interest and
 166 that a block formed from covariates 3, 4 and 5 is to be treated as
 167 nuisance.
 168 
 169    =cbu_cov_partition={ {},[3,4,5]}}
 170 
 171 indicates that there are no covariates of interest but a block
 172 formed from covariates 3, 4, and 5 is to be treated as nuisance.
 173 
 174 The default value of cbu_cov_partition is {}: i.e. none.
 175 
 176 [5] =cbu_cov_block_labels=<cell array of cell arrays of integer strings>
 177 
 178 is used to label to covariates in the analysis. The cell
 179 structure must match that given for the cov_partition e.g.
 180 
 181 {{'Mean RT','Stimulus Rat'},{'Movement parameters'}} would match
 182 {{[1],[2]},{[3,4,5]}} which has the same 2+1 structure, but not
 183 {{[1],[7],[3,4,5]}} which has a 3+0 structure.
 184 
 185 =====================================
 186 DESIGN DATASET LINES are of the form:
 187 =====================================
 188 
 189 EITHER
 190 
 191 it starts with a '%' and is treated as a comment; this can be
 192 useful both for reminding you of aspects of your study or for
 193 'commenting out' some datasets from the current analysis without
 194 actually need to drop the corresponding lines. In this way a
 195 subset of subjects, or conditions, or whatever can be conveniently
 196 reanalysed.
 197 
 198 OR
 199 
 200 the line starts with a '#' which sets up a global absolute path;
 201 
 202 OR
 203 
 204 the line starts with a '@' which sets a relative subdirectory;
 205 
 206 OR
 207 
 208 the line contains length(cbu_factors)+cbu_cov_covariates
 209 comma-separated columns containing the designated factor indices
 210 and covariate values, followed by the name of the corresponding
 211 .img dataset. If the final 'filename' field starts with a '/' it
 212 is treated as an absolute pathname regardless of current settings
 213 via '#' or '@'. If the filename does not start with a '/' then it
 214 is prefixed by the concatenated values of '#' and '@'. Typically
 215 you would use a single '#' to set up the directory in which the
 216 data for your imaging study are located, and then use a series of
 217 '@' commands, but either of '#' or '@' may be unused and empty, or
 218 set once only.
 219 
 220 White space after commas is optional but aids legibility.
 221 
 222 Blank lines are ignored.
 223 
 224 ==================================================================
 225 EXAMPLE of 2 subject, 4 conditions, 3 separate nuisance covariates
 226 ==================================================================
 227 
 228 =cbu_title='dummy';
 229 % your comments on this line
 230 =cbu_factors='SC';
 231 =cbu_cov_columns=[3];
 232 =cbu_cov_partition={{},{[1],[2, 3]}};
 233 =cbu_cov_block_labels={{},{'A','B and C'}};
 234 +
 235 #/cbu/imagers/data/brain.imager/Stroop_Pilot/
 236 % the main directory for the current study ...
 237 @970110/p00/00/spm/
 238 % subdirectory for subject 1
 239 1, 1, 2.1, 1.5, 4.6, snemiss_000_tra.img
 240 1, 1, 2.2, 3.2, 4.0, snemiss_004_tra.img
 241 1, 1, 2.3, 2.7, 4.1, snemiss_011_tra.img
 242 1, 2, 2.4, 3.0, 4.9, snemiss_001_tra.img
 243 1, 2, 2.8, 3.4, 4.5, snemiss_005_tra.img
 244 %1, 2, 2.6, 3.2, 4.7, snemiss_008_tra.img
 245 1, 2, 2.6, 3.2, 4.7, /cbu/imagers/data/brain.imager/subj2/average_1_5.img
 246 % dodgy data replace by average
 247 1, 3, 2.6, 5.1, 4.8, snemiss_002_tra.img
 248 1, 3, 2.7, 5.7, 4.6, snemiss_007_tra.img
 249 1, 3, 2.7, 4.2, 4.2, snemiss_009_tra.img
 250 1, 4, 2.8, 3.4, 4.3, snemiss_003_tra.img
 251 1, 4, 2.9, 4.7, 4.0, snemiss_006_tra.img
 252 1, 4, 2.6, 3.9, 4.3, snemiss_010_tra.img
 253 @970111/p00/00/spm/
 254 % subdirectory for subject 2
 255 2, 1, 2.1, 1.5, 4.6, snemiss_000_tra.img
 256 2, 1, 2.2, 3.2, 4.0, snemiss_004_tra.img
 257 2, 1, 2.3, 2.7, 4.1, snemiss_011_tra.img
 258 2, 2, 2.4, 3.0, 4.9, snemiss_001_tra.img
 259 2, 2, 2.5, 3.4, 4.8, snemiss_005_tra.img
 260 2, 2, 2.6, 3.9, 4.3, snemiss_010_tra.img
 261 2, 3, 2.6, 5.1, 4.8, snemiss_002_tra.img
 262 2, 3, 2.7, 5.7, 4.6, snemiss_007_tra.img
 263 2, 3, 2.7, 4.2, 4.2, snemiss_009_tra.img
 264 2, 4, 2.8, 3.4, 4.3, snemiss_003_tra.img
 265 2, 4, 2.9, 4.7, 4.0, snemiss_006_tra.img
 266 .... etc.
 267 
 268 ==================================================
 269 Mapping 'GSCR' onto the Basic and Standard Designs
 270 ==================================================
 271 
 272 Since I find the the 'GSCR' mnemonics useful in understanding
 273 designs I have stuck to using them to enter all designs. If you
 274 are using one of the basic, standard or SPM96 designs here is how
 275 'GSCR' map onto the SPM's labels for these design factors:
 276 
 277 %=======================================================================
 278 % - Basic Stats Design definitions
 279 %=======================================================================
 280 'One sample t-test',
 281     R='obs',C='',S='',G='',
 282 
 283 'Two sample t-test',
 284     R='obs',C='group',S='',G='',
 285 
 286 'Paired t-test',
 287     R='',C='cond',S='pair',G='',
 288 
 289 'One way Anova',
 290     R='repl',C='group',S='',G='',
 291 
 292 'Simple regression (correlation)',
 293     R='repl',C='',S='',G='',
 294 
 295 'Multiple regression',
 296     R='repl',C='',S='',G='',
 297 
 298 'AnCova',
 299     R='repl',C='group',S='',G='',
 300 
 301 %=======================================================================
 302 % - Standard (SPM99) PET/SPECT Design definitions
 303 %=======================================================================
 304 'Single-subject: conditions & covariates',
 305     R='repl',C='condition',S='',G='',
 306 
 307 'Single-subject: covariates only',
 308     R='repl',C='',S='',G='',
 309 
 310 'Multi-subj: conditions & covariates',
 311     R='repl',C='condition',S='subject',G='',
 312 
 313 'Multi-subj: cond x subj interaction & covariates',
 314     R='repl',C='condition',S='subject',G='',
 315 
 316 'Multi-subj: covariates only',
 317     R='repl',C='',S='subject',G='',
 318 
 319 'Multi-group: conditions & covariates',
 320     R='repl',C='condition',S='subject',G='group',
 321 
 322 'Multi-group: covariates only',
 323     R='repl',C='',S='subject',G='group',
 324 
 325 'Population main effect: 2 conds, 1 scan/cond (paired t-test)',
 326     R='',C='condition',S='subject',G='',
 327 
 328 'Dodgy population main effect: >2 conds, 1 scan/cond',
 329     R='',C='condition',S='subject',G='',
 330 
 331 'Compare-populations: 1 scan/subject (two sample t-test)',
 332     R='subject',C='group',S='',G='',
 333 
 334 'The Full Monty ',
 335     R='repl',C='cond',S='subj',G='group',
 336 
 337 %=======================================================================
 338 % - SPM96 PET/SPECT Design definitions
 339 %=======================================================================
 340 'SPM96:Single-subject: replicated conditions',
 341     R='repl',C='condition',S='',G='',
 342 
 343 'SPM96:Single-subject: replicated conditions & covariates',
 344     R='repl',C='condition',S='',G='',
 345 
 346 'SPM96:Single-subject: covariates only',
 347     R='repl',C='',S='',G='',
 348 
 349 'SPM96:Multi-subject: different conditions',
 350     R='',C='condition',S='subject',G='',
 351 
 352 'SPM96:Multi-subject: replicated conditions',
 353     R='repl',C='condition',S='subject',G='',
 354 
 355 'SPM96:Multi-subject: different conditions & covariates',
 356     R='',C='condition',S='subject',G='',
 357 
 358 'SPM96:Multi-subject: replicated conditions & covariates',
 359     R='repl',C='condition',S='subject',G='',
 360 
 361 'SPM96:Multi-subject: covariates only',
 362     R='repl',C='',S='subject',G='',
 363 
 364 'SPM96:Multi-study: different conditions',
 365     R='',C='cond',S='subj',G='study',
 366 
 367 'SPM96:Multi-study: replicated conditions',
 368     R='repl',C='cond',S='subj',G='study',
 369 
 370 'SPM96:Multi-study: different conditions & covariates',
 371     R='',C='cond',S='subj',G='study',
 372 
 373 'SPM96:Multi-study: replicated conditions & covariates',
 374     R='',C='cond',S='subj',G='study',
 375 
 376 'SPM96:Multi-study: covariates only',
 377     R='repl',C='',S='subj',G='study',
 378 
 379 'SPM96:Compare-groups: 1 scan per subject',
 380     R='subject',C='group',S='',G='',