# Difference between revisions of "User Reference:Matlab Tools"

m (→bci2000path) |
|||

Line 59: | Line 59: | ||

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

+ | |||

+ | ==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== | ==read_bcidate== |

## Revision as of 00:57, 17 March 2012

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.

## Contents

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