Technical Reference:Parameter Definition

This page describes the concept of BCI2000 parameters, in conjunction with their textual representation as a "parameter line".

For information about how to access parameters from code, please refer to Programming Reference:Environment Class. For information about individual parameters, please refer to User Reference:Parameters.

Parameter Concept

Parameters are variables that primarily represent user configuration choices. Typical quantities encoded by parameters are:

• size and location of the feedback window
• subject ID
• sampling rate
• spatial filtering matrix.

Typically, parameters are constant throughout a run, often throughout a session or an entire experiment. In a BCI2000 data file, a full set of parameters is stored along with the data, allowing for reconstruction of the system configuration off-line.

As parameters represent user choices, the direction of information flow generally is Parameter Value->BCI2000 Module, i.e. parameter information is used to set BCI2000 modules to a defined state at initialization time. There are, however, some important exceptions to that rule.

• Source Modules may not be able to control all aspects of data acquisition. Control is limited by the design of the vendor-provided software interface to data acquisition hardware. As a typcial example, consider an EEG amplifier connected through a TCP-based socket interface. Generally, the amplifier will be configured in a separate user interface, and BCI2000 source module parameters such as SourceCh (number of channels) or SamplingRate must be chosen in accordance with that external UI's settings.
• System-internal Configuration is represented as parameters, and of potential interest to the user, but not user configurable. These parameters are placed in the configuration editor's System tab. Important examples comprise versioning information (e.g., the EEGSourceVersion parameter), others govern the connection between modules (e.g., the EEGSourceIP parameter).
• Automatic Adaptation to the subject's brain signals may be reflected by automatically updated parameters. For such parameters, the user specifies initial parameter values that may be overwritten at the end of a run. Unless changed by the user, these modified values will be the next run's initial values, and documented as such in that run's data file. As typical examples, consider the Normalizer filter's NormalizerOffsets and NormalizerGains parameters.

Parameter Lines

Parameter lines are a human-readable format used to represent individual parameters in:

• BCI2000 parameter files
• BCI2000 data files
• Filters' Publish() function
• BCI2000 messages sent between modules.

The basic format of a parameter line is

Section DataType Name= Value DefaultValue LowRange HighRange // Comment

Note that the = sign must follow the Name field immediately, without white space. However, white space after the = sign is mandatory.

If DataType is list, intlist or floatlist, the format is as follows:

Section DataType Name= (NumValues|Labels) Value(s) DefaultValue LowRange HighRange 
  // Comment

where Labels is a list of textual labels that optionally substitute the number denoted by NumValues. A list of labels is enclosed by {} or [], as in [low medium high]. If DataType is matrix , the format is as follows:

Section DataType Name= (NumRows|RowLabels)
    (NumColumns|ColumnLabels) Value(s) DefaultValue LowRange
    HighRange // Comment

where, again, each NumValues entry may be substituted by a list of textual labels. For matrices, values are given in row-major order, i.e. listing values from the first row first, then values from the second row, and so on, as in

Value(0,0) Value(0,1) ... Value(0,m) Value(1,0) Value(1,1) ... Value(1,m) ...

Data Types

The DataType field is not interpreted in a very strict sense. Rather, parameter values are always stored as strings, and converted into numerical values only when accessed as such from BCI2000 modules. For consistency, and to avoid user confusion, the following primitive types should be specified as appropriate:

Primitive Parameter Data Types

Name	Description
variant	unspecified type
int	unlimited range integer value
float	unlimited range, arbitrary precision float value
string	any string of characters (see the Special characters section for details)

A list or matrix type may be formed from these primitive types when concatenated with list or matrix, as in intlist, stringmatrix. For a list or matrix with entries of unspecified type, use an unprefixed list or matrix rather than variantlist or variantmatrix.

Special Characters

To allow for special characters and white space within parameter values and textual labels, an URL-like encoding scheme is adopted. In this encoding, a % character followed by up to two hexadecimal digits represents a byte value in hexadecimal notation which is interpreted according to the ASCII-Latin1 character table. Thus, %20 represents a space character, and %, %0, and %00 all represent an empty string value; %% represents the % character itself. The line

Demo string SomeString= a%20string%20with%20spaces % % %
    // White space example

defines a parameter SomeString which contains the value "a string with spaces". The single % characters indicate that the DefaultValue , LowRange and HighRange fields should be empty strings.

Sub-parameters

Any parameter value may itself be a sub-parameter. Sub-parameters are represented by a short-form matrix definition omitting the Section and Name fields, enclosed in a pair of braces:

Demo matrix NestedMatrices= 1 2 11 { matrix 2 2 1211 1212 1221 1222 }
    // Nested matrix example

