User Tools

Site Tools


xff_-_sdm_format

SDM (BrainVoyager QX's Single-study design matrix) file format

Motivation

The most common approach to identify brain areas that are active during a specific task is by creating regressors used in a multiple linear regression model (General Linear Model; GLM). BrainVoyager QX uses a text-based file format that, after applying a convolution to the stimulus-based stick- or block functions, stores a set of columns, each representing one of the experimental conditions (or parametric modulations of these) as well as any additional variables added to the model, such as motion parameters, filters, heart-rate or respiratory influences on the hemodynamic BOLD response in the brain.

General setup

The information contained in BrainVoyager QX text files is either given in the form:

NameOfField:      Value

or, if a short list of values (e.g. an RGB color code triplet) is given, as

NameOfList:       Value1 Value2 Value3

or yet, in case several values are to be coded, as an array of values (or strings) without any header

Row1Col1 Row1Col2 Row1Col3
Row2Col1 Row2Col2 Row2Col3
...

Text-based tokens (constant values) are generally given without quotes, names are given with quotes (with exceptions noted where appropriate)! Linebreaks are added for increased readability. They do, however, not impact the actual reading of information from the file!

Example

example.sdm
FileVersion:            1

NrOfPredictors:         3
NrOfDataPoints:         60
IncludesConstant:       1
FirstConfoundPredictor: 3

255          255          0            0            255          255          255          255          255
"hand" "foot" "Constant"
0.000000     0.000000     1.000000
0.000000     0.000000     1.000000
0.000000     0.000000     1.000000
0.000000     0.000000     1.000000
0.000000     0.000000     1.000000
0.000000     0.000000     1.000000
0.000000     0.000000     1.000000
0.000000     0.000000     1.000000
0.000000     0.000000     1.000000
0.003554     0.000000     1.000000
0.113691     0.000000     1.000000
0.460896     0.000000     1.000000
0.831251     0.000000     1.000000
1.050803     0.000000     1.000000
1.133200     0.000000     1.000000
1.138367     0.000000     1.000000
1.109856     0.000000     1.000000
1.073621     0.000000     1.000000
1.039519     0.000000     1.000000
0.908721     0.000000     1.000000
0.549604     0.003554     1.000000
0.173206     0.113691     1.000000
-0.049103    0.460896     1.000000
-0.132650    0.831251     1.000000
-0.138260    1.050803     1.000000
-0.109856    1.133200     1.000000
-0.073621    1.138367     1.000000
-0.043074    1.109856     1.000000
-0.022412    1.073621     1.000000
-0.010500    1.039519     1.000000
-0.004457    0.908721     1.000000
0.001855     0.549604     1.000000
0.113141     0.173206     1.000000
0.460789     -0.049103    1.000000
0.831251     -0.132650    1.000000
1.050803     -0.138260    1.000000
1.133200     -0.109856    1.000000
1.138367     -0.073621    1.000000
1.109856     -0.043074    1.000000
1.073621     -0.022412    1.000000
1.039519     -0.010500    1.000000
0.908721     -0.004457    1.000000
0.549604     0.001855     1.000000
0.173206     0.113141     1.000000
-0.049103    0.460789     1.000000
-0.132650    0.831251     1.000000
-0.138260    1.050803     1.000000
-0.109856    1.133200     1.000000
-0.073621    1.138367     1.000000
-0.043074    1.109856     1.000000
-0.022412    1.073621     1.000000
-0.010500    1.039519     1.000000
-0.004457    0.908721     1.000000
-0.001700    0.549604     1.000000
-0.000550    0.173206     1.000000
-0.000107    -0.049103    1.000000
0.000000     -0.132650    1.000000
0.000000     -0.138260    1.000000
0.000000     -0.109856    1.000000
0.000000     -0.073621    1.000000

Fields

As almost any text-based file format in BrainVoyager QX, a FileVersion field allows the program to add new features. Given that information, the following fields are currently supported by NeuroElf/xff:

Field name Type Content Meaning
FileVersion single number 1 as the SDM file format has replaced the former RTC file format (which in its most recent form had file version 3), the enumeration restarted at 1
NrOfPredictors single number e.g. 3 specifies the number of columns to be read from the file (equivalent to the number of regressors/predictors used in the regression of one run/session/study
NrOfDataPoints single number e.g. 60 specifies the number of rows to be read from the file (equivalent to the number of data/sample/time points that will enter the regression)
IncludesConstant numeric flag either 0 or 1 if the regression table contains a column coding the constant (intercept) of the regression equation, this flag must be set to 1; in that case, the constant column should be the last column in the table
FirstConfoundPredictor single number e.g. 3 as an enhancement of the SDM over the former RTC format, additional regressors that are of no real interest (such as error trials, motion parameters, etc.) can be added to the model; importantly these regressors can vary across subjects, whereas all non-counfound regressors must match; this number thus tells BrainVoyager just as NeuroElf which regressors should be discarded after performing the actual regression
PredictorColors numeric array of RGB color code triplets e.g. 255 0 0 0 255 0 the example gives two RGB colors (red and green); the number of triplets must match the NrOfPredictors field, only integer values in the closed range of 0 through 255 can be used
PredictorNames array of strings e.g. “p1” “p2” “Constant” list of strings, each encapsulated in double quotes, representing the names of each of the columns (incl. the confound columns!); number must match the NrOfPredictors field, names should be unique and the name of the last column, if it is the constant/intercept regressor, should be “Constant”
SDMMatrix 2D array of numbers e.g. see above this is a tabular format of the regressors with the size NrOfDataPoints by NrOfPredictors; a value of 0 indicates that the condition in question does not have any pull over the regression equation for that data/sample/time point

Further notes

In addition to HRF-convolved design matrices, two further applications are given for the SDM format:

  • deconvolution design matrices - instead of applying a convolution with an assumed response shape, the length of a response function window is specified, which then leads to a series of 0/1-coded predictors, each additional regressor being a shifted copy of the initial stick function impulse response regressor, which allows to estimate the shape of the response (in the resolution of the data); please note that this model is still regressed in the temporal resolution of the data! that means that event-related models will incur a certain amount of temporal smoothing when the response is estimated
  • storing other regressor data - as pretty much any hypothesis driven test requires a regression of some sort (e.g. a correlation with a behavioral covariate), the SDM format can also be used to store arbitrary regressors (e.g. IQ or average reaction time for different tasks per subject; heart-rate for each time point, etc.)
xff_-_sdm_format.txt · Last modified: 2010/06/12 03:46 by jochen