Technical Reference:State Definition

From BCI2000 Wiki
Jump to: navigation, search

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

For information about how to access state values from code, please refer to Programming Reference:Environment Class. For information about individual states, please refer to User Reference:States.

State Concept

States are variables that represent the internal state of a BCI2000 system as it is evolving over time in response to:

  • brain signal input
  • user interaction through the operator interface
  • trial sequencing by the application module.

Typical quantities/qualities encoded by states are:

  • whether the system is running or suspended
  • the time when a block of data was recorded
  • stimulus or task being presented
  • the classification result
  • the state of an external marker (trigger) to be saved for off-line analysis.

Typically, state values change once per block of data, or once per trial. In a BCI2000 data file, the full set of states is stored along with the data, allowing for reconstruction of on-line system state off-line.

State Vector

In a BCI2000 system, a collection of states is maintained as a State List. For each state present in that state list, its value is kept as a range of bits in a bit vector called State Vector. BCI2000 modules and filters may read and write state values during processing. The state vector's content is saved, in its binary form, into BCI2000 data files per-block. Using the ByteLocation, BitLocation, and Length fields from the state definitions present in a file, a state's value may be read from the data file.

A state vector is a narrowly packed bit field in little endian ordering. This implies that, for a state containing more than a single bit, more significant bits are placed at higher bit and byte locations.

As an example, consider a state vector consisting of a 1-bit state "Running", and a 16-bit state "SourceTime". This will result in a three-byte state vector layout like this:

State Vector Byte 0 State Vector Byte 1 State Vector Byte 2
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
Running SourceTime unused
0 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15  

State Lines

State lines are a human-readable format used to represent individual states in

Core modules and the operator module use this format to communicate in the system initialization phase, as well as during system performance and for system termination.

The format of a state line is

Name Length Value ByteLocation BitLocation CRLF

where Length refers to the number of bits used to represent the state's value, and ByteLocation and BitLocation refer to its position in the State Vector, with BitLocation ranging from 0 to 7.

Depending on the context of a state line, one or more of its fields may be ignored:

  • In a State message sent from the operator module to a core module, Length, ByteLocation, and BitLocation will be ignored.
  • In a State line contained in a data file, the Value field matches the state's value stored with the first block of data samples.

Generally, the Value field specifies an initial value of a state. Actual values are stored in the State Vector data structure.

State values are interpreted as unsigned integers, and limited to 32 bit in the current implementation (as defined by the State::ValueType typedef in BCI2000/src/shared/types/State.h).

See also

User Reference:States, Technical Reference:Parameter Definition