View source for 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 [[Technical Reference:BCI2000 File Format|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 <tt>SourceCh</tt> (number of channels) or <tt>SamplingRate</tt> 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 <tt>EEGSourceVersion</tt> parameter), others govern the connection between modules (e.g., the <tt>EEGSourceIP</tt> 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  <tt>NormalizerOffsets</tt> and <tt>NormalizerGains</tt> parameters.

==Parameter Lines==
Parameter lines are a human-readable format used to represent individual parameters in:
*[[Technical Reference:Parameter File|BCI2000 parameter files]]
*[[Technical Reference:BCI2000 File Format|BCI2000 data files]]
*[[Programming Reference:GenericFilter Class|Filters' Publish() function]]
*[[Technical Reference:BCI2000 Messages|BCI2000 messages]] sent between modules.

The basic format of a parameter line is
<pre>
Section DataType Name= Value DefaultValue LowRange HighRange // Comment
</pre>
Note that the = sign must follow the <tt>Name</tt> 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:
<pre>
Section DataType Name= (NumValues|Labels) Value(s) DefaultValue LowRange HighRange 
  // Comment
</pre>
where <tt>Labels</tt> is a list of textual labels that optionally
substitute the number denoted by <tt>NumValues</tt>. A list of labels
is enclosed by <nowiki>{} or []</nowiki>, as in
<tt><nowiki>[low medium high]</nowiki></tt>.
If DataType is ''matrix'' , the format is as follows:
<pre>
Section DataType Name= (NumRows|RowLabels)
    (NumColumns|ColumnLabels) Value(s) DefaultValue LowRange
    HighRange // Comment
</pre>
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:
{|border="1"
|+ 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 <tt>%</tt> 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, <tt>%20</tt> represents a space character, and
<tt>%</tt>, <tt>%0</tt>, and <tt>%00</tt> all represent an empty string value;
<tt>%%</tt> represents the <tt>%</tt> character itself.
The line
<pre>
Demo string SomeString= a%20string%20with%20spaces % % %
    // White space example
</pre>
defines a parameter ''SomeString''  which contains the value
"a string
with spaces". 
The single <tt>%</tt> 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:
<pre>
Demo matrix NestedMatrices= 1 2 11 { matrix 2 2 1211 1212 1221 1222 }
    // Nested matrix example
</pre>
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 <tt>DataType</tt> 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:
<tt>(identifier)</tt>.
Currently, the following format identifiers are implemented:

{| border="1"
|+ Currently defined format identifiers
! Identifier !! Description
|- 
| <tt>(enumeration)</tt> || a choice from an enumerated set of values
|-
| <tt>(boolean)</tt> || a yes/no choice 
|-
| <tt>(inputfile)</tt> || path to a file to be opened for reading 
|-
| <tt>(outputfile)</tt> || path to a file to be opened for writing 
|-
| <tt>(directory)</tt> || path to a directory 
|-
| <tt>(color)</tt> || RGB color 
|}

===<tt>(enumeration)</tt>===
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 <tt>int</tt>.
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: 
<pre>
Breakfast int BreakfastDrink= 1 1 1 3
  // Drink for breakfast: 1 Tea, 2 Coffee, 3 Juice (enumeration)
</pre>
will display a drop down menu with entries "Tea," "Coffee,", and
"Juice."
The menu will be labeled "Drink for breakfast."

===<tt>(boolean)</tt>===
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 <tt>int</tt>.
To ensure human readability of parameter files, the possible values
and their meaning may
appear in the comment (e. g. <tt>0: no, 1: yes</tt>) but will not
be displayed with the
check box. For example:
<pre>
Breakfast int ServeBreakfast= 1 1 0 1
  // Serve breakfast: 0 no, 1 yes (boolean)
</pre>
will display a check box labeled "Serve breakfast."

===<tt>(inputfile)(outputfile)(directory)</tt>===
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 <tt>string</tt>.
<pre>
Breakfast string WakeupSound= doorbell.wav 
  // Sound to play in the morning (inputfile)
</pre>

===<tt>(color)</tt>===
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 <tt>string</tt>, with its value
containing the color
in hexadecimal RGB encoding:
<pre>
Breakfast string TableClothColor= 0x00FF00 0xFFFFFF 0x000000 0xFFFFFF
  // Color of table cloth to put up for breakfast (color)
</pre>

{| border="1"
|+ Currently defined policy specifiers
! Identifier !! Description
|- 
| <tt>(readonly)</tt> || readonly
|-
| <tt>(allow_override)</tt> || allow override
|-
| <tt>(parent_scope)</tt> || attach parameter to parent scope
|}

===<tt>(readonly)</tt>===
The parameter cannot be edited by the user.

===<tt>(allow_override)</tt>===
<tt>allow_override</tt> is related to the way how parameters are published by filters.
Without <tt>allow_override</tt>, 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 <tt>SourceCh</tt>, <tt>SourceChGain</tt>, <tt>SourceChOffset</tt>, and <tt>ChannelNames</tt> 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 <tt>allow_override</tt> flag was introduced to mark parameters for which "override current value" was desired as a policy.

===<tt>(parent_scope)</tt>===
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 <tt>ChoiceCombination</tt> class), parameters from the common base class may be duplicated, which is undesired.
In this case, using <tt>(parent_scope)</tt> in the parameter declarations of the common base class will move ownership
up to the <tt>ChoiceCombination</tt> 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 <tt>Section</tt> 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 <tt>Section</tt> field, finer grained grouping may be expressed
by specifying
sub-sections separated by colon characters, e.g., a <tt>Section</tt>
value of
<tt>UsrTask:WindowDimensions</tt>
will indicate that a parameter belongs to a <tt>WindowDimensions</tt>
subsection of
a section called <tt>UsrTask</tt>. 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
<tt>Section</tt> 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]]

[[Category:Specification]]