# Programming Reference:MatlabFilter

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.

## Contents

## Filter Interface

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.

## Signal Format

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]`.

## Error Reporting

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.

## Troubleshooting

- Make sure your script directory is part of the Matlab search path.
- If no Matlab instance opens up, execute

matlab /regserver

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.

## See also

Technical Reference:Core Modules#Signal Processing Module, Technical Reference:Parameter Definition, Technical Reference:State Definition, Programming Reference:GenericFilter Class, Programming Reference:Filter Chain