User Reference:DataIOFilter
Function
The DataIOFilter is part of every source module, and manages data acquisition, storage, and signal calibration into physical units (muV). For data acquisition, the DataIOFilter interfaces to an ADC component present inside a source module. For actual data storage, the DataIOFilter uses one of multiple FileWriter components present in a source module.
Parameters
Data Acquisition
Generally, data acquisition parameters are used for AD hardware configuration. If the software interface to the AD hardware does not allow for hardware configuration, data acquisition parameters and actual AD configuration must be synchronized manually.
SourceCh
The number of channels to digitized, and stored in the data file.
SampleBlockSize
The number of sample points that make up a BCI2000 sample block. The temporal duration of such a sample block is given by the ratio of SampleBlockSize to SamplingRate, and determines timing resolution for feedback.
SamplingRate
The number of samples per second per channel.
ChannelNames
A list of textual labels associated with channels. For EEG recordings, channel names should be electrode positions according to the 10-20 system (Fz, CPz, CP3, ...). While not mandatory, providing labels is a means to document recording locations in the data file itself, so no extra information needs to be maintained. Also, BCI2000 allows referring to channels by their labels. Thus, channel labels make it easier to avoid errors in configuring feedback parameters.
SourceChOffset, SourceChGain
Calibration information defining conversion from AD units into physical units (muV). Raw data are converted into muV according to
Common Data Storage Parameters
These are storage parameters common to all Data File Formats. For individual output file formats, additional parameters may be available.
DataDirectory
Path to an existing directory. Recorded data will be stored below that directory. The path may be absolute, or relative to the source module's working directory at startup. Usually, the working directory at startup matches the source module's executable location in the prog directory.
DataFile
The path to the data file relative to the directory, including the file name.
The DataFile parameter is a string that may contain references to other parameters in the form ${Parameter}. By default, it contains a session directory, named according to the ${SubjectSession} parameter, and a file name containing the ${SubjectRun} parameter along with the session number, and a date.
Date variables: The user can introduce date and/or time into the file name. One may enter ${DateTime:<format string>} to add date and/or time in an arbitrary format. <format string> must be a date-time format string as defined for the POSIX strftime() function. For example, ${DateTime:%F} will produce the date in the standard format YYYY-MM-DD. Be careful with time formats which will typically contain the : character, which is illegal in Windows file names. To produce both date and time, use ${DateTime:%F-%H-%M-%S}.
NOTE: When the file name contains both a run number, and a date/time string, auto-incrementing the run number will not work properly. Auto-incrementing the run number depends on all other components of the file name being constant, which is not the case for date and time.
SubjectName
A textual ID for the subject. This text may appear in session directories, and data file names.
SubjectSession
A textual ID for the current session. Sessions correspond to data directories. By default, the path of a session directory is constructed according to
${DataDirectory}/${SubjectName}${SubjectSession}
SubjectRun
A number indicating the current run. Runs correspond to data files. To avoid accidental loss of data, run numbers are auto-incremented to the largest unused value. Within a session directory, data file names are by default constructed according to
${SubjectName}S${SubjectSession}R${SubjectRun}.${FileFormat}
By default, a data file's extension depends on its File Format.
ID_System, ID_Amp, ID_Montage
These parameters are provided for documentation purposes and may contain arbitrary text.
FileSplittingCondition
While recording, recorded files may be split into multiple files with part2, part3, ... partN appended to the file name (before the extension). The first file will not be renamed to part1, though. When a condition is entered into the FileSplittingCondition parameter, it will be evaluated after each block of data has been written. Each time the condition is fulfilled, the old file will be closed, and a new one will be opened. Each partial file will be a valid file in the chosen FileWriter's format in its own right; only file names will carry information about how files should be combined to result in the full run file.
Conditions are simple strings representing either
- a temporal duration, e.g. 00:00:30 for a duration of 30 seconds, or
- a file size, e.g. 1.5MB for a size of 1.5 megabytes. Units of kB, MB, GB, TB and kiB, MiB, GiB, and TiB are supported. Prefixes without the i will refer to powers of 1000, whereas prefixes with an i refer to powers of 1024.
By default, the FileSplittingCondition parameter is empty, i.e. no file splitting occurs.
PrimaryOutputChannels
List of channels stored into the primary output file (see SecondaryOutputFiles below). Channel names may contain * and ? wildcards, and character ranges enclosed in []; wildcard patterns may be negated by prepending an exclamation mark. Ranges of channels may be specified using : or - to separate begin from end.
By default, this is set to "*", indicating that all channels should be recorded.
Examples:
1-8 // the first 8 channels 1-8 !4 // the first 8 channels except the 4th EEG* // wildcard pattern that matches all channels beginnning with "EEG" MCQ01-MCQ23 // range of channels by name
SecondaryOutputFiles
A matrix where each row corresponds to a secondary output file. Columns are:
name
A string that identifies the output file. When constructing a file name, that string is appended to the run's base name. Example: When "name" is "EEG", and the primary output file's name is "Wilbur001Run02.dat", then the secondary file name will be "Wilbur001R02.EEG.dat".
prefix
A string that is prepended to the output file name, separated with a dot. This may be used alternatively, or in conjunction with "name". The combination of "prefix" and "name" must uniquely identify the output file.
channels
A channel list as described for PrimaryOutputChannels above.
decimation
An optional integer decimation factor used to downsample the secondary output file's data. Before downsampling, a 3rd order IIR filter is applied to avoid aliasing artifacts. Note that the decimation factor must also be a divisor of the sample block size.
Visualization
VisualizeTiming
Switches display of timing information on or off. See User Reference:Timing for details.
VisualizeSource
Switches display of the raw source signal on or off.
VisualizeSourceDecimation
An integer decimation factor for the source signal display, resulting in display of every N-th sample only.
VisualizeSourceTime
The amount of time displayed in the source signal display.
SourceMin, SourceMax
For the source signal display, the minimum and maximum expected signal value in microvolts. SourceMin may exceed SourceMax to allow inversion of the signal display.
States
Running
1 while data is being processed, 0 in suspended state. Setting this state to 0 from a filter, or over the App Connector interface, will result in BCI2000 being suspended.
Recording
1 while data is being recorded, 0 otherwise. In a data file, this state will always be 1.
SourceTime
A 16-bit time stamp with a resolution of 1ms, and wrap-around occurring every 65536ms. The time stamp is set immediately after a block of data has been acquired from the AD converter.
StimulusTime
A 16-bit time stamp in the same format as the SourceTime state. This time stamp is set immediately after the application module has updated the stimulus/feedback display.