User Reference:Matlab MEX Files: Difference between revisions

From BCI2000 Wiki
Jump to navigation Jump to search
No edit summary
(42 intermediate revisions by 4 users not shown)
Line 2: Line 2:
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.
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.
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 [[User_Reference:Matlab_Tools|Matlab tools]] page.
 
==Downloading BCI2000 MEX files==
Download the [https://bci2000.org/downloads/mex.zip BCI2000 MEX files here].


==Using BCI2000 MEX files==
==Using BCI2000 MEX files==
===Microsoft Windows===
BCI2000 comes with pre-built MEX files for a number of platforms, including 32- and 64-bit Windows, Mac OS X, and Linux for the amd64 architecture.  
BCI2000 comes with pre-compiled MEX files for Microsoft Windows platforms.
Add <tt>BCI2000/tools/mex</tt> to your Matlab path to use these files.
Add <tt>BCI2000/tools/mex</tt> 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 [http://gcc.gnu.org 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 [http://www.mathworks.com/support/compilers/current_release/ list of compatible compiler versions].
*After downloading the [[Programming Reference:BCI2000 Source Code|BCI2000 source code]], start Matlab and make sure that the mex command is configured to use the [http://gcc.gnu.org gcc compiler]. Typing <tt>help mex</tt> from the Matlab command line will guide you in configuring the mex command.
*Change Matlab's working directory to <tt>BCI2000/src/core/Tools/mex/</tt>.
*Execute <tt>buildmex</tt> from the Matlab command line.
*Add <tt>BCI2000/tools/mex</tt> to your Matlab path to use the newly built MEX files.


'''Pre-built 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.
==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 [[Programming_Howto:Building_and_Customizing_BCI2000|tutorial on building BCI2000 from source]], and make sure to check the <tt>BUILD_MEX_FILES</tt> option in the CMake configuration step.


==BCI2000 MEX functions==
==BCI2000 MEX functions==


===<tt>load_bcidat</tt>===
===<tt>load_bcidat</tt>===
[ signal, states, parameters ] = load_bcidat( 'filename1', 'filename2', ... )
  [ signal, states, parameters, total_samples, file_samples ] ...
    = load_bcidat( 'filename1', 'filename2', ... )
 
loads signal, state, and parameter data from the files whose names are given
loads signal, state, and parameter data from the files whose names are given
as function arguments.
as function arguments.
Line 28: Line 28:
  files = dir( '*.dat' );
  files = dir( '*.dat' );
  [ signal, states, parameters ] = load_bcidat( files.name );
  [ signal, states, parameters ] = load_bcidat( files.name );
 
  files = struct( 'name', uigetfile( 'MultiSelect', 'on' ) );
  files = struct( 'name', uigetfile( 'MultiSelect', 'on' ) );
  [ signal, states, parameters ] = load_bcidat( files.name );
  [ signal, states, parameters ] = load_bcidat( files.name );
Line 38: Line 38:
smallest Matlab data type that accommodates them.
smallest Matlab data type that accommodates them.
To obtain signal data calibrated into physical units (microvolts),
To obtain signal data calibrated into physical units (microvolts),
specify <tt>'-calibrated'</tt> as an option anywhere in the argument list.
specify '-calibrated' as an option anywhere in the argument list.


The 'states' output variable will be a Matlab struct with BCI2000 state
The 'states' output variable will be a Matlab struct with BCI2000 state
Line 46: Line 46:
The 'parameters' output variable will be a Matlab struct with BCI2000
The 'parameters' output variable will be a Matlab struct with BCI2000
parameter names as struct member names.
parameter names as struct member names.
Individual parameter values are represented as cell arrays of strings, and may
Individual parameter values are represented as cell arrays of strings in a
be converted into numeric matrices by Matlab's str2double function.
'Value' struct member, and additionally as numeric matrices in a 'NumericValue'
If multiple files are given, parameter values will match the ones contained  
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.
in the first file.


Line 57: Line 60:
parameters from a file without reading sample data:
parameters from a file without reading sample data:
  [ ignored, states, parameters ] = load_bcidat( 'filename', [0 0] );
  [ 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]  );
===<tt>save_bcidat</tt>===
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 <tt>load_bcidat</tt>, or <tt>convert_bciprm</tt> 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 <tt>save_bcidat</tt> in conjunction with <tt>load_bcidat</tt>,
see the [[Contributions:FilterGUI|FilterGUI]] tool contribution.


===<tt>convert_bciprm</tt>===
===<tt>convert_bciprm</tt>===
Line 69: Line 100:


When the input is a cell array rather than a Matlab struct, convert_bciprm
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:
will interpret the input as a list of BCI2000 parameter definition strings (ignoring the NumericValue field if present).


  parameter_struct = convert_bciprm( parameter_lines );
  parameter_struct = convert_bciprm( parameter_lines );


===<tt>mem</tt>===
===<tt>mem</tt>===
This command estimates an amplitude spectrum, using the AR based spectral estimator
This command estimates a power spectrum, using the AR based spectral estimator
that is also present in the [[User Reference:ARFilter|ARFilter]].
that is also present in the [[User Reference:ARFilter|ARFilter]].
The calling syntax is:
The calling syntax is:
  [spectrum, frequencies] = mem(signal, parms)
  [spectrum, frequencies] = mem(signal, parms);
with <signal> and <spectrum> having dimensions channels x values, and
with <signal> and <spectrum> having dimensions values x channels, and
with <parms> being a vector of parameter values:
with <parms> being a vector of parameter values:
*model order,
*model order,
Line 86: Line 117:
*evaluations per bin,
*evaluations per bin,
*detrend option (optional, 0: none, 1: mean, 2: linear; defaults to none),
*detrend option (optional, 0: none, 1: mean, 2: linear; defaults to none),
*frequency (optional, defaults to 1).
*sampling frequency (optional, defaults to 1).
For a detailed description of configuration parameters, see the [[User Reference:ARFilter]] page.
For a detailed description of configuration parameters, see the [[User Reference:ARFilter]] page.


[[Category:Contents]][[Category:External Interfaces]][[Category:Data Analysis Tools]]
==See also==
[[User Reference:Data File Formats]], [[User Reference:ARFilter]]
 
[[Category:Contents]]
[[Category:Matlab]]
[[Category:Data Analysis Tools]]
[[Category:External Interfaces]]

Revision as of 18:44, 19 April 2022

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, Mac OS X, and Linux for the amd64 architecture. Add BCI2000/tools/mex to your Matlab path to use these files.

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.

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