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:

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!

Example

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

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!

NeuroElf wiki

Table of Contents