A GDS file describes all the information necessary to produce simulated experimental data for multiple subjects. It uses a simple syntax allowing to easily create and modify all necessary specifications. A typical GDS file looks like this:
The file above specifies a two-factorial experimental design with one between and one within factor. You may use the file as a starting point for creating your own data sets. The file ("Design_1W1B.gds") is located in the help folder for this plugin ("BVQXExtensions/Plugins/GroupDataSimulatorPluginHelp/"). This folder contains also example GDS files for several other designs.
A GDS file must start with the "FileVersion" entry, which must be "1" at present. Following this entry, the next three entries specify the number of between and within factors as well as the number of covariates:
NrOfWithinFactors: 1 NrOfBetweenFactors: 1 NrOfCovariates: 0
Note that in version 1 of the plugin, no covariates are supported, i.e. the value "NrOfCovariates" is ignored. The current version supports designs with up to 3 within factors and 1 between factor. Furture versions will allow generating data for more designs. The next entry defines a name for the simulated experiment:
ExpNameForFileNames: "VisualExperiment"
The name must be enclosed with quote signs in order to allow names with blanks. This holds also for other names provided. Note that the experiment name will be used as part of the file names generated by the plugin. Since some operating systems have difficulties with blanks in file names, it might be advisable to chose a name without blanks. The next section of the GDS file describes the levels for the specified factors. First all levels for the within factors must be defined, followed by the levels of the between factors. In the example GDS file, the levels for one within and one between factor are specified as follows:
NameOfWithinFactor1: "Visual Stimuli" NrOfLevels: 4 Level1: 255 0 0 "Faces" Level2: 0 255 0 "Houses" Level3: 0 0 255 "Objects" Level4: 255 0 255 "Patterns" NameOfBetweenFactor1: "Sex" NrOfLevels: 2 Level1: 255 255 0 "Male" Level2: 0 255 255 "Female"
For each factor, first the factor's name is defined. The within factor is named "Visual Stimuli" and the between factor is named "Sex" in our example Then the number of levels are specified using the "NrOfLevels" entry, which are four for the within factor and two for the between factor. For each level, you must further provide a color and a name, which will be used in generated protocols. Each color must be specified with three values defining a red, green and blue component, respectively, in the range from "0" to "255". Note that the colors and names are used in protocol files only for within factor levels since the between factors are used in subsequent analyses to categorize the subjects into different groups, e.g. into "male" and "female" for this example. In future extensions of the plugin, however, colors and names for between factor levels might also be used to prepare graphical output. Following the definition of the factor levels, importnat flags specify further details about the data to be generated:
BalancedDesign: Yes BaselineBetweenConditions: Yes BaselineEpochDuration: 6 NrOfSubjectsPerGroup: 10
The entry "BalancedDesign" must be set to "Yes" in the current version. A balanced design contains an equal number of subjects in each group. Future updates will allow to also simulate data for unbalanced designs. If the entry "BaselineBetweenConditions" is set to "Yes", baseline epochs are automatically added between each main condition interval in the generated protocols (recommended). If this option is set to "No", a "baseline" may be added as a level of within factors. In this case, "baseline" epochs will appear in a random sequence as any other main condition. If the "BaselineBetweenConditions" entry is set to "Yes", the entry "BaselineEpochDuration" must be defined next, otherwise this entry must not appear. The "BaselineEpochDuration" determines the duration in time points (TR's) for the baseline epochs, which may be different as for the main conditions. The "NrOfSubjectsPerGroup" entry specifies the number of subjects for each level of the between factors. Since in our case there is one between factor with two levels, data for 20 subjects will be generated, 10 for each of the two groups ("male" and "female"). The next entries provide important information for the generation of protocols:
RunsPerSubject: 1 TimePointsPerCondition: 8 RepetitionsPerCondition: 3 BaselineTimesAtStart: 0 BaselineTimesAtEnd: 4
The "RunsPerSubject" value specifies how many runs (VTC files) should be created per subject. At present this value must be "1". Higher values will allow in future versions to model multi-study data. The "TimePointsPerCondition" determines the interval length in time points (TR's) used for each occurrence of a main condition. The value "RepetitionsPerCondition" determines how often each condition occurs in the protocol. With the specified values "8" and "3" for these values, each of the 4 conditions of the within factor will occur three times with a duration of 8 time points. The order of occurrence of the 4 x 3 = 12 intervals will be randomized for the generation of the subject's protocols leading typically to a different protocol per subject. The produced protocols (as well as VTC and RTC files) will start with a "S
VTCBoundingBoxX: 68 188 VTCBoundingBoxY: 171 231 VTCBoundingBoxZ: 103 145 VTCResolution: 3 VTCTR: 2000
Since the plugin generates simulated data, it is not necessary to create full-blown VTC files. In order to save disk space, generation of small VTC files is recommended. It is, however, possible to generate full (e.g. Talairach space) VTC files in various resolutions. If you want to create full VTC files, specify the values "59" and "197" for the "BoundingBoxX" range, the values "57" and "231" for the "BoundingBoxY" range, and the values "52" and "172" (or "196" for extended TAL space) for the "BoundingBoxZ" range. The smaller bounding box used in the example creates a VTC file located mainly in the visual cortex. Note that the range values assume a "hosting" VMR with X/Y/Z dimensions of 256 voxels each. The "VTCResolution" value specifies whether one VTC voxel corresponds to 1 VMR voxel (value "1"), or to 2 x 2 x 2 = 8 VMR voxels (value "2"), or to 3 x 3 x 3 = 27 VMR voxels (value "3"). The "VTCTR" value specifies the TR value for the simulated data influencing how the expected data is generated from the protocol using a convolution operation. The next values specify how voxel time courses are modelled:
BaselineSignalLevel: 300 SubjBaselineSDev: 50 VoxelBaselineSDev: 0 MeasurementNoiseLevel: 1.0
The "BaselineSignalLevel" defines the mean signal level of voxel time courses before noise and effects are added. If this value is lower than "150" it will be forced to "150" in order to avoid exclusion in statistical analysis (if not turned off, BrainVoyager QX excludes voxel time courses with signal levels below 100 in order to mask out background voxels in real data). The "SubjBaselineSDev" value adds variability across subjects and the "VoxelBaselineSDev" adds variability from voxel to voxel within the VTC of a subject. The "MeasuremntNoiseLevel" specifies the amount of Gaussian noise added to modelled ideal time courses (see below). This value is defined with respect to a signal level of "100" and scales with the level of the signal. If the baseline signal level is "300", the standard deviation used to calculate Gaussian random numbers will be "3.0 x MeasurementNoiseLevel". For all "background voxels", the simulated time courses consist of the baseline signal level plus Gaussian noise using the described parameters. To model experimental effects, one or more regions (Volumes-Of-Interest, VOIs) have to be specified:
NrOfVOIs: 2 COG-VOI-1: -30 -74 -10 COG-VOI-2: 25 -80 10 SphereRadius-VOI-1: 1 SphereRadius-VOI-2: 2 SubjSpatialSDev-VOI-1: 0 SubjSpatialSDev-VOI-2: 0
Until now, all voxels would be modelled with a stationary time course exhibiting Gaussian noise fluctuations around the specified baseline signal level. To test procedures localizing activity (e.g. GLM, ANOVA, ICA), fluctuations due to experimental effects may be superimposed at various spatial positions specified by VOIs. The parameter "NrOfVOIs" determines the number of spatial regions (clusters) used to model experimental effects. Each VOI is created (roughly) as a sphere from coordinates specifying its center of gravity (COG) in Talairach coordinates and its radius in VTC voxels. Note that the x, y, and z coordinates should fall within the specified VTC bounding box. You can easily check that by adding "128" to the negative value of a Talairach coordinate (e.g. -Y + 128) resulting in voxel coordinates within a Talairach-VMR file with dimensions of 256. The radii of each VOI are defined next. These should be rather small values if a "VTCResolution" value of "3" is used since the radius is interpreted in VTC voxels. To model effects in a single voxel, use a "SphereRadius" value of "0". You may also specify that the VOIs position spatially vary around the provided position across subjects. This is, for example, useful to study the effect of partial spatial overlap as well as the statistical improvements achievable when defining subject-specific (individual) VOIs in the context of a ROI analysis. The spatial variability is provided for each VOI using the "SubjjSpatialSDev" parameter. The next three values define how the modelled effects are specified.
MeansForGroupsOrSubjects: Groups SubjSDevWithinCells: 1.0 TypeOfDataValues: PSC
The "MeansForGroupsOrSubjects" specifies whether condition effects are provided for each subject or for group mean values. At present only "Groups" are supported. If "Groups" is specified, the entry "SubjSDevWithinCells" is expected next specifying the variability of the effect across subjects. If this value is set to "0.0" all subjects within a group will have the same effect and the values will only differ (slightly) due to measurement noise. If this value is larger than "0.0", variability across subjects is added by drawing from a Gaussian noise distribution. The "TypeOfDataValues" specifies how the modelled effects are interpreted. At present, only the value "PSC" is possible specifying that effects (as well as the across-subject variability value "SubjSDevWithinCells") are modelled as percent signal changes. Finally the mean effects are provided separately for each defined VOI.
EffectsAtVOI-1: 5.0 2.0 3.0 -0.1 3.0 0.0 1.0 0.0 EffectsAtVOI-2: 4.0 1.0 0.0 0.0 1.5 4.0 0.0 2.0
The "EffectsAtVOI" entries specify effect sizes for each condition separate for each VOI. Since we have specified two VOIs, two effect tables are shown. Each row of the table specifies the desired mean effects for one group. Since we have one between factor with two groups, two rows are shown. Within a row, all within factor effects are modelled. Since we have specified one within factor with four levels, their are four columns within the tables. The first row in the "EffectsAtVOI-2" table thus provides the mean effects for the first group ("male") for the four conditions "Faces" (value "4.0"), "Houses" (value "1.0"), "Objects" (value "0.0") and "Patterns" (value "0.0"). Note that in the second VOI an interaction effect is modelled between the two groups. For details of the analysis of the described specific design, click here. If more than one within factor is specified, the levels of the first factor changes fastest, followed by the levels of the second factor, followed by the levels of the third factor. With two factors A and B with two levels for both factors, the within condition effects must be specified as "A1B1 A2B1 A1B2 A2B2".