====== MDM (BrainVoyager QX's Multiple-Design-Matrix) file format ======

===== Motivation =====
For several reasons, it is useful to be able to inspect and alter the list of studies used in particular analysis (e.g. to use a search-and-replace edit command in case files have been moved).

===== 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 (with exceptions noted where appropriate)! Linebreaks and empty lines are added for increased readability. They do, however, not impact the actual reading of information from the file!

===== Example =====
<file - example.mdm>

FileVersion:          3
TypeOfFunctionalData: VTC

RFX-GLM:              1

PSCTransformation:    1
zTransformation:      0
SeparatePredictors:   2

NrOfStudies:          5
"/Data/Study/Sub01/Sub01_MNI.vtc" "/Data/Study/Sub01/Sub01_Protocol.prt"
"/Data/Study/Sub02/Sub02_MNI.vtc" "/Data/Study/Sub02/Sub02_Protocol.prt"
"/Data/Study/Sub03/Sub03_MNI.vtc" "/Data/Study/Sub03/Sub03_Protocol.prt"
"/Data/Study/Sub04/Sub04_MNI.vtc" "/Data/Study/Sub04/Sub04_Protocol.prt"
"/Data/Study/Sub05/Sub05_MNI.vtc" "/Data/Study/Sub05/Sub05_Protocol.prt"
</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'', ''2'', or ''3''  | the default is ''3'', as it allows the most flexibility (see notes of other fields below)  |
| TypeOfFunctionalData  | text token  | either of ''FMR'', ''VTC'', or ''MTC''  | indicates which filetype is referenced by the MDM file (for ''MTC'', this also means that a third column of reference filenames is used, see below); **this field is only present for ''FileVersion'' 2 and higher!**  |
| RFX-GLM           | boolean number  | either ''0'' or ''1''  | if set top ''1'' (for now the only supported mode in NeuroElf!) the error term of the data is discarded; this also forces the SeparatePredictors to ''2''; **this field is only present for ''FileVersion'' 3 (and higher)!**  |
| PSCTransformation  | boolean number  | either ''0'' or ''1''  | if set to ''1'' data read from the referenced time course files will be %-change transformed before undergoing regression; this setting is mutually exclusive with ''zTransformation'' being set to ''1'' as well; **this field is only present for ''FileVersion'' 2 and higher!**  |
| zTransformation   | boolean number  | either ''0'' or ''1''  | if set to ''1'' data read from the referenced time course files will be z-transformed (mean := 0, std := 1) before undergoing regression; this setting is mutually exclusive with ''PSCTransformation'' being set to ''1'' as well  |
| SeparatePredictors  | single number  | either of ''0'', ''1'', or ''2''  | codes whether predictors of equal name are either concatenated across all runs of all subjects (''0''), only across runs of the same subject, but separate across subjects (''2''), or fully separated across runs and subjects (''1'')  |
| NrOfStudies       | single number   | e.g. ''5''      | gives the number of referenced time course (and model) filenames  |
| ReferencedFiles   | array of strings  | (see example)  | for ''TypeOfFunctionalData'' being set to either ''FMR'' or ''VTC'' there are two columns of strings (in double quotes): time course filenames (either FMR or VTC files) and design matrix filenames (SDM or, for older files, RTC files; **note: NeuroElf supports and encourages setting the names of these files to the PRT files that are used to generate the design matrix files!**), if ''TypeOfFunctionalData'' is set to ''MTC'' a third column of SSM (surface-to-surface mapping) files is expected as the first column of files that allows BrainVoyager to store data more efficiently (by computing statistics for vertices of assumed equal location across subjects)  |

===== Notes =====
  * NeuroElf stores additional information in the ''.RunTimeVars'' construct (see the [[xff#auxiliary_functionality|Auxiliary functionality]] sub-section of the page describing the [[xff]] class), such as a list of motion parameters (being used to regress out motion-related artifact from the data), temporal filtering parameters, grouping of subjects (for the plotting of trial-related averages, etc.)