The MatlabFilter calls the Matlab engine to act upon signals, parameters, and states. It provides the full BCI2000 filter interface to a Matlab filter implementation.
For each BCI2000 filter member function, there is a corresponding Matlab function as follows:
GenericFilter member Matlab function syntax ==================== ====================== Constructor [parameters, states] = bci_Construct Destructor bci_Destruct Preflight out_signal_dim = bci_Preflight( in_signal_dim ) Initialize bci_Initialize( in_signal_dim, out_signal_dim ) Process out_signal = bci_Process( in_signal ) StartRun bci_StartRun StopRun bci_StopRun Resting bci_Resting Halt bci_Halt
Existence of the above-listed Matlab functions is not mandatory. The MatlabFilter uses the Matlab exist command to determine whether a given function is available, and will not call the Matlab engine when this is not the case. If either of the bci_Preflight, bci_Initialize, or bci_Process functions is not available, a warning will be displayed to the user.
Accessing Parameters and States
Parameters and states are accessible via global Matlab structs called bci_Parameters and bci_States. In Matlab, write
global bci_Parameters bci_States; my_sampling_rate = bci_Parameters.SamplingRate;
Parameters may be changed from inside the bci_StopRun and bci_Resting scripts, and will automatically be propagated to the other modules. State values may be modified from the bci_Process function.
Declaring Parameters and States
To add parameters and states to the BCI2000 list of states, the bci_Construct function may return non-empty cell arrays of strings in its parameters and states return values. The strings constituting these cell arrays are parameter and state definitions.
Your added parameters will appear in the operator module's parameter configuration dialog.
BCI2000 signals are mapped to Matlab matrices with channel index first, and sample (element) index second. Signal dimension arguments of bci_Preflight and bci_Initialize are vectors of integers (1x2 matrices) as in [n_channels n_elements].
To report errors from Matlab functions, use Matlab's error command. Your error messages will be displayed to the user from the operator module.
Combining with BCI2000 Signal Processing Filters
In the BCI2000 binary distribution, the MatlabFilter is shipped inside the MatlabSignalProcessing executable. There, the signal processing chain consists of the SpatialFilter and the MatlabFilter. However, by editing src/core/SignalProcessing/Matlab/PipeDefinition.cpp, you may add as many signal processing filters as you wish. (See Programming Reference:Filter Chain for information about defining a filter chain.)
This modification requires access to the BCI2000 source code. You will need to rebuild the MatlabSignalProcessing executable.
- Make sure your script directory is part of the Matlab search path.
- If no Matlab instance opens up, execute
from the command line when logged in with administrative privileges.
- If you get linker errors after editing PipeDefinition.cpp, make sure that all filters' cpp files are part of the MatlabSignalProcessing project.
Technical Reference:Core Modules#Signal Processing Module, Technical Reference:Parameter Definition, Technical Reference:State Definition, Programming Reference:GenericFilter Class, Programming Reference:Filter Chain