Technical Reference:BCI2000 File Format: Difference between revisions

From BCI2000 Wiki
Jump to navigation Jump to search
 
(8 intermediate revisions by 2 users not shown)
Line 2: Line 2:
Its associated file name extension is <code>.dat</code>.
Its associated file name extension is <code>.dat</code>.
The header consists of a definition of all system parameters and states.  
The header consists of a definition of all system parameters and states.  
Thus, parameter values cannot change within a [[Glossary#Run|run]], which in turn corresponds to a single data file.
Thus, parameter values cannot change within a [[BCI2000 Glossary#Run|run]], which in turn corresponds to a single data file.


==Header==
==Header==
Line 45: Line 45:


==Binary Data==
==Binary Data==
The binary data directly follows the last CRLF.
The end of the header is marked by CRLF CRLF, and the binary data directly follows the last CRLF.  
For each sample, data values for all channels are stored, followed by <code>StateVectorLength</code> bytes for the state vector.
For each sample, data values for all channels are stored, followed by <code>StateVectorLength</code> bytes for the state vector.
Data samples are always stored in little endian byte ordering.
Data samples are always stored in little endian byte ordering.
Line 66: Line 66:
     +\texttt{StateVectorLength}}
     +\texttt{StateVectorLength}}
</math>
</math>
==Required Parameters==
These parameters will be present in any BCI2000 data file.
While some of these parameters are required to interpret a data file's content (source parameters), others reflect information about external circumstances (storage parameters), or internal housekeeping (system parameters).
===Section Source===
The parameters in this section are required to be present in any BCI2000 data file.
These parameters are necessary to interpret the raw data contained in the file, and are thus belonging into section ''Source''.
{|border="1"
|+Required Parameters
! Type !! Parameter Name !! Description
|-
| int || SampleBlockSize || number of samples acquired, transmitted, and stored at a time
|-
| float || SamplingRate || data acquisition rate in samples per second
|-
| int || SourceCh || number of digitized and stored channels
|-
| floatlist || SourceChOffset || raw data zero offset in AD units
|-
| floatlist || SourceChGain || factor to convert raw AD units into <math>\mu V</math>
|-
| int || AlignChannels || flag indicating whether data require alignment in time
|-
| floatlist || SourceChTimeOffset || individual channel offsets in time, ranging between 0 and 1; -1 indicates that offsets are distributed uniformly over 0..1
|}
===Section Storage===
These parameters are used to identify external circumstances of a recording, by listing subject, technical equipment, and technician information.
{|border="1"
|+Storage Parameters
! Type !! Parameter Name !! Description
|-
| string || SubjectName || subject alias
|-
| string || SubjectSession || subject session number
|-
| string || SubjectRun || run number within session (auto-incremented)
|-
| string || DataDirectory || directory under which the session directory is to be created
|-
| string || ID_System || rowspan="3" | equipment identification
|-
| string || ID_Amp
|-
| string || ID_Montage
|}
===Section System===
The parameters in this section are used by the BCI2000 modules to organize their connections, and they provide module versioning information.
{|border="1"
|+System Parameters
! Type !! Parameter Name !! Description
|-
| string || EEGsourceIP|| IP address the source module listens on
|-
| int || EEGsourcePort|| IP port the source module listens on
|-
| matrix || EEGsourceVersion || source module versioning information
|-
| string || SignalProcessingIP|| IP address the signal processing module listens on
|-
| int || SignalProcessingPort|| IP port the signal processing module listens on
|-
| matrix || SignalProcessingVersion || signal processing module versioning information
|-
| string || ApplicationIP|| IP address the application module listens on
|-
| int || ApplicationPort|| IP port the application module listens on
|-
| matrix || ApplicationVersion || application module versioning information
|-
| matrix || OperatorVersion || operator module versioning information
|-
| int || StateVectorLength || length of the state vector in bytes
|}
==Required States==
These states are present in all BCI2000 data files.
Individual [[User Reference:Filters|filters]] may add states to the system; see filter reference pages for a description of these states.
{|border="1"
|+Common States
! Length (bits) !! State Name !! Remarks
|-
| 1 || Running || Setting this state to 0 will put BCI2000 into suspended mode.
|-
| 16 || SourceTime || rowspan="2" | Time of data acquisition/stimulus delivery as an unsigned wrap-around value with a resolution of 1ms. This information is used to measure [[User Reference:Timing|system timing]].
|-
| 16 || StimulusTime
|}


==Software Components==
==Software Components==
*For writing, information about the BCI2000 data file format is encapsulated into the [[User Reference:BCI2000FileWriter|<code>shared/fileio/dat/BCI2000FileWriter</code>]] component.
*For writing, information about the BCI2000 data file format is encapsulated into the [[User Reference:BCI2000FileWriter|<code>shared/fileio/dat/BCI2000FileWriter</code>]] component.
*For reading, information about the BCI2000 data file format is encapsulated into [[Programming Reference:BCI2000FileReader|<code>shared/fileio/dat/BCI2000FileReader</code>]].
*For reading, information about the BCI2000 data file format is encapsulated into [[Programming Reference:BCI2000FileReader|<code>shared/fileio/dat/BCI2000FileReader</code>]].
*A Matlab mex file to read BCI2000 data files is provided at [[User Reference:load_bcidat|<code>Tools/mex/load_bcidat</code>]]. This mex file uses the <code>BCI2000FileReader</code> component.
*A Matlab mex file to read BCI2000 data files is provided at [[User Reference:Matlab MEX Files#load_bcidat|<code>Tools/mex/load_bcidat</code>]]. This mex file uses the <code>BCI2000FileReader</code> component.


==See also==
==See also==

Latest revision as of 18:54, 27 April 2010

A BCI2000 data file consists of a header and the actual raw brain signals. Its associated file name extension is .dat. The header consists of a definition of all system parameters and states. Thus, parameter values cannot change within a run, which in turn corresponds to a single data file.

Header

The header of a data file consists of lines of ASCII characters, separated by a carriage return/line feed (CRLF) control character sequence typically present in DOS/Windows text files. Its total length is given by the HeaderLen field in the first line. The header contains meta information, state (event) definitions, and parameters.

Meta Information

The fields in the first line specify meta information required to access the binary data that follows the header.

Since version 1.1, the first line begins with a BCI2000V field containing a floating point version number, and ends with a DataFormat field describing the format of the binary data as int16, int32, or float32. A missing BCI2000V field indicates a file format version of 1.0, and a DataFormat of int16.

The number of bytes in the state vector is determined by the sum of the lengths (given in bits) for all states, rounded up to the next byte (which equals the value of StateVectorLength in both the first line and, since StateVectorLength is also a system-wide parameter, in one of the lines in the [ Parameter Definition ] section). Thus, the first line contains all information required to read the binary information contained in the data file.

State Definitions

State definitions are preceded with a line [ State Vector Definition ], and given in the general State Definition format. In the context of the file header, the state definitions' value fields are redundant since they match the values associated with the first sample in the data file.

Parameter Definitions

Parameter definitions are preceded with a line [ Parameter Definition ], and follow the general Parameter Definition format. They represent the respective parameters' values at the beginning of the recording.

Summary

BCI2000V= 1.1 HeaderLen= l SourceCh= m StateVectorLength= k DataFormat= f CRLF
[ State Vector Definition ] CRLF
Name1 Length1 Value1 ByteLocation1 BitLocation1 CRLF
Name2 Length2 Value2 ByteLocation2 BitLocation2 CRLF
Name3 Length3 Value3 ByteLocation3 BitLocation3 CRLF
...
[ Parameter Definition ] CRLF
Section1 DataType1 Name1= Value1 DefaultValue1 LowRange1 HighRange1 // Comment CRLF
Section2 DataType2 Name2= Value2 DefaultValue2 LowRange2 HighRange2 // Comment CRLF
Section3 DataType3 Name3= Value3 DefaultValue3 LowRange3 HighRange3 // Comment CRLF
...
CRLF

Binary Data

The end of the header is marked by CRLF CRLF, and the binary data directly follows the last CRLF. For each sample, data values for all channels are stored, followed by StateVectorLength bytes for the state vector. Data samples are always stored in little endian byte ordering. Their format depends on the DataFormat field:

DataFormat field data type
int16 2-byte signed integer
int32 4-byte signed integer
float32 4-byte floating point (IEEE 754)

From the total file size, and the information present in the header's first line, the number of samples in a data file may be calculated as follows:

Required Parameters

These parameters will be present in any BCI2000 data file. While some of these parameters are required to interpret a data file's content (source parameters), others reflect information about external circumstances (storage parameters), or internal housekeeping (system parameters).

Section Source

The parameters in this section are required to be present in any BCI2000 data file. These parameters are necessary to interpret the raw data contained in the file, and are thus belonging into section Source.

Required Parameters
Type Parameter Name Description
int SampleBlockSize number of samples acquired, transmitted, and stored at a time
float SamplingRate data acquisition rate in samples per second
int SourceCh number of digitized and stored channels
floatlist SourceChOffset raw data zero offset in AD units
floatlist SourceChGain factor to convert raw AD units into
int AlignChannels flag indicating whether data require alignment in time
floatlist SourceChTimeOffset individual channel offsets in time, ranging between 0 and 1; -1 indicates that offsets are distributed uniformly over 0..1

Section Storage

These parameters are used to identify external circumstances of a recording, by listing subject, technical equipment, and technician information.

Storage Parameters
Type Parameter Name Description
string SubjectName subject alias
string SubjectSession subject session number
string SubjectRun run number within session (auto-incremented)
string DataDirectory directory under which the session directory is to be created
string ID_System equipment identification
string ID_Amp
string ID_Montage


Section System

The parameters in this section are used by the BCI2000 modules to organize their connections, and they provide module versioning information.

System Parameters
Type Parameter Name Description
string EEGsourceIP IP address the source module listens on
int EEGsourcePort IP port the source module listens on
matrix EEGsourceVersion source module versioning information
string SignalProcessingIP IP address the signal processing module listens on
int SignalProcessingPort IP port the signal processing module listens on
matrix SignalProcessingVersion signal processing module versioning information
string ApplicationIP IP address the application module listens on
int ApplicationPort IP port the application module listens on
matrix ApplicationVersion application module versioning information
matrix OperatorVersion operator module versioning information
int StateVectorLength length of the state vector in bytes

Required States

These states are present in all BCI2000 data files. Individual filters may add states to the system; see filter reference pages for a description of these states.

Common States
Length (bits) State Name Remarks
1 Running Setting this state to 0 will put BCI2000 into suspended mode.
16 SourceTime Time of data acquisition/stimulus delivery as an unsigned wrap-around value with a resolution of 1ms. This information is used to measure system timing.
16 StimulusTime

Software Components

See also

User Reference:Data File Formats, Technical Reference:Parameter Definition, Technical Reference:State Definition