For several reasons, it is useful to be able to inspect and alter the experimental design in a human-readable form (text).
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 (with exceptions noted where appropriate)! Linebreaks are added for increased readability. They do, however, not impact the actual reading of information from the file!
FileVersion: 2 ResolutionOfTime: msec Experiment: New experiment BackgroundColor: 0 0 0 TextColor: 255 255 255 TimeCourseColor: 192 192 192 TimeCourseThick: 2 ReferenceFuncColor: 0 0 80 ReferenceFuncThick: 2 NrOfConditions: 3 rest 0 Color: 224 224 224 acc_neu 4 48710 54605 151307 157207 192313 198207 384321 390212 Color: 139 139 0 rea_neu 2 315919 321811 552919 558815 Color: 255 255 0
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 | 2 or 3 | if FileVersion is set to 3, next to on/offsets one column of parametric weights can be stored (and is expected if ParametricWeights is set to 1, see below) |
| ResolutionOfTime | text token | either Volumes or msec | gives the resolution of the on/offsets (either as 1-based numbers of volumes or as 0-based millisecond time index) |
| Experiment | text | free-form text | name/description of experiment to which PRT file belongs |
| BackgroundColor | RGB color code | e.g. 255 0 0 | integer-based color code for the protocol plot in BrainVoyager (default: 0 0 0) |
| TextColor | RGB color code | e.g. 255 255 255 | integer-based color code for the text display alongside protocols in BrainVoyager (default: 255 255 255) |
| TimeCourseColor | RGB color code | e.g. 0 255 255 | integer-based color code for the extracted time-course plot in BrainVoyager |
| TimeCourseThick | single number | e.g. 2 | thickness of line used to plot/draw the extracted time-course |
| ReferenceFuncColor | RGB color code | e.g. 0 255 255 | integer-based color code for the reference time-course plot in BrainVoyager |
| ReferenceFuncThick | single number | e.g. 2 | thickness of line used to plot/draw the reference time-course |
| ParametricWeights | boolean number | either 0 or 1 | only available if FileVersion is set to 3! if set to 1, BrainVoyager expects a third value per onset that specifies the parametric weight for that particular stimulus |
| NrOfConditions | single number | e.g. 3 | number of conditions that are described in the rest of the file |
For each of the conditions (up to NrOfConditions), BrainVoyager then expects the following information (please note that other than the Color for each condition, the fields do NOT come with a field token in the file but just “as is”!!):
| Field name | Type | Content | Meaning |
|---|---|---|---|
| ConditionName | text | free-form name | this is used to distinguish and correctly group regressors in later estimation procedures (GLM); Please note: this field does NOT come with the fieldname but instead just as the name without any additional token!; condition names must be unique within one protocol file; the number of conditions (NrOfConditions field) must match the actually given conditions! |
| NrOfOnOffsets | single number | e.g. 2 | number of on/offsets (and possibly weights for this condition); can be 0 (if this condition does not have any onsets in this run/session); must match the actually given onset list! |
| OnOffsets | numeric array | (see example) | this is a two-column (or, if FileVersion := 3 and ParametricWeights := 1, three-column) array, of which the first column gives the onsets (either in Volumes or milliseconds) of each of the stimuli and the offset of that stimulus (which differs from programs such as SPM where onset and duration are given!); for Volume-based protocols, the offset Volume is still considered to show the effect of stimulation (i.e. it is impossible to code a typical event-related design with hypothetically zero-length stimulation as Volume-based PRT, as the shortest stimulation duration is 1 volume!); for Volume-based protocols the time starts with 1 (first volume), whereas for millisecond-based protocols the time starts with 0 (0 ms); in either case, the first two columns must only contain integer values; if in a parametrically modulated design not all conditions carry a parametric regressor, all weights must be set to 1 |
| Color | RGB color code | e.g. 0 255 0 | specifies the color which will be carried over into the GLM file for beta plots, etc.; NOTE: this field DOES have its proper field name as a prefix token! (see example above) |
FileVersion property/field to 3 and the ParametricWeights property/field to 1!