Table of Contents

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

  1. whenever you wish to use parametric weights, make sure to set the FileVersion property/field to 3 and the ParametricWeights property/field to 1!