User Reference:Matlab MEX Files

From BCI2000 Wiki
Jump to navigation Jump to 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.

Downloading BCI2000 MEX files

Download the BCI2000 MEX files here.

Using BCI2000 MEX files

BCI2000 comes with pre-built MEX files for a number of platforms, including 32- and 64-bit Windows, macOS, and Linux for the amd64 architecture. Alternatively, if you don't want to install BCI2000, MEX files are available in the download mentioned in the previous paragraph.

Add BCI2000/tools/mex to your Matlab path to use these files if you downloaded the BCI2000 source code or BCI2000 installer, and the location where you extracted the MEX files if obtained from the above download.

macOS security settings

On macOS, you may need to explicitly allow the execution of each individual MEX file. When executing a MEX file for the first time, a warning message may appear:

Mex macOS Warning.png

Here, click "OK" to close the warning. Then, go to "Settings"->"Privacy & Security", and click "Allow Anyway" to allow execution of the MEX file:

Mex macOS Privacy.png

You will be asked for your user password to change security settings. Enter your password, and click on "Modify Settings":

Mex macOS Password.png

Finally, when executing the MEX file again, you will get another warning, but this time there is an option to open the MEX file nevertheless:

Mex macOS Warning2.png

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, follow the tutorial on building BCI2000 from source, and make sure to check the BUILD_MEX_FILES option in the CMake configuration step.

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.

NOTE: for list valued parameters, the dimension of the Value field must be N x 1. If it is 1 x N, the list parameter will be implicitly converted to a matrix, possibly resulting in problems when loading the parameter into BCI2000.

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