====== PRT (BrainVoyager QX's Protocol) file format ======

===== Motivation =====
For several reasons, it is useful to be able to inspect and alter the experimental design in a human-readable form (text).

===== 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 are added for increased readability. They do, however, not impact the actual reading of information from the file!

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

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</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   | ''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)  |

===== Notes =====
  - **whenever you wish to use parametric weights, make sure to set the ''FileVersion'' property/field to ''3'' and the ''ParametricWeights'' property/field to ''1''!**