User Reference:Matlab MEX Files: Difference between revisions
Emilycohen (talk | contribs) 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 | 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== | ||
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- | |||
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. | ||
==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, 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 | 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 | Individual parameter values are represented as cell arrays of strings in a | ||
be | '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. | 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 | 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 | 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: | ==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.