User Reference:Matlab MEX Files

Introduction

MEX files allow the execution of externally compiled code from within Matlab. Because Matlab code is interpreted at runtime, and MEX files contain binary code that has been compiled prior to use, MEX files are generally faster than equivalent Matlab code.

BCI2000 MEX files contain code that interfaces with BCI2000-specific data structures, i.e. BCI2000 data files, and parameter definitions. This allows access to the underlying data from Matlab, without duplicating code that implements these data structures.

Using BCI2000 MEX files

Microsoft Windows

BCI2000 comes with pre-compiled MEX files for Microsoft Windows platforms. Add BCI2000/tools/mex to your Matlab path to use these files.

Other Platforms

For platforms other than 32-bit Windows, BCI2000 provides a Matlab script that can be used to build MEX files.

• Independently of system libraries, Matlab creates its own execution environment for MEX files. For MEX files, this means that they usually won't work unless compiled with a version of the gcc compiler that matches the one used to build Matlab itself, and linked against libraries that match the ones used by Matlab. To check, see the list of compatible compiler versions.
• After downloading the BCI2000 source code, start Matlab and make sure that the mex command is configured to use the gcc compiler. Typing help mex from the Matlab command line will guide you in configuring the mex command.
• Change Matlab's working directory to BCI2000/src/core/Tools/mex/.
• Execute buildmex from the Matlab command line.
• Add BCI2000/tools/mex to your Matlab path to use the newly built MEX files.

Pre-built non-Windows MEX files: BCI2000 now comes with pre-built MEX files for a number of platforms, including Mac OS X and 32-bit as well as 64-bit Linux. Support for these MEX files is experimental, and they may or may not work on your particular configuration.

BCI2000 MEX functions

load_bcidat

[ signal, states, parameters ] = load_bcidat( 'filename1', 'filename2', ... )

loads signal, state, and parameter data from the files whose names are given as function arguments.

Examples for loading multiple files:

files = dir( '*.dat' );
[ signal, states, parameters ] = load_bcidat( files.name );

files = struct( 'name', uigetfile( 'MultiSelect', 'on' ) );
[ signal, states, parameters ] = load_bcidat( files.name );

For multiple files, number of channels, states, and signal type must be consistent.

By default, signal data will be in raw A/D units, and will be represented by the smallest Matlab data type that accommodates them. To obtain signal data calibrated into physical units (microvolts), specify '-calibrated' as an option anywhere in the argument list.

The 'states' output variable will be a Matlab struct with BCI2000 state names as struct member names, and the number of state value entries matching the first dimension of the 'signal' output variable.

The 'parameters' output variable will be a Matlab struct with BCI2000 parameter names as struct member names. Individual parameter values are represented as cell arrays of strings in a 'Value' struct member, and additionally as numeric matrices in a 'NumericValue' struct member. When there is no numeric interpretation possible, the corresponding matrix entry will be NaN. For nested matrices, no NumericValue field is provided. If multiple files are given, parameter values will match the ones contained in the first file.

Optionally, sample ranges may be specified for individual files:

[ signal, states, parameters ] = load_bcidat( 'filename', [first last] )

will load a subset of samples defined by first and last sample index. Specifying [0 0] for an empty sample range allows to read states and parameters from a file without reading sample data:

[ ignored, states, parameters ] = load_bcidat( 'filename', [0 0] );

convert_bciprm

A Matlab (mex) subroutine that converts BCI2000 parameters from Matlab struct into string representation and back.

parameter_lines = convert_bciprm( parameter_struct );

converts a BCI2000 parameter struct (as created by load_bcidat) into a cell array of strings containing valid BCI2000 parameter definition strings.

When the input is a cell array rather than a Matlab struct, convert_bciprm definition strings (ignoring the NumericValue field if present).

parameter_struct = convert_bciprm( parameter_lines );

mem

This command estimates an amplitude spectrum, using the AR based spectral estimator that is also present in the ARFilter. The calling syntax is:

[spectrum, frequencies] = mem(signal, parms)

with <signal> and <spectrum> having dimensions channels x values, and with <parms> being a vector of parameter values:

• model order,
• first bin center,
• last bin center,
• bin width,
• evaluations per bin,
• detrend option (optional, 0: none, 1: mean, 2: linear; defaults to none),
• frequency (optional, defaults to 1).

For a detailed description of configuration parameters, see the User Reference:ARFilter page.