User Reference:Matlab Tools: Difference between revisions

From BCI2000 Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
Line 33: Line 33:
The [[User_Reference:Command_Line_Processing|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 [[User_Reference:Filters|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 [[User_Reference:Command_Line_Processing|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 [[User_Reference:Filters|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 <tt>bci2000chain</tt> function uses the command-line tools (calling them via Matlab's builtin function <tt>system</tt>), but it hides the details and presents itself to you as a single Matlab function.  To do this, it requires the [[User_Reference:Command_Line_Processing|command-line binaries]] to have been built in <tt>tools/cmdline</tt>, and for <tt>tools/cmdline</tt> to be on the operating-system path (not to be confused with the Matlab path) for the session.  It also [[User_Reference:Matlab_MEX_Files|BCI2000 mex files]] to be on the Matlab path.  One way of satisfying these path requirements is shown above, using the <tt>bci2000path</tt> function.
The <tt>bci2000chain</tt> function uses the command-line tools (calling them via Matlab's builtin function <tt>system</tt>), but it hides the details and presents itself to you as a single Matlab function.


===Dependencies===
<tt>bci2000chain</tt> requires the [[User_Reference:Command_Line_Processing|command-line binaries]], including <tt>bci_dat2stream</tt> and <tt>bci_stream2mat</tt> as well as any specific filter tools you intend to use, to have been built in <tt>tools/cmdline</tt>. The <tt>tools/cmdline</tt> directory must be on the operating-system path (not to be confused with the Matlab path) for the session.  The [[User_Reference:Matlab_MEX_Files|BCI2000 mex files]] <tt>load_bcidat</tt> and <tt>convert_bciprm</tt>, and the m-files  <tt>make_bciprm.m</tt>, <tt>read_bciprm.m</tt> and <tt>read_bcidate.m</tt>, must be in directories that are on the Matlab path. One way of satisfying these path requirements is shown above, using the <tt>bci2000path</tt> 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 parameter using the ones in <tt>ExampleParameters.prm</tt>, and then further override the spatial filter setting by switching it to CAR mode:
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 parameter using the ones in <tt>ExampleParameters.prm</tt>, and then further override the spatial filter setting by switching it to CAR mode:



Revision as of 01:41, 28 January 2012

In the tools/matlab directory of your BCI2000 distribution, there are several of Matlab m-files that are useful for offline analysis of recorded data-files, from 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 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.

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. Personally, I write the following lines either in my startup.m file, or in some other handy function in the My Documents\MATLAB or $HOME/matlab so that I 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 parameter 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.

make_bciprm

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

read_bciprm

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

read_bcidate

Reads 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.