Programming Reference:BCI2000FileReader Class

From BCI2000 Wiki
Jump to: navigation, search

The BCI2000FileReader class provides an interface to data stored in a single BCI2000 data file.

Methods

BCI2000FileReader([file name])

With a file name given as an argument, the constructor will try to open the specified file.

Open(file name, [buffer size=50kB])

Will open the specified data file. Use the IsOpen and ErrorState properties to check whether a file is actually open. In a second argument, the size of BCI2000FileReader's internal data buffer may be specified in bytes; when no buffer size argument is given, a default size of 50kB is used.

RawValue(channel, sample)

Sets the current sample position to the value specified in the second argument, and returns the raw sample value for the channel specified in the first argument.

CalibratedValue(channel, sample)

Sets the current sample position to the value specified in the second argument, and returns the calibrated sample value for the channel specified in the first argument. The calibrated sample value is obtained by applying channel-specific sample offsets and gains as present in the file's SourceChOffset and SourceChGain parameters.

ReadStateVector(sample)

Sets the current sample position to the specified value, and reads state vector data.

Properties

IsOpen (r)

true when a file has been opened successfully, false otherwise.

ErrorState (r)

One of

  • NoError,
  • FileOpenError,
  • MalformedHeader.

NumSamples (r)

The number of samples in the currently opened data file.

SamplingRate (r)

The currently opened data file's sampling rate.

SignalProperties (r)

A SignalProperties object describing the current file's data format, number of channels, sample block size (in its Elements property), and physical units.

FileFormatVersion (r)

A string describing the file's format as specified by the file header. Currently, this is "1.0" or "1.1".

HeaderLength (r)

The data file's header length in bytes.

StateVectorLength (r)

The state vector's length in bytes.

Parameters (r)

A ParamList object that contains all parameters present in the file.

Parameter (r)

Access to an individual parameter, following the syntax provided by the Environment class.

States (r)

A StateList object containing all state variables present in the file.

State (r)

Access to an individual state variable, following the syntax provided by the Environment class. The returned value will match the state variable's value at the current sample position, as specified to a previous call to one of the RawValue, CalibratedValue, or ReadStateVector methods.

StateVector (r)

Access to the full state vector, with state values matching those at the current sample position.

Performance Considerations

To improve performance when reading data, BCI2000FileReader uses an internal buffer which is 50kB in size by default but may be set to a different value using an optional second argument to BCI2000FileReader::Open().

Buffering strategy is optimized for sequential forward access, which is supposed to be the most relevant use case. Buffering is non-overlapping, with the requested sample always the first one in the buffer in case the buffer needs updating. In case of sequential access in reverse direction, this buffering scheme breaks down and becomes maximally inefficient because the entire buffer is updated on each access.

In a BCI2000 data file, data is organized such that, for each sample, values from all channels and states are stored, followed with all values from the next sample point, etc. When reading data from multiple channels, this implies that it is favorable to iterate over channels in an inner loop, and over samples in an outer loop; otherwise, buffering will become less efficient by a factor identical to the number of channels read.

See also

Technical Reference:BCI2000 File Format, User Reference:BCI2000FileWriter