will define a matrix parameter whose 1,2 entry is a 2x2 matrix. While the syntax allows for any combination of parameter and subparameter types, the current implementation of the parameter editor GUI only supports matrix-type sub-parameters within matrices as in the example above.

Display Format/Policy specifiers

Generally, a parameter's DataType field will be used to determine its appropriate display in a parameter editor. However, often a more user-friendly display may be achieved if additional information about a parameter's content is available.

To allow for such information, the comment line that is introduced by the two slashes (//) may contain a format identifier that is used by the Operator module to modify the display of the particular parameter. Format identifiers are strictly optional and are introduced as follows: (identifier). Currently, the following format identifiers are implemented:

Currently defined format identifiers

Identifier	Description
(enumeration)	a choice from an enumerated set of values
(boolean)	a yes/no choice
(inputfile)	path to a file to be opened for reading
(outputfile)	path to a file to be opened for writing
(directory)	path to a directory
(color)	RGB color

(enumeration)

The parameter value is presented as a drop down menu, with entries corresponding to the possible values listed in the comment. The first part of the comment appears above the drop down menu. All interpunction characters present in the comment are ignored. The data type of the parameter must be int. All possible values must appear in the comment, and the parameter's LowRange and HighRange fields must be consistent with the enumeration. LowRange will usually be 0, but may be any integer. For example:

Breakfast int BreakfastDrink= 1 1 1 3
  // Drink for breakfast: 1 Tea, 2 Coffee, 3 Juice (enumeration)

will display a drop down menu with entries "Tea," "Coffee,", and "Juice." The menu will be labeled "Drink for breakfast."

(boolean)

The parameter value is presented as a check box; the first part of the comment appears to the right of the check box. LowRange and HighRange must be 0 and 1. The parameter's data type must be int. To ensure human readability of parameter files, the possible values and their meaning may appear in the comment (e. g. 0: no, 1: yes) but will not be displayed with the check box. For example:

Breakfast int ServeBreakfast= 1 1 0 1
  // Serve breakfast: 0 no, 1 yes (boolean)

will display a check box labeled "Serve breakfast."

(inputfile)(outputfile)(directory)

The parameter value is presented as an edit field. Beside the edit field, there is a button that opens up a file or directory and selects dialog when clicked. The parameter's data type must be string.

Breakfast string WakeupSound= doorbell.wav 
  // Sound to play in the morning (inputfile)

(color)

The parameter value is presented as an edit field. To the right of the edit field there is a button that opens up a color selector dialog when clicked. The parameter's data type must be string, with its value containing the color in hexadecimal RGB encoding:

Breakfast string TableClothColor= 0x00FF00 0xFFFFFF 0x000000 0xFFFFFF
  // Color of table cloth to put up for breakfast (color)

Currently defined policy specifiers

Identifier	Description
(readonly)	readonly
(allow_override)	allow override
(parent_scope)	attach parameter to parent scope

(readonly)

The parameter cannot be edited by the user.

(allow_override)

allow_override is related to the way how parameters are published by filters. Without allow_override, the policy is that if the same parameter is published by two filters in sequence, the parameter values assigned by the first one will remain.

However, this is not desired in all cases. E.g., signal property parameters such as SourceCh, SourceChGain, SourceChOffset, and ChannelNames should

• be set to reasonable defaults by the DataIOFilter because not all ADC filters set them,
• allow for being overridden by ADC filters because a number of ADC filters need to set them to "auto", or ADC specific actual values.

Changing general policy is not an option because it would break some code, so the allow_override flag was introduced to mark parameters for which "override current value" was desired as a policy.

(parent_scope)

Just as filters themselves, parameters are located inside a hierarchy of filter nodes. By default, parameters are attached to the filter node by which they are published. In rare cases, such as inheritance of filters from a common base class, and their use in alternation (as by the ChoiceCombination class), parameters from the common base class may be duplicated, which is undesired. In this case, using (parent_scope) in the parameter declarations of the common base class will move ownership up to the ChoiceCombination and thus they will only exist once despite being published by each of the two choices.

Grouping Parameters into Sections

A user interface may use fields in the parameter Section fields to collect parameters into groups, e.g., by displaying all parameters with identical section fields on the same register tab of a GUI parameter editor dialog window. In the Section field, finer grained grouping may be expressed by specifying sub-sections separated by colon characters, e.g., a Section value of UsrTask:WindowDimensions will indicate that a parameter belongs to a WindowDimensions subsection of a section called UsrTask. A parameter editor implementation might display the respective parameter on a register tab called "UsrTask" and inside a group box labelled "WindowDimensions". Although any number of sub-sections may be present in the Section field, a user interface implementation may ignore sub-section entries below a level chosen by the implementer.

See also

User Reference:Parameters, Technical Reference:State Definition