Paradigm File Format in BESA
| Module information | |
| Modules | BESA Research Basic or higher |
| Version | 5.2 or higher |
Contents
General remarks
A paradigm description file (“PDG file”) contains the information which is relevant for describing an experimental setup in terms of the stimulation and response events that occurred. To describe the experimental paradigm, three terms are introduced:
- An attribute is used to group trigger events into a certain class. For example, in an auditory experiment, triggers could be grouped according to an attribute “modality” to distinguish stimulation and response, and another attribute “side” to distinguish left and right.
- An attribute value defines how a trigger event is classified in the class defined by an attribute. For example, the trigger with the code 1 could be a tone stimulus, and the trigger with the code 2 could be the subject’s response. That means that for the “modality” attribute, trigger 1 would receive an attribute value “tone”, whereas trigger 2 would receive an attribute value “response”.
- A condition defines which trigger events form the set of events that should be averaged. For example, this could simply be all trigger events with the modality “tone”, or all trigger events which have the modality “response”, and follow a trigger event with the modality “tone”.
The PDG file is written in ASCII format and can thus be viewed and edited in any text editor. It is subdivided into a maximum of 9 sections:
| [Attributes] | Attributes which are used to group the trigger events. This section is mandatory. |
| [Values] | A table of attribute values which are defined for the triggers used in the experiment. |
| [Names] | Names of conditions which are defined in detail in section 8 |
| [Epochs] | For each condition, averaging epochs, baseline epochs, and some other epochs are defined. |
| [Thresholds] | Threshold settings used for artifact rejection |
| [Averaging] | Defines which conditions are selected for averaging |
| [Filter] | Filter settings for averaging |
| [TimeFrequency] | Settings for time-frequency analysis |
| [Selections] | Each condition is written here as a statement using Boolean logic. |
| [ArtifactScan] | The artifact scan results are written here. |
Most sections can be omitted; their entries are then filled with default values. The default settings are given in the detailed description (see below). The most relevant sections for describing an experiment are Attributes, Values, and Selections.
Connection to BESA paradigm editing tool: Sections 1 and 2 define entries in the “Trigger” tab. Sections 3 and 9 define entries in the “Condition” tab. Section 4 defines entries in the “Epoch” tab. Sections 5 and 10 define entries in the “Artifact” tab. Section 6 defines entries in the “Average” tab. Section 7 defines entries in the “Filter” tab. Section 8 defines entries in the “Coherence” tab (if available).
All values can be edited in the respective tabs of the paradigm editing tool.
Detailed description of the sections
Attributes
This section is mandatory. It holds the attributes which are used to group the trigger events. The first attribute is always the trigger code (“code”). Attributes are separated by a tabulator. By default, the ERP module defines a second attribute “name” which can take trigger names as attribute values.
Example:
[Attributes] code name modality
Values
This section holds a table of attribute values which are defined for the triggers used in the experiment. Each row defines one trigger. The first column holds the trigger codes, since the trigger code is the only mandatory attribute. The second column holds the values for the second attribute (default in the ERP module: name), and so on. If no value is defined for an attribute, “NULL” is entered. For trigger codes which are not listed, no values are defined.
Example:
[Values] 0 NULL NULL 1 tone auditory 2 rare auditory 3 frequent auditory 128 response motor
The trigger with code 0 has no values defined, the trigger with code 1 has the name “tone” and the modality “auditory”, and so on.
Names
This section holds the names of conditions which are defined in detail in the section “Selections”. It is not necessary to give names to conditions. By default, conditions are simply named “Condition 1” through “Condition 32”. If a name is given, it is followed by the zero-based index of the condition it refers to. This enables mixing of conditions with user-given names and conditions with default names.
Example:
[Names] target 0 hit 1
The first condition obtains the name “target”, the second one obtains the name “hit”.
Epochs
This section holds the averaging epochs for each condition. Furthermore, additional epochs can be specified. Each epoch is defined by a floating point value which gives the pre-stimulus interval in milliseconds (ms), and a second floating point value which gives the post-stimulus interval in ms. Epochs are given in the following order:
Averaging epoch: The epoch used for averaging
Baseline epoch: The epoch over which the baseline is calculated
Epoch used for artifact rejection: The epoch in which the data are checked for artifacts
Stimulus artifact epoch: An epoch where a stimulus artifact occurred. This epoch is interpolated over before artifact rejection takes place
Stimulus delay: Only one value. This value gives the delay of the stimulus relative to the trigger event (e.g. when tactile stimulation is performed, where air pressure builds up after the trigger was set).
Not all epochs have to be provided. If the epochs list for a condition is incomplete, default values are used.
By default, the following values are used:
| Epoch | Pre-stimulus value | Post-stimulus value |
|---|---|---|
| Averaging | -100 | 500 |
| Baseline | -100 | 0 |
| Artifact rejection | -100 | 500 |
| Stimulus artifact | 0 | 0 |
| Stimulus delay | 0 |
Example:
[Epochs] -500.0 1000.0 -100.0 0.0 -500.0 1000.0 0.0 0.0 0.0 -800.0 500.0 -800.0 -700.0 -800.0 500.0 0.0 0.0 0.0
The first condition is averaged from 500ms before the trigger event to 1000ms after the trigger event. Baseline is calculated in the pre-stimulus interval between 100ms before the trigger event and the trigger event. Artifacts are rejected between –500ms and +1000ms, i.e. over the entire averaging epoch. No stimulus artifact interval and no stimulus delay is given.
For the second condition, averaging and artifact rejection are set to –800...500 ms, and baseline calculation is performed in the interval from –800ms to –700ms. Again, no stimulus artifact interval, and no stimulus delay is given.
Thresholds
This section holds values for artifact rejection. It can hold two sets of values. The first set contains settings for the color normalization of the BESA artifact scan tool. These values are not directly used for artifact rejection, but merely for visual control if the BESA artifact scan tool is used for artifact rejection.
The line following the first set of values contains either the string “AUTO_REJECT”, or “MANUAL_REJECT”. The second set contains settings for automatic rejection of artifacts. It is used if the preceding line contains the string “AUTO_REJECT”. Otherwise, only artifacts which were manually marked in the data are excluded from the averaging process.
The following table gives the order of the entries in the thresholds section:
| Line # | First column | Second column |
|---|---|---|
| 1 | Max. amplitude in EEG [µV] (display) | Max. amplitude in MEG [fT or fT/cm] (display) |
| 2 | Square root of variance of gradient in EEG (display) | Square root of variance of gradient in MEG (display) |
| 3 | Max. gradient in EEG (display) | Max. gradient in MEG (display) |
| 4 | AUTO_REJECT or MANUAL_REJECT | |
| 5 | Max. amplitude in EEG [µV] (for rejection) | Max. amplitude in MEG [fT or fT/cm] (for rejection) |
| 6 | Square root of variance of gradient in EEG (for rejection) | Square root of variance of gradient in MEG (for rejection) |
| 7 | Max. gradient in EEG (for rejection) | Max. gradient in MEG (for rejection) |
If no values are given , the following values are used by default:
| Threshold type | EEG | MEG |
|---|---|---|
| Max. amplitude | 100 µV | 1000 fT or fT/cm (depending on data) |
| Variance of gradient | 0.001 µV/∂T | 64 fT/∂T or 64 fT/(∂T cm) (depending on data) |
| Max. gradient | 75 µV/∂T | 800 fT/∂T or fT/(cm ∂T) (depending on data) |
The unit ∂T stands for the sampling interval.
Example:
[Thresholds] 100.0 1000.0 0.001 64.000 75.0 800.0 AUTO_REJECT 100.0 1000.0 0.001 64.000 75.0 800.0
Automatic artifact rejection is active. The rejection thresholds are:
- 100 µV for EEG amplitude,
- 1000 fT for MEG amplitude,
- µV/∂T for the square root of the variance of the gradient of the EEG signal,
- 64 fT/∂T for the square root of the variance of the gradient of the MEG signal,
- 75 µV/∂T for the gradient of the EEG amplitude, and
- 800 fT/∂T for the gradient of the MEG amplitude.
The display thresholds for the BESA artifact scan tool are set to the same values.
Rejection behavior:
A sweep is rejected from averaging if:
- The signal exceeds the max. amplitude threshold at any sampling point in any of the “good” channels.
- The variance of the gradient of the signal, taken over the whole sweep, does not exceed the variance threshold in any of the “good” channels. This criteria is especially useful for MEG channels, where channels may show a flat signal temporarily during the measurement.
- The gradient of the signal exceeds the max. gradient threshold at any sampling point in any of the “good” channels.
Averaging
This section holds the conditions which are selected for averaging, and further information about whether all sweeps or a sub-set will be averaged.
The first line holds the number of conditions currently selected (N). If N=0 or if the section is not present, all conditions which have at least 1 matching trigger event are automatically selected for averaging.
The next N lines are organized as follows:
Column 1: 1 if the condition is selected and activated, 0 if it is selected, but not activated.
Column 2: Zero-based index of the condition.
Column 3: Information about whether all sweeps or a sub-set will be averaged, encoded bit-wise:
| Bit | If set: |
|---|---|
| 0 | Average all matching sweeps |
| 1 | Average every second matching sweep (even) |
| 2 | Average every second matching sweep (odd) |
| 3 | Average the first half of matching sweeps |
| 4 | Average the second half of matching sweeps |
If more than one bit is set, a different averaging buffer will be created for each sub-set.
Example:
[Averaging] 1 1 1 9
One condition was selected. The second condition (condition index 1) is selected and activated, and two buffers will be averaged: the first buffer for all matching sweeps (bit 0 set), the second buffer for the first half of matching sweeps (bit 3 set).
Filter
This section holds filter settings which were chosen for averaging. The following table gives the possible settings.
| Line # | Filter type | Column 1 | Column 2 | Column 3 | Column 4 |
|---|---|---|---|---|---|
| 1 | High pass | Frequency [Hz] | Slope (see below) | Type (see below) | 1 if filter is applied,
0 if not applied |
| 2 | Low pass | Frequency [Hz] | Slope (see below) | Type (see below) | 1 if filter is applied,
0 if not applied |
| 3 | Notch | Frequency [Hz] | Width [Hz] | TRUE if on,
FALSE if off |
|
| 4 | Band pass | Frequency [Hz] | Width [Hz] | TRUE if on,
FALSE if off |
|
| 5 | Polygraphic channels | TRUE if polygraphic channels unfiltered,
FALSE if filtered like EEG/MEG channels |
TRUE if polygraphic channels rectified,
FALSE if not rectified |
||
| 6 | Selected channels | TRUE if selected channels differentiated,
FALSE if not differentiated |
TRUE if selected channels rectified,
FALSE if not rectified |
TRUE if selected channels smoothed,
FALSE if not smoothed |
|
| 7 | High pass,
Low pass |
TRUE if high pass filter applied to artifact scan,
FALSE if not |
TRUE if low pass filter applied to artifact scan,
FALSE if not |
The parameters Slope and Type are set to one of the following values:
| Slope value in file | Corresponding filter slope [dB/Oct] |
|---|---|
| 0 | 6 |
| 1 | 12 |
| 2 | 24 |
| 3 | 48 |
| Type value in file | Corresponding filter type |
|---|---|
| 0 | Zero phase |
| 1 | Forward |
| 2 | Backward |
If any of the required settings are missing, the filters that are currently set in the data file are used for averaging.
Example:
[Filter] 0.200000 0 1 1 75.000000 1 0 0 0.000000 1.000000 FALSE 75.000000 7.500000 FALSE FALSE FALSE FALSE FALSE FALSE TRUE FALSE
The filters are set as follows:
High pass at 0.2 Hz, 6 db/Oct, forward filtering, activated.
Low pass at 75.0 Hz, 12 db/Oct, zero phase filtering, not activated
Notch filter at 0 Hz, width 1 Hz, not activated
Band pass filter at 75 Hz, width 7.5 Hz, not activated
Polygraphic channels are filtered like the EEG and MEG channels. They are not rectified.
Selected channels are not differentiated, not rectified, and not smoothed.
High pass filter is also activated for the artifact scan, and low pass filter is not activated for the artifact scan.
So, the only filter that will be applied to the data for both averaging and artifact scan is the high pass filter at 0.2 Hz.
The last line holds activation settings for the artifact scan. Thus, it is possible to activate or de-activate filters solely for the artifact scan.
TimeFrequency
This section holds the settings of the Time-Frequency dialog. It is only read if the time-frequency module is loaded. The following values are stored:
| Line # | First column | Second column | Third column |
|---|---|---|---|
| 1 | ID for analysis type:
0: time-frequency 1: mean coherence 2: coherence |
ID for coherence computation type:
2: fixed reference channel 6: any reference channel. Currently, this value is always used. |
Channel index in case a fixed
reference channel was used. Currently, this value is meaningless. |
| 2 | Reduced sampling interval (in microseconds)
after time-frequency transformation |
||
| 3 | Index of the condition which
was chosen as target condition |
TRUE if a control condition was specified,
FALSE if not |
Index of the control condition if a
control condition was specified, or -1 if no condition was specified |
| 4 | ID for option of regional source usage:
0: radial orientation (not available for MEG) 1: all traces are taken 2: orientation which maximizes power is taken (not yet available) 3: first orientation is taken (interesting for oriented sources) |
TRUE if a Gaussian FIR filter is used
for complex demodulation (default), FALSE if a non-Gaussian FIR filter is used for complex demodulation |
|
| 5 | Index for the frequency spacing
that is used (index of the array entry in the combo box array of the dialog box) |
ID for bandwidth of the
demodulation filter that was chosen. 2: 2 frequency spacings 4: 4 frequency spacings (default) |
|
| 6 | ID for lower frequency cutoff index
(index of the array entry in the combo box array of the dialog box) |
Value of lower frequency cutoff in Hz | ID for higher frequency cutoff (index
of the array entry in the combo box array of the dialog box) |
| 7 | ID for the range in which mean coherence is
computed (currently not used): 1: whole data set 2: all epochs 3: epochs with a specific label |
ID of the epoch which was chosen for mean
coherence computation (currently not used) |
Example:
[TimeFrequency] 2 6 0 25000.000000 2 FALSE -1 0 TRUE 4 4 3 4.000000 6 1 0
In this example, the values have the following meaning:
1st line: Coherence analysis with any reference channel possible.
2nd line: The reduced sampling interval after Time-frequency transformation is 25 ms, i.e. 25000 µs.
3rd line: Target condition has condition index 2, no control condition was specified.
4th line: For regional sources, the radial orientation is taken. The Gaussian FIR filter is used.
5th line: Array entry with index 4 was chosen for the frequency spacing. The demodulation filter is calculated for a bandwidth of 4 frequency spacings.
6th line: Array entry with index 3 was chosen for the lower frequency cutoff. The lower cutoff frequency is 4 Hz. Array entry with index 6 was chosen for the higher frequency cutoff.
7th line: (currently not used) For mean coherence analysis, the whole data set is used. The epoch length of each epoch is given by array index 0.
Selections
This section holds the definition of conditions in boolean logic. Each line corresponds to either a logic statement, a bracket, or a boolean operator. Conditions are separated by blank lines. There are no default settings for this section.
Tokens are written in uppercase.
A statement consists of
- a qualifier that can be either CURRENT, PREVIOUS, or NEXT depending on which trigger event is tested
- an attribute (e.g. code, name, interval, ...)
- a comparison operator (IS, IS NOT, IS MORE THAN, IS LESS THAN)
- a value (e.g. “tone”, 300ms, ...)
Operators can be AND, OR. Bracketing is also possible.
Example:
[Selections] CURRENT.name IS "tone" CURRENT.name IS "response" AND PREVIOUS.name IS "tone" AND PREVIOUS.interval IS LESS THAN 300ms CURRENT.name IS "response" AND ( PREVIOUS.name IS "rare" OR PREVIOUS.name IS "frequent" )
This example contains 3 conditions.
The first one selects all trigger events with the value “tone” for the attribute “name”.
The second one selects all trigger events with the value “response” for the attribute “name” which are preceded by trigger events with the name “tone” with an interval between the two of less than 300ms.
The third one selects all trigger events with the name “response” which are preceded by either a trigger event with the name “rare” or a trigger event with the name “frequent”. The bracket is important; without the bracket, the order of testing is changed, with a possibly different result.
Artifact Scan
This section holds the results of an artifact scan. They are plotted in the artifact tab central window. For each epoch which was scanned, all values are written. The format contains 4 header lines, followed by 4 lines for each epoch:
Line 1: <Number of EEG channels> <Number of magnetometer or axial gradiometer channels> <Number of planar gradiometer channels>
Line 2: <Channel badness flag for channel 1> <Channel badness flag for channel 2> … <Channel badness flag for channel N>
The channel badness flag is set as follows:
| 0 | not bad or bad due to user interaction |
|---|---|
| bit 0 set: | bad due to minimum signal/variance crit., max. |
| bit 1 set: | bad due to amplitude criterion, integral crit. |
| bit 2 set: | bad due to amplitude criterion, max. crit. |
| bit 3 set: | bad due to gradient criterion, integral crit. |
| bit 4 set: | bad due to gradient criterion, max. crit. |
| bit 5 set: | bad due to minimum signal/variance crit., int. |
Line 3: <Number of conditions><index of first condition in list><index of 2nd condition in list>…<index of last condition in list>
The list is the artifact scan list of conditions.
Line 4: <Start of scanned range (position in microseconds)><end of scanned range (position in microseconds>
The remaining lines come in groups of 4. Each group contains the settings for one epoch. For each epoch:
Line 1: <artifact scan list index><position in microseconds>
The artifact scan list index is not necessarily the same as the condition index. It is possible that no artifact scan list index exists for a condition index, e.g. if no matches were found for a condition. The artifact scan list index runs from 0 to the number of conditions for which a scan was performed. The relation to the real condition index is given by the header line 3.
Line 2: <max_amp_in_channel1>< max_amp_in_channel2>…< max_amp_in_channelN>
Line 3: <variance_in_channel1><variance_in_channel2>…<variance_in_channelN>
Line 4: <max_gradient_in_channel1>< max_gradient_in_channel2>…< max_gradient_in_channelN>
Example:
Please note that one color denotes one line in the PDG-file.
[ArtifactScan]
65 0 0
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
0 0 0 8 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
0 0 0 0 0
2 1 2
0.000000 319120000.000000
0 7700000.00
6.71 18.46 44.48 23.50 48.68 24.34 60.42 13.43 20.14 44.48 21.82 60.42 25.18 62.94 15.11 35.25 18.46 36.93 51.19 32.73 41.96 16.78 35.25
20.14 26.02 4.20 35.25 12.59 35.25 21.82 33.57 21.82 7.55 15.95 34.41 31.89 31.89 16.78 27.69 28.53 36.09 11.75 29.37 46.16 19.30 24.34 10.91
26.86 19.30 31.05 7.55 22.66 36.93 33.57 37.77 27.69 21.82 10.91 28.53 34.41 48.68 27.69 27.69 15.95 0.00
1.04 5.87 14.84 4.36 13.35 4.95 12.75 3.38 5.63 13.72 3.78 17.54 4.54 13.11 2.97 14.77 2.69 16.07 10.95 8.41 8.39 4.74 14.73 1.92 6.49 0.65
7.46 1.51 15.48 3.92 9.27 4.01 0.89 3.29 10.13 9.02 11.43 3.75 6.81 6.77 7.77 1.39 9.51 25.05 4.51 6.36 1.27 5.50 4.19 10.37 0.91 5.93 11.32
8.88 9.77 9.11 6.51 1.79 7.68 10.50 14.24 8.82 8.22 2.95 0.00
2.52 6.71 10.07 5.04 8.39 5.04 10.07 4.20 6.71 11.75 5.04 12.59 5.04 9.23 5.04 10.07 4.20 10.07 8.39 7.55 8.39 5.87 11.75 3.36 5.04 1.68
7.55 2.52 10.91 5.04 6.71 5.04 2.52 5.04 12.59 11.75 14.27 5.87 6.71 6.71 7.55 2.52 13.43 15.11 5.87 8.39 3.36 7.55 8.39 13.43 2.52 8.39
10.07 7.55 8.39 10.91 9.23 4.20 6.71 13.43 11.75 11.75 10.91 6.71 0.00
1 8050000.00
8.39 15.95 35.25 21.82 22.66 19.30 26.86 12.59 17.62 31.89 21.82 20.98 17.62 26.86 15.11 23.50 16.78 30.21 29.37 22.66 22.66 16.78 22.66
15.95 23.50 5.87 22.66 13.43 25.18 19.30 26.86 17.62 6.71 11.75 20.14 19.30 23.50 14.27 27.69 21.82 20.98 9.23 20.14 64.62 17.62 23.50 8.39 15.11 15.11 21.82
6.71 20.98 29.37 24.34 20.98 16.78 17.62 11.75 25.18 26.86 24.34 20.98 21.82 15.11 0.00
1.37 6.08 14.32 7.01 11.00 7.54 11.19 3.85 7.11 13.96 6.67 12.18 7.18 10.64 5.47 16.83 3.79 21.73 9.60 12.82 9.11 5.45 12.86 3.74 8.62
0.83 9.30 2.92 14.68 5.85 13.81 5.18 1.28 3.44 8.30 7.25 12.03 4.16 8.80 9.74 7.23 1.76 8.49 56.16 5.41 7.29 1.70 4.96 4.45 9.66 1.35
7.16 12.32 10.99 8.29 6.38 6.61 2.07 8.25 13.16 8.23 8.70 8.71 4.44 0.00
2.52 6.71 10.91 8.39 9.23 8.39 9.23 6.71 6.71 10.91 8.39 9.23 8.39 9.23 5.87 11.75 5.04 12.59 9.23 10.91 7.55 5.87 11.75 5.87 8.39 2.52
7.55 5.87 9.23 6.71 11.75 6.71 3.36 4.20 7.55 7.55 10.07 5.87 9.23 7.55 7.55 3.36 7.55 28.53 7.55 8.39 3.36 5.87 5.87 9.23 3.36 9.23 9.23
7.55 6.71 7.55 7.55 4.20 9.23 11.75 7.55 8.39 8.39 7.55 0.00
This example contains the first 2 epochs from an artifact scan.
65 0 0
This line shows the number of EEG (65), MAG and GRA channels.
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 8 0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0 0
This line shows the badness of the channels. One channel has badness 8, which stands for gradient and integral criterion.
2 1 2
This line states the number of conditions in the artifact scan list, and their indices: There are 2 conditions; the list element 0 contains condition 1, list element 1 contains condition 2. Condition 0 is not part of the scan.
0.000000 319120000.000000
A range from 0 – 319.120 seconds was scanned. The next lines give the values for the epochs in groups of 4:
0 7700000.00
This entry has artifact list index 0 (which corresponds to condition index 1, see above), and the position of the epoch is 7.700000 seconds.
The next 3 lines hold amplitudes, variances, and gradients for each channel.
