Programming Reference:MatlabFilter: Difference between revisions

From BCI2000 Wiki
Jump to navigation Jump to search
(22 intermediate revisions by 2 users not shown)
Line 1: Line 1:
The ''MatlabFilter'' calls the Matlab engine to act upon signals,
==Overview==
parameters, and states.
It provides the full BCI2000 [[Programming Reference:GenericFilter Class|filter interface]]
to a Matlab filter implementation.


==Filter Interface==
The MatlabFilter implements a mechanism for using the Matlab engine within the BCI2000 pipeline. The ''MatlabFilter'' calls the Matlab engine to act upon signals, parameters, and states. It provides the full BCI2000 [[Programming Reference:GenericFilter Class|filter interface]] to a Matlab filter implementation.
For each BCI2000 filter member function, there is a corresponding Matlab
function as follows:
<pre>
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
</pre>


Existence of the above-listed Matlab functions is not mandatory.
While BCI2000 is running, each block of data is pushed to the Matlab engine and a well-specified Matlab function (i.e. *.m file) is executed. As explained in more detail in the Programming reference for the  [[Programming_Reference:GenericFilter_Class|GenericFilter Class]], all BCI2000 filters consist of a set of functions. The MatlabFilter will, upon execution of each of these functions, contact the Matlab engine and execure the corresponding Matlab function equivalent. Furthermore, the MatlabFilter copies the input signal and the states to the Matlab engine, and copies the output signal and states from the engine after processing the signal.
The MatlabFilter uses the Matlab <tt>exist</tt> command to determine whether a
given function is available, and will not try to call that function when this
is not the case.


