====== 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:

<file>NameOfField:      Value</file>

or, if a short list of values (e.g. an RGB color code triplet) is given, as
<file>NameOfList:       Value1 Value2 Value3</file>

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

<file>Row1Col1 Row1Col2 Row1Col3
Row2Col1 Row2Col2 Row2Col3
...</file>

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 =====
<file - 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
</file>

===== 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.)