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:Parameters. For information about individual parameters, please refer to User Reference:Parameters.

Parameter Concept

Parameters are variables that primarily represent user configuration choices. Typical entities 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]9, 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 to 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

The basic format of a parameter line is

Section DataType Name= Value DefaultValue LowRange HighRange // Comment CRLF

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

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

where Labels is a list of textual labels that optionally substitutes 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 CRLF

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

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

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 does only support matrix-type sub-parameters within matrices as in the example above.

Display Format

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:

The 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 parameter's data type 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.

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.

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, a button exists that opens up a file or directory choosing 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. Right to the edit field, a button exists that opens up a color chooser 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)

Grouping Parameters

A user interface may use parameters' Section fields to collect parameters into groups, \eg{} 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, \eg{} 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 choose to 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.