BCI2000 Wiki - User contributions [en]

User:Roostenveld

2019-06-25T15:07:14Z

Roostenveld: updated URL, capitalize MATLAB

Robert Oostenveld is the main developer of the [http://www.fieldtriptoolbox.org FieldTrip] software, an open source MATLAB toolbox for (mainly offline) EEG and MEG analysis. He has contributed the [[Contributions:FieldTripBuffer|FieldTripBuffer]] to the BCI2000 project and contributes to the documentation of using BCI2000 together with MATLAB for offline and online scenarios.

Contributions:FieldTripBuffer

2008-12-02T15:57:03Z

Roostenveld: /* Synopsis */

==Synopsis==
The ''FieldTripBuffer'' filter is an interface between BCI2000 and the FieldTrip Toolbox. The filter hosts a [http://neuroimaging.ruhosting.nl/fieldtrip/doku.php?id=fieldtrip:development:realtime FieldTrip realtime buffer], and writes its input into that buffer, formatted as ''buffer data''.

A separate MATLAB session on either the same or another computer can then use the reading and writing functions from the [http://neuroimaging.ruhosting.nl/fieldtrip FieldTrip toolbox] to communicate with the buffer asynchronously, reading data from BCI2000, and writing back results into BCI2000.

BCI2000 [[BCI2000 Glossary#State Variable|state variables]] may be translated into FieldTrip buffer events; in turn, buffer events are read back from the buffer into BCI2000 state variables. A dedicated FieldTrip buffer event type may be used to determine the filter's output into the BCI2000 processing pipe.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/SignalProcessing/FieldTripBuffer

==Versioning==
===Authors===
Jürgen Mellinger, Robert Oostenveld
===Source Code Revisions===
*Initial development: 2044
*Tested under: 2094
*Known to compile under: 2095

==Parameters==
===FTBufferAddress===
The FieldTrip buffer's listening address, given as an IP:port combination. Software agents connect to this address using a TCP-based protocol.

===FTInitialOutput===
A matrix-valued parameter that determines dimensions as well as initial values of the filter's output signal.
In the matrix, rows map to signal channels, and columns map to elements.

===FTOutputEventType===
A string representing the FieldTrip buffer event type that corresponds to the filter's output signal.
For each block of data, the ''FieldTripBuffer'' filter checks whether an event of that type has been inserted into the buffer; whenever this is the case, the filter's output signal will be updated from the values contained in the event. If the event's data dimensions do not fit the output signal, parts of the output signal will not be updated, or event data will be ignored silently.

===FTStatesToBuffer===
A list of states that are to be converted into events, and written into the buffer. The buffer event type matches the BCI2000 state name.
An asterisk (*) represents any state name; a minus (-) sign before a state name means to exclude the respective state from the transmission.
States may either be written to, or read from, the buffer, but not both; states listed in the ''FTStatesFromBuffer'' parameter are always excluded from writing.

===FTStatesFromBuffer===
A list of states that are to be set from events. When no event of matching type has been posted to the buffer, the state will not change; when multiple events have been posted since the FieldTrip buffer processed the last block of data, then the most recent event determines the state's value.

==States==
Any state name may be specified in the ''FTStatesToBuffer'' and ''FTStatesFromBuffer'' parameters.

==See also==
[[User Reference:MatlabFilter]], [[Programming Reference:MatlabFilter]]

An example is given in the [[Programming Tutorial:Working with the FieldTrip buffer]]

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

Contributions:FieldTripBuffer

2008-12-02T15:56:10Z

Roostenveld: /* Synopsis */

==Synopsis==
The ''FieldTripBuffer'' filter is an interface between BCI2000 and the FieldTrip Toolbox. The filter hosts a [http://neuroimaging.ruhosting.nl/fieldtrip/doku.php?id=fieldtrip:development:realtime FieldTrip realtime buffer], and writes its input into that buffer, formatted as ''buffer data''.

A separate MATLAB session on either the same or another computer can then use the reading and writing functions from the FieldTrip toolbox to communicate with the buffer asynchronously, reading data from BCI2000, and writing back results into BCI2000.

BCI2000 [[BCI2000 Glossary#State Variable|state variables]] may be translated into FieldTrip buffer events; in turn, buffer events are read back from the buffer into BCI2000 state variables. A dedicated FieldTrip buffer event type may be used to determine the filter's output into the BCI2000 processing pipe.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/SignalProcessing/FieldTripBuffer

==Versioning==
===Authors===
Jürgen Mellinger, Robert Oostenveld
===Source Code Revisions===
*Initial development: 2044
*Tested under: 2094
*Known to compile under: 2095

==Parameters==
===FTBufferAddress===
The FieldTrip buffer's listening address, given as an IP:port combination. Software agents connect to this address using a TCP-based protocol.

===FTInitialOutput===
A matrix-valued parameter that determines dimensions as well as initial values of the filter's output signal.
In the matrix, rows map to signal channels, and columns map to elements.

===FTOutputEventType===
A string representing the FieldTrip buffer event type that corresponds to the filter's output signal.
For each block of data, the ''FieldTripBuffer'' filter checks whether an event of that type has been inserted into the buffer; whenever this is the case, the filter's output signal will be updated from the values contained in the event. If the event's data dimensions do not fit the output signal, parts of the output signal will not be updated, or event data will be ignored silently.

===FTStatesToBuffer===
A list of states that are to be converted into events, and written into the buffer. The buffer event type matches the BCI2000 state name.
An asterisk (*) represents any state name; a minus (-) sign before a state name means to exclude the respective state from the transmission.
States may either be written to, or read from, the buffer, but not both; states listed in the ''FTStatesFromBuffer'' parameter are always excluded from writing.

===FTStatesFromBuffer===
A list of states that are to be set from events. When no event of matching type has been posted to the buffer, the state will not change; when multiple events have been posted since the FieldTrip buffer processed the last block of data, then the most recent event determines the state's value.

==States==
Any state name may be specified in the ''FTStatesToBuffer'' and ''FTStatesFromBuffer'' parameters.

==See also==
[[User Reference:MatlabFilter]], [[Programming Reference:MatlabFilter]]

An example is given in the [[Programming Tutorial:Working with the FieldTrip buffer]]

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

Contributions:FieldTripBuffer

2008-12-02T15:53:47Z

Roostenveld: /* See also */

==Synopsis==
The ''FieldTripBuffer'' filter is an interface between BCI2000 and the FieldTrip Toolbox. The filter hosts a [http://neuroimaging.ruhosting.nl/fieldtrip/doku.php?id=fieldtrip:development:realtime FieldTrip realtime buffer], and writes its input into that buffer, formatted as ''buffer data''.

FieldTrip software agents may then use the FieldTrip realtime protocol to communicate with the buffer asynchronously, reading data from BCI2000, and writing back results into BCI2000.

BCI2000 [[BCI2000 Glossary#State Variable|state variables]] may be translated into FieldTrip buffer events; in turn, buffer events are read back from the buffer into BCI2000 state variables. A dedicated FieldTrip buffer event type may be used to determine the filter's output into the BCI2000 processing pipe.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/SignalProcessing/FieldTripBuffer

==Versioning==
===Authors===
Jürgen Mellinger, Robert Oostenveld
===Source Code Revisions===
*Initial development: 2044
*Tested under: 2094
*Known to compile under: 2095

==Parameters==
===FTBufferAddress===
The FieldTrip buffer's listening address, given as an IP:port combination. Software agents connect to this address using a TCP-based protocol.

===FTInitialOutput===
A matrix-valued parameter that determines dimensions as well as initial values of the filter's output signal.
In the matrix, rows map to signal channels, and columns map to elements.

===FTOutputEventType===
A string representing the FieldTrip buffer event type that corresponds to the filter's output signal.
For each block of data, the ''FieldTripBuffer'' filter checks whether an event of that type has been inserted into the buffer; whenever this is the case, the filter's output signal will be updated from the values contained in the event. If the event's data dimensions do not fit the output signal, parts of the output signal will not be updated, or event data will be ignored silently.

===FTStatesToBuffer===
A list of states that are to be converted into events, and written into the buffer. The buffer event type matches the BCI2000 state name.
An asterisk (*) represents any state name; a minus (-) sign before a state name means to exclude the respective state from the transmission.
States may either be written to, or read from, the buffer, but not both; states listed in the ''FTStatesFromBuffer'' parameter are always excluded from writing.

===FTStatesFromBuffer===
A list of states that are to be set from events. When no event of matching type has been posted to the buffer, the state will not change; when multiple events have been posted since the FieldTrip buffer processed the last block of data, then the most recent event determines the state's value.

==States==
Any state name may be specified in the ''FTStatesToBuffer'' and ''FTStatesFromBuffer'' parameters.

==See also==
[[User Reference:MatlabFilter]], [[Programming Reference:MatlabFilter]]

An example is given in the [[Programming Tutorial:Working with the FieldTrip buffer]]

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

Programming Tutorial:Working with the FieldTrip buffer

2008-12-02T15:52:07Z

Roostenveld: /* Getting the data in Matlab */

One of the user-contributed Signal Processing filters is the FieldTripBuffer. The FieldTripBuffer allows you to use BCI2000 in conjunction with MATLAB, just as with the MatlabFilter. The difference between the two interfaces to MATLAB is that the MatlabFilter causes some MATLAB code to be executed in the BCI2000 pipeline, i.e. BCI2000 stays in control over the timing and the MATLAB session only sees a small fragment of the data. That also forces you to write your MATLAB code to use recursive/incremental updating schemes. The FieldTripBuffer interface to MATLAB allows you to control the timing from within MATLAB and read arbitrary sections of data from the ongoing data stream as if it were a continuously growing file, giving more flexibility in the MATLAB code that you can employ.

The advantage of the FieldTripBuffer interface is that you have all control in MATLAB that you are used to. You can write your MATLAB code for offline-analysis (i.e. reading data from a file) and apply exactly the same code to online analysis (i.e. reading from BCI2000). Of course for the online analysis to make some sense, your analysis script has to be meaningful and has to work with relatively small data fragments (e.g. one second or less), otherwise the MATLAB code would not really run in real-time. Another interesting feature is that in MATLAB you can use the profiler (type "help profile") to determine which parts of your code take a long time to execute and speed those parts up.

The remainder of this page gives an example of how to get the data into MATLAB, plot the data using standard MATLAB code, and how to close the BCI loop by writing an event back to BCI2000. The example below does not do any useful processing, it is up to you to decide how you want to process the data in MATLAB. A number of realtime applications are included in the realtime module of the FieldTrip toolbox. Additional documentation for that can be found on the FieldTrip website, under development->realtime.

==Getting the data in Matlab==

The FieldTrip buffer is a multi-threaded and network transparent buffer that allows data to be streamed to it by BCI2000, while at the same time allowing a seperate MATLAB session on the same or another computer to read data from the buffer for analysis. Besides writing the data, BCI2000 also writes the changed status variables as events.

To use the FieldTrip buffer, you start BCI2000 with the FieldTripBuffer as the Signal Processing application. Subsequently you start MATLAB yourself, i.e. your MATLAB session is a normal standalone application. You should have a recent copy of the FieldTrip toolbox installed, or at least a copy of the FieldTrip fileio module. The FieldTrip toolbox and its components are available for download from http://www.ru.nl/neuroimaging/fieldtrip. Please make sure that the correct version of the fileio module is on your MATLAB search path.

Subsequently you can do something like the following code belos. You should be able to copy and paste the code into the MATLAB command window and get a real-time updating MATLAB figure with the data from BCI2000.

<pre>
filename = 'buffer://localhost:1972';

% read the header for the first time to determine number of channels and sampling rate
hdr = read_header(filename, 'cache', true);

count = 0;
prevSample = 0
blocksize = hdr.Fs;
chanindx = 1:hdr.nChans;

while true
% determine number of samples available in buffer
hdr = read_header(filename, 'cache', true);

% see whether new samples are available
newsamples = (hdr.nSamples*hdr.nTrials-prevSample);

if newsamples>=blocksize

% determine the samples to process
begsample = prevSample+1;
endsample = prevSample+blocksize ;

% remember up to where the data was read
prevSample = endsample;
count = count + 1;
fprintf('processing segment %d from sample %d to %d\n', count, begsample, endsample);

% read data segment from buffer
dat = read_data(filename, 'header', hdr, 'begsample', begsample, 'endsample', endsample, 'chanindx', chanindx);

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% subsequently the data can be processed, here it is only plotted
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% create a matching time-axis
time = (begsample:endsample)/hdr.Fs;

% plot the data just like a standard FieldTrip raw data strucute
plot(time, dat);

% ensure tight axes
xlim([time(1) time(end)]);

% force Matlab to update the figure
drawnow

end % if new samples available
end % while true
</pre>

==Closing the loop, writing a control signal from Matlab to BCI2000==

To close the loop, you have to write teh control signal back to BCI2000. Since the FieldTrip buffer can only hold raw data, the control signal cannot be written as data. Instead, the control signal is written as an event. This is easily demonstrated if you run the Feedback Demo Task.

<pre>
event_up.type = 'Signal';
event_up.value = 1;
</pre>

<pre>
event_down.type = 'Signal';
event_down.value = -1;
</pre>

<pre>
event_null.type = 'Signal';
event_null.value = 0;
</pre>

You can write the events to the buffer according to the following example code:

<pre>
filename = 'buffer://localhost:1972';

write_event(filename, event_up); % ... the cursor will move up ...

write_event(filename, event_down); % ... the cursor will move down ...

write_event(filename, event_null); % ... the cursor will stay at a constant value ...
</pre>

The control signal in BCI2000 remains at a constant value as long as you don't write another event with another control signal.

==See also==

[[Contributions:FieldTripBuffer]],
[[Programming Reference:MatlabFilter]],
[[User Reference:MatlabFilter]]

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

Programming Tutorial:Working with the FieldTrip buffer

2008-12-02T15:50:41Z

Roostenveld:

One of the user-contributed Signal Processing filters is the FieldTripBuffer. The FieldTripBuffer allows you to use BCI2000 in conjunction with MATLAB, just as with the MatlabFilter. The difference between the two interfaces to MATLAB is that the MatlabFilter causes some MATLAB code to be executed in the BCI2000 pipeline, i.e. BCI2000 stays in control over the timing and the MATLAB session only sees a small fragment of the data. That also forces you to write your MATLAB code to use recursive/incremental updating schemes. The FieldTripBuffer interface to MATLAB allows you to control the timing from within MATLAB and read arbitrary sections of data from the ongoing data stream as if it were a continuously growing file, giving more flexibility in the MATLAB code that you can employ.

The advantage of the FieldTripBuffer interface is that you have all control in MATLAB that you are used to. You can write your MATLAB code for offline-analysis (i.e. reading data from a file) and apply exactly the same code to online analysis (i.e. reading from BCI2000). Of course for the online analysis to make some sense, your analysis script has to be meaningful and has to work with relatively small data fragments (e.g. one second or less), otherwise the MATLAB code would not really run in real-time. Another interesting feature is that in MATLAB you can use the profiler (type "help profile") to determine which parts of your code take a long time to execute and speed those parts up.

The remainder of this page gives an example of how to get the data into MATLAB, plot the data using standard MATLAB code, and how to close the BCI loop by writing an event back to BCI2000. The example below does not do any useful processing, it is up to you to decide how you want to process the data in MATLAB. A number of realtime applications are included in the realtime module of the FieldTrip toolbox. Additional documentation for that can be found on the FieldTrip website, under development->realtime.

==Getting the data in Matlab==

The FieldTrip buffer is a multi-threaded and network transparent buffer that allows data to be streamed to it by BCI2000, while at the same time allowing a seperate MATLAB session on the same or another computer to read data from the buffer for analysis. Besides writing the data, BCI2000 also writes the changed status variables as events.

To use the FieldTrip buffer, you start BCI2000 with the FieldTripBuffer as the Signal Processing application. Subsequently you start MATLAB yourself, i.e. your MATLAB session is a normal standalone application. You should have a recent copy of the FieldTrip toolbox installed, or at least a copy of the FieldTrip fileio module. The FieldTrip toolbox and its components are available for download from http://www.ru.nl/neuroimaging/fieldtrip. Please make sure that the correct version of the fileio module is on your MATLAB search path.

Subsequently you can do something like this

<pre>
filename = 'buffer://localhost:1972';

% read the header for the first time to determine number of channels and sampling rate
hdr = read_header(filename, 'cache', true);

count = 0;
prevSample = 0
blocksize = hdr.Fs;
chanindx = 1:hdr.nChans;

while true
% determine number of samples available in buffer
hdr = read_header(filename, 'cache', true);

% see whether new samples are available
newsamples = (hdr.nSamples*hdr.nTrials-prevSample);

if newsamples>=blocksize

% determine the samples to process
begsample = prevSample+1;
endsample = prevSample+blocksize ;

% remember up to where the data was read
prevSample = endsample;
count = count + 1;
fprintf('processing segment %d from sample %d to %d\n', count, begsample, endsample);

% read data segment from buffer
dat = read_data(filename, 'header', hdr, 'begsample', begsample, 'endsample', endsample, 'chanindx', chanindx);

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% subsequently the data can be processed, here it is only plotted
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% create a matching time-axis
time = (begsample:endsample)/hdr.Fs;

% plot the data just like a standard FieldTrip raw data strucute
plot(time, dat);

% ensure tight axes
xlim([time(1) time(end)]);

% force Matlab to update the figure
drawnow

end % if new samples available
end % while true
</pre>

==Closing the loop, writing a control signal from Matlab to BCI2000==

To close the loop, you have to write teh control signal back to BCI2000. Since the FieldTrip buffer can only hold raw data, the control signal cannot be written as data. Instead, the control signal is written as an event. This is easily demonstrated if you run the Feedback Demo Task.

<pre>
event_up.type = 'Signal';
event_up.value = 1;
</pre>

<pre>
event_down.type = 'Signal';
event_down.value = -1;
</pre>

<pre>
event_null.type = 'Signal';
event_null.value = 0;
</pre>

You can write the events to the buffer according to the following example code:

<pre>
filename = 'buffer://localhost:1972';

write_event(filename, event_up); % ... the cursor will move up ...

write_event(filename, event_down); % ... the cursor will move down ...

write_event(filename, event_null); % ... the cursor will stay at a constant value ...
</pre>

The control signal in BCI2000 remains at a constant value as long as you don't write another event with another control signal.

==See also==

[[Contributions:FieldTripBuffer]],
[[Programming Reference:MatlabFilter]],
[[User Reference:MatlabFilter]]

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

Programming Tutorial:Working with the FieldTrip buffer

2008-12-02T15:34:29Z

Roostenveld: /* Closing the loop, writing a control signal from Matlab to BCI2000 */

==Getting the data in Matlab==

The FieldTrip buffer is a multi-threaded and network transparent buffer that allows data to be streamed to it by BCI2000, while at the same time allowing a seperate MATLAB session on the same or another computer to read data from the buffer for analysis. Besides writing the data, BCI2000 also writes the changed status variables as events.

To use the FieldTrip buffer, you start BCI2000 with the FieldTripBuffer as the Signal Processing application. Subsequently you start MATLAB yourself, i.e. your MATLAB session is a normal standalone application. You should have a recent copy of the FieldTrip toolbox installed, or at least a copy of the FieldTrip fileio module. The FieldTrip toolbox and its components are available for download from http://www.ru.nl/neuroimaging/fieldtrip. Please make sure that the correct version of the fileio module is on your MATLAB search path.

Subsequently you can do something like this

<pre>
filename = 'buffer://localhost:1972';

% read the header for the first time to determine number of channels and sampling rate
hdr = read_header(filename, 'cache', true);

count = 0;
prevSample = 0
blocksize = hdr.Fs;
chanindx = 1:hdr.nChans;

while true
% determine number of samples available in buffer
hdr = read_header(filename, 'cache', true);

% see whether new samples are available
newsamples = (hdr.nSamples*hdr.nTrials-prevSample);

if newsamples>=blocksize

% determine the samples to process
begsample = prevSample+1;
endsample = prevSample+blocksize ;

% remember up to where the data was read
prevSample = endsample;
count = count + 1;
fprintf('processing segment %d from sample %d to %d\n', count, begsample, endsample);

% read data segment from buffer
dat = read_data(filename, 'header', hdr, 'begsample', begsample, 'endsample', endsample, 'chanindx', chanindx);

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% subsequently the data can be processed, here it is only plotted
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% create a matching time-axis
time = (begsample:endsample)/hdr.Fs;

% plot the data just like a standard FieldTrip raw data strucute
plot(time, dat);

% ensure tight axes
xlim([time(1) time(end)]);

% force Matlab to update the figure
drawnow

end % if new samples available
end % while true
</pre>

==Closing the loop, writing a control signal from Matlab to BCI2000==

To close the loop, you have to write teh control signal back to BCI2000. Since the FieldTrip buffer can only hold raw data, the control signal cannot be written as data. Instead, the control signal is written as an event. This is easily demonstrated if you run the Feedback Demo Task.

<pre>
event_up.type = 'Signal';
event_up.value = 1;
</pre>

<pre>
event_down.type = 'Signal';
event_down.value = -1;
</pre>

<pre>
event_null.type = 'Signal';
event_null.value = 0;
</pre>

You can write the events to the buffer according to the following example code:

<pre>
filename = 'buffer://localhost:1972';

write_event(filename, event_up); % ... the cursor will move up ...

write_event(filename, event_down); % ... the cursor will move down ...

write_event(filename, event_null); % ... the cursor will stay at a constant value ...
</pre>

The control signal in BCI2000 remains at a constant value as long as you don't write another event with another control signal.

==See also==

[[Contributions:FieldTripBuffer]],
[[Programming Reference:MatlabFilter]],
[[User Reference:MatlabFilter]]

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

Programming Tutorial:Working with the FieldTrip buffer

2008-12-02T15:26:34Z

Roostenveld: /* Getting the data in Matlab */

==Getting the data in Matlab==

The FieldTrip buffer is a multi-threaded and network transparent buffer that allows data to be streamed to it by BCI2000, while at the same time allowing a seperate MATLAB session on the same or another computer to read data from the buffer for analysis. Besides writing the data, BCI2000 also writes the changed status variables as events.

To use the FieldTrip buffer, you start BCI2000 with the FieldTripBuffer as the Signal Processing application. Subsequently you start MATLAB yourself, i.e. your MATLAB session is a normal standalone application. You should have a recent copy of the FieldTrip toolbox installed, or at least a copy of the FieldTrip fileio module. The FieldTrip toolbox and its components are available for download from http://www.ru.nl/neuroimaging/fieldtrip. Please make sure that the correct version of the fileio module is on your MATLAB search path.

Subsequently you can do something like this

<pre>
filename = 'buffer://localhost:1972';

% read the header for the first time to determine number of channels and sampling rate
hdr = read_header(filename, 'cache', true);

count = 0;
prevSample = 0
blocksize = hdr.Fs;
chanindx = 1:hdr.nChans;

while true
% determine number of samples available in buffer
hdr = read_header(filename, 'cache', true);

% see whether new samples are available
newsamples = (hdr.nSamples*hdr.nTrials-prevSample);

if newsamples>=blocksize

% determine the samples to process
begsample = prevSample+1;
endsample = prevSample+blocksize ;

% remember up to where the data was read
prevSample = endsample;
count = count + 1;
fprintf('processing segment %d from sample %d to %d\n', count, begsample, endsample);

% read data segment from buffer
dat = read_data(filename, 'header', hdr, 'begsample', begsample, 'endsample', endsample, 'chanindx', chanindx);

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% subsequently the data can be processed, here it is only plotted
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% create a matching time-axis
time = (begsample:endsample)/hdr.Fs;

% plot the data just like a standard FieldTrip raw data strucute
plot(time, dat);

% ensure tight axes
xlim([time(1) time(end)]);

% force Matlab to update the figure
drawnow

end % if new samples available
end % while true
</pre>

==Closing the loop, writing a control signal from Matlab to BCI2000==

To close the loop, you have to write teh control signal back to BCI2000. Since the FieldTrip buffer can only hold raw data, the control signal cannot be written as data. Instead, the control signal is written as an event. This is easily demonstrated if you run the Feedback Demo Task.

<pre>
event_up.type = 'Signal';
event_up.value = 1;
</pre>

<pre>
event_down.type = 'Signal';
event_down.value = -1;
</pre>

<pre>
event_null.type = 'Signal';
event_null.value = 0;
</pre>

You can write the events to the buffer according to the following example code:

<pre>
filename = 'buffer://localhost:1972';

write_event(filename, event_up);

% ... the cursor will move up ...

write_event(filename, event_down);

% ... the cursor will move down ...

write_event(filename, event_null);

% ... the cursor will stay at a constant value ...
</pre>

The control signal in BCI2000 remains at a constant value as long as you don't write another event with another control signal.

==See also==

[[Contributions:FieldTripBuffer]],
[[Programming Reference:MatlabFilter]],
[[User Reference:MatlabFilter]]

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

Programming Tutorial:Working with the FieldTrip buffer

2008-12-02T15:07:24Z

Roostenveld: /* Getting the data in Matlab */

==Getting the data in Matlab==

The FieldTrip buffer is a multi-threaded and network transparent buffer that allows data to be streamed to it by BCI2000, while at the same time allowing a seperate MATLAB session on the same or another computer to read data from the buffer for analysis. Besides writing the data, BCI2000 also writes the changed status variables as events.

To use the FieldTrip buffer, you start BCI2000 with the FieldTripBuffer as the Signal Processing application. Subsequently you start MATLAB yourself, i.e. your MATLAB session is a normal standalone application.

To read from the FieldTrip buffer, you should have a copy of the FieldTrip toolbox, or at least a copy of the FieldTrip fileio module. Subsequently you can do something like this

<pre>
filename = 'buffer://localhost:1972';

% read the header for the first time to determine number of channels and sampling rate
hdr = read_header(filename, 'cache', true);

count = 0;
prevSample = 0
blocksize = hdr.Fs;
chanindx = 1:hdr.nChans;

while true
% determine number of samples available in buffer
hdr = read_header(filename, 'cache', true);

% see whether new samples are available
newsamples = (hdr.nSamples*hdr.nTrials-prevSample);

if newsamples>=blocksize

% determine the samples to process
begsample = prevSample+1;
endsample = prevSample+blocksize ;

% remember up to where the data was read
prevSample = endsample;
count = count + 1;
fprintf('processing segment %d from sample %d to %d\n', count, begsample, endsample);

% read data segment from buffer
dat = read_data(filename, 'header', hdr, 'begsample', begsample, 'endsample', endsample, 'chanindx', chanindx);

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% subsequently the data can be processed, here it is only plotted
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% create a matching time-axis
time = (begsample:endsample)/hdr.Fs;

% plot the data just like a standard FieldTrip raw data strucute
plot(time, dat);

% ensure tight axes
xlim([time(1) time(end)]);

% force Matlab to update the figure
drawnow

end % if new samples available
end % while true
</pre>

==Closing the loop, writing a control signal from Matlab to BCI2000==

To close the loop, you have to write teh control signal back to BCI2000. Since the FieldTrip buffer can only hold raw data, the control signal cannot be written as data. Instead, the control signal is written as an event. This is easily demonstrated if you run the Feedback Demo Task.

<pre>
event_up.type = 'Signal';
event_up.value = 1;
</pre>

<pre>
event_down.type = 'Signal';
event_down.value = -1;
</pre>

<pre>
event_null.type = 'Signal';
event_null.value = 0;
</pre>

You can write the events to the buffer according to the following example code:

<pre>
filename = 'buffer://localhost:1972';

write_event(filename, event_up);

% ... the cursor will move up ...

write_event(filename, event_down);

% ... the cursor will move down ...

write_event(filename, event_null);

% ... the cursor will stay at a constant value ...
</pre>

The control signal in BCI2000 remains at a constant value as long as you don't write another event with another control signal.

==See also==

[[Contributions:FieldTripBuffer]],
[[Programming Reference:MatlabFilter]],
[[User Reference:MatlabFilter]]

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

Programming Tutorial:Working with the FieldTrip buffer

2008-12-02T14:56:01Z

Roostenveld: /* Getting the data in Matlab */

==Getting the data in Matlab==

The FieldTrip buffer is a multi-threaded and network transparent buffer that allows data to be streamed to it by BCI2000, while at the same time allowing a seperate MATLAB session on the same or another computer to read data from the buffer for analysis. Besides writing the data, BCI2000 also writes the changed status variables as events.

To read from the FieldTrip buffer, you should have a copy of the FieldTrip toolbox, or at least a copy of the FieldTrip fileio module. Subsequently you can do something like this

<pre>
filename = 'buffer://localhost:1972';

% read the header for the first time to determine number of channels and sampling rate
hdr = read_header(filename, 'cache', true);

count = 0;
prevSample = 0
blocksize = hdr.Fs;
chanindx = 1:hdr.nChans;

while true
% determine number of samples available in buffer
hdr = read_header(filename, 'cache', true);

% see whether new samples are available
newsamples = (hdr.nSamples*hdr.nTrials-prevSample);

if newsamples>=blocksize

% determine the samples to process
begsample = prevSample+1;
endsample = prevSample+blocksize ;

% remember up to where the data was read
prevSample = endsample;
count = count + 1;
fprintf('processing segment %d from sample %d to %d\n', count, begsample, endsample);

% read data segment from buffer
dat = read_data(filename, 'header', hdr, 'begsample', begsample, 'endsample', endsample, 'chanindx', chanindx);

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% subsequently the data can be processed, here it is only plotted
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% create a matching time-axis
time = (begsample:endsample)/hdr.Fs;

% plot the data just like a standard FieldTrip raw data strucute
plot(time, dat);

% ensure tight axes
xlim([time(1) time(end)]);

% force Matlab to update the figure
drawnow

end % if new samples available
end % while true
</pre>

==Closing the loop, writing a control signal from Matlab to BCI2000==

To close the loop, you have to write teh control signal back to BCI2000. Since the FieldTrip buffer can only hold raw data, the control signal cannot be written as data. Instead, the control signal is written as an event. This is easily demonstrated if you run the Feedback Demo Task.

<pre>
event_up.type = 'Signal';
event_up.value = 1;
</pre>

<pre>
event_down.type = 'Signal';
event_down.value = -1;
</pre>

<pre>
event_null.type = 'Signal';
event_null.value = 0;
</pre>

You can write the events to the buffer according to the following example code:

<pre>
filename = 'buffer://localhost:1972';

write_event(filename, event_up);

% ... the cursor will move up ...

write_event(filename, event_down);

% ... the cursor will move down ...

write_event(filename, event_null);

% ... the cursor will stay at a constant value ...
</pre>

The control signal in BCI2000 remains at a constant value as long as you don't write another event with another control signal.

==See also==

[[Contributions:FieldTripBuffer]],
[[Programming Reference:MatlabFilter]],
[[User Reference:MatlabFilter]]

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

Programming Tutorial:Working with the FieldTrip buffer

2008-12-02T14:54:42Z

Roostenveld: /* Getting the data in Matlab */

==Getting the data in Matlab==

The FieldTrip buffer is a multi-threaded and network transparent buffer that allows data to be streamed to it by BCI2000, while at the same time allowing a seperate MATLAB session on the same or another computer to read data from the buffer for analysis. Besides writing the data, BCI2000 also writes the changed status variables as events.

To read from the FieldTrip buffer, you should have a copy of the FieldTrip toolbox, or at least a copy of the FieldTrip fileio module. Subsequently you can do something like this

<pre>
% read the header for the first time to determine number of channels and sampling rate
hdr = read_header(filename, 'cache', true);

count = 0;
prevSample = 0
blocksize = hdr.Fs;
chanindx = 1:hdr.nChans;

while true
% determine number of samples available in buffer
hdr = read_header(filename, 'cache', true);

% see whether new samples are available
newsamples = (hdr.nSamples*hdr.nTrials-prevSample);

if newsamples>=blocksize

% determine the samples to process
begsample = prevSample+1;
endsample = prevSample+blocksize ;

% remember up to where the data was read
prevSample = endsample;
count = count + 1;
fprintf('processing segment %d from sample %d to %d\n', count, begsample, endsample);

% read data segment from buffer
dat = read_data(filename, 'header', hdr, 'begsample', begsample, 'endsample', endsample, 'chanindx', chanindx);

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% subsequently the data can be processed, here it is only plotted
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% create a matching time-axis
time = (begsample:endsample)/hdr.Fs;

% plot the data just like a standard FieldTrip raw data strucute
plot(time, dat);

% ensure tight axes
xlim([time(1) time(end)]);

% force Matlab to update the figure
drawnow

end % if new samples available
end % while true
</pre>

==Closing the loop, writing a control signal from Matlab to BCI2000==

To close the loop, you have to write teh control signal back to BCI2000. Since the FieldTrip buffer can only hold raw data, the control signal cannot be written as data. Instead, the control signal is written as an event. This is easily demonstrated if you run the Feedback Demo Task.

<pre>
event_up.type = 'Signal';
event_up.value = 1;
</pre>

<pre>
event_down.type = 'Signal';
event_down.value = -1;
</pre>

<pre>
event_null.type = 'Signal';
event_null.value = 0;
</pre>

You can write the events to the buffer according to the following example code:

<pre>
filename = 'buffer://localhost:1972';

write_event(filename, event_up);

% ... the cursor will move up ...

write_event(filename, event_down);

% ... the cursor will move down ...

write_event(filename, event_null);

% ... the cursor will stay at a constant value ...
</pre>

The control signal in BCI2000 remains at a constant value as long as you don't write another event with another control signal.

==See also==

[[Contributions:FieldTripBuffer]],
[[Programming Reference:MatlabFilter]],
[[User Reference:MatlabFilter]]

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

Programming Tutorial:Working with the FieldTrip buffer

2008-12-02T14:54:21Z

Roostenveld: /* Getting the data in Matlab */

==Getting the data in Matlab==

The FieldTrip buffer is a multi-threaded and network transparent buffer that allows data to be streamed to it by BCI2000, while at the same time allowing a seperate MATLAB session on the same or another computer to read data from the buffer for analysis. Besides writing the data, BCI2000 also writes the changed status variables as events.

To read from the FieldTrip buffer, you should have a copy of the FieldTrip toolbox, or at least a copy of the FieldTrip fileio module. Subsequently you can do something like this

<pre>
% read the header for the first time to determine number of channels and sampling rate
hdr = read_header(filename, 'cache', true);

count = 0;
prevSample = 0
blocksize = hdr.Fs;
chanindx = 1:hdr.nChans;

while true
% determine number of samples available in buffer
hdr = read_header(filename, 'cache', true);

% see whether new samples are available
newsamples = (hdr.nSamples*hdr.nTrials-prevSample);

if newsamples>=blocksize

% determine the samples to process
begsample = prevSample+1;
endsample = prevSample+blocksize ;

% remember up to where the data was read
prevSample = endsample;
count = count + 1;
fprintf('processing segment %d from sample %d to %d\n', count, begsample, endsample);

% read data segment from buffer
dat = read_data(filename, 'header', hdr, 'begsample', begsample, 'endsample', endsample, 'chanindx', chanindx);

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% subsequently the data can be processed, here it is only plotted
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% create a matching time-axis
time = (begsample:endsample)/hdr.Fs;

% plot the data just like a standard FieldTrip raw data strucute
plot(time, dat);

% ensure tight axes
xlim([time(1) time(end)]);

% force Matlab to update the figure
drawnow

end % if new samples available
end % while true
</pre>

==Closing the loop, writing a control signal from Matlab to BCI2000==

To close the loop, you have to write teh control signal back to BCI2000. Since the FieldTrip buffer can only hold raw data, the control signal cannot be written as data. Instead, the control signal is written as an event. This is easily demonstrated if you run the Feedback Demo Task.

<pre>
event_up.type = 'Signal';
event_up.value = 1;
</pre>

<pre>
event_down.type = 'Signal';
event_down.value = -1;
</pre>

<pre>
event_null.type = 'Signal';
event_null.value = 0;
</pre>

You can write the events to the buffer according to the following example code:

<pre>
filename = 'buffer://localhost:1972';

write_event(filename, event_up);

% ... the cursor will move up ...

write_event(filename, event_down);

% ... the cursor will move down ...

write_event(filename, event_null);

% ... the cursor will stay at a constant value ...
</pre>

The control signal in BCI2000 remains at a constant value as long as you don't write another event with another control signal.

==See also==

[[Contributions:FieldTripBuffer]],
[[Programming Reference:MatlabFilter]],
[[User Reference:MatlabFilter]]

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

Programming Tutorial:Working with the FieldTrip buffer

2008-12-02T14:44:44Z

Roostenveld: /* Closing the loop, writing a control signal from Matlab to BCI2000 */

==Getting the data in Matlab==

The FieldTrip buffer is a multi-threaded and network transparent buffer that allows data to be streamed to it by BCI2000, while at the same time allowing a seperate MATLAB session on the same or another computer to read data from the buffer for analysis. Besides writing the data, BCI2000 also writes the changed status variables as events.

To read from the FieldTrip buffer, you should have a copy of the FieldTrip toolbox, or at least a copy of the FieldTrip fileio module. Subsequently you can do something like this

<pre>
% read the header for the first time to determine number of channels and sampling rate
hdr = read_header(filename, 'cache', true);

count = 0;
prevSample = 0
blocksize = hdr.Fs;
chanindx = 1:hdr.nChans;

while true
% determine number of samples available in buffer
hdr = read_header(filename, 'cache', true);

% see whether new samples are available
newsamples = (hdr.nSamples*hdr.nTrials-prevSample);

if newsamples>=blocksize

% determine the samples to process
begsample = prevSample+1;
endsample = prevSample+blocksize ;

% remember up to where the data was read
prevSample = endsample;
count = count + 1;
fprintf('processing segment %d from sample %d to %d\n', count, begsample, endsample);

% read data segment from buffer
dat = read_data(filename, 'header', hdr, 'begsample', begsample, 'endsample', endsample, 'chanindx', chanindx);

% create a matching time-axis
time = (begsample:endsample)/hdr.Fs;

% plot the data just like a standard FieldTrip raw data strucute
plot(time, dat);

% ensure tight axes
xlim([time(1) time(end)]);

% force Matlab to update the figure
drawnow

end % if new samples available
end % while true
</pre>

==Closing the loop, writing a control signal from Matlab to BCI2000==

To close the loop, you have to write teh control signal back to BCI2000. Since the FieldTrip buffer can only hold raw data, the control signal cannot be written as data. Instead, the control signal is written as an event. This is easily demonstrated if you run the Feedback Demo Task.

<pre>
event_up.type = 'Signal';
event_up.value = 1;
</pre>

<pre>
event_down.type = 'Signal';
event_down.value = -1;
</pre>

<pre>
event_null.type = 'Signal';
event_null.value = 0;
</pre>

You can write the events to the buffer according to the following example code:

<pre>
filename = 'buffer://localhost:1972';

write_event(filename, event_up);

% ... the cursor will move up ...

write_event(filename, event_down);

% ... the cursor will move down ...

write_event(filename, event_null);

% ... the cursor will stay at a constant value ...
</pre>

The control signal in BCI2000 remains at a constant value as long as you don't write another event with another control signal.

==See also==

[[Contributions:FieldTripBuffer]],
[[Programming Reference:MatlabFilter]],
[[User Reference:MatlabFilter]]

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

Programming Tutorial:Working with the FieldTrip buffer

2008-12-02T14:44:29Z

Roostenveld: /* Closing the loop, writing a control signal from Matlab to BCI2000 */

==Getting the data in Matlab==

The FieldTrip buffer is a multi-threaded and network transparent buffer that allows data to be streamed to it by BCI2000, while at the same time allowing a seperate MATLAB session on the same or another computer to read data from the buffer for analysis. Besides writing the data, BCI2000 also writes the changed status variables as events.

To read from the FieldTrip buffer, you should have a copy of the FieldTrip toolbox, or at least a copy of the FieldTrip fileio module. Subsequently you can do something like this

<pre>
% read the header for the first time to determine number of channels and sampling rate
hdr = read_header(filename, 'cache', true);

count = 0;
prevSample = 0
blocksize = hdr.Fs;
chanindx = 1:hdr.nChans;

while true
% determine number of samples available in buffer
hdr = read_header(filename, 'cache', true);

% see whether new samples are available
newsamples = (hdr.nSamples*hdr.nTrials-prevSample);

if newsamples>=blocksize

% determine the samples to process
begsample = prevSample+1;
endsample = prevSample+blocksize ;

% remember up to where the data was read
prevSample = endsample;
count = count + 1;
fprintf('processing segment %d from sample %d to %d\n', count, begsample, endsample);

% read data segment from buffer
dat = read_data(filename, 'header', hdr, 'begsample', begsample, 'endsample', endsample, 'chanindx', chanindx);

% create a matching time-axis
time = (begsample:endsample)/hdr.Fs;

% plot the data just like a standard FieldTrip raw data strucute
plot(time, dat);

% ensure tight axes
xlim([time(1) time(end)]);

% force Matlab to update the figure
drawnow

end % if new samples available
end % while true
</pre>

==Closing the loop, writing a control signal from Matlab to BCI2000==

To close the loop, you have to write teh control signal back to BCI2000. Since the FieldTrip buffer can only hold raw data, the control signal cannot be written as data. Instead, the control signal is written as an event. This is easily demonstrated if you run the Feedback Demo Task.

<pre>
event_up.type = 'Signal';
event_up.value = 1;
</pre>

<pre>
event_down.type = 'Signal';
event_down.value = -1;
</pre>

<pre>
event_null.type = 'Signal';
event_null.value = 0;
</pre>

You can write the events to the buffer according to the following example code:

<pre>
filename = 'buffer://localhost:1972';
write_event(filename, event_up);

% ... the cursor will move up ...

write_event(filename, event_down);

% ... the cursor will move down ...

write_event(filename, event_null);

% ... the cursor will stay at a constant value ...
</pre>

The control signal in BCI2000 remains at a constant value as long as you don't write another event with another control signal.

==See also==

[[Contributions:FieldTripBuffer]],
[[Programming Reference:MatlabFilter]],
[[User Reference:MatlabFilter]]

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

Programming Tutorial:Working with the FieldTrip buffer

2008-12-02T14:43:52Z

Roostenveld: /* Closing the loop, writing a control signal from Matlab to BCI2000 */

==Getting the data in Matlab==

The FieldTrip buffer is a multi-threaded and network transparent buffer that allows data to be streamed to it by BCI2000, while at the same time allowing a seperate MATLAB session on the same or another computer to read data from the buffer for analysis. Besides writing the data, BCI2000 also writes the changed status variables as events.

To read from the FieldTrip buffer, you should have a copy of the FieldTrip toolbox, or at least a copy of the FieldTrip fileio module. Subsequently you can do something like this

<pre>
% read the header for the first time to determine number of channels and sampling rate
hdr = read_header(filename, 'cache', true);

count = 0;
prevSample = 0
blocksize = hdr.Fs;
chanindx = 1:hdr.nChans;

while true
% determine number of samples available in buffer
hdr = read_header(filename, 'cache', true);

% see whether new samples are available
newsamples = (hdr.nSamples*hdr.nTrials-prevSample);

if newsamples>=blocksize

% determine the samples to process
begsample = prevSample+1;
endsample = prevSample+blocksize ;

% remember up to where the data was read
prevSample = endsample;
count = count + 1;
fprintf('processing segment %d from sample %d to %d\n', count, begsample, endsample);

% read data segment from buffer
dat = read_data(filename, 'header', hdr, 'begsample', begsample, 'endsample', endsample, 'chanindx', chanindx);

% create a matching time-axis
time = (begsample:endsample)/hdr.Fs;

% plot the data just like a standard FieldTrip raw data strucute
plot(time, dat);

% ensure tight axes
xlim([time(1) time(end)]);

% force Matlab to update the figure
drawnow

end % if new samples available
end % while true
</pre>

==Closing the loop, writing a control signal from Matlab to BCI2000==

To close the loop, you have to write teh control signal back to BCI2000. Since the FieldTrip buffer can only hold raw data, the control signal cannot be written as data. Instead, the control signal is written as an event. This is easily demonstrated if you run the '''Feedback Demo Task'''.

<pre>
event_up.type = 'Signal';
event_up.value = 1;
</pre>

<pre>
event_down.type = 'Signal';
event_down.value = -1;
</pre>

<pre>
event_null.type = 'Signal';
event_null.value = 0;
</pre>

You can write the events to the buffer according to the following example code:

<pre>
filename = 'buffer://localhost:1972';
write_event(filename, event_up);
% ... the cursor will move up
write_event(filename, event_down);
% ... the cursor will move down
write_event(filename, event_null);
% ... the cursor will stay at a constant value
</pre>

The control signal in BCI2000 remains at a constant value as long as you don't write another event with another control signal.

==See also==

[[Contributions:FieldTripBuffer]],
[[Programming Reference:MatlabFilter]],
[[User Reference:MatlabFilter]]

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

Programming Tutorial:Working with the FieldTrip buffer

2008-12-02T14:38:57Z

Roostenveld: /* Getting the data in Matlab */

Programming Tutorial:Working with the FieldTrip buffer

2008-12-02T14:36:56Z

Roostenveld:

Programming Tutorial:Working with the FieldTrip buffer

2008-12-02T14:28:23Z

Roostenveld:

==See also==

[[Contributions:FieldTripBuffer]],
[[Programming Reference:MatlabFilter]],
[[User Reference:MatlabFilter]]

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

Programming Reference:Contents

2008-12-02T14:27:14Z

Roostenveld: /* Tutorials */

This part of the reference provides background information which you need in order
to understand, modify, or create code that depends on the BCI2000 framework.

You should read it before writing your own BCI2000 module, or modifying an existing
one as presented in the tutorial examples.

==Getting Started==
*[[Programming Howto:Building BCI2000]]
*[[Programming Howto:SVN Client Setup]]
*[[Programming Howto:Using TortoiseSVN]]
*[[Programming FAQ]]

==Conceptual Overview==
*[[Programming Reference:Filter Chain]]
*[[Programming Reference:Signals]]
*[[Programming Reference:Error Handling]]
*[[Programming Reference:Localization]]
*[[Programming Reference:Rapid Development]]

==Programming Interface Documentation==

===Generic Filter Interface===
*[[Programming Reference:GenericFilter Class]]
*[[Programming Reference:Environment Class]]
*[[Programming Reference:GenericVisualization Class]]

===Text Messages===
*[[Programming Reference:Errors and Warnings]]
*[[Programming Reference:Debug Output]]
*[[Programming Reference:LogFile Class]]

===Data I/O===
*[[Programming Reference:GenericFileWriter Class]]
*[[Programming Reference:GenericADC Class]]
*[[Programming Reference:BCI2000FileReader Class]]

===Signal Processing Modules===
*[[Programming Reference:IIRFilterBase Class]]

===Application Modules===
*[[Programming Reference:ApplicationBase Class]]

====Feedback Applications====
*[[Programming Reference:FeedbackTask Class]]
*[[Programming Reference:FeedbackDemo Application]]

====Stimulus Presentation/ERP Spelling Applications====
*[[Programming Reference:StimulusTask Class]]
*[[Programming Reference:Stimulus Class]]
*[[Programming Reference:Target Class]]
*[[Programming Reference:AssociationMap Class]]
*[[Programming Reference:Speller Class]]

====Visual Output====
*[[Programming Reference:GraphDisplay Class]]
*[[Programming Reference:GraphObject Class]]
*[[Programming Reference:3D API]]

====Audio Output====
*[[Programming Reference:MidiPlayer Class]]
*[[Programming Reference:WavePlayer Class]]
*[[Programming Reference:TextToSpeech Class]]

===Miscellaneous===
*[[Programming Reference:TrialStatistics Class]]
*[[Programming Reference:BlockRandSeq Class]]
*[[Programming Reference:RandomGenerator Class]]
*[[Programming Reference:EnvironmentExtension Class]]

==Tutorials==
*[[Programming Tutorial:Implementing a Data Acquisition Module]]
*[[Programming Tutorial:Implementing a Signal Processing Filter]]
*[[Programming Tutorial:Implementing a Matlab-based Filter]]
*[[Programming Tutorial:Working with the FieldTrip buffer]]
*[[Programming Tutorial:Implementing another Matlab-based Filter]]
*[[Programming Tutorial:Implementing an Input Logger]]

==See also==
[[Technical Reference:Contents]], [[User Reference:Contents]]

[[Category:Contents]]

Programming Reference:Contents

2008-12-02T14:27:03Z

Roostenveld: /* Tutorials */

This part of the reference provides background information which you need in order
to understand, modify, or create code that depends on the BCI2000 framework.

You should read it before writing your own BCI2000 module, or modifying an existing
one as presented in the tutorial examples.

==Getting Started==
*[[Programming Howto:Building BCI2000]]
*[[Programming Howto:SVN Client Setup]]
*[[Programming Howto:Using TortoiseSVN]]
*[[Programming FAQ]]

==Conceptual Overview==
*[[Programming Reference:Filter Chain]]
*[[Programming Reference:Signals]]
*[[Programming Reference:Error Handling]]
*[[Programming Reference:Localization]]
*[[Programming Reference:Rapid Development]]

==Programming Interface Documentation==

===Generic Filter Interface===
*[[Programming Reference:GenericFilter Class]]
*[[Programming Reference:Environment Class]]
*[[Programming Reference:GenericVisualization Class]]

===Text Messages===
*[[Programming Reference:Errors and Warnings]]
*[[Programming Reference:Debug Output]]
*[[Programming Reference:LogFile Class]]

===Data I/O===
*[[Programming Reference:GenericFileWriter Class]]
*[[Programming Reference:GenericADC Class]]
*[[Programming Reference:BCI2000FileReader Class]]

===Signal Processing Modules===
*[[Programming Reference:IIRFilterBase Class]]

===Application Modules===
*[[Programming Reference:ApplicationBase Class]]

====Feedback Applications====
*[[Programming Reference:FeedbackTask Class]]
*[[Programming Reference:FeedbackDemo Application]]

====Stimulus Presentation/ERP Spelling Applications====
*[[Programming Reference:StimulusTask Class]]
*[[Programming Reference:Stimulus Class]]
*[[Programming Reference:Target Class]]
*[[Programming Reference:AssociationMap Class]]
*[[Programming Reference:Speller Class]]

====Visual Output====
*[[Programming Reference:GraphDisplay Class]]
*[[Programming Reference:GraphObject Class]]
*[[Programming Reference:3D API]]

====Audio Output====
*[[Programming Reference:MidiPlayer Class]]
*[[Programming Reference:WavePlayer Class]]
*[[Programming Reference:TextToSpeech Class]]

===Miscellaneous===
*[[Programming Reference:TrialStatistics Class]]
*[[Programming Reference:BlockRandSeq Class]]
*[[Programming Reference:RandomGenerator Class]]
*[[Programming Reference:EnvironmentExtension Class]]

==Tutorials==
*[[Programming Tutorial:Implementing a Data Acquisition Module]]
*[[Programming Tutorial:Implementing a Signal Processing Filter]]
*[[Programming Tutorial:Implementing a Matlab-based Filter]]
*[[Programming Tutorial:IWorking with the FieldTrip buffer]]
*[[Programming Tutorial:Implementing another Matlab-based Filter]]
*[[Programming Tutorial:Implementing an Input Logger]]

==See also==
[[Technical Reference:Contents]], [[User Reference:Contents]]

[[Category:Contents]]

Contributions:FieldTripBuffer

2008-11-26T10:08:01Z

Roostenveld: fix url

==Synopsis==
The ''FieldTripBuffer'' filter is an interface between BCI2000 and the FieldTrip Toolbox. The filter hosts a [http://neuroimaging.ruhosting.nl/fieldtrip/doku.php?id=fieldtrip:development:realtime FieldTrip realtime buffer], and writes its input into that buffer, formatted as ''buffer data''.

FieldTrip software agents may then use the FieldTrip realtime protocol to communicate with the buffer asynchronously, reading data from BCI2000, and writing back results into BCI2000.

BCI2000 [[BCI2000 Glossary#State Variable|state variables]] may be translated into FieldTrip buffer events; in turn, buffer events are read back from the buffer into BCI2000 state variables. A dedicated FieldTrip buffer event type may be used to determine the filter's output into the BCI2000 processing pipe.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/SignalProcessing/FieldTripBuffer

==Versioning==
===Authors===
Jürgen Mellinger, Robert Oostenveld
===Source Code Revisions===
*Initial development: 2044
*Tested under: 2094
*Known to compile under: 2095

==Parameters==
===FTBufferAddress===
The FieldTrip buffer's listening address, given as an IP:port combination. Software agents connect to this address using a TCP-based protocol.

===FTInitialOutput===
A matrix-valued parameter that determines dimensions as well as initial values of the filter's output signal.
In the matrix, rows map to signal channels, and columns map to elements.

===FTOutputEventType===
A string representing the FieldTrip buffer event type that corresponds to the filter's output signal.
For each block of data, the ''FieldTripBuffer'' filter checks whether an event of that type has been inserted into the buffer; whenever this is the case, the filter's output signal will be updated from the values contained in the event. If the event's data dimensions do not fit the output signal, parts of the output signal will not be updated, or event data will be ignored silently.

===FTStatesToBuffer===
A list of states that are to be converted into events, and written into the buffer. The buffer event type matches the BCI2000 state name.
An asterisk (*) represents any state name; a minus (-) sign before a state name means to exclude the respective state from the transmission.
States may either be written to, or read from, the buffer, but not both; states listed in the ''FTStatesFromBuffer'' parameter are always excluded from writing.

===FTStatesFromBuffer===
A list of states that are to be set from events. When no event of matching type has been posted to the buffer, the state will not change; when multiple events have been posted since the FieldTrip buffer processed the last block of data, then the most recent event determines the state's value.

==States==
Any state name may be specified in the ''FTStatesToBuffer'' and ''FTStatesFromBuffer'' parameters.

==See also==
[[User Reference:MatlabFilter]], [[Programming Reference:MatlabFilter]]

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

Contributions:FieldTripBuffer

2008-11-26T10:07:33Z

Roostenveld: updated URL to FT wiki

==Synopsis==
The ''FieldTripBuffer'' filter is an interface between BCI2000 and the FieldTrip Toolbox. The filter hosts a [http://neuroimaging.ru.nl/fieldtrip/doku.php?id=fieldtrip:development:realtime FieldTrip realtime buffer], and writes its input into that buffer, formatted as ''buffer data''.

FieldTrip software agents may then use the FieldTrip realtime protocol to communicate with the buffer asynchronously, reading data from BCI2000, and writing back results into BCI2000.

BCI2000 [[BCI2000 Glossary#State Variable|state variables]] may be translated into FieldTrip buffer events; in turn, buffer events are read back from the buffer into BCI2000 state variables. A dedicated FieldTrip buffer event type may be used to determine the filter's output into the BCI2000 processing pipe.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/SignalProcessing/FieldTripBuffer

==Versioning==
===Authors===
Jürgen Mellinger, Robert Oostenveld
===Source Code Revisions===
*Initial development: 2044
*Tested under: 2094
*Known to compile under: 2095

==Parameters==
===FTBufferAddress===
The FieldTrip buffer's listening address, given as an IP:port combination. Software agents connect to this address using a TCP-based protocol.

===FTInitialOutput===
A matrix-valued parameter that determines dimensions as well as initial values of the filter's output signal.
In the matrix, rows map to signal channels, and columns map to elements.

===FTOutputEventType===
A string representing the FieldTrip buffer event type that corresponds to the filter's output signal.
For each block of data, the ''FieldTripBuffer'' filter checks whether an event of that type has been inserted into the buffer; whenever this is the case, the filter's output signal will be updated from the values contained in the event. If the event's data dimensions do not fit the output signal, parts of the output signal will not be updated, or event data will be ignored silently.

===FTStatesToBuffer===
A list of states that are to be converted into events, and written into the buffer. The buffer event type matches the BCI2000 state name.
An asterisk (*) represents any state name; a minus (-) sign before a state name means to exclude the respective state from the transmission.
States may either be written to, or read from, the buffer, but not both; states listed in the ''FTStatesFromBuffer'' parameter are always excluded from writing.

===FTStatesFromBuffer===
A list of states that are to be set from events. When no event of matching type has been posted to the buffer, the state will not change; when multiple events have been posted since the FieldTrip buffer processed the last block of data, then the most recent event determines the state's value.

==States==
Any state name may be specified in the ''FTStatesToBuffer'' and ''FTStatesFromBuffer'' parameters.

==See also==
[[User Reference:MatlabFilter]], [[Programming Reference:MatlabFilter]]

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

Contributions:ctfneurod

2008-10-22T14:50:58Z

Roostenveld: added detailed build instructions, based on Donders system

==Synopsis==
''ctfneurod'' is a relay program that reads data from the CTF Acq program's RealTime
interface, and provides them to client software over a TCP socket.
On the client side, ''ctfneurod'' implements the Neuroscan Acquire protocol, allowing
to use the [[Contributions:NeuroscanADC|BCI2000 Neuroscan Source Module]] for MEG
data acquisition.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/SignalSource/Neuroscan/ctfneurod

==Author==
''ctfneurod'' was written by <tt>juergen.mellinger@uni-tuebingen.de</tt>. When using it in your
research, please give credit by citing the following reference:

J. Mellinger, G. Schalk, C. Braun, H. Preissl, W. Rosenstiel, N. Birbaumer, A. Kübler:
An MEG-based brain-computer interface (BCI), NeuroImage 2007 Mar;36(3):581-93.

==Compiling and Linking==
''ctfneurod'' requires CTF's development SDK. It links against the <tt>ctfds</tt> and <tt>ctfutil</tt> libraries, and requires the associated header files to compile. If the CTF development SDK is not yet installed on your CTF acquisition system, you can find it on a CDROM labeled "C++ Dataset Library". You should copy "/mnt/cdrom/develop.linux" to your home directory, resulting in the following files and directories

<tt>
/home/meg/develop.linux/code 
/home/meg/develop.linux/doc 
/home/meg/develop.linux/Makefile 
/home/meg/develop.linux/Makefile.local 
develop.linux/obj.linux
</tt>

The ctfneurod directory from BCI2000 should be copied into /home/meg/develop.linux/code/ctfneurod and the Makefile should be edited to list ctfneurod as one of the "PROGS" to be compiled. Subsequently you can type "make" on the linux command line and all programs, including ctfneurod will be compiled.

==Usage==
''ctfneurod'' runs on the data acquisition machine connected to the MEG system, and must be started before CTF's Acq program. When started up, ''ctfneurod'' waits for
the Acq software to begin streaming data, and acts like a Neuroscan Acquire server once
data is available.
Its command line syntax is

ctfneurod <listening address> <options>

There, the server's listening address is specified in the form <tt><ip>:<port></tt>, and defaults to
<tt>localhost:4000</tt>.

==Options==
===<tt>--pattern <regular expression></tt>===
Restricts transmission to a subset of channels available from the Acq RealTime interface.
The subset is defined by matching an extended regular expression against channel names, e.g.
<tt>ctfneurod --pattern "^MLC.*"</tt>
will only transfer channels whose names begin with "MLC".
The default is to transfer all channels that are present on the Acq side.

===<tt>--freqCorrection <factor></tt>===
Normally, the sampling rate on the Neuroscan side is reported to be identical to the
one on the Acq side. When a correction factor is specified, this is multiplied onto the
Acq sampling rate prior to reporting the sampling rate.

===<tt>--outputFormat <nbits></tt>===
Defines the bit depth of data transmission, which is either 16 or 32, and defaults to 16.
When 16 bit data transmission is selected, the lower two bits of data are ignored to avoid
numeric overflow.

===<tt>--disableHP</tt>===
By default, ctfneurod applies a first-order HP filter with a corner frequency of 0.1Hz
to Acq data prior to transmission. If this is undesired, use the --disableHP option to
disable HP filtering.

==See also==
[[Contributions:ADCs]]

[[Category:Contributions]][[Category:Data Acquisition]]

Programming Tutorial:Implementing a simple Matlab-based Filter

2008-08-13T20:30:37Z

Roostenveld: /* An Example Algorithm based on an Existing Matlab Function */

==Online Algorithm Verification==
In the field of BCI signal processing research, novel methods are often proposed and tested on the basis of existing data.
While this is adequate as a research strategy, it is important to keep in mind that timely feedback of brain signal classification is an essential element of a BCI.
From this, it is clear that, ideally, a proposed BCI signal processing or classification method should be verified with respect to its viability and usefulness in a true online setting, providing feedback to the participant causally and in real-time.

BCI2000 facilitates the transformation of an existing offline data analysis method into a functional online system.
*For signal processing components, it provides a convenient, straightforward programming interface.
*A signal processing component may be implemented as a set of Matlab scripts.

Still, it is easy to underestimate the effort required to transform an existing offline implementation of a signal processing algorithm into a functional online implementation. While BCI2000 tries to make the transformation as simple as possible, it cannot remove the effort required to deal with chunks of data, which implies the need of
*buffering -- rather than having immediate access to a continuous data set, it may be necessary to maintain an additional data buffer;
*with the Matlab interface, maintaining a consistent state between subsequent calls to the processing script.

==An Example Algorithm in MATLAB==

In this scenario, we use a simple, straightforward BCI signal processing algorithm, to show the steps necessary to modify the algorithm such
that it may be used to build an online system in BCI2000.

In the example, signal processing consists of IIR bandpass filtering, followed with RMS envelope computation, and linear classification.
A typical Matlab implementation of that algorithm might consist of about ten lines:

<pre>
function class_result = classify( data, band, classifier );

% Use as
% class_result = classify( data, band, classifier )
%
% This function takes raw data as a [channels x samples] vector in the 'data'
% input variable.
%
% Then, it computes bandpower features for the band specified in the 'band'
% input variable, which is a number between 0 and 0.5, specifying
% center frequency in terms of the sampling rate.
%
% As a last step, it applies the 'classifier' matrix to the features in order
% to obtain a single classification result for each sample. The 'classifier'
% vector specifies a classification weight for each processed channel.
%
% The result is a single classification result for each sample.
%
% This requires the Matlab signal processing toolbox.

% Design bandpass filters and apply them to the data matrix.
% The filtered data will contain bandpass filtered data as channels.
[n,Wn]=buttord(band*[0.9 1.1]/2,band*[0.7 1.4]/2,1,60);
[b,a]=butter(n,Wn);
processed_data = filter(b,a,data);

% For demodulation, rectify and apply a low pass.
[b,a]=butter(1,band/4);
processed_data = filter(b,a,abs(processed_data));

% Finally, apply the linear classifier.
class_result = processed_data * classifier;
</pre>

Note that, to be viable in an online environment, an algorithm must operate
on its signal in a causal way, i.e. it may not use future samples in order to
process present samples. (Still, a certain amount of non-causality may be possible
by windowed operation on buffered data, although this will increase the effective
delay between input and output data.)

Also note that the <tt>classify</tt> function omits spatial filtering -- in Matlab,
this may be done easily by pre-multiplying the data with a spatial filter matrix
if desired.

==Translating the existing MATLAB code into BCI2000 functions==

For use with BCI2000, the signal processing code needs to be cast into a form
that suits the BCI2000 filter interface.
In this event-based model, portions of code are called at certain times to configure
a filter component's internal state, and to act upon the signal in chunks on its way through
the BCI2000 chain of filters.

===Process===

The most central event in the filter interface is the ''Process'' event.
The ''Process'' event handler receives a signal input, will process this input
according to the filter component's role in the signal processing chain, and
return the result of processing in a signal output variable.
It is important to understand that the ''Process'' handler is called separately
for each chunk of data, and thus does not see the signal in its entirety.
Also, the size of data blocks (chunks) is freely configurable by the user, although
restricted to limits stemming from recording hardware properties.
This implies that ''Process'' scripts may not depend on a certain
data block size, and will sometimes need to maintain their own data buffers when
the algorithm in question operates on windows of data rather than continuously.
In the current example, this is not the case, so we need not maintain an internal
data buffer.
Still, we need to maintain an internal state between calls to the ''Process''
handler in order to preserve the state of IIR filter delays.
This will allow continuous operation on the signal with the same processing result
as in the offline version of the algorithm.

The algorithm's online version in the <tt>bci_Process</tt> script will thus be:
<pre>
function out_signal = bci_Process( in_signal )

% Process a single block of data by applying a filter to in_signal,
% and return the result in out_signal.
% Signal dimensions are ( channels x samples ).

% We use global variables to store classifier,
% filter coefficients and filter state.
global a b z lpa lpb lpz classifier;

[out_signal, z] = filter( b, a, in_signal, z );
out_signal = abs( out_signal );
[out_signal, lpz] = filter( lpb, lpa, out_signal, lpz );
out_signal = out_signal * classifier;
</pre>

===Initialize===

Determination of filter coefficients is part of per-run initialization, and occurs in the
''Initialize'' event handler:

<pre>
function bci_Initialize( in_signal_dims, out_signal_dims )

% Perform configuration for the bci_Process script.

% Parameters and states are global variables.
global bci_Parameters bci_States;

% We use global variables to store classifier vector,
% filter coefficients and filter state.
global a b z lpa lpb lpz classifier;

% Configure the Bandpass filter
band = str2double( bci_Parameters.Passband ) / str2double( bci_Parameters.SamplingRate );
[n,Wn]=buttord(band*[0.9 1.1]/2,band*[0.7 1.4]/2,1,60);
[b,a]=butter(n,Wn);
z=zeros(max(length(a),length(b))-1,in_signal_dims(1));

% Configure the Lowpass filter
[lpb,lpa]=butter(1,band/4);
lpz=zeros(max(length(lpa),length(lpb))-1,in_signal_dims(1));

% Configure the Classifier vector
classifier = str2double( bci_Parameters.ClassVector );
</pre>

===StartRun===

In addition, we need to reset filter state at the beginning of each run, using the ''StartRun''
event handler:

<pre>
function bci_StartRun

% Reset filter state at the beginning of a run.

global z lpz;
z = zeros(size(z));
lpz = zeros(size(lpz));
</pre>

===Constructor===
To complete the Matlab filter code, we need to declare the ''Band'' and ''Classifier''
parameters in a ''Constructor'' event handler:

<pre>
function [ parameters, states ] = bci_Construct

% Request BCI2000 parameters by returning parameter definition
% lines as demonstrated below.

parameters = { ...
[ 'BPClassifier float Passband= 10 10 0 % % // Bandpass frequency in Hz' ] ...
[ 'BPClassifier matrix ClassVector= 1 1 1 0 % % // Linear classifier vector' ] ...
};
</pre>

===Preflight===

Finally, we need to check parameters for consistency in a ''Preflight''
script, and declare the size of our filter's output signal:

<pre>
function [ out_signal_dim ] = bci_Preflight( in_signal_dim )

% Check whether parameters are accessible, and whether
% parameters have values that allow for safe processing by the
% bci_Process function.
% Also, report output signal dimensions in the 'out_signal_dim' argument.

% Parameters and states are global variables.
global bci_Parameters bci_States;

band = str2double( bci_Parameters.Passband ) / str2double( bci_Parameters.SamplingRate );
if( band <= 0 )
error( 'The passband parameter must be greater zero' );
elseif( band > 0.5 / 1.4 )
error( 'The Passband parameter conflicts with the sampling rate' );
end

out_signal_dim = [ 1, size( in_signal_dim, 2 ) ];
if( in_signal_dim( 1 ) ~= size( bci_Parameters.ClassVector, 2 ) )
error( 'ClassVector length must match the input signal''s number of channels' );
end
</pre>

==See also==

[[Programming Reference:MatlabFilter]],
[[User Reference:MatlabFilter]],
[[Contributions:FieldTripBuffer]]

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

Programming Tutorial:Implementing a simple Matlab-based Filter

2008-08-13T20:30:08Z

Roostenveld: /* An Example Algorithm */

==Online Algorithm Verification==
In the field of BCI signal processing research, novel methods are often proposed and tested on the basis of existing data.
While this is adequate as a research strategy, it is important to keep in mind that timely feedback of brain signal classification is an essential element of a BCI.
From this, it is clear that, ideally, a proposed BCI signal processing or classification method should be verified with respect to its viability and usefulness in a true online setting, providing feedback to the participant causally and in real-time.

BCI2000 facilitates the transformation of an existing offline data analysis method into a functional online system.
*For signal processing components, it provides a convenient, straightforward programming interface.
*A signal processing component may be implemented as a set of Matlab scripts.

Still, it is easy to underestimate the effort required to transform an existing offline implementation of a signal processing algorithm into a functional online implementation. While BCI2000 tries to make the transformation as simple as possible, it cannot remove the effort required to deal with chunks of data, which implies the need of
*buffering -- rather than having immediate access to a continuous data set, it may be necessary to maintain an additional data buffer;
*with the Matlab interface, maintaining a consistent state between subsequent calls to the processing script.

==An Example Algorithm based on an Existing Matlab Function==

In this scenario, we use a simple, straightforward BCI signal processing algorithm, to show the steps necessary to modify the algorithm such
that it may be used to build an online system in BCI2000.

In the example, signal processing consists of IIR bandpass filtering, followed with RMS envelope computation, and linear classification.
A typical Matlab implementation of that algorithm might consist of about ten lines:

<pre>
function class_result = classify( data, band, classifier );

% Use as
% class_result = classify( data, band, classifier )
%
% This function takes raw data as a [channels x samples] vector in the 'data'
% input variable.
%
% Then, it computes bandpower features for the band specified in the 'band'
% input variable, which is a number between 0 and 0.5, specifying
% center frequency in terms of the sampling rate.
%
% As a last step, it applies the 'classifier' matrix to the features in order
% to obtain a single classification result for each sample. The 'classifier'
% vector specifies a classification weight for each processed channel.
%
% The result is a single classification result for each sample.
%
% This requires the Matlab signal processing toolbox.

% Design bandpass filters and apply them to the data matrix.
% The filtered data will contain bandpass filtered data as channels.
[n,Wn]=buttord(band*[0.9 1.1]/2,band*[0.7 1.4]/2,1,60);
[b,a]=butter(n,Wn);
processed_data = filter(b,a,data);

% For demodulation, rectify and apply a low pass.
[b,a]=butter(1,band/4);
processed_data = filter(b,a,abs(processed_data));

% Finally, apply the linear classifier.
class_result = processed_data * classifier;
</pre>

Note that, to be viable in an online environment, an algorithm must operate
on its signal in a causal way, i.e. it may not use future samples in order to
process present samples. (Still, a certain amount of non-causality may be possible
by windowed operation on buffered data, although this will increase the effective
delay between input and output data.)

Also note that the <tt>classify</tt> function omits spatial filtering -- in Matlab,
this may be done easily by pre-multiplying the data with a spatial filter matrix
if desired.

==Translating the existing MATLAB code into BCI2000 functions==

For use with BCI2000, the signal processing code needs to be cast into a form
that suits the BCI2000 filter interface.
In this event-based model, portions of code are called at certain times to configure
a filter component's internal state, and to act upon the signal in chunks on its way through
the BCI2000 chain of filters.

===Process===

The most central event in the filter interface is the ''Process'' event.
The ''Process'' event handler receives a signal input, will process this input
according to the filter component's role in the signal processing chain, and
return the result of processing in a signal output variable.
It is important to understand that the ''Process'' handler is called separately
for each chunk of data, and thus does not see the signal in its entirety.
Also, the size of data blocks (chunks) is freely configurable by the user, although
restricted to limits stemming from recording hardware properties.
This implies that ''Process'' scripts may not depend on a certain
data block size, and will sometimes need to maintain their own data buffers when
the algorithm in question operates on windows of data rather than continuously.
In the current example, this is not the case, so we need not maintain an internal
data buffer.
Still, we need to maintain an internal state between calls to the ''Process''
handler in order to preserve the state of IIR filter delays.
This will allow continuous operation on the signal with the same processing result
as in the offline version of the algorithm.

The algorithm's online version in the <tt>bci_Process</tt> script will thus be:
<pre>
function out_signal = bci_Process( in_signal )

% Process a single block of data by applying a filter to in_signal,
% and return the result in out_signal.
% Signal dimensions are ( channels x samples ).

% We use global variables to store classifier,
% filter coefficients and filter state.
global a b z lpa lpb lpz classifier;

[out_signal, z] = filter( b, a, in_signal, z );
out_signal = abs( out_signal );
[out_signal, lpz] = filter( lpb, lpa, out_signal, lpz );
out_signal = out_signal * classifier;
</pre>

===Initialize===

Determination of filter coefficients is part of per-run initialization, and occurs in the
''Initialize'' event handler:

<pre>
function bci_Initialize( in_signal_dims, out_signal_dims )

% Perform configuration for the bci_Process script.

% Parameters and states are global variables.
global bci_Parameters bci_States;

% We use global variables to store classifier vector,
% filter coefficients and filter state.
global a b z lpa lpb lpz classifier;

% Configure the Bandpass filter
band = str2double( bci_Parameters.Passband ) / str2double( bci_Parameters.SamplingRate );
[n,Wn]=buttord(band*[0.9 1.1]/2,band*[0.7 1.4]/2,1,60);
[b,a]=butter(n,Wn);
z=zeros(max(length(a),length(b))-1,in_signal_dims(1));

% Configure the Lowpass filter
[lpb,lpa]=butter(1,band/4);
lpz=zeros(max(length(lpa),length(lpb))-1,in_signal_dims(1));

% Configure the Classifier vector
classifier = str2double( bci_Parameters.ClassVector );
</pre>

===StartRun===

In addition, we need to reset filter state at the beginning of each run, using the ''StartRun''
event handler:

<pre>
function bci_StartRun

% Reset filter state at the beginning of a run.

global z lpz;
z = zeros(size(z));
lpz = zeros(size(lpz));
</pre>

===Constructor===
To complete the Matlab filter code, we need to declare the ''Band'' and ''Classifier''
parameters in a ''Constructor'' event handler:

<pre>
function [ parameters, states ] = bci_Construct

% Request BCI2000 parameters by returning parameter definition
% lines as demonstrated below.

parameters = { ...
[ 'BPClassifier float Passband= 10 10 0 % % // Bandpass frequency in Hz' ] ...
[ 'BPClassifier matrix ClassVector= 1 1 1 0 % % // Linear classifier vector' ] ...
};
</pre>

===Preflight===

Finally, we need to check parameters for consistency in a ''Preflight''
script, and declare the size of our filter's output signal:

<pre>
function [ out_signal_dim ] = bci_Preflight( in_signal_dim )

% Check whether parameters are accessible, and whether
% parameters have values that allow for safe processing by the
% bci_Process function.
% Also, report output signal dimensions in the 'out_signal_dim' argument.

% Parameters and states are global variables.
global bci_Parameters bci_States;

band = str2double( bci_Parameters.Passband ) / str2double( bci_Parameters.SamplingRate );
if( band <= 0 )
error( 'The passband parameter must be greater zero' );
elseif( band > 0.5 / 1.4 )
error( 'The Passband parameter conflicts with the sampling rate' );
end

out_signal_dim = [ 1, size( in_signal_dim, 2 ) ];
if( in_signal_dim( 1 ) ~= size( bci_Parameters.ClassVector, 2 ) )
error( 'ClassVector length must match the input signal''s number of channels' );
end
</pre>

==See also==

[[Programming Reference:MatlabFilter]],
[[User Reference:MatlabFilter]],
[[Contributions:FieldTripBuffer]]

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

Programming Tutorial:Implementing a simple Matlab-based Filter

2008-08-13T20:28:54Z

Roostenveld: /* Transformation into BCI2000 Matlab Scripts */

==Online Algorithm Verification==
In the field of BCI signal processing research, novel methods are often proposed and tested on the basis of existing data.
While this is adequate as a research strategy, it is important to keep in mind that timely feedback of brain signal classification is an essential element of a BCI.
From this, it is clear that, ideally, a proposed BCI signal processing or classification method should be verified with respect to its viability and usefulness in a true online setting, providing feedback to the participant causally and in real-time.

BCI2000 facilitates the transformation of an existing offline data analysis method into a functional online system.
*For signal processing components, it provides a convenient, straightforward programming interface.
*A signal processing component may be implemented as a set of Matlab scripts.

Still, it is easy to underestimate the effort required to transform an existing offline implementation of a signal processing algorithm into a functional online implementation. While BCI2000 tries to make the transformation as simple as possible, it cannot remove the effort required to deal with chunks of data, which implies the need of
*buffering -- rather than having immediate access to a continuous data set, it may be necessary to maintain an additional data buffer;
*with the Matlab interface, maintaining a consistent state between subsequent calls to the processing script.

==An Example Algorithm==
In this scenario, we use a simple, straightforward BCI signal processing algorithm, to show the steps necessary to modify the algorithm such
that it may be used to build an online system in BCI2000.

In the example, signal processing consists of IIR bandpass filtering, followed with RMS envelope computation, and linear classification.
A typical Matlab implementation of that algorithm might consist of about ten lines:

<pre>
function class_result = classify( data, band, classifier );

% Use as
% class_result = classify( data, band, classifier )
%
% This function takes raw data as a [channels x samples] vector in the 'data'
% input variable.
%
% Then, it computes bandpower features for the band specified in the 'band'
% input variable, which is a number between 0 and 0.5, specifying
% center frequency in terms of the sampling rate.
%
% As a last step, it applies the 'classifier' matrix to the features in order
% to obtain a single classification result for each sample. The 'classifier'
% vector specifies a classification weight for each processed channel.
%
% The result is a single classification result for each sample.
%
% This requires the Matlab signal processing toolbox.

% Design bandpass filters and apply them to the data matrix.
% The filtered data will contain bandpass filtered data as channels.
[n,Wn]=buttord(band*[0.9 1.1]/2,band*[0.7 1.4]/2,1,60);
[b,a]=butter(n,Wn);
processed_data = filter(b,a,data);

% For demodulation, rectify and apply a low pass.
[b,a]=butter(1,band/4);
processed_data = filter(b,a,abs(processed_data));

% Finally, apply the linear classifier.
class_result = processed_data * classifier;
</pre>

Note that, to be viable in an online environment, an algorithm must operate
on its signal in a causal way, i.e. it may not use future samples in order to
process present samples. (Still, a certain amount of non-causality may be possible
by windowed operation on buffered data, although this will increase the effective
delay between input and output data.)

Also note that the <tt>classify</tt> function omits spatial filtering -- in Matlab,
this may be done easily by pre-multiplying the data with a spatial filter matrix
if desired.

==Translating the existing MATLAB code into BCI2000 functions==

For use with BCI2000, the signal processing code needs to be cast into a form
that suits the BCI2000 filter interface.
In this event-based model, portions of code are called at certain times to configure
a filter component's internal state, and to act upon the signal in chunks on its way through
the BCI2000 chain of filters.

===Process===

The most central event in the filter interface is the ''Process'' event.
The ''Process'' event handler receives a signal input, will process this input
according to the filter component's role in the signal processing chain, and
return the result of processing in a signal output variable.
It is important to understand that the ''Process'' handler is called separately
for each chunk of data, and thus does not see the signal in its entirety.
Also, the size of data blocks (chunks) is freely configurable by the user, although
restricted to limits stemming from recording hardware properties.
This implies that ''Process'' scripts may not depend on a certain
data block size, and will sometimes need to maintain their own data buffers when
the algorithm in question operates on windows of data rather than continuously.
In the current example, this is not the case, so we need not maintain an internal
data buffer.
Still, we need to maintain an internal state between calls to the ''Process''
handler in order to preserve the state of IIR filter delays.
This will allow continuous operation on the signal with the same processing result
as in the offline version of the algorithm.

The algorithm's online version in the <tt>bci_Process</tt> script will thus be:
<pre>
function out_signal = bci_Process( in_signal )

% Process a single block of data by applying a filter to in_signal,
% and return the result in out_signal.
% Signal dimensions are ( channels x samples ).

% We use global variables to store classifier,
% filter coefficients and filter state.
global a b z lpa lpb lpz classifier;

[out_signal, z] = filter( b, a, in_signal, z );
out_signal = abs( out_signal );
[out_signal, lpz] = filter( lpb, lpa, out_signal, lpz );
out_signal = out_signal * classifier;
</pre>

===Initialize===

Determination of filter coefficients is part of per-run initialization, and occurs in the
''Initialize'' event handler:

<pre>
function bci_Initialize( in_signal_dims, out_signal_dims )

% Perform configuration for the bci_Process script.

% Parameters and states are global variables.
global bci_Parameters bci_States;

% We use global variables to store classifier vector,
% filter coefficients and filter state.
global a b z lpa lpb lpz classifier;

% Configure the Bandpass filter
band = str2double( bci_Parameters.Passband ) / str2double( bci_Parameters.SamplingRate );
[n,Wn]=buttord(band*[0.9 1.1]/2,band*[0.7 1.4]/2,1,60);
[b,a]=butter(n,Wn);
z=zeros(max(length(a),length(b))-1,in_signal_dims(1));

% Configure the Lowpass filter
[lpb,lpa]=butter(1,band/4);
lpz=zeros(max(length(lpa),length(lpb))-1,in_signal_dims(1));

% Configure the Classifier vector
classifier = str2double( bci_Parameters.ClassVector );
</pre>

===StartRun===

In addition, we need to reset filter state at the beginning of each run, using the ''StartRun''
event handler:

<pre>
function bci_StartRun

% Reset filter state at the beginning of a run.

global z lpz;
z = zeros(size(z));
lpz = zeros(size(lpz));
</pre>

===Constructor===
To complete the Matlab filter code, we need to declare the ''Band'' and ''Classifier''
parameters in a ''Constructor'' event handler:

<pre>
function [ parameters, states ] = bci_Construct

% Request BCI2000 parameters by returning parameter definition
% lines as demonstrated below.

parameters = { ...
[ 'BPClassifier float Passband= 10 10 0 % % // Bandpass frequency in Hz' ] ...
[ 'BPClassifier matrix ClassVector= 1 1 1 0 % % // Linear classifier vector' ] ...
};
</pre>

===Preflight===

Finally, we need to check parameters for consistency in a ''Preflight''
script, and declare the size of our filter's output signal:

<pre>
function [ out_signal_dim ] = bci_Preflight( in_signal_dim )

% Check whether parameters are accessible, and whether
% parameters have values that allow for safe processing by the
% bci_Process function.
% Also, report output signal dimensions in the 'out_signal_dim' argument.

% Parameters and states are global variables.
global bci_Parameters bci_States;

band = str2double( bci_Parameters.Passband ) / str2double( bci_Parameters.SamplingRate );
if( band <= 0 )
error( 'The passband parameter must be greater zero' );
elseif( band > 0.5 / 1.4 )
error( 'The Passband parameter conflicts with the sampling rate' );
end

out_signal_dim = [ 1, size( in_signal_dim, 2 ) ];
if( in_signal_dim( 1 ) ~= size( bci_Parameters.ClassVector, 2 ) )
error( 'ClassVector length must match the input signal''s number of channels' );
end
</pre>

==See also==

[[Programming Reference:MatlabFilter]],
[[User Reference:MatlabFilter]],
[[Contributions:FieldTripBuffer]]

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

Contributions:SignalProcessing

2008-08-11T15:28:24Z

Roostenveld: added fieldtripbuffer

The following signal processing filters are available in the Contributions section of BCI2000:

*[[Contributions:FIRFilter]]: A finite impulse response filter.
*[[Contributions:PeakDetector]]: A peak detector filter.
*[[Contributions:SigfriedSigProc]]: Signal processing module SIGFRIED.
*[[Contributions:Statistics]]: Original statistics filtering from version 1.
*[[Contributions:SWSignalProcessing]]: Signal processing module for slow wave (SCP) feedback.
*[[Contributions:BCPy2000]]: Signal processing and application module for calling custom Python functions.
*[[Contributions:FieldTripBuffer]]: Realtime analysis of EEG data in MATLAB using the FieldTrip toolbox.

==See also==
[[User Reference:Filters]]

[[Category:Signal Processing]][[Category:Contents]]

MARIO:Contents

2008-08-11T15:25:25Z

Roostenveld: added category matlab

MARIO is a collection of Matlab programs for off-line BCI2000 data analysis and prototyping of processing algorithms.
The following information is available about MARIO:
*[[MARIO Technical Documentation]]
:A conceptual description of the MARIO software and its design.
*[[Mu Rhythm Off-line Analysis Tutorial]]
:Introduction to the use of the MARIO tool to analyze recorded sessions of mu rhythm modulation
*[[P300 Off-line Analysis Tutorial]]
:Introduction to the use of the MARIO tool to analyze recorded sessions of mu P300 letter spelling

[[Category:Contents]]
[[Category:Matlab]]
[[Category:Data Analysis Tools]]

User talk:Roostenveld

2008-07-14T13:30:53Z

Roostenveld:

TODO:
* Programming_Tutorial:Implementing_a_Matlab-based_Filter
* Contributions:FieldTripBuffer

Programming Tutorial:Implementing a simple Matlab-based Filter

2008-07-14T13:23:37Z

Roostenveld: /* See also */

==Online Algorithm Verification==
In the field of BCI signal processing research, novel methods are often proposed and tested on the basis of existing data.
While this is adequate as a research strategy, it is important to keep in mind that timely feedback of brain signal classification is an essential element of a BCI.
From this, it is clear that, ideally, a proposed BCI signal processing or classification method should be verified with respect to its viability and usefulness in a true online setting, providing feedback to the participant causally and in real-time.

BCI2000 facilitates the transformation of an existing offline data analysis method into a functional online system.
*For signal processing components, it provides a convenient, straightforward programming interface.
*A signal processing component may be implemented as a set of Matlab scripts.

Still, it is easy to underestimate the effort required to transform an existing offline implementation of a signal processing algorithm into a functional online implementation. While BCI2000 tries to make the transformation as simple as possible, it cannot remove the effort required to deal with chunks of data, which implies the need of
*buffering -- rather than having immediate access to a continuous data set, it may be necessary to maintain an additional data buffer;
*with the Matlab interface, maintaining a consistent state between subsequent calls to the processing script.

==An Example Algorithm==
In this scenario, we use a simple, straightforward BCI signal processing algorithm, to show the steps necessary to modify the algorithm such
that it may be used to build an online system in BCI2000.

In the example, signal processing consists of IIR bandpass filtering, followed with RMS envelope computation, and linear classification.
A typical Matlab implementation of that algorithm might consist of about ten lines:

<pre>
function class_result = classify( data, band, classifier );

% Use as
% class_result = classify( data, band, classifier )
%
% This function takes raw data as a [channels x samples] vector in the 'data'
% input variable.
%
% Then, it computes bandpower features for the band specified in the 'band'
% input variable, which is a number between 0 and 0.5, specifying
% center frequency in terms of the sampling rate.
%
% As a last step, it applies the 'classifier' matrix to the features in order
% to obtain a single classification result for each sample. The 'classifier'
% vector specifies a classification weight for each processed channel.
%
% The result is a single classification result for each sample.
%
% This requires the Matlab signal processing toolbox.

% Design bandpass filters and apply them to the data matrix.
% The filtered data will contain bandpass filtered data as channels.
[n,Wn]=buttord(band*[0.9 1.1]/2,band*[0.7 1.4]/2,1,60);
[b,a]=butter(n,Wn);
processed_data = filter(b,a,data);

% For demodulation, rectify and apply a low pass.
[b,a]=butter(1,band/4);
processed_data = filter(b,a,abs(processed_data));

% Finally, apply the linear classifier.
class_result = processed_data * classifier;
</pre>

Note that, to be viable in an online environment, an algorithm must operate
on its signal in a causal way, i.e. it may not use future samples in order to
process present samples. (Still, a certain amount of non-causality may be possible
by windowed operation on buffered data, although this will increase the effective
delay between input and output data.)

Also note that the <tt>classify</tt> function omits spatial filtering -- in Matlab,
this may be done easily by pre-multiplying the data with a spatial filter matrix
if desired.

==Transformation into BCI2000 Matlab Scripts==

For use with BCI2000, the signal processing code needs to be cast into a form
that suits the BCI2000 filter interface.
In this event-based model, portions of code are called at certain times to configure
a filter component's internal state, and to act upon the signal in chunks on its way through
the BCI2000 chain of filters.

===Process===

The most central event in the filter interface is the ''Process'' event.
The ''Process'' event handler receives a signal input, will process this input
according to the filter component's role in the signal processing chain, and
return the result of processing in a signal output variable.
It is important to understand that the ''Process'' handler is called separately
for each chunk of data, and thus does not see the signal in its entirety.
Also, the size of data blocks (chunks) is freely configurable by the user, although
restricted to limits stemming from recording hardware properties.
This implies that ''Process'' scripts may not depend on a certain
data block size, and will sometimes need to maintain their own data buffers when
the algorithm in question operates on windows of data rather than continuously.
In the current example, this is not the case, so we need not maintain an internal
data buffer.
Still, we need to maintain an internal state between calls to the ''Process''
handler in order to preserve the state of IIR filter delays.
This will allow continuous operation on the signal with the same processing result
as in the offline version of the algorithm.

The algorithm's online version in the <tt>bci_Process</tt> script will thus be:
<pre>
function out_signal = bci_Process( in_signal )

% Process a single block of data by applying a filter to in_signal,
% and return the result in out_signal.
% Signal dimensions are ( channels x samples ).

% We use global variables to store classifier,
% filter coefficients and filter state.
global a b z lpa lpb lpz classifier;

[out_signal, z] = filter( b, a, in_signal, z );
out_signal = abs( out_signal );
[out_signal, lpz] = filter( lpb, lpa, out_signal, lpz );
out_signal = out_signal * classifier;
</pre>

===Initialize===

Determination of filter coefficients is part of per-run initialization, and occurs in the
''Initialize'' event handler:

<pre>
function bci_Initialize( in_signal_dims, out_signal_dims )

% Perform configuration for the bci_Process script.

% Parameters and states are global variables.
global bci_Parameters bci_States;

% We use global variables to store classifier vector,
% filter coefficients and filter state.
global a b z lpa lpb lpz classifier;

% Configure the Bandpass filter
band = str2double( bci_Parameters.Passband ) / str2double( bci_Parameters.SamplingRate );
[n,Wn]=buttord(band*[0.9 1.1]/2,band*[0.7 1.4]/2,1,60);
[b,a]=butter(n,Wn);
z=zeros(max(length(a),length(b))-1,in_signal_dims(1));

% Configure the Lowpass filter
[lpb,lpa]=butter(1,band/4);
lpz=zeros(max(length(lpa),length(lpb))-1,in_signal_dims(1));

% Configure the Classifier vector
classifier = str2double( bci_Parameters.ClassVector );
</pre>

===StartRun===

Finally, we need to reset filter state at the beginning of each run, using the ''StartRun''
event handler:

<pre>
function bci_StartRun

% Reset filter state at the beginning of a run.

global z lpz;
z = zeros(size(z));
lpz = zeros(size(lpz));
</pre>

===Constructor===
To complete the Matlab filter code, we need to declare the ''Band'' and ''Classifier''
parameters in a ''Constructor'' event handler:

<pre>
function [ parameters, states ] = bci_Construct

% Request BCI2000 parameters by returning parameter definition
% lines as demonstrated below.

parameters = { ...
[ 'BPClassifier float Passband= 10 10 0 % % // Bandpass frequency in Hz' ] ...
[ 'BPClassifier matrix ClassVector= 1 1 1 0 % % // Linear classifier vector' ] ...
};
</pre>

===Preflight===

Finally, we need to check parameters for consistency in a ''Preflight''
script, and declare the size of our filter's output signal:

<pre>
function [ out_signal_dim ] = bci_Preflight( in_signal_dim )

% Check whether parameters are accessible, and whether
% parameters have values that allow for safe processing by the
% bci_Process function.
% Also, report output signal dimensions in the 'out_signal_dim' argument.

% Parameters and states are global variables.
global bci_Parameters bci_States;

band = str2double( bci_Parameters.Passband ) / str2double( bci_Parameters.SamplingRate );
if( band <= 0 )
error( 'The passband parameter must be greater zero' );
elseif( band > 0.5 / 1.4 )
error( 'The Passband parameter conflicts with the sampling rate' );
end

out_signal_dim = [ 1, size( in_signal_dim, 2 ) ];
if( in_signal_dim( 1 ) ~= size( bci_Parameters.ClassVector, 2 ) )
error( 'ClassVector length must match the input signal''s number of channels' );
end
</pre>

==See also==

[[Programming Reference:MatlabFilter]],
[[User Reference:MatlabFilter]],
[[Contributions:FieldTripBuffer]]

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

Programming Tutorial:Implementing a simple Matlab-based Filter

2008-07-14T13:23:07Z

Roostenveld: /* See also */ added link to fieldtripfilter

==Online Algorithm Verification==
In the field of BCI signal processing research, novel methods are often proposed and tested on the basis of existing data.
While this is adequate as a research strategy, it is important to keep in mind that timely feedback of brain signal classification is an essential element of a BCI.
From this, it is clear that, ideally, a proposed BCI signal processing or classification method should be verified with respect to its viability and usefulness in a true online setting, providing feedback to the participant causally and in real-time.

BCI2000 facilitates the transformation of an existing offline data analysis method into a functional online system.
*For signal processing components, it provides a convenient, straightforward programming interface.
*A signal processing component may be implemented as a set of Matlab scripts.

Still, it is easy to underestimate the effort required to transform an existing offline implementation of a signal processing algorithm into a functional online implementation. While BCI2000 tries to make the transformation as simple as possible, it cannot remove the effort required to deal with chunks of data, which implies the need of
*buffering -- rather than having immediate access to a continuous data set, it may be necessary to maintain an additional data buffer;
*with the Matlab interface, maintaining a consistent state between subsequent calls to the processing script.

==An Example Algorithm==
In this scenario, we use a simple, straightforward BCI signal processing algorithm, to show the steps necessary to modify the algorithm such
that it may be used to build an online system in BCI2000.

In the example, signal processing consists of IIR bandpass filtering, followed with RMS envelope computation, and linear classification.
A typical Matlab implementation of that algorithm might consist of about ten lines:

<pre>
function class_result = classify( data, band, classifier );

% Use as
% class_result = classify( data, band, classifier )
%
% This function takes raw data as a [channels x samples] vector in the 'data'
% input variable.
%
% Then, it computes bandpower features for the band specified in the 'band'
% input variable, which is a number between 0 and 0.5, specifying
% center frequency in terms of the sampling rate.
%
% As a last step, it applies the 'classifier' matrix to the features in order
% to obtain a single classification result for each sample. The 'classifier'
% vector specifies a classification weight for each processed channel.
%
% The result is a single classification result for each sample.
%
% This requires the Matlab signal processing toolbox.

% Design bandpass filters and apply them to the data matrix.
% The filtered data will contain bandpass filtered data as channels.
[n,Wn]=buttord(band*[0.9 1.1]/2,band*[0.7 1.4]/2,1,60);
[b,a]=butter(n,Wn);
processed_data = filter(b,a,data);

% For demodulation, rectify and apply a low pass.
[b,a]=butter(1,band/4);
processed_data = filter(b,a,abs(processed_data));

% Finally, apply the linear classifier.
class_result = processed_data * classifier;
</pre>

Note that, to be viable in an online environment, an algorithm must operate
on its signal in a causal way, i.e. it may not use future samples in order to
process present samples. (Still, a certain amount of non-causality may be possible
by windowed operation on buffered data, although this will increase the effective
delay between input and output data.)

Also note that the <tt>classify</tt> function omits spatial filtering -- in Matlab,
this may be done easily by pre-multiplying the data with a spatial filter matrix
if desired.

==Transformation into BCI2000 Matlab Scripts==

For use with BCI2000, the signal processing code needs to be cast into a form
that suits the BCI2000 filter interface.
In this event-based model, portions of code are called at certain times to configure
a filter component's internal state, and to act upon the signal in chunks on its way through
the BCI2000 chain of filters.

===Process===

The most central event in the filter interface is the ''Process'' event.
The ''Process'' event handler receives a signal input, will process this input
according to the filter component's role in the signal processing chain, and
return the result of processing in a signal output variable.
It is important to understand that the ''Process'' handler is called separately
for each chunk of data, and thus does not see the signal in its entirety.
Also, the size of data blocks (chunks) is freely configurable by the user, although
restricted to limits stemming from recording hardware properties.
This implies that ''Process'' scripts may not depend on a certain
data block size, and will sometimes need to maintain their own data buffers when
the algorithm in question operates on windows of data rather than continuously.
In the current example, this is not the case, so we need not maintain an internal
data buffer.
Still, we need to maintain an internal state between calls to the ''Process''
handler in order to preserve the state of IIR filter delays.
This will allow continuous operation on the signal with the same processing result
as in the offline version of the algorithm.

The algorithm's online version in the <tt>bci_Process</tt> script will thus be:
<pre>
function out_signal = bci_Process( in_signal )

% Process a single block of data by applying a filter to in_signal,
% and return the result in out_signal.
% Signal dimensions are ( channels x samples ).

% We use global variables to store classifier,
% filter coefficients and filter state.
global a b z lpa lpb lpz classifier;

[out_signal, z] = filter( b, a, in_signal, z );
out_signal = abs( out_signal );
[out_signal, lpz] = filter( lpb, lpa, out_signal, lpz );
out_signal = out_signal * classifier;
</pre>

===Initialize===

Determination of filter coefficients is part of per-run initialization, and occurs in the
''Initialize'' event handler:

<pre>
function bci_Initialize( in_signal_dims, out_signal_dims )

% Perform configuration for the bci_Process script.

% Parameters and states are global variables.
global bci_Parameters bci_States;

% We use global variables to store classifier vector,
% filter coefficients and filter state.
global a b z lpa lpb lpz classifier;

% Configure the Bandpass filter
band = str2double( bci_Parameters.Passband ) / str2double( bci_Parameters.SamplingRate );
[n,Wn]=buttord(band*[0.9 1.1]/2,band*[0.7 1.4]/2,1,60);
[b,a]=butter(n,Wn);
z=zeros(max(length(a),length(b))-1,in_signal_dims(1));

% Configure the Lowpass filter
[lpb,lpa]=butter(1,band/4);
lpz=zeros(max(length(lpa),length(lpb))-1,in_signal_dims(1));

% Configure the Classifier vector
classifier = str2double( bci_Parameters.ClassVector );
</pre>

===StartRun===

Finally, we need to reset filter state at the beginning of each run, using the ''StartRun''
event handler:

<pre>
function bci_StartRun

% Reset filter state at the beginning of a run.

global z lpz;
z = zeros(size(z));
lpz = zeros(size(lpz));
</pre>

===Constructor===
To complete the Matlab filter code, we need to declare the ''Band'' and ''Classifier''
parameters in a ''Constructor'' event handler:

<pre>
function [ parameters, states ] = bci_Construct

% Request BCI2000 parameters by returning parameter definition
% lines as demonstrated below.

parameters = { ...
[ 'BPClassifier float Passband= 10 10 0 % % // Bandpass frequency in Hz' ] ...
[ 'BPClassifier matrix ClassVector= 1 1 1 0 % % // Linear classifier vector' ] ...
};
</pre>

===Preflight===

Finally, we need to check parameters for consistency in a ''Preflight''
script, and declare the size of our filter's output signal:

<pre>
function [ out_signal_dim ] = bci_Preflight( in_signal_dim )

% Check whether parameters are accessible, and whether
% parameters have values that allow for safe processing by the
% bci_Process function.
% Also, report output signal dimensions in the 'out_signal_dim' argument.

% Parameters and states are global variables.
global bci_Parameters bci_States;

band = str2double( bci_Parameters.Passband ) / str2double( bci_Parameters.SamplingRate );
if( band <= 0 )
error( 'The passband parameter must be greater zero' );
elseif( band > 0.5 / 1.4 )
error( 'The Passband parameter conflicts with the sampling rate' );
end

out_signal_dim = [ 1, size( in_signal_dim, 2 ) ];
if( in_signal_dim( 1 ) ~= size( bci_Parameters.ClassVector, 2 ) )
error( 'ClassVector length must match the input signal''s number of channels' );
end
</pre>

==See also==

[[Programming Reference:MatlabFilter]],
[[User Reference:MatlabFilter]],
[[Contributions:FieldTripFilter]]

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

Talk:Programming Tutorial:Implementing a simple Matlab-based Filter

2008-07-14T13:21:52Z

Roostenveld:

Robert - 14 July 2008:

I suggest to remove the section "Online Algorithm Verification" and to have a discussion on Matlab for offline and online processing somewhere else.

Talk:Programming Tutorial:Implementing a simple Matlab-based Filter

2008-07-14T13:20:58Z

Roostenveld:

I suggest to remove the section "Online Algorithm Verification" and to have a discussion on Matlab for offline and online processing somewhere else.

Programming Reference:MatlabFilter

2008-07-14T13:19:08Z

Roostenveld: /* See also */

==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 [[Programming Reference:GenericFilter Class|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 [[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.

{| style="color:black;background-color:#ffffcc;" cellpadding="5" cellspacing="0" border="2"
!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
|}

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

==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 parameters and states 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:
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 <tt>bci_Preflight</tt> and <tt>bci_Initialize</tt> are integer vectors of size 1x2 with <tt>[n_channels n_elements]</tt>.

==Error Reporting==

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

==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. 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==
===Debugging Matlab functions===
#Start BCI2000. The ''MatlabFilter'' will open a Matlab instance in its own window in minimized state.
#Switch to the minimized Matlab instance.
#Type, e.g., <code>edit bci_Process.m</code> to open a Matlab editor window connected to the Matlab interactive window.
#In the editor window, set breakpoints as you would normally.
#Execution will be paused, and you may examine variables moving the mouse over them.

===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.

===There is no Matlab engine started up===
Execute <code>matlab /regserver</code> from the command line when logged in with administrative privileges.
===Changes to M-files appear to have no effect===
Switch to the Matlab engine's command window, and enter <code>clear;</code> or <code>clear scriptname;</code> each time you change a Matlab function.

===You get linker errors when rebuilding ''MatlabSignalProcessing''===
If you get linker errors after editing <tt>PipeDefinition.cpp</tt>, make sure that all filters' cpp files are part of the ''MatlabSignalProcessing'' project.
===You get a message window with an "Entry Point Not Found" message===
This error is likely to indicate confusion of multiple installations of Matlab on your machine.
Check your Windows ''%PATH%'' environment variable, e.g. by opening a command console window and typing
echo %PATH%
When it contains references to more than a single Matlab installation, remove all apart from the reference to the installation you are going to use with BCI2000. Also, make sure to execute
matlab /regserver
for the Matlab installation you intend to use.

==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]]

* 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:Filters]]
[[Category:Signal Processing]]
[[Category:Matlab]]
[[Category:Development]]
[[Category:External Interfaces]]

User Reference:Filters

2008-07-14T13:18:06Z

Roostenveld: /* Signal Processing Module */ moved matlabfilter ref

''Filters'' are the most important building blocks of a BCI2000 system.
This document describes the ''filter'' concept for users who will configure BCI2000 for their own experiments, and provides links to the documentation pages of individual filters, describing each filter's purpose and parameterization.

==Data Processing as a Pipe==
Each of the three BCI2000 core modules contains a ''chain of filters'', i.e. a sequence of filters forming a pipe where, basically, brain signal data enter on one side, and a processed version of these data leaves on the other side.

The notion of a ''pipe'' implies that, for each portion of data entering on the input side, there will be exactly one portion of output data on the output side.
This is analogous to a water pipe: unlike a water stream (a brook, or a river), it is impossible to insert or remove water from inside the pipe without breaking it.
Similarly, albeit signal portions may change their shape on their way through the pipe (filter chain), it is impossible to insert or remove any of them.
Thus, each data portion acquired by the data acquisition module will run through the entire BCI2000 system, being processed by a sequence of filters.

==Configuration Overview==
In principle, these filters may be placed in any order by the writer (programmer) of a BCI2000 module, and it is [[Programming Reference:Filter Chain|technically easy]] to change the number, and order, of filters.
However, not all combinations or orderings of filters make sense.

The table shows modules and filters for BCI2000 configurations included in the core distribution:

{| border="1" style="text-align:center"
!   || colspan="3" | Data Acquisition
! colspan="5" | Signal Processing
! colspan="3" | Application
|-
! SMR Feedback

| rowspan="3" |
{| border="0" style="text-align:center"
| colspan="2" | [[User Reference:DataIOFilter|DataIOFilter]]
|-
| ADC || FileWriter
|}
| rowspan="3" | [[User Reference:AlignmentFilter|AlignmentFilter]]
| rowspan="3" | [[User Reference:TransmissionFilter|TransmissionFilter]]
| rowspan="3" | [[User Reference:SpatialFilter|SpatialFilter]]
| [[User Reference:ARFilter|ARFilter]] or [[User Reference:FFTFilter|FFTFilter]]
| rowspan="3" | [[User Reference:LinearClassifier|LinearClassifier]]
| rowspan="3" | [[User Reference:LPFilter|LPFilter]]
| rowspan="3" | [[User Reference:Normalizer|Normalizer]]
| rowspan="3" | [[User Reference:ConnectorInput|ConnectorInput]]
| [[User Reference:CursorTask|CursorTask]]
| rowspan="3" | [[User Reference:ConnectorOutput|ConnectorOutput]]
|-
! P3 Speller
| rowspan="2" | [[User Reference:P3TemporalFilter|P3TemporalFilter]]
| [[User Reference:P3SpellerTask|P3SpellerTask]]
|-
! Stimulus Presentation
| [[User Reference:StimulusPresentationTask|StimulusPresentationTask]]
|}

==Data Acquisition Module==
In the data acquisition (source) module, the DataIOFilter manages data acquisition and storage in a general manner.
Actual acquisition of data is provided by ADC filters,
actual writing into data files is done by FileWriter filters representing various [[User Reference:Data File Formats|Data Formats]].
In addition to managing the operation of ADC and FileWriter filters, the DataIOFilter handles signal calibration into physical units (typically, <math>\mu V</math>), and visualization of the source signal.

Filter documentation for source modules is available for
===General Filters===
*[[User Reference:DataIOFilter]]: Storage and acquisition management, calibration.
*[[User Reference:SourceFilter]]: HP/LP/notch filtering prior to storage.
*[[User Reference:AlignmentFilter]]: Temporal alignment.
*[[User Reference:TransmissionFilter]]: Subset selection for online processing.

===Data Acquisition===
*[[User Reference:SignalGeneratorADC]]: A signal generator for testing purposes.
*[[User Reference:gUSBampADC]]: Interface to the g.tec gUSBamp amplifier.
*[[User Reference:gMOBIlabADC]]: Interface to the g.tec gMOBIlab amplifier.
*[[Contributions:ADCs]]: Contributed code interfacing to other hardware.

===Data Storage===
*[[User Reference:BCI2000FileWriter]]: BCI2000 data format.
*[[User Reference:EDFFileWriter]]: European Data Format.
*[[User Reference:GDFFileWriter]]: General Data Format for Biosignals.
*[[User Reference:NullFileWriter]]: Suppressing file output.
*[[Contributions:FileWriters]]: Contributed code supporting other output formats.

==Signal Processing Module==
In the signal processing module, brain signals are filtered spatially and temporally, resulting in a set of extracted features. In the Classifier, these features are used to differentiate amongst a small number of mental states (classes). Finally, the Normalizer adjusts the Classifier's output to zero mean and unit variance.

Filter documentation for signal processing filters is available for
===Feature Extraction===
*[[User Reference:SpatialFilter]]: Instantaneous (i.e., sample-wise) linear transformation of brain signal input.
*[[User Reference:ARFilter]]: Auto-regression based spectral amplitude estimator.
*[[User Reference:FFTFilter]]: Short-term FFT for display or feature extraction purposes.
*[[User Reference:P3TemporalFilter]]: Segmenting and averaging for ERP feature extraction.

===Translation Algorithm===
*[[User Reference:LinearClassifier]]: Linear projection of signal features onto low-dimensional classification space (control signal).
*[[User Reference:Normalizer]]: Adjustment of control signal to zero mean/unit variance.

===Miscellaneous Filters===
*[[User Reference:LPFilter]]: Temporal low-pass filtering at any stage of processing.
*[[User Reference:ConditionalIntegrator]]: An offline replacement for cursor movement in an online task.
*[[User Reference:StateTransform]]: An offline replacement for hitting targets in an online task.
*[[User Reference:ExpressionFilter]]: Computes filter output using arithmetic expressions.
*[[User Reference:MatlabFilter]]: Using MATLAB to implement online processing in the pipeline.

==Application Module==
Basically, the application module contains a single filter that handles trial sequencing and brain signal feedback.
In the standard configuration, this ''task'' filter is surrounded by ConnectorInput and ConnectorOutput filters. These connector filters allow for exchanging data with external software over a UDP based socket protocol.

Filter documentation of application module filters is available for
===Stimulus Presentation and Feedback===
*[[User Reference:CursorTask]]: Feedback of brain signals in form of up to 3-dimensional cursor movement.
*[[User Reference:StimulusPresentationTask]]: Sequential presentation of stimuli.
*[[User Reference:P3SpellerTask]]: A P300 speller matrix application.
===External Interfaces===
*[[User Reference:ConnectorOutput]]: Reports state information to a UDP socket.
*[[User Reference:ConnectorInput]]: Sets state information according to input from a UDP socket.
*[[User Reference:KeystrokeFilter]]: Translates state information into simulated keyboard input.
*[[User Reference:JoystickFilter]]: Records joystick movements into a state.
*[[User Reference:KeyLogFilter]]: Records keyboard and mouse key presses into a state.
*[[User Reference:MouseFilter]]: Records mouse pointer coordinates into a state.

===Internationalization===
*[[User Reference:Localization]]: Translating subject-visible messages.

==See also==
[[Technical Reference:Core Modules]]

[[Category:Contents]][[Category:Filters]]

Programming Reference:MatlabFilter

2008-07-14T13:16:17Z

Roostenveld: /* Overview */

==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 [[Programming Reference:GenericFilter Class|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 [[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.

{| style="color:black;background-color:#ffffcc;" cellpadding="5" cellspacing="0" border="2"
!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
|}

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

==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 parameters and states 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:
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 <tt>bci_Preflight</tt> and <tt>bci_Initialize</tt> are integer vectors of size 1x2 with <tt>[n_channels n_elements]</tt>.

==Error Reporting==

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

==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. 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==
===Debugging Matlab functions===
#Start BCI2000. The ''MatlabFilter'' will open a Matlab instance in its own window in minimized state.
#Switch to the minimized Matlab instance.
#Type, e.g., <code>edit bci_Process.m</code> to open a Matlab editor window connected to the Matlab interactive window.
#In the editor window, set breakpoints as you would normally.
#Execution will be paused, and you may examine variables moving the mouse over them.

===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.

===There is no Matlab engine started up===
Execute <code>matlab /regserver</code> from the command line when logged in with administrative privileges.
===Changes to M-files appear to have no effect===
Switch to the Matlab engine's command window, and enter <code>clear;</code> or <code>clear scriptname;</code> each time you change a Matlab function.

===You get linker errors when rebuilding ''MatlabSignalProcessing''===
If you get linker errors after editing <tt>PipeDefinition.cpp</tt>, make sure that all filters' cpp files are part of the ''MatlabSignalProcessing'' project.
===You get a message window with an "Entry Point Not Found" message===
This error is likely to indicate confusion of multiple installations of Matlab on your machine.
Check your Windows ''%PATH%'' environment variable, e.g. by opening a command console window and typing
echo %PATH%
When it contains references to more than a single Matlab installation, remove all apart from the reference to the installation you are going to use with BCI2000. Also, make sure to execute
matlab /regserver
for the Matlab installation you intend to use.

==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]]

Tutorials:
* [[Programming_Tutorial:Implementing_a_Matlab-based_Filter|IIR bandpass filtering, followed with RMS envelope computation, and linear classification]]
* [[Programming_Tutorial:Implementing_another_Matlab-based_Filter|adaptive spatial filtering using a beamformer, power computation and normalization]]

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

Programming Reference:MatlabFilter

2008-07-14T13:14:44Z

Roostenveld: /* Overview */ typo

==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 [[Programming Reference:GenericFilter Class|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 [[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.

{| style="color:black;background-color:#ffffcc;" cellpadding="5" cellspacing="0" border="2"
!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
|}

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 <tt>bci_Process</tt>, which is executed every time a new block of data is passed through the pipeline. Furthermore <tt>bci_Construct</tt> is executed at the beginning and determines the parameters and states, <tt>bci_Initialize</tt> determines whether all requirements are met, and <tt>bci_StartRun</tt> 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 <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 parameters and states 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:
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 <tt>bci_Preflight</tt> and <tt>bci_Initialize</tt> are integer vectors of size 1x2 with <tt>[n_channels n_elements]</tt>.

==Error Reporting==

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

==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. 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==
===Debugging Matlab functions===
#Start BCI2000. The ''MatlabFilter'' will open a Matlab instance in its own window in minimized state.
#Switch to the minimized Matlab instance.
#Type, e.g., <code>edit bci_Process.m</code> to open a Matlab editor window connected to the Matlab interactive window.
#In the editor window, set breakpoints as you would normally.
#Execution will be paused, and you may examine variables moving the mouse over them.

===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.

===There is no Matlab engine started up===
Execute <code>matlab /regserver</code> from the command line when logged in with administrative privileges.
===Changes to M-files appear to have no effect===
Switch to the Matlab engine's command window, and enter <code>clear;</code> or <code>clear scriptname;</code> each time you change a Matlab function.

===You get linker errors when rebuilding ''MatlabSignalProcessing''===
If you get linker errors after editing <tt>PipeDefinition.cpp</tt>, make sure that all filters' cpp files are part of the ''MatlabSignalProcessing'' project.
===You get a message window with an "Entry Point Not Found" message===
This error is likely to indicate confusion of multiple installations of Matlab on your machine.
Check your Windows ''%PATH%'' environment variable, e.g. by opening a command console window and typing
echo %PATH%
When it contains references to more than a single Matlab installation, remove all apart from the reference to the installation you are going to use with BCI2000. Also, make sure to execute
matlab /regserver
for the Matlab installation you intend to use.

==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]]

Tutorials:
* [[Programming_Tutorial:Implementing_a_Matlab-based_Filter|IIR bandpass filtering, followed with RMS envelope computation, and linear classification]]
* [[Programming_Tutorial:Implementing_another_Matlab-based_Filter|adaptive spatial filtering using a beamformer, power computation and normalization]]

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

Programming Reference:GenericFilter Class

2008-07-14T13:14:19Z

Roostenveld: /* Initialize */ changed heading from level 2 to 3

==The <tt>GenericFilter</tt> class==
<tt>GenericFilter</tt> is a base class that provides a programming
interface for all user code inside the core modules of this BCI2000
implementation.
Programming your own data acquisition module, your own filter inside
Signal Processing, or your own application, implies deriving your
own
class from <tt>GenericFilter</tt>.
<tt>GenericFilter</tt>'s member functions represent the various
initialization and processing events that occur during system startup
and operation (see [[Technical Reference:States of Operation]]).
Your own filter code ''must'' implement its own
versions of some of these member functions:

==Required Members==
===Constructor===
The ''Constructor'', besides its general purpose of initializing member data, declares the parameters and states your filter wants to introduce into the system (the <tt>BEGIN_...</tt> and <tt>END_...</tt> macros handle the actual function calls):
<pre>
MyFilter::MyFilter()
: mMyParam( 1 ),
mMyOtherParam( 0.1 ),
mCount( 0 )
{
BEGIN_PARAMETER_DEFINITIONS
"MySection int MyParam= 1 "
"0 0 3 // This is range-checked between 0 and 3",
"MySection float MyOtherParam= 0.1 "
"0 % % // This is not automatically range-checked",
END_PARAMETER_DEFINITIONS

BEGIN_STATE_DEFINITIONS
"MyState 1 0 0 0",
END_STATE_DEFINITIONS
} </pre>
The data between the <code>BEGIN_...</code> and <code>END_...</code> macros are lists of comma-separated C-strings, which are additionally broken across lines to improve readability. For the compiler, anything is fine here that can go between the curly braces in
const char* array[] = { "entry 1", "entry 2", "entry 3", };
For successful filter instantiation at runtime, the strings must also be valid [[Technical Reference:Parameter Definition|parameter]] and [[Technical Reference:State Definition|state definitions]].

===Preflight===
The <tt>Preflight</tt> function checks whether the preconditions for successful operation are met. This function is called whenever parameter values are re- applied, i.e., whenever the user presses "Set Config", "Start", or "Resume" in the operator window. If <tt>Preflight</tt> does not report an error via <tt>bcierr</tt>, this counts as a statement that <tt>Initialize</tt> and <tt>Process</tt> will work properly with the current parameters. The first argument to <tt>Preflight</tt> will inform you about what kind of input signal your filter is going to receive, and your filter is expected to report the properties of its output signal via the second parameter:
<pre>
void MyFilter::Preflight( const SignalProperties& Input,
SignalProperties& Output ) const
{
PreflightCondition( Parameter( "MyOtherParam" ) > 0.0 );
PreflightCondition( Input.Channels() > 0 );
PreflightCondition( Output.Elements( 0 ) > 0 );
Output = Input;
} </pre>

Note that the <tt>const</tt> keyword following the function argument list forbids altering any data member of your filter object. This avoids diffusion of initialization code from <tt>Initialize</tt> into <tt>Preflight</tt>. If you have your own sub-objects instantiated and maintained by your filter, you should provide them with their own <tt>Preflight() const</tt> member functions, and call these from your filter's <tt>Preflight</tt>.

===Initialize===
<tt>Initialize</tt> is called after a successful <tt>Preflight</tt>. Thus, it may safely omit all checks related to parameter consistency. In <tt>Initialize</tt>, your filter's data members are set to the values implied by the user's choices, or to the initial values required for the filter's operation:
<pre>
void MyFilter::Initialize( const SignalProperties& Input,
const SignalProperties& Output )
{
mMyParam = Parameter( "MyParam" );
mMyOtherParam = Parameter( "MyOtherParam" );
mCount = 0;
} </pre>

===Process===
The <tt>Process</tt> function is called once for each block of EEG data. It receives an input in its first argument, and sets the output signal to values resulting from the filter operation. In the current BCI2000 implementation, there is a single chain of filters; one filter's output signal is the next filter's input. A filter which does not perform any modification to the signal (e.g., a statistics filter) needs to copy its input signal into the output signal, as in the example:
<pre>
void MyFilter::Process( const GenericSignal& Input,
GenericSignal& Output )
{
if( Input( 0, 0 ) > mMyOtherParam )
++mCount;
Output = Input;
} </pre>

The <tt>Process</tt> function should not acquire or release resources (opening/closing files, allocating memory, etc). Natural places for such operations are the <tt>Initialize</tt>, <tt>StartRun</tt>, and <tt>StopRun</tt> member functions.

==Optional Member Functions==
Other member functions are ''optional;'' you may decide whether
you
override their default implementation with your own version,
depending on what your filter needs to do:

===StartRun===
<tt>StartRun</tt> is called when the system enters the running state. As opposed to <tt>Initialize</tt>, which is the place for tasks that need to be performed on each parameter change, <tt>StartRun</tt> is provided for tasks that need to be performed each time the user clicks "Run" or "Resume" in the operator window. As a canonical example, the <tt>DataIOFilter</tt> opens a new <tt>.dat</tt> file from its <tt>StartRun</tt> member function.

===StopRun===
<tt>StopRun</tt> is called each time the system leaves the running state, entering the suspended state. Typically, this happens whenever the user clicks "Suspend" in the operator window. The <tt>DataIOFilter</tt> provides an example for its usage: This filter closes the current <tt>.dat</tt> file from its <tt>StopRun</tt> member function.

<tt>StopRun</tt> is also the only function from which a filter may change a parameter value. Any parameter changes inside <tt>StopRun</tt> will propagate to the other modules without any explicit request from your side.

===Resting===
<tt>Resting</tt> is called instead of <tt>Process</tt> while the system is in suspended state.

===Halt===
The <tt>Halt</tt> function is called before any reconfiguration of the system takes place. If your filter initiates asynchronous operations such as playing a sound file, acquiring EEG data, or executing threads, its <tt>Halt</tt> member function should terminate all such operations immediately. Failure to do so might result in a non-responding module, or in other errors difficult to track down. For descendants of <tt>GenericADC</tt>, implementing the <tt>Halt</tt> function is mandatory.

===Destructor===
Your filter's ''Destructor'' should free all resources acquired in the Constructor or in <tt>Initialize</tt>. In many cases, freeing of resources will be done automatically if you use direct members instead of pointers, removing the need for a destructor. However, if your filter has a non-empty <tt>Halt</tt> function, it needs a destructor that calls <tt>Halt</tt> - this can not be done from the base class destructor because overridden virtual functions cannot be called from base class constructors or destructors.
<pre>
MyFilter::~MyFilter()
{
Halt();
} </pre>

===AllowsVisualization===
Unlike the previous members of <code>GenericFilter</code>, this function represents a property rather than an event.
Through its return value, a filter can decide whether its output may be offered for visualization by the framework, i.e. whether it appears in the Processing Stages section in the operator's Visualize tab.

<code>AllowsVisualization</code> is called once at instantiation, and then after each Initialize() that occurs.
If it returns false at instantiation, no visualization parameter is created for the filter.
If it returns false at initialization time, no default visualization is displayed,
independently of the visualization parameter's value.
The filter itself may still maintain its own visualization parameters and [[Programming Reference:GenericVisualization Class|GenericVisualization]] object.

==Rules for Parameter and State access==
For consistent and robust overall system operation, it is crucial that individual filters actually check [[BCI2000 Glossary#Parameter|parameter]] values and [[BCI2000 Glossary#States|state]] accessibility from their <code>Preflight()</code> function. To support this idea, the BCI2000 framework imposes a set of rules to parameter and state access:
*Parameters and states accessed during initialization or processing ''must'' be accessed during the preflight phase. Otherwise, an error message will be displayed when the first access occurs.
*To avoid pointless cludging of the <code>Preflight()</code> function, there are some exceptions to this rule:
**States defined in a filter's constructor are known to be present, and thus need not be accessed from that filter's <code>Preflight()</code> function.
**Parameters defined in a filter's constructor will be range-checked automatically if any of their <code>LowRange</code> or <code>HighRange</code> [[Technical Reference:Parameter Definition|properties]] is set, and need not be accessed explicitly from <code>Preflight()</code>.
**To disable automatic range checking, set both these properties to the empty string in your [[Technical Reference:Parameter Definition|parameter definition line]]: <code>MySection int MyParam= 1 0 % % // a parameter that is not automatically range-checked</code> This implies that you need to implement your own range-check in <code>Preflight()</code>. If there are no actual constraints on the parameter's value, just add a line <code>Parameter( "MyParam" );</code> to the filter's <code>Preflight()</code> function.
*[[User Reference:Expression Syntax|Expressions]] may involve state names, and thus need to be evaluated in order to check whether referred-to states are present. Just add a line <code>Expression( Parameter( "MyExpressionParam" ) ).Evaluate();</code> to the filter's <code>Preflight()</code> function.

[[Category:Framework API]][[Category:Development]]

Programming Reference:GenericFilter Class

2008-07-14T13:13:54Z

Roostenveld: added initialize heading

==The <tt>GenericFilter</tt> class==
<tt>GenericFilter</tt> is a base class that provides a programming
interface for all user code inside the core modules of this BCI2000
implementation.
Programming your own data acquisition module, your own filter inside
Signal Processing, or your own application, implies deriving your
own
class from <tt>GenericFilter</tt>.
<tt>GenericFilter</tt>'s member functions represent the various
initialization and processing events that occur during system startup
and operation (see [[Technical Reference:States of Operation]]).
Your own filter code ''must'' implement its own
versions of some of these member functions:

==Required Members==
===Constructor===
The ''Constructor'', besides its general purpose of initializing member data, declares the parameters and states your filter wants to introduce into the system (the <tt>BEGIN_...</tt> and <tt>END_...</tt> macros handle the actual function calls):
<pre>
MyFilter::MyFilter()
: mMyParam( 1 ),
mMyOtherParam( 0.1 ),
mCount( 0 )
{
BEGIN_PARAMETER_DEFINITIONS
"MySection int MyParam= 1 "
"0 0 3 // This is range-checked between 0 and 3",
"MySection float MyOtherParam= 0.1 "
"0 % % // This is not automatically range-checked",
END_PARAMETER_DEFINITIONS

BEGIN_STATE_DEFINITIONS
"MyState 1 0 0 0",
END_STATE_DEFINITIONS
} </pre>
The data between the <code>BEGIN_...</code> and <code>END_...</code> macros are lists of comma-separated C-strings, which are additionally broken across lines to improve readability. For the compiler, anything is fine here that can go between the curly braces in
const char* array[] = { "entry 1", "entry 2", "entry 3", };
For successful filter instantiation at runtime, the strings must also be valid [[Technical Reference:Parameter Definition|parameter]] and [[Technical Reference:State Definition|state definitions]].

===Preflight===
The <tt>Preflight</tt> function checks whether the preconditions for successful operation are met. This function is called whenever parameter values are re- applied, i.e., whenever the user presses "Set Config", "Start", or "Resume" in the operator window. If <tt>Preflight</tt> does not report an error via <tt>bcierr</tt>, this counts as a statement that <tt>Initialize</tt> and <tt>Process</tt> will work properly with the current parameters. The first argument to <tt>Preflight</tt> will inform you about what kind of input signal your filter is going to receive, and your filter is expected to report the properties of its output signal via the second parameter:
<pre>
void MyFilter::Preflight( const SignalProperties& Input,
SignalProperties& Output ) const
{
PreflightCondition( Parameter( "MyOtherParam" ) > 0.0 );
PreflightCondition( Input.Channels() > 0 );
PreflightCondition( Output.Elements( 0 ) > 0 );
Output = Input;
} </pre>

Note that the <tt>const</tt> keyword following the function argument list forbids altering any data member of your filter object. This avoids diffusion of initialization code from <tt>Initialize</tt> into <tt>Preflight</tt>. If you have your own sub-objects instantiated and maintained by your filter, you should provide them with their own <tt>Preflight() const</tt> member functions, and call these from your filter's <tt>Preflight</tt>.

==Initialize==
<tt>Initialize</tt> is called after a successful <tt>Preflight</tt>. Thus, it may safely omit all checks related to parameter consistency. In <tt>Initialize</tt>, your filter's data members are set to the values implied by the user's choices, or to the initial values required for the filter's operation:
<pre>
void MyFilter::Initialize( const SignalProperties& Input,
const SignalProperties& Output )
{
mMyParam = Parameter( "MyParam" );
mMyOtherParam = Parameter( "MyOtherParam" );
mCount = 0;
} </pre>

===Process===
The <tt>Process</tt> function is called once for each block of EEG data. It receives an input in its first argument, and sets the output signal to values resulting from the filter operation. In the current BCI2000 implementation, there is a single chain of filters; one filter's output signal is the next filter's input. A filter which does not perform any modification to the signal (e.g., a statistics filter) needs to copy its input signal into the output signal, as in the example:
<pre>
void MyFilter::Process( const GenericSignal& Input,
GenericSignal& Output )
{
if( Input( 0, 0 ) > mMyOtherParam )
++mCount;
Output = Input;
} </pre>

The <tt>Process</tt> function should not acquire or release resources (opening/closing files, allocating memory, etc). Natural places for such operations are the <tt>Initialize</tt>, <tt>StartRun</tt>, and <tt>StopRun</tt> member functions.

==Optional Member Functions==
Other member functions are ''optional;'' you may decide whether
you
override their default implementation with your own version,
depending on what your filter needs to do:

===StartRun===
<tt>StartRun</tt> is called when the system enters the running state. As opposed to <tt>Initialize</tt>, which is the place for tasks that need to be performed on each parameter change, <tt>StartRun</tt> is provided for tasks that need to be performed each time the user clicks "Run" or "Resume" in the operator window. As a canonical example, the <tt>DataIOFilter</tt> opens a new <tt>.dat</tt> file from its <tt>StartRun</tt> member function.

===StopRun===
<tt>StopRun</tt> is called each time the system leaves the running state, entering the suspended state. Typically, this happens whenever the user clicks "Suspend" in the operator window. The <tt>DataIOFilter</tt> provides an example for its usage: This filter closes the current <tt>.dat</tt> file from its <tt>StopRun</tt> member function.

<tt>StopRun</tt> is also the only function from which a filter may change a parameter value. Any parameter changes inside <tt>StopRun</tt> will propagate to the other modules without any explicit request from your side.

===Resting===
<tt>Resting</tt> is called instead of <tt>Process</tt> while the system is in suspended state.

===Halt===
The <tt>Halt</tt> function is called before any reconfiguration of the system takes place. If your filter initiates asynchronous operations such as playing a sound file, acquiring EEG data, or executing threads, its <tt>Halt</tt> member function should terminate all such operations immediately. Failure to do so might result in a non-responding module, or in other errors difficult to track down. For descendants of <tt>GenericADC</tt>, implementing the <tt>Halt</tt> function is mandatory.

===Destructor===
Your filter's ''Destructor'' should free all resources acquired in the Constructor or in <tt>Initialize</tt>. In many cases, freeing of resources will be done automatically if you use direct members instead of pointers, removing the need for a destructor. However, if your filter has a non-empty <tt>Halt</tt> function, it needs a destructor that calls <tt>Halt</tt> - this can not be done from the base class destructor because overridden virtual functions cannot be called from base class constructors or destructors.
<pre>
MyFilter::~MyFilter()
{
Halt();
} </pre>

===AllowsVisualization===
Unlike the previous members of <code>GenericFilter</code>, this function represents a property rather than an event.
Through its return value, a filter can decide whether its output may be offered for visualization by the framework, i.e. whether it appears in the Processing Stages section in the operator's Visualize tab.

<code>AllowsVisualization</code> is called once at instantiation, and then after each Initialize() that occurs.
If it returns false at instantiation, no visualization parameter is created for the filter.
If it returns false at initialization time, no default visualization is displayed,
independently of the visualization parameter's value.
The filter itself may still maintain its own visualization parameters and [[Programming Reference:GenericVisualization Class|GenericVisualization]] object.

==Rules for Parameter and State access==
For consistent and robust overall system operation, it is crucial that individual filters actually check [[BCI2000 Glossary#Parameter|parameter]] values and [[BCI2000 Glossary#States|state]] accessibility from their <code>Preflight()</code> function. To support this idea, the BCI2000 framework imposes a set of rules to parameter and state access:
*Parameters and states accessed during initialization or processing ''must'' be accessed during the preflight phase. Otherwise, an error message will be displayed when the first access occurs.
*To avoid pointless cludging of the <code>Preflight()</code> function, there are some exceptions to this rule:
**States defined in a filter's constructor are known to be present, and thus need not be accessed from that filter's <code>Preflight()</code> function.
**Parameters defined in a filter's constructor will be range-checked automatically if any of their <code>LowRange</code> or <code>HighRange</code> [[Technical Reference:Parameter Definition|properties]] is set, and need not be accessed explicitly from <code>Preflight()</code>.
**To disable automatic range checking, set both these properties to the empty string in your [[Technical Reference:Parameter Definition|parameter definition line]]: <code>MySection int MyParam= 1 0 % % // a parameter that is not automatically range-checked</code> This implies that you need to implement your own range-check in <code>Preflight()</code>. If there are no actual constraints on the parameter's value, just add a line <code>Parameter( "MyParam" );</code> to the filter's <code>Preflight()</code> function.
*[[User Reference:Expression Syntax|Expressions]] may involve state names, and thus need to be evaluated in order to check whether referred-to states are present. Just add a line <code>Expression( Parameter( "MyExpressionParam" ) ).Evaluate();</code> to the filter's <code>Preflight()</code> function.

[[Category:Framework API]][[Category:Development]]

Programming Reference:MatlabFilter

2008-07-14T13:11:54Z

Roostenveld: /* Overview */ fixed typo in link

==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 [[Programming Reference:GenericFilter Class|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 [[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.

{| style="color:black;background-color:#ffffcc;" cellpadding="5" cellspacing="0" border="2"
!BCI2000 function
!Matlab equivalent
|-
|[[Programming_Reference:GenericFilter_Class#Constructor|Constructor()]]
|bci_Construct
|-
|[[Programming_Reference:GenericFilter_Class#Prefligh|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
|}

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 <tt>bci_Process</tt>, which is executed every time a new block of data is passed through the pipeline. Furthermore <tt>bci_Construct</tt> is executed at the beginning and determines the parameters and states, <tt>bci_Initialize</tt> determines whether all requirements are met, and <tt>bci_StartRun</tt> 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 <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 parameters and states 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:
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 <tt>bci_Preflight</tt> and <tt>bci_Initialize</tt> are integer vectors of size 1x2 with <tt>[n_channels n_elements]</tt>.

==Error Reporting==

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

==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. 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==
===Debugging Matlab functions===
#Start BCI2000. The ''MatlabFilter'' will open a Matlab instance in its own window in minimized state.
#Switch to the minimized Matlab instance.
#Type, e.g., <code>edit bci_Process.m</code> to open a Matlab editor window connected to the Matlab interactive window.
#In the editor window, set breakpoints as you would normally.
#Execution will be paused, and you may examine variables moving the mouse over them.

===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.

===There is no Matlab engine started up===
Execute <code>matlab /regserver</code> from the command line when logged in with administrative privileges.
===Changes to M-files appear to have no effect===
Switch to the Matlab engine's command window, and enter <code>clear;</code> or <code>clear scriptname;</code> each time you change a Matlab function.

===You get linker errors when rebuilding ''MatlabSignalProcessing''===
If you get linker errors after editing <tt>PipeDefinition.cpp</tt>, make sure that all filters' cpp files are part of the ''MatlabSignalProcessing'' project.
===You get a message window with an "Entry Point Not Found" message===
This error is likely to indicate confusion of multiple installations of Matlab on your machine.
Check your Windows ''%PATH%'' environment variable, e.g. by opening a command console window and typing
echo %PATH%
When it contains references to more than a single Matlab installation, remove all apart from the reference to the installation you are going to use with BCI2000. Also, make sure to execute
matlab /regserver
for the Matlab installation you intend to use.

==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]]

Tutorials:
* [[Programming_Tutorial:Implementing_a_Matlab-based_Filter|IIR bandpass filtering, followed with RMS envelope computation, and linear classification]]
* [[Programming_Tutorial:Implementing_another_Matlab-based_Filter|adaptive spatial filtering using a beamformer, power computation and normalization]]

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

Programming Reference:MatlabFilter

2008-07-14T13:11:30Z

Roostenveld: /* Overview */ added lins in table

==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 [[Programming Reference:GenericFilter Class|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 [[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.

{| style="color:black;background-color:#ffffcc;" cellpadding="5" cellspacing="0" border="2"
!BCI2000 function
!Matlab equivalent
|-
|[[Programming_Reference:GenericFilter_Class#Constructor|Constructor()]]
|bci_Construct
|-
|[[Programming_Reference:GenericFilter_Class#Prefligh|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_ClassResting|#Resting()]]
|bci_Resting
|-
|[[Programming_Reference:GenericFilter_Class#Halt|Halt()]]
|bci_Halt
|-
|[[Programming_Reference:GenericFilter_Class#Destructor|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 <tt>bci_Process</tt>, which is executed every time a new block of data is passed through the pipeline. Furthermore <tt>bci_Construct</tt> is executed at the beginning and determines the parameters and states, <tt>bci_Initialize</tt> determines whether all requirements are met, and <tt>bci_StartRun</tt> 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 <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 parameters and states 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:
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 <tt>bci_Preflight</tt> and <tt>bci_Initialize</tt> are integer vectors of size 1x2 with <tt>[n_channels n_elements]</tt>.

==Error Reporting==

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

==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. 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==
===Debugging Matlab functions===
#Start BCI2000. The ''MatlabFilter'' will open a Matlab instance in its own window in minimized state.
#Switch to the minimized Matlab instance.
#Type, e.g., <code>edit bci_Process.m</code> to open a Matlab editor window connected to the Matlab interactive window.
#In the editor window, set breakpoints as you would normally.
#Execution will be paused, and you may examine variables moving the mouse over them.

===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.

===There is no Matlab engine started up===
Execute <code>matlab /regserver</code> from the command line when logged in with administrative privileges.
===Changes to M-files appear to have no effect===
Switch to the Matlab engine's command window, and enter <code>clear;</code> or <code>clear scriptname;</code> each time you change a Matlab function.

===You get linker errors when rebuilding ''MatlabSignalProcessing''===
If you get linker errors after editing <tt>PipeDefinition.cpp</tt>, make sure that all filters' cpp files are part of the ''MatlabSignalProcessing'' project.
===You get a message window with an "Entry Point Not Found" message===
This error is likely to indicate confusion of multiple installations of Matlab on your machine.
Check your Windows ''%PATH%'' environment variable, e.g. by opening a command console window and typing
echo %PATH%
When it contains references to more than a single Matlab installation, remove all apart from the reference to the installation you are going to use with BCI2000. Also, make sure to execute
matlab /regserver
for the Matlab installation you intend to use.

==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]]

Tutorials:
* [[Programming_Tutorial:Implementing_a_Matlab-based_Filter|IIR bandpass filtering, followed with RMS envelope computation, and linear classification]]
* [[Programming_Tutorial:Implementing_another_Matlab-based_Filter|adaptive spatial filtering using a beamformer, power computation and normalization]]

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

Programming Reference:MatlabFilter

2008-07-14T13:08:55Z

Roostenveld: general cleanup

==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 [[Programming Reference:GenericFilter Class|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 [[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.

{| style="color:black;background-color:#ffffcc;" cellpadding="5" cellspacing="0" border="2"
!BCI2000 function
!Matlab equivalent
|-
|[[Programming_Reference:GenericFilter_Class#Constructor|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 <tt>bci_Process</tt>, which is executed every time a new block of data is passed through the pipeline. Furthermore <tt>bci_Construct</tt> is executed at the beginning and determines the parameters and states, <tt>bci_Initialize</tt> determines whether all requirements are met, and <tt>bci_StartRun</tt> 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 <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 parameters and states 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:
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 <tt>bci_Preflight</tt> and <tt>bci_Initialize</tt> are integer vectors of size 1x2 with <tt>[n_channels n_elements]</tt>.

==Error Reporting==

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

==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. 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==
===Debugging Matlab functions===
#Start BCI2000. The ''MatlabFilter'' will open a Matlab instance in its own window in minimized state.
#Switch to the minimized Matlab instance.
#Type, e.g., <code>edit bci_Process.m</code> to open a Matlab editor window connected to the Matlab interactive window.
#In the editor window, set breakpoints as you would normally.
#Execution will be paused, and you may examine variables moving the mouse over them.

===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.

===There is no Matlab engine started up===
Execute <code>matlab /regserver</code> from the command line when logged in with administrative privileges.
===Changes to M-files appear to have no effect===
Switch to the Matlab engine's command window, and enter <code>clear;</code> or <code>clear scriptname;</code> each time you change a Matlab function.

===You get linker errors when rebuilding ''MatlabSignalProcessing''===
If you get linker errors after editing <tt>PipeDefinition.cpp</tt>, make sure that all filters' cpp files are part of the ''MatlabSignalProcessing'' project.
===You get a message window with an "Entry Point Not Found" message===
This error is likely to indicate confusion of multiple installations of Matlab on your machine.
Check your Windows ''%PATH%'' environment variable, e.g. by opening a command console window and typing
echo %PATH%
When it contains references to more than a single Matlab installation, remove all apart from the reference to the installation you are going to use with BCI2000. Also, make sure to execute
matlab /regserver
for the Matlab installation you intend to use.

==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]]

Tutorials:
* [[Programming_Tutorial:Implementing_a_Matlab-based_Filter|IIR bandpass filtering, followed with RMS envelope computation, and linear classification]]
* [[Programming_Tutorial:Implementing_another_Matlab-based_Filter|adaptive spatial filtering using a beamformer, power computation and normalization]]

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

User Reference:MatlabFilter

2008-07-14T12:46:06Z

Roostenveld: /* Detailled explanation */ fixed link

==Synopsis==

The Matlab filter implements an interface between BCI2000 and a standalone Matlab engine. It allows you to implement and/or use Matlab functions for filtering data within the BCI2000 pipeline.

==Parameters==

The Matlab filter does not have a set of default parameters that it uses. Instead, the user-supplied Matlab functions that are executed by the Matlab filter specify the parameters. After initialization, these parameters are displayed in the [[User_Reference:Operator_Module|Operator]] and can be modified there.

==States==

The Matlab filter does not have a set of default states that it uses. Instead, the user-supplied Matlab functions that are executed by the Matlab filter specify the states.

==Detailled explanation==

The Matlab filter does not implement any algorithms itself, but instead allows you to implement the algorithms of your choice in Matlab.

Once BCI2000 is running with the Matlab filter, you will see that a very simple Matlab command line window has openend. In that command line window you can type commands that show you the variables that BCI2000 communicates to the Matlab engine. For example, you can do

% show the variables
whos

% plot the first channel of the data (see below)
plot(bci_InSignal(1,:))

% plot the first channel of the data and continuously update the plot (see below)
while(1); plot(bci_InSignal(1,:)); pause(0.01); end

If you try these examples above like this, you will notice that Matlab takes quite a considerable amount of time to open a new figure. While the figure is being openend by Matlab, the engine is blocked , which causes the MatlabFilter to fail writing new data to the engine. Hence the MatlabFilter will return an error and you will have to restart BCI2000. The reason is that the Matlab engine gives you access through the command window, but that the Matlab engine is not capable of executing the commands that it receives from BCI2000 and the commands that it receives from you through the command window simultaneously.

To get the above example to run correctly, you will have to open the figure /prior/ to starting BCI2000 by typing <tt>figure</tt> (this will open an empty figure). Subsequently, once BCI2000 is running, the content of the figure can be updated.

However, the above example already shows that the Matlab engine is not intended to be used concurrently from the BCI2000 MatlabFilter and from the command window. Instead of typing your own commands in the command window, you will have to give full control of command execution to the MatlabFilter to ensure that timing is controlled. The way that BCI2000 and Matlab interact is that each of the components of a standard filter is mapped onto a corresponding Matlab function. If the Matlab filter is running within BCI2000, it will call the Matlab engine and execute the required Matlab function. The easiest way of getting started with the Matlab filter is by using one of the provided programming tutorials:
* [[Programming_Tutorial:Implementing_a_Matlab-based_Filter|IIR bandpass filtering, followed with RMS envelope computation, and linear classification]]
* [[Programming_Tutorial:Implementing_another_Matlab-based_Filter|adaptive spatial filtering using a beamformer, power computation and normalization]]

A detailled description of how to implement your own signal processing functions in Matlab can be found in the [[Programming_Reference:MatlabFilter|Programming reference for the Matlab filter]].

==Troubleshooting:==

===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.

===There is no Matlab engine started up===
Execute <code>matlab /regserver</code> from the command line when logged in with administrative privileges.

==See also==
[[Programming_Reference:MatlabFilter]],
[[Contributions:FieldTripBuffer]]

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

Contributions:FieldTripBuffer

2008-07-14T12:45:20Z

Roostenveld: /* See also */ fixed links

==Synopsis==

==Location==

==Parameters==

==States==

==See also==
[[User_Reference:MatlabFilter]], [[Programming_Reference:MatlabFilter]]

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

Programming Reference:Rapid Development

2008-07-14T12:43:55Z

Roostenveld: /* Matlab Integration */

This page describes elements of BCI2000 intended to simplify a programmer's task when implementing a new BCI2000 filter, or application.

==Templates==
*The [[Programming Reference:FeedbackDemo Application]] may serve as a starting point for a trial-based application.
*The [[Programming Reference:IIRFilter Class]] filter stub allows you to easily implement IIR filters.

==Helper Classes==
*[[Programming Reference:WavePlayer Class]] plays back audio files.
*[[Programming Reference:TextToSpeech Class]] provides synthetic speech.
*[[Programming Reference:MidiPlayer Class]] plays back MIDI data.
*[[Programming Reference:TrialStatistics Class]] computes accuracies and bit rates.
*[[Programming Reference:LogFile Class]] transparently maintains a log file in the current data directory.

==Matlab Integration==
*The [[Programming Reference:MatlabFilter]] lets Matlab code act upon BCI2000 data.
*There is also a [[Programming Tutorial:Implementing a Matlab-based Filter|tutorial on implementing a Matlab-based tilter]] for temporal filtering, and [[Programming Tutorial:Implementing another Matlab-based Filter| another tutorial]] on implementing an adaptive spatial filter using beamforming.

[[Category:Contents]]
[[Category:Development]]

Programming Reference:Contents

2008-07-14T12:39:24Z

Roostenveld: /* Tutorials */ added another matlab demo

This part of the reference provides background information which you need in order
to understand, modify, or create code that depends on the BCI2000 framework.

You should read it before writing your own BCI2000 module, or modifying an existing
one as presented in the tutorial examples.

==Getting Started==
*[[Programming Howto:Building BCI2000]]
*[[Programming Howto:SVN Client Setup]]
*[[Programming Howto:Using TortoiseSVN]]
*[[Programming FAQ]]

==Conceptual Overview==
*[[Programming Reference:Filter Chain]]
*[[Programming Reference:Signals]]
*[[Programming Reference:Error Handling]]
*[[Programming Reference:Localization]]
*[[Programming Reference:Rapid Development]]

==Programming Interface Documentation==

===Generic Filter Interface===
*[[Programming Reference:GenericFilter Class]]
*[[Programming Reference:Environment Class]]
*[[Programming Reference:GenericVisualization Class]]

===Text Messages===
*[[Programming Reference:Errors and Warnings]]
*[[Programming Reference:Debug Output]]
*[[Programming Reference:LogFile Class]]

===Data I/O===
*[[Programming Reference:GenericFileWriter Class]]
*[[Programming Reference:GenericADC Class]]
*[[Programming Reference:BCI2000FileReader Class]]

===Signal Processing Modules===
*[[Programming Reference:IIRFilter Class]]

===Application Modules===
*[[Programming Reference:ApplicationBase Class]]
*[[Programming Reference:FeedbackTask Class]]
*[[Programming Reference:StimulusTask Class]]

====Visual Presentation====
*[[Programming Reference:3D API]]

====Auditory Presentation====
*[[Programming Reference:MidiPlayer Class]]
*[[Programming Reference:WavePlayer Class]]
*[[Programming Reference:TextToSpeech Class]]

==Tutorials==
*[[Programming Tutorial:Implementing a Data Acquisition Module]]
*[[Programming Tutorial:Implementing a Signal Processing Filter]]
*[[Programming Tutorial:Implementing a Matlab-based Filter]]
*[[Programming Tutorial:Implementing another Matlab-based Filter]]

==See also==
[[Technical Reference:Contents]], [[User Reference:Contents]]

[[Category:Contents]]

Programming Reference:MatlabFilter

2008-07-14T12:38:14Z

Roostenveld: /* See also */

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.

==Filter Interface==
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.
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
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
<tt>bci_Parameters</tt> and <tt>bci_States</tt>. In Matlab, write

global bci_Parameters bci_States;
my_sampling_rate = bci_Parameters.SamplingRate;

*Parameter values may be changed from inside the <tt>bci_StopRun</tt> script, and will automatically be propagated to the other modules.

*State values may be modified from the <tt>bci_Process</tt> function.

==Declaring Parameters and States==
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>
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:
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''.

==Signal Format==
BCI2000 signals are mapped to Matlab matrices with channel index first,
and sample (element) index second.
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==
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]].

==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 [[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.

==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==
===Debugging Matlab functions===
#Start BCI2000. The ''MatlabFilter'' will open a Matlab instance in its own window in minimized state.
#Switch to the minimized Matlab instance.
#Type, e.g., <code>edit bci_Process.m</code> to open a Matlab editor window connected to the Matlab interactive window.
#In the editor window, set breakpoints as you would normally.
#Execution will be paused, and you may examine variables moving the mouse over them.

===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.

===There is no Matlab engine started up===
Execute <code>matlab /regserver</code> from the command line when logged in with administrative privileges.
===Changes to M-files appear to have no effect===
Switch to the Matlab engine's command window, and enter <code>clear;</code> or <code>clear scriptname;</code> each time you change a Matlab function.

===You get linker errors when rebuilding ''MatlabSignalProcessing''===
If you get linker errors after editing <tt>PipeDefinition.cpp</tt>, make sure that all filters' cpp files are part of the ''MatlabSignalProcessing'' project.
===You get a message window with an "Entry Point Not Found" message===
This error is likely to indicate confusion of multiple installations of Matlab on your machine.
Check your Windows ''%PATH%'' environment variable, e.g. by opening a command console window and typing
echo %PATH%
When it contains references to more than a single Matlab installation, remove all apart from the reference to the installation you are going to use with BCI2000. Also, make sure to execute
matlab /regserver
for the Matlab installation you intend to use.

==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 Matlab-based Filter]]
[[Programming Tutorial:Implementing another Matlab-based Filter]],
[[Contributions:FieldTripBuffer]]

[[Category:Development]]
[[Category:External Interfaces]]

User Reference:MatlabFilter

2008-07-14T12:36:41Z

Roostenveld: /* See also */

==Synopsis==

The Matlab filter implements an interface between BCI2000 and a standalone Matlab engine. It allows you to implement and/or use Matlab functions for filtering data within the BCI2000 pipeline.

==Parameters==

The Matlab filter does not have a set of default parameters that it uses. Instead, the user-supplied Matlab functions that are executed by the Matlab filter specify the parameters. After initialization, these parameters are displayed in the [[User_Reference:Operator_Module|Operator]] and can be modified there.

==States==

The Matlab filter does not have a set of default states that it uses. Instead, the user-supplied Matlab functions that are executed by the Matlab filter specify the states.

==Detailled explanation==

The Matlab filter does not implement any algorithms itself, but instead allows you to implement the algorithms of your choice in Matlab.

Once BCI2000 is running with the Matlab filter, you will see that a very simple Matlab command line window has openend. In that command line window you can type commands that show you the variables that BCI2000 communicates to the Matlab engine. For example, you can do

% show the variables
whos

% plot the first channel of the data (see below)
plot(bci_InSignal(1,:))

% plot the first channel of the data and continuously update the plot (see below)
while(1); plot(bci_InSignal(1,:)); pause(0.01); end

If you try these examples above like this, you will notice that Matlab takes quite a considerable amount of time to open a new figure. While the figure is being openend by Matlab, the engine is blocked , which causes the MatlabFilter to fail writing new data to the engine. Hence the MatlabFilter will return an error and you will have to restart BCI2000. The reason is that the Matlab engine gives you access through the command window, but that the Matlab engine is not capable of executing the commands that it receives from BCI2000 and the commands that it receives from you through the command window simultaneously.

To get the above example to run correctly, you will have to open the figure /prior/ to starting BCI2000 by typing <tt>figure</tt> (this will open an empty figure). Subsequently, once BCI2000 is running, the content of the figure can be updated.

However, the above example already shows that the Matlab engine is not intended to be used concurrently from the BCI2000 MatlabFilter and from the command window. Instead of typing your own commands in the command window, you will have to give full control of command execution to the MatlabFilter to ensure that timing is controlled. The way that BCI2000 and Matlab interact is that each of the components of a standard filter is mapped onto a corresponding Matlab function. If the Matlab filter is running within BCI2000, it will call the Matlab engine and execute the required Matlab function. The easiest way of getting started with the Matlab filter is by using one of the provided programming tutorials:
* [[Programming_Tutorial:Implementing_a_Matlab-based_Filter|IIR bandpass filtering, followed with RMS envelope computation, and linear classification]]
* [[Programming_Tutorial:Implementing_another_Matlab-based_Filter|adaptive spatial filtering using a beamformer, power computation and normalization]]

A detailled description of how to implement your own signal processing functions in Matlab can be found in the [[Programming_Reference:Matlab|Programming reference for the Matlab filter]].

==Troubleshooting:==

===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.

===There is no Matlab engine started up===
Execute <code>matlab /regserver</code> from the command line when logged in with administrative privileges.

==See also==
[[Programming_Reference:MatlabFilter]],
[[Contributions:FieldTripBuffer]]

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

User Reference:MatlabFilter

2008-07-14T12:36:14Z

Roostenveld: /* See also */

==Synopsis==

The Matlab filter implements an interface between BCI2000 and a standalone Matlab engine. It allows you to implement and/or use Matlab functions for filtering data within the BCI2000 pipeline.

==Parameters==

The Matlab filter does not have a set of default parameters that it uses. Instead, the user-supplied Matlab functions that are executed by the Matlab filter specify the parameters. After initialization, these parameters are displayed in the [[User_Reference:Operator_Module|Operator]] and can be modified there.

==States==

The Matlab filter does not have a set of default states that it uses. Instead, the user-supplied Matlab functions that are executed by the Matlab filter specify the states.

==Detailled explanation==

The Matlab filter does not implement any algorithms itself, but instead allows you to implement the algorithms of your choice in Matlab.

Once BCI2000 is running with the Matlab filter, you will see that a very simple Matlab command line window has openend. In that command line window you can type commands that show you the variables that BCI2000 communicates to the Matlab engine. For example, you can do

% show the variables
whos

% plot the first channel of the data (see below)
plot(bci_InSignal(1,:))

% plot the first channel of the data and continuously update the plot (see below)
while(1); plot(bci_InSignal(1,:)); pause(0.01); end

If you try these examples above like this, you will notice that Matlab takes quite a considerable amount of time to open a new figure. While the figure is being openend by Matlab, the engine is blocked , which causes the MatlabFilter to fail writing new data to the engine. Hence the MatlabFilter will return an error and you will have to restart BCI2000. The reason is that the Matlab engine gives you access through the command window, but that the Matlab engine is not capable of executing the commands that it receives from BCI2000 and the commands that it receives from you through the command window simultaneously.

To get the above example to run correctly, you will have to open the figure /prior/ to starting BCI2000 by typing <tt>figure</tt> (this will open an empty figure). Subsequently, once BCI2000 is running, the content of the figure can be updated.

However, the above example already shows that the Matlab engine is not intended to be used concurrently from the BCI2000 MatlabFilter and from the command window. Instead of typing your own commands in the command window, you will have to give full control of command execution to the MatlabFilter to ensure that timing is controlled. The way that BCI2000 and Matlab interact is that each of the components of a standard filter is mapped onto a corresponding Matlab function. If the Matlab filter is running within BCI2000, it will call the Matlab engine and execute the required Matlab function. The easiest way of getting started with the Matlab filter is by using one of the provided programming tutorials:
* [[Programming_Tutorial:Implementing_a_Matlab-based_Filter|IIR bandpass filtering, followed with RMS envelope computation, and linear classification]]
* [[Programming_Tutorial:Implementing_another_Matlab-based_Filter|adaptive spatial filtering using a beamformer, power computation and normalization]]

A detailled description of how to implement your own signal processing functions in Matlab can be found in the [[Programming_Reference:Matlab|Programming reference for the Matlab filter]].

==Troubleshooting:==

===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.

===There is no Matlab engine started up===
Execute <code>matlab /regserver</code> from the command line when logged in with administrative privileges.

==See also==
[[Contributions:FieldTripBuffer]], [[Programming_Reference:MatlabFilter]]

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

User Reference:MatlabFilter

2008-07-14T12:35:29Z

Roostenveld: moved text over from matlab to matlabfilter

==Synopsis==

The Matlab filter implements an interface between BCI2000 and a standalone Matlab engine. It allows you to implement and/or use Matlab functions for filtering data within the BCI2000 pipeline.

==Parameters==

The Matlab filter does not have a set of default parameters that it uses. Instead, the user-supplied Matlab functions that are executed by the Matlab filter specify the parameters. After initialization, these parameters are displayed in the [[User_Reference:Operator_Module|Operator]] and can be modified there.

==States==

The Matlab filter does not have a set of default states that it uses. Instead, the user-supplied Matlab functions that are executed by the Matlab filter specify the states.

==Detailled explanation==

The Matlab filter does not implement any algorithms itself, but instead allows you to implement the algorithms of your choice in Matlab.

Once BCI2000 is running with the Matlab filter, you will see that a very simple Matlab command line window has openend. In that command line window you can type commands that show you the variables that BCI2000 communicates to the Matlab engine. For example, you can do

% show the variables
whos

% plot the first channel of the data (see below)
plot(bci_InSignal(1,:))

% plot the first channel of the data and continuously update the plot (see below)
while(1); plot(bci_InSignal(1,:)); pause(0.01); end

If you try these examples above like this, you will notice that Matlab takes quite a considerable amount of time to open a new figure. While the figure is being openend by Matlab, the engine is blocked , which causes the MatlabFilter to fail writing new data to the engine. Hence the MatlabFilter will return an error and you will have to restart BCI2000. The reason is that the Matlab engine gives you access through the command window, but that the Matlab engine is not capable of executing the commands that it receives from BCI2000 and the commands that it receives from you through the command window simultaneously.

To get the above example to run correctly, you will have to open the figure /prior/ to starting BCI2000 by typing <tt>figure</tt> (this will open an empty figure). Subsequently, once BCI2000 is running, the content of the figure can be updated.

However, the above example already shows that the Matlab engine is not intended to be used concurrently from the BCI2000 MatlabFilter and from the command window. Instead of typing your own commands in the command window, you will have to give full control of command execution to the MatlabFilter to ensure that timing is controlled. The way that BCI2000 and Matlab interact is that each of the components of a standard filter is mapped onto a corresponding Matlab function. If the Matlab filter is running within BCI2000, it will call the Matlab engine and execute the required Matlab function. The easiest way of getting started with the Matlab filter is by using one of the provided programming tutorials:
* [[Programming_Tutorial:Implementing_a_Matlab-based_Filter|IIR bandpass filtering, followed with RMS envelope computation, and linear classification]]
* [[Programming_Tutorial:Implementing_another_Matlab-based_Filter|adaptive spatial filtering using a beamformer, power computation and normalization]]

A detailled description of how to implement your own signal processing functions in Matlab can be found in the [[Programming_Reference:Matlab|Programming reference for the Matlab filter]].

==Troubleshooting:==

===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.

===There is no Matlab engine started up===
Execute <code>matlab /regserver</code> from the command line when logged in with administrative privileges.

==See also==
[[Contributions:FieldTripBuffer]]

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