User Reference:Matlab MEX Files

From BCI2000 Wiki
Jump to: navigation, search

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 BCI2000 data from Matlab, without duplicating code that implements those data structures.

Higher-level Matlab routines for data-analysis and management, which make use of these mex files, are documented on the Matlab tools page.

Using BCI2000 MEX files

Microsoft Windows 32

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

Other platforms

BCI2000 comes with pre-built MEX files for a number of platforms, including 64-bit Windows, Mac OS X, and Linux for the i386 as well as the amd64 architecture. Support for these MEX files is experimental at present, and they may or may not work on your particular configuration. On 64-bit Windows, the MEX files require the Visual Studio runtime libraries. If you want to use them on a machine that doesn't have Visual Studio installed, you will need to install the Visual Studio runtime libraries first.

Building BCI2000 MEX files

Typically, you will use pre-built binary versions of BCI2000 MEX files as described above. If you need to build BCI2000 MEX files yourself, the following information applies. BCI2000 provides a Matlab script that can be used to build MEX files.

  • After downloading the BCI2000 source code, start Matlab and make sure that the mex command is configured to use a compiler that is able to compile C++ code. On Windows platforms, you may use the compiler included with the freely available Windows SDK. On Unix platforms, you will typically 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.
  • On Unix-based platforms, Matlab creates its own execution environment for MEX files, independently of system libraries. 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.

BCI2000 MEX functions

load_bcidat

 [ signal, states, parameters, total_samples, file_samples ] ...
    = 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. When 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] );

The 'total_samples' output variable reports the total number of samples present in all files, independently of how many samples have been specified as sample ranges. This allows to retrieve the number of samples in a file without actually loading the file:

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

Similarly, the 'file_samples' output variable provides a vector containing the number of samples within each input file, regardless of any sample ranges that may have been specified.

[ ignored, states, parameters, total_samples, file_samples ] = load_bcidat( 'filename1', [0 0], 'filename2', [0 0]  );

save_bcidat

save_bcidat( 'filename', signal, states, parameters );

saves signal, state, and parameter data into the named file.

The signal, state, and parameter arguments must be Matlab structs as created by the load_bcidat, or convert_bciprm mex files. Signal data is always interpreted as raw data, i.e. it will be written into the output file unchanged.

The output file format is deduced from the output file's extension, which may be .dat, .edf, or .gdf. When no extension is recognized, the BCI2000 dat file format is used.

For an example how to use save_bcidat in conjunction with load_bcidat, see the FilterGUI tool contribution.

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 will interpret the input as a list of BCI2000 parameter definition strings (ignoring the NumericValue field if present).

parameter_struct = convert_bciprm( parameter_lines );

mem

This command estimates a power 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 values x channels, 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),
  • sampling frequency (optional, defaults to 1).

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

See also

User Reference:Data File Formats, User Reference:ARFilter