Contributions:FilePlayback

From BCI2000 Wiki
Jump to navigation Jump to search

Synopsis

A source module that replays EEG data from BCI2000 .dat files.

NOTE: Make sure you read the FAQ entry on replaying a BCI2000 data file.

Location

http://www.bci2000.org/svn/trunk/src/contrib/SignalSource/FilePlayback

Authors

Adam Wilson, Jeremy Hill

Function

The FilePlaybackADC module allows previously recorded BCI2000 data to be "acquired" into BCI2000 as though it was acquired from an amplifier. This functionality could be useful for testing new algorithms, debugging, or generating screenshots or video captures after an experiment. The file will begin to be played back as soon as Set Config is pressed. However, it will jump back and play from the beginning (or other specified time-point) when the run starts.

IMPORTANT CAVEAT

Although playback mode is very useful during the development cycle of a BCI system, it is worth making the following caveat: if you record some EEG data, learn signal-processing parameters from it, slot those parameters into the config and replay the file, performance will probably be very good. Don't celebrate too soon (and please don't publish yet). Performance nearly always is very good when it's assessed on exactly the same data that you've just trained on. Performance on new data, which the parameter estimation procedure has not yet seen, is what counts.

So far so obvious, we hope. But note that the same principle applies, in perhaps a slightly less obvious manner, to cross-validation. If you train your classifier on file A and test it on file B, that's fine. However, you might then decide to go back, tweak the classification method, re-apply it to A and re-test it on B. Your tweaking-and-retesting has now become part of the learning procedure, and now B is "seen" (to more or less of an extent, depending on how much tweaking room you allowed yourself). So you can't report a truly honest assessment of your approach by reporting the performance-on-B of the classification approach that you have now found to perform best-on-B. To assess your method properly, you have to finish the A-B iteration, fix all possible learning parameters (including those optimized "by eye"), and test on new data C, D, E...

Parameters

The FilePlayback module can be started using a command-line parameter, --PlaybackFileName=FOO.DAT. In this case, the named file (FOO.DAT in this example) is used as a template for the session: this means that all the file's recorded states are declared as states of the FilePlayback module, and all the file's parameters are read and declared as parameters of the FilePlayback module, with default values equal to the values they had in the file. Exceptions to this are parameters from the System tab (which are set by the operator as appropriate for the playback session), and flags for enabling loggers (such as LogMouse), which are set to 0 by default. To turn on logging, specify (for example) --LogMouse=1 on the command-line as usual. To play back logged mouse data from the file, leave LogMouse as 0 and set PlaybackStates to 1.

Without the command-line switch, the FilePlayback module provides just three basic parameters for recreating the original conditions: SourceCh, SampleBlockSize and SamplingRate.

In either case, the module declares several additional playback-specific parameters, whose names all start with "Playback" to avoid possible name conflicts.

SourceCh

The number of digitized and stored channels that should be read from the file. This should be equal to or less than the SourceCh parameter in the dat file.

SampleBlockSize

The number of samples transmitted at a time. This value does not need to match the value stored in the dat file. However, it should be noted that the timing of events during the file playback may change relative to the event timing in the saved file, particularly if the event timing is specified in blocks, and not seconds.

SamplingRate

The data sampling rate in Hz. This must match the value in the dat file.

PlaybackFileName

The path to the BCI2000 data file to be played back. Note that this parameter may also be given as a command-line option when starting the module: in this case, the file is also used as a template for the session (its recorded parameters and states are declared as parameters and states of the FilePlayback module).

PlaybackStartTime

The starting time of the file (in blocks if no units or given, or in time units which you specify explicitly). This allows playback to begin at an arbitrary point in the file.

PlaybackChList

Leave this list empty to play back all available channels (default behavior). Or populate it, to specify a subset or re-ordering of the channels for playback. The length of the list must correspond to the value of SourceCh (and hence you must also adjust the lengths of your ChannelNames, SourceChGain and SourceChOffset parameters to match). Each element of the list must either be a valid index to a channel in the file that is being played back, or the label of a channel as given in the file's recorded ChannelNames parameter.

PlaybackSpeed

A factor indicating the acquisition speed. For example, if a value of 2 is specified, then the data will be read back at double the speed implied by SamplingRate, if CPU resources allow. A factor of 0.5 slows the data playback to half speed (start the module with --EvaluateTiming=0 to avoid any resulting error from violating the realtime constraint). As a special case, a value of 0 indicates that there should be no pause in-between blocks of data, and that the data should be acquired as quickly as possible. This playback speed will be limited by the processing capabilities of the computer, including the time required to read the data from the file, and to do any signal processing required by the SignalProcessing module.

PlaybackStates

This boolean value indicates whether the state variables recorded in the file should also be played back, along with the data. Playback is limited to state variables that are declared in both the file and the current BCI2000 session. (You can specify the --PlaybackFileName parameter as a command-line argument in order to ensure that all the file's states are declared in the current session.) Furthermore, SourceTime and StimulusTime are not played back, but set according to the timing of the playback session, as usual.

PlaybackLooped

This boolean value indicates whether BCI2000 should loop around to the beginning of the file when reaching the end of the file, or Suspend at the end of the file.

PlaybackReverseData

This boolean value indicates whether BCI2000 should play the EEG signal backwards. NB: If PlaybackStates is turned on, the states are still played forwards regardless. The idea is that the events of a particular run can be recreated while scrambling the EEG relative to them.

Additional Information

Data Storage

As with any acquisition module, the acquired data will be saved in a new dat file. While this may be desired in some instances, it usually makes sense to disable writing the data, since the raw signal will be identical. Therefore, you can pass --FileFormat=Null to prevent duplicate data being saved.

Random Sequences

The Application module typically generates a random sequence of events, such as the target number in the cursor task, or the stimulus number in the stimulus presentation task. When playing back a file, there is no guarantee that the same sequence will be displayed during the playback as was stored in the file.

However, BCI2000 allows a RandomSeed parameter to be specified, that will ensure that the same sequences are generated each time. To do so, pass --RandomSeed=10 to the Application module at the command line. Note, though, that the same seed must be used in both the original data file and the FilePlayback run. For more information on using this parameter, see Random Sequences in the User FAQ.

Data Format

The data is acquired from the file uncalibrated; therefore, it is still necessary to enter appropriate SourceChGain and SourceChOffset values for correct processing.

Known Issues

The trick of specifying a template file on the command-line, and thereby making every parameter default to the value it had in the file, only works if the FilePlayback module is the last module to connect to the operator. To make this more likely to happen, when a command-line template file is specified, the FilePlayback module waits for 2 seconds before connecting to the operator. However, if the SignalProcessing or Application module is started 2 sec or more later than the FilePlayback module, their parameter declarations may overwrite the default values from the template.

See also

User Reference:DataIOFilter, Programming Reference:GenericADC Class