User Reference:Matlab Tools

From BCI2000 Wiki
Jump to navigation Jump to search

In the tools/matlab directory of your BCI2000 distribution, there are several Matlab functions for offline analysis of recorded data-files, for use on the Matlab command-line or in your own custom scripts. The principal function is bci2000chain, which allows you to recreate a BCI2000 processing chain offline, explore the effect of parameter changes, and examine the results in Matlab.

NB: if you prefer clicking the mouse to writing lines of Matlab code, you will probably be happier with the Offline Analysis Matlab GUI or the (now non-Matlab-based) P300Classifier tool.

Here we provide an overview of the main Matlab functions without going into the details of their calling syntax. As always, to get full documentation on a particular function you can go to the Matlab prompt and type something like

>> help bci2000chain

Note that most of the Matlab functions here require the BCI2000 mex files as a dependency. In addition, bci2000chain requires binaries of the BCI2000 command-line tools.


bci2000path

This is a bootstrapping utility. Before you do anything, Matlab needs to know where the tools are. This function uses the generic function managepath (also supplied) to allow you to:

  • tell Matlab where your BCI2000 distribution is;
  • return the full absolute path to a sub-part of the BCI2000 distribution: for example, bci2000path('tools/matlab/bci2000path.m') would return the full path to this file itself (or at least, to where it should be);
  • add subdirectories of the BCI2000 distribution to the Matlab path, for the duration of the current Matlab session;
  • add subdirectories of the BCI2000 distribution to the system shell's path, for the duration of the current Matlab session;
  • remove directories from the path again, or even remove everything BCI2000-related from the Matlab and system paths in one go.

Of course, before you can call bci2000path, Matlab needs to know where bci2000path itself is. This chicken-and-egg problem is typical of Matlab path-juggling. You could use the graphical pathtool to add an absolute reference to the tools/matlab directory "permanently" to the Matlab path, but anyone who has made heavy use of Matlab for some time, and is in the habit of using more than one third-party toolbox, will know that this leads to problems sooner or later. So we do not recommend the path GUI. One solution is to adapt the following lines and put them either in your startup.m file, or in some other handy function in the My Documents\MATLAB (or $HOME/matlab) directory so that you can call it when needed:

olddir = pwd;
cd('C:\BCI2000')   % The absolute path has to be hardcoded somewhere, and here it is.  Watch out, in case this is (or becomes) incorrect 
cd tools, cd matlab
bci2000path -AddToMatlabPath tools/matlab
bci2000path -AddToMatlabPath tools/mex
bci2000path -AddToSystemPath tools/cmdline   % required so that BCI2000CHAIN can call the command-line tools
cd(olddir) % change directory back to where we were before
clear olddir

bci2000chain

The BCI2000 command-line tools allow the online processing performed by BCI2000 to be recreated exactly offline. This is possible because online BCI2000 modules consist of a chain of filters, each filter being implemented in a self-contained source file. We can therefore take the individual filter implementations and build them singly, as separate executables that can be called from the system command-line. Recreating a preprocessing chain offline is then a question of passing a stream of data through a chain of these filter tools, connected by an operating-system "pipe".

The bci2000chain function uses the command-line tools (calling them via Matlab's builtin function system), but it hides the details and presents itself to you as a single Matlab function.

Dependencies

bci2000chain requires the command-line binaries, including bci_dat2stream and bci_stream2mat as well as any specific filter tools you intend to use, to have been built in tools/cmdline. The tools/cmdline directory must be on the operating-system path (not to be confused with the Matlab path) for the session. The BCI2000 mex files load_bcidat and convert_bciprm, and the m-files make_bciprm.m, read_bciprm.m and read_bcidate.m, must be in directories that are on the Matlab path. One way of satisfying these path requirements is shown above, using the bci2000path function.

Example

The following example reads and replays a sample data file through the specified filter chain (TransmissionFilter, then SpatialFilter, then ARFilter). The parameters for these filters start out having the same values that they did when the file was recorded. But in this example, we override some of the spectral estimation parameters using the ones in ExampleParameters.prm, and then further override the spatial filter setting by switching it to CAR mode:

fn = bci2000path('data', 'samplefiles', 'eeg3_2.dat');

s = bci2000chain(fn, 'TransmissionFilter|SpatialFilter|ARFilter',  'ExampleParameters.prm', 'SpatialFilterType', 3)

See the help documentation in the Matlab file for more details.

create_bcidat

This utility allows you to create "toy" BCI2000 .dat files easily, perhaps using only a numeric signal array and a scalar sampling rate. Read the help for this function in order to see how to run a bci2000chain on a signal that is stored in a Matlab variable rather than a pre-existing file.

read_bciprm

This utility allows you to read BCI2000 parameters from a data file, a parameter file, or from a structure, string, or cell array of strings in Matlab. It requires the mex-files load_bcidat and convert_bciprm.

make_bciprm

This utility allows you to read, combine, and write BCI2000 parameters from multiple sources, making use of read_bciprm.

decode_bcitime

This function takes a BCI2000 parameter value that is supposed to indicate time, and figures out whether it is expressed in seconds/milliseconds/microseconds with an explicit PhysicalUnit, or in sexagesimal notation (e.g. MM:SS), or whether it is a bare number indicating a number of SampleBlocks. In all cases the value is returned, unambiguously, in seconds.

read_bcidate

This function uses read_bciprm to read one particular parameter, StorageTime, from a data file, from a parameter file, or from some representation of a BCI2000 parameter set in memory. This datestamp is returned either as a scalar value (i.e. a Matlab datenum) or as a string formatted according to your specification.

rename_bcidat

Are you involved in a large BCI research program? Is it difficult to keep track of all the different experiments, subjects and measurements? Do you have a lot of files that are called something like TestS001R01.dat, some of them important, some of them not, all threatening to overwrite each other as soon as somebody accidentally drags and drops something in the wrong place? Do you find that many of your measurements are done with SubjectSession 001 and an uninformative SubjectName, simply because you were "just quickly trying something out" and have no disciplined procedure for determining and setting the correct session numbers (a difficult question in any case, when experimental conditions keep changing)?

If so, you are not alone. But help is at hand. All BCI2000 data files contain a date stamp, in the form of the StorageTime parameter. Wouldn't it be useful if all your data files were named uniquely according to this date stamp, as well as the SubjectName, SubjectSession and SubjectRun that are also stored in the file? Wouldn't it be useful if files from different subjects could be kept together but always appeared in chronological order in the file-system, and could be quickly checked against your experimental calendar? For more information, type help rename_bcidat at your nearest Matlab prompt, today.