If either of the <tt>bci_Preflight</tt>, <tt>bci_Initialize</tt>, or <tt>bci_Process</tt> functions
{| style="color:black;background-color:#ffffcc;" cellpadding="5" cellspacing="0" border="2"
is not available, a warning will be displayed to the user.
!BCI2000 function
!Matlab equivalent
|-
|[[Programming_Reference:GenericFilter_Class#Constructor|Constructor()]]
|bci_Construct
|-
|[[Programming_Reference:GenericFilter_Class#Preflight|Preflight()]]
|bci_Preflight
|-
|[[Programming_Reference:GenericFilter_Class#Initialize|Initialize()]]
|bci_Initialize
|-
|[[Programming_Reference:GenericFilter_Class#StartRun|StartRun()]]
|bci_StartRun
|-
|[[Programming_Reference:GenericFilter_Class#Process|Process()]]
|bci_Process
|-
|[[Programming_Reference:GenericFilter_Class#StopRun|StopRun()]]
|bci_StopRun
|-
|[[Programming_Reference:GenericFilter_Class#Resting|Resting()]]
|bci_Resting
|-
|[[Programming_Reference:GenericFilter_Class#Halt|Halt()]]
|bci_Halt
|-
|[[Programming_Reference:GenericFilter_Class#Destructor|Destructor()]]
|bci_Destruct
|}


==Accessing Parameters and States==
Existence of the above-listed Matlab functions is not mandatory, the Matlab 'exist' command will be used 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.
Parameters and states are accessible via global Matlab structs called
<tt>bci_Parameters</tt> and <tt>bci_States</tt>. In Matlab, write


   global bci_Parameters bci_States;
Most of these Matlab functions do not take input arguments, except for
   my_sampling_rate = bci_Parameters.SamplingRate;
  function [parameters, states] = bci_Construct;
 
   function [out_signal_dim] = bci_Preflight( in_signal_dim );
    
  function bci_Initialize( in_signal_dim, out_signal_dim );
 
  function [out_signal] = bci_Process( in_signal );


*Parameter values may be changed from inside the <tt>bci_StopRun</tt> script, and will automatically be propagated to the other modules.
The most important functions is <tt>bci_Process</tt>, which is executed every time a new block of data is passed through the pipeline. The <tt>bci_Construct</tt> function is executed at the beginning and determines the parameters and states. The <tt>bci_Initialize</tt> function determines whether all requirements are met. The <tt>bci_StartRun</tt> function prepares the computation that is done during processing (e.g. computing filter parameters). Communication between these Matlab functions is done using global variables.


*State values may be modified from the <tt>bci_Process</tt> function.
==Parameters and States==


==Declaring Parameters and States==
Parameters and states are accessible via global Matlab structs called  'bci_Parameters' and 'bci_States'. Parameters may be changed from <tt>bci_StopRun</tt> and <tt>bci_Resting</tt>, and will automatically be propagated to the other modules. State values may be modified from the <tt>bci_Process</tt> function.
To add parameters and states to the BCI2000 list of states, the <tt>bci_Construct</tt>
 
function may return non-empty cell arrays of strings in its <tt>parameters</tt>
To add parameters and states to the BCI2000 list of states, the <tt>bci_Construct</tt> function may return non-empty cell arrays of strings in its parameters and states return values. The strings constituting these cell arrays are [[Technical Reference:Parameter Definition|parameter]] and [[Technical Reference:State Definition|state definitions]].
and <tt>states</tt> return values. The strings constituting these cell arrays are [[Technical Reference:Parameter Definition|parameter]] and [[Technical Reference:State Definition|state definitions]].


Your added parameters will appear in the [[User Reference:Operator Module|operator module's]] parameter configuration dialog. Your parameter definition's section name will be used to direct its position in the configuration dialog's register cards:
Your added parameters will appear in the [[User Reference:Operator Module|operator module's]] parameter configuration dialog. Your parameter definition's section name will be used to direct its position in the configuration dialog's register cards:
Line 51: Line 62:
will display the parameter on the ''Filtering'' register card, inside a group called ''MyFilter''.
will display the parameter on the ''Filtering'' register card, inside a group called ''MyFilter''.


==Signal Format==
==Input and Output Signal Format==
BCI2000 signals are mapped to Matlab matrices with channel index first,
 
and sample (element) index second.
BCI2000 signals are mapped to Matlab matrices with channel index first, and sample (element) index second. The signal dimension arguments of <tt>bci_Preflight</tt> and <tt>bci_Initialize</tt> are integer vectors of size 1x2 with <tt>[n_channels n_elements]</tt>.
Signal dimension arguments of <tt>bci_Preflight</tt> and <tt>bci_Initialize</tt> are
vectors of integers (1x2 matrices) as in <tt>[n_channels n_elements]</tt>.


==Error Reporting==
==Error Reporting==
To report errors from Matlab functions, use Matlab's <tt>error</tt> command.
To report errors from Matlab functions, use Matlab's <tt>error</tt> command.
Your error messages will be displayed to the user from the [[User Reference:Operator Module|operator module]].
Your error messages will be displayed to the user from the [[User Reference:Operator Module|operator module]].


==Combining with BCI2000 Signal Processing Filters==
==Combining the MatlabFilter with other Signal Processing Filters==
In the BCI2000 binary distribution, the ''MatlabFilter'' is shipped inside the ''MatlabSignalProcessing'' executable.
There, the signal processing chain consists of the [[User Reference:SpatialFilter|SpatialFilter]] and the ''MatlabFilter''.
However, by editing <tt>src/core/SignalProcessing/Matlab/PipeDefinition.cpp</tt>, you may add as many [[User Reference:Filters|signal processing filters]] as you wish.
(See [[Programming Reference:Filter Chain]] for information about defining a filter chain.)


This modification requires access to the [[Programming Reference:BCI2000 Source Code|BCI2000 source code]]. You will need to rebuild the ''MatlabSignalProcessing'' executable.
In the BCI2000 binary distribution, the ''MatlabFilter'' is shipped inside the ''MatlabSignalProcessing'' executable. There, the signal processing chain consists of the [[User Reference:SpatialFilter|SpatialFilter]] and the ''MatlabFilter''. However, by editing <tt>src/core/SignalProcessing/Matlab/PipeDefinition.cpp</tt>, you may add as many [[User Reference:Filters|signal processing filters]] as you wish.
 
See [[Programming Reference:Filter Chain]] for information about defining a filter chain. Modification of the filter chain requires access to the [[Programming Reference:BCI2000 Source Code|BCI2000 source code]]. You will need to rebuild the ''MatlabSignalProcessing'' executable.
 
==Command Line Options==
===MatlabWD===
By default, the Matlab engine's working directory is set to the signal processing module's working directory at startup. When using the Matlab filter for signal processing, your filter's code will be contained in the <tt>bci_Process</tt> and associated Matlab functions, which will typically be located inside a dedicated directory. Thus, you may switch between Matlab-based filter implementations by selecting a Matlab working directory at startup.
This may be done by specifying the <tt>MatlabWD</tt> parameter from the command line when starting the MatlabSignalProcessing module:
<pre>start MatlabSignalProcessing.exe --MatlabWD="./matlab" 127.0.0.1</pre>
will change Matlab's working directory to a directory called "matlab" inside the BCI2000 "prog" directory at startup, and execute <tt>bci_Process</tt> and associated functions from there.
 
This parameter must be set from the command line; later changes will have no effect.
 
Using the <tt>--MatlabWD</tt> command line option, you may easily switch between multiple Matlab-based BCI2000 configurations.
Simply create a separate startup batch file for each configuration, and specify the respective configuration's path on the command line that starts up the MatlabFilter.
 
===MatlabStayOpen===
By default, the Matlab instance associated with the Matlab engine will be closed when BCI2000 quits.
Generally, this behavior is desired to ensure a well-defined BCI2000 system state after each startup.
For debugging purposes, though, it is sometimes useful to have the engine's command window available even after BCI2000 has been quit.
This behavior is controlled by another command-line parameter, <tt>MatlabStayOpen</tt>, which may take the following values:
*0 is the default (no change in behavior),
*1 keeps the Matlab engine's command window open but clears variables used to transmit information forth and back between BCI2000 and Matlab,
*2 also preserves intermediate variables (such as bci_Parameters and bci_States) in the Matlab engine's workspace.
 
To set this parameter to 2, use this command line to start up the signal processing module:
<pre>start MatlabSignalProcessing.exe --MatlabStayOpen=2 127.0.0.1</pre>
 
Once the <tt>MatlabStayOpen</tt> parameter has been set from the command line, it will be listed on the Operator Module's parameter configuration dialog's "system" tab, and may be modified from there. The change will be applied when clicking ''Set Config''.


==Troubleshooting==
==Troubleshooting==
===Debugging your scripts===
===Debugging Matlab functions===
#Start BCI2000. The ''MatlabFilter'' will open a Matlab instance in its own window in minimized state.
#Start BCI2000. The ''MatlabFilter'' will open a Matlab instance in its own window in minimized state.
#Switch to the minimized Matlab instance.
#Switch to the minimized Matlab instance.
#Type, e.g.,<br /><code>edit bci_Process.m</code><br />to open a Matlab editor window connected to the Matlab interactive window.
#Type, e.g.,<br /><code>edit bci_Process.m</code><br />to open a Matlab editor window connected to the Matlab interactive window.
#In the editor window, set breakpoints as you would normally.
#In the editor window, set breakpoints as you would normally.
#Execution will be paused, and you may examine variables moving the mouse over them.
#Execution will be paused, and you may examine variables hovering the mouse over them.
 
Unfortunately, recent versions of Matlab have limited support for interactive debugging of functions executed in the Matlab engine. Setting breakpoints prior to executing code, and stepping through the code should work, but it may not be possible to modify breakpoints while debugging. Further, clicking "continue" may lead to a Matlab exception message, from which "Attempt to Continue" can be clicked to continue execution.
For an official suggestion from MathWorks, see [http://www.mathworks.com/support/solutions/en/data/1-2CEUK6/index.html?product=ML&solution=1-2CEUK6].
 
===Matlab doesn't find your functions===
Make sure to
*either set Matlab's working directory to the directory containing your functions, using the <tt>--MatlabWD</tt> command line option described above,
*or add the respective directory to your Matlab path.
Generally, the first option is recommended over the second one.


===Matlab doesn't find your scripts===
Make sure your script directory is part of the Matlab search path. Example scripts are located inside <tt>prog/matlab</tt>.
===There is no Matlab engine started up===
===There is no Matlab engine started up===
Execute<br /><code>matlab /regserver</code><br />from the command line when logged in with administrative privileges.
For using the MatlabEngine on Windows systems, you need to make sure that
===Changes to script files appear to have no effect===
*the processor architecture (32 or 64 bit) of the installed version of Matlab matches that of the BCI2000 module,
Switch to the Matlab engine's command window, and enter<br /><code>clear;</code><br /> or <br /><code>clear scriptname;</code><br />each time you change a script.
*Matlab can be executed from the command line by running "matlab.exe".
In case of multiple concurrently installed versions of Matlab, the MatlabFilter will always connect to the one that starts up when executing "matlab" from a command prompt.
Also, it may help to execute<br /><code>matlab /regserver</code><br />from the command line under the account that is going to use the MatlabFilter.


===You get linker errors when rebuilding ''MatlabSignalProcessing''===
===You get linker errors when rebuilding ''MatlabSignalProcessing''===
Line 88: Line 131:


==See also==
==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]], [[Programming Tutorial:Implementing a Filter using Matlab Scripts]]
[[Technical Reference:Core Modules#Signal Processing Module]],  
[[Technical Reference:Parameter Definition]],  
[[Technical Reference:State Definition]],  
[[Programming Reference:GenericFilter Class]],  
[[Programming Reference:Filter Chain]],  
[[Contributions:FieldTripBuffer]]
 
* Matlab tutorial for [[Programming_Tutorial:Implementing_a_Matlab-based_Filter|IIR bandpass filtering, followed with RMS envelope computation, and linear classification]]
* Matlab tutorial for [[Programming_Tutorial:Implementing_another_Matlab-based_Filter|adaptive spatial filtering using a beamformer, power computation and normalization]]


[[Category:Development]] [[Category:External Interfaces]]
[[Category:Filters]]
[[Category:Signal Processing]]
[[Category:Matlab]]
[[Category:Development]]
[[Category:External Interfaces]]

Revision as of 15:13, 9 September 2013

Overview

The MatlabFilter implements a mechanism for using the Matlab engine within the BCI2000 pipeline. 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.

While BCI2000 is running, each block of data is pushed to the Matlab engine and a well-specified Matlab function (i.e. *.m file) is executed. As explained in more detail in the Programming reference for the GenericFilter Class, all BCI2000 filters consist of a set of functions. The MatlabFilter will, upon execution of each of these functions, contact the Matlab engine and execure the corresponding Matlab function equivalent. Furthermore, the MatlabFilter copies the input signal and the states to the Matlab engine, and copies the output signal and states from the engine after processing the signal.

BCI2000 function Matlab equivalent
Constructor() bci_Construct
Preflight() bci_Preflight
Initialize() bci_Initialize
StartRun() bci_StartRun
Process() bci_Process
StopRun() bci_StopRun
Resting() bci_Resting
Halt() bci_Halt
Destructor() bci_Destruct

Existence of the above-listed Matlab functions is not mandatory, the Matlab 'exist' command will be used 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.

Most of these Matlab functions do not take input arguments, except for

 function [parameters, states] = bci_Construct;
 
 function [out_signal_dim] = bci_Preflight( in_signal_dim );
 
 function bci_Initialize( in_signal_dim, out_signal_dim );
 
 function [out_signal] = bci_Process( in_signal );

The most important functions is bci_Process, which is executed every time a new block of data is passed through the pipeline. The bci_Construct function is executed at the beginning and determines the parameters and states. The bci_Initialize function determines whether all requirements are met. The bci_StartRun function prepares the computation that is done during processing (e.g. computing filter parameters). Communication between these Matlab functions is done using global variables.

Parameters and States

Parameters and states are accessible via global Matlab structs called 'bci_Parameters' and 'bci_States'. Parameters may be changed from bci_StopRun and bci_Resting, and will automatically be propagated to the other modules. State values may be modified from the bci_Process function.

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. Your parameter definition's section name will be used to direct its position in the configuration dialog's register cards:

MyFilter int MyParam= 2 0 0 2 // ...

will display the MyParam parameter on separate register card named MyFilter.

Filtering:MyFilter int MyParam= 2 0 0 2 // ...

will display the parameter on the Filtering register card, inside a group called MyFilter.

Input and Output Signal Format

BCI2000 signals are mapped to Matlab matrices with channel index first, and sample (element) index second. The signal dimension arguments of bci_Preflight and bci_Initialize are integer vectors of size 1x2 with [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 the MatlabFilter with other 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. Modification of the filter chain requires access to the BCI2000 source code. You will need to rebuild the MatlabSignalProcessing executable.

Command Line Options

MatlabWD

By default, the Matlab engine's working directory is set to the signal processing module's working directory at startup. When using the Matlab filter for signal processing, your filter's code will be contained in the bci_Process and associated Matlab functions, which will typically be located inside a dedicated directory. Thus, you may switch between Matlab-based filter implementations by selecting a Matlab working directory at startup. This may be done by specifying the MatlabWD parameter from the command line when starting the MatlabSignalProcessing module:

start MatlabSignalProcessing.exe --MatlabWD="./matlab" 127.0.0.1

will change Matlab's working directory to a directory called "matlab" inside the BCI2000 "prog" directory at startup, and execute bci_Process and associated functions from there.

This parameter must be set from the command line; later changes will have no effect.

Using the --MatlabWD command line option, you may easily switch between multiple Matlab-based BCI2000 configurations. Simply create a separate startup batch file for each configuration, and specify the respective configuration's path on the command line that starts up the MatlabFilter.

MatlabStayOpen

By default, the Matlab instance associated with the Matlab engine will be closed when BCI2000 quits. Generally, this behavior is desired to ensure a well-defined BCI2000 system state after each startup. For debugging purposes, though, it is sometimes useful to have the engine's command window available even after BCI2000 has been quit. This behavior is controlled by another command-line parameter, MatlabStayOpen, which may take the following values:

  • 0 is the default (no change in behavior),
  • 1 keeps the Matlab engine's command window open but clears variables used to transmit information forth and back between BCI2000 and Matlab,
  • 2 also preserves intermediate variables (such as bci_Parameters and bci_States) in the Matlab engine's workspace.

To set this parameter to 2, use this command line to start up the signal processing module:

start MatlabSignalProcessing.exe --MatlabStayOpen=2 127.0.0.1

Once the MatlabStayOpen parameter has been set from the command line, it will be listed on the Operator Module's parameter configuration dialog's "system" tab, and may be modified from there. The change will be applied when clicking Set Config.

Troubleshooting

Debugging Matlab functions

  1. Start BCI2000. The MatlabFilter will open a Matlab instance in its own window in minimized state.
  2. Switch to the minimized Matlab instance.
  3. Type, e.g.,
    edit bci_Process.m
    to open a Matlab editor window connected to the Matlab interactive window.
  4. In the editor window, set breakpoints as you would normally.
  5. Execution will be paused, and you may examine variables hovering the mouse over them.

Unfortunately, recent versions of Matlab have limited support for interactive debugging of functions executed in the Matlab engine. Setting breakpoints prior to executing code, and stepping through the code should work, but it may not be possible to modify breakpoints while debugging. Further, clicking "continue" may lead to a Matlab exception message, from which "Attempt to Continue" can be clicked to continue execution. For an official suggestion from MathWorks, see [1].

Matlab doesn't find your functions

Make sure to

  • either set Matlab's working directory to the directory containing your functions, using the --MatlabWD command line option described above,
  • or add the respective directory to your Matlab path.

Generally, the first option is recommended over the second one.

There is no Matlab engine started up

For using the MatlabEngine on Windows systems, you need to make sure that

  • the processor architecture (32 or 64 bit) of the installed version of Matlab matches that of the BCI2000 module,
  • Matlab can be executed from the command line by running "matlab.exe".

In case of multiple concurrently installed versions of Matlab, the MatlabFilter will always connect to the one that starts up when executing "matlab" from a command prompt. Also, it may help to execute
matlab /regserver
from the command line under the account that is going to use the MatlabFilter.

You get linker errors when rebuilding MatlabSignalProcessing

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, Contributions:FieldTripBuffer