BCI2000 Wiki - User contributions [en]

P300 Off-line Analysis Tutorial

2007-05-22T20:11:21Z

Atennissen:

Programming Tutorial:Implementing a Signal Processing Filter

2007-05-22T15:55:36Z

Atennissen:

This tutorial shows you how to derive a new filter class from
<tt>GenericFilter</tt>, how to check preconditions, initialize your
filter,
and process data.
It will also show you how to visualize the output signal of the filter and present it
to the operator user.

==A simple low pass filter==
We want to implement a low pass filter with a time constant <math>T</math> (given
in units
of a sample's duration), a sequence <math>S_{in,t}</math> as input and a sequence
<math>S_{out,t}</math> as output (where <math>t</math> is an sample index proportional to
time), and obeying

<math>S_{out, 0} = \left( 1-e^{-1/T} \right) S_{in, 0}</math>

<math>S_{out, t} = e^{-1/T} S_{out, t-1} + \left( 1-e^{-1/T} \right) S_{in, t}</math>

==The filter skeleton==

The resulting filter class is to be called <tt>LPFilter</tt>.
We create two new files, <tt>LPFilter.h</tt>, and
<tt>LPFilter.cpp</tt>,
and put a minimal filter declaration into <tt>LPFilter.h</tt>:

<pre>
#ifndef LP_FILTER_H
#define LP_FILTER_H

#include "GenericFilter.h"

class LPFilter : public GenericFilter
{
public:
LPFilter();
~LPFilter();

void Preflight( const SignalProperties&, SignalProperties& ) const;
void Initialize();
void Process( const GenericSignal*, GenericSignal* );
};
#endif // LP_FILTER_H
</pre>
Into <tt>LPFilter.cpp</tt> we put the lines
<pre>
#include "PCHIncludes.h" // Make the compiler's Pre-Compiled Headers feature happy
#pragma hdrstop

#include "LPFilter.h"

#include "MeasurementUnits.h"
#include "BCIError.h"
#include <vector>
#include <cmath>

using namespace std;
</pre>

==The <tt>Process</tt> function==
When implementing a filter, a good strategy is to begin with the
<tt>Process</tt>
function, and to consider the remaining class member functions mere
helpers, mainly
determined by the code of <tt>Process</tt>.
So we convert the filter prescription into the <tt>Process</tt>
code, introducing member variables ''ad hoc'' , ignoring possible
error
conditions, and postponing efficiency considerations:
<pre>
void LPFilter::Process( const GenericSignal* input, GenericSignal* output )
{
// This implements the prescription's second line for all channels:
for( size_t channel = 0; channel < input->Channels(); ++channel )
{
for( size_t sample = 0; sample < input->Elements(); ++sample )
{
mPreviousOutput[ channel ] *= mDecayFactor;
mPreviousOutput[ channel ] +=
( *input )( channel, sample ) * ( 1.0 - mDecayFactor );
( *output )( channel, sample ) = mPreviousOutput[ channel ];
}
}
}
</pre>

==The <tt>Initialize</tt> member function==
As you will notice when comparing <tt>Process</tt> to the equations above, we introduced member variables representing these sub-expressions:

<math>\texttt{mPreviousOutput[ ]}= S_{out, t-1}</math>

<math>\texttt{mDecayFactor} = e^{-1/T}</math>

We introduce these members into the class declaration, adding the
following lines
after the <tt>Process</tt> declaration:
<pre>
private:
float mDecayFactor;
std::vector<float> mPreviousOutput;
</pre>
The next step is to initialize these member variables, introducing
filter
parameters as needed. This is done in the <tt>Initialize</tt> member
function --
we write it down without considering possible error conditions:
<pre>
void LPFilter::Initialize( const SignalProperties& inputProperties,
const SignalProperties& outputProperties )
{
// This will initialize all elements with 0,
// implementing the first line of the filter prescription:
mPreviousOutput.resize( inputProperties.Channels(), 0 );

float timeConstant = Parameter( "LPTimeConstant" );
mDecayFactor = ::exp( -1.0 / timeConstant );
mPreviousOutput.clear();
}
</pre>
Now this version is quite inconvenient for a user going to configure our filter
-- the time constant is given in units of a sample's duration, resulting in a
need to re-configure each time the sampling rate is changed.
A better idea is to let the user choose whether to give the
time constant in seconds or in sample blocks.
To achieve this, there is a utility class <tt>MeasurementUnits</tt>
that has
a member <tt>ReadAsTime()</tt>, returning values in units of sample
blocks which
is the natural time unit in a BCI2000 system.
Writing a number followed by an "s" will allow the user to specify a
time value in
seconds; writing a number without the "s" will be interpreted as sample blocks.
Thus, our user friendly version of <tt>Initialize</tt> reads
<pre>
void LPFilter::Initialize()
{
// Get the time constant in units of a sample block's duration:
float timeConstant = MeasurementUnits::ReadAsTime( Parameter(
"LPTimeConstant" ) );
// Convert it into units of a sample's duration:
timeConstant *= Parameter( "SampleBlockSize" );

mDecayFactor = ::exp( -1.0 / timeConstant );
mPreviousOutput.clear();
}
</pre>
==The <tt>Preflight</tt> function==
Up to now, we have not considered any error conditions that might occur
during
execution of our filter code. Scanning through the <tt>Process</tt>
and
<tt>Initialize</tt> code, we identify a number of implicit
assumptions:

#The time constant is not zero -- otherwise, a division by zero will occur.
#The time constant is not negative -- otherwise, the output signal is no longer guaranteed to be finite, and a numeric overflow may occur.
#Input and output signal pointers are assumed to point to valid locations in memory.
#The output signal is assumed to hold at least as much data as the input signal contains.
The first two assumptions may be violated if a user enters an illegal
value into the LPTimeConstant parameter; we need to make sure that an
error
is reported, and no code is executed that depends on these two
assumptions.
The third assumption will hold if the framework code does what it is
supposed
to do, so we do not need to check for it.
For the last assumption, we request an appropriate output signal from
the
<tt>Preflight</tt> function. Thus, the <tt>Preflight</tt> code reads
<pre>
void LPFilter::Preflight( const SignalProperties& inputProperties,
SignalProperties& outputProperties ) const
{
float LPTimeConstant
= MeasurementUnits::ReadAsTime( Parameter( "LPTimeConstant" ) );
LPTimeConstant *= Parameter( "SampleBlockSize" );
// The PreflightCondition macro will automatically generate an error
// message if its argument evaluates to false.
// However, we need to make sure that its argument is user-readable
// -- this is why we chose a variable name that matches the
parameter
// name.
PreflightCondition( LPTimeConstant > 0 );
// Alternatively, we might write:
if( LPTimeConstant <= 0 )
bcierr << "The LPTimeConstant parameter must be greater 0" << endl;

// Request output signal properties:
outputProperties = inputProperties;
}
</pre>

==Constructor and destructor==
Because we do not explicitly acquire resources, nor perform
asynchronous
operations, there is nothing to be done inside the <tt>LPFilter</tt>
''destructor'' .
Our ''constructor'' will contain initializers for the members we
declared,
and a BCI2000 parameter definition for LPTimeConstant:
<pre>
LPFilter::LPFilter()
: mDecayFactor( 0 ),
mPreviousOutput( 0 )
{
BEGIN_PARAMETER_DEFINITIONS
"Filtering float LPTimeConstant= 16s"
" 16s 0 0 // time constant for the low pass filter in blocks or
seconds",
END_PARAMETER_DEFINITIONS
}

LPFilter::~LPFilter()
{
}
</pre>

==Filter instantiation==
To have our filter instantiated in a signal processing module, we add
a line
containing a <tt>Filter</tt> statement to the module's
<tt>PipeDefinition.cpp</tt>.
This statement expects a string parameter which is used to determine
the filter's
position in the filter chain.
If we want to use the filter in the AR Signal Processing module, and
place it after
the <tt>SpatialFilter</tt>, we add
<pre>
#include "LPFilter.h"
...
Filter( LPFilter, 2.B1 );
</pre>
to the file <tt>SignalProcessing/AR/PipeDefinition.cpp</tt>.
Now, if we compile and link the AR Signal Processing module, we get an
"unresolved
external" linker error that reminds us to add our
<tt>LPFilter.cpp</tt> to that module's project.

==Visualizing filter output==
In order to present the LPFilter's output signal in an operator window, we introduce a member of type
<tt>GenericVisualization</tt>
into our filter class, adding
<pre>
#include "GenericVisualization.h"
...
class LPFilter : public GenericFilter
{
...
private:
...
GenericVisualization mSignalVis;
};
...
</pre>
<tt>GenericVisualization</tt>'s constructor takes a one-byte
visualization
ID as a parameter; we need to get a unique ID in order to get our data
routed
to the correct operator window.
This can be done by adding an entry
<tt>LowPass</tt> at the end of the <tt>SOURCEID</tt> enumeration in
the file
<tt>shared/defines.h</tt>.
Then, in our <tt>.cpp</tt> file, we add
<pre>
#include "defines.h"
</pre>
and change the <tt>LPFilter</tt> constructor to read
<pre>
LPFilter::LPFilter()
: mDecayFactor( 0 ),
mPreviousOutput( 0 ),
mSignalVis( SOURCEID::LowPass )
{
BEGIN_PARAMETER_DEFINITIONS
"Filtering float LPTimeConstant= 16s"
" 16s 0 0 // time constant for the low pass filter in blocks or
seconds",
"Visualize int VisualizeLowPass= 1"
" 1 0 1 // visualize low pass output signal (0=no, 1=yes)",
"Visualize int LPVisMin= -100 0 0 0 "
"// low pass visualization min value",
"Visualize int LPVisMax= 100 0 0 0 "
"// low pass visualization max value",
END_PARAMETER_DEFINITIONS
}
</pre>
where LPVisMin and LPVisMax parameters determine the default scaling
of the
displayed signal; these parameters may even be reversed, resulting in
an inversion
of the displayed signal, so there is no need to check these parameters
from
<tt>Preflight</tt>.
In <tt>Initialize</tt>, we add
<pre>
mSignalVis.Send( CFGID::WINDOWTITLE, "Low Pass" );
mSignalVis.Send( CFGID::graphType, CFGID::polyline );
mSignalVis.Send( CFGID::MINVALUE, Parameter( "LPVisMin" ) );
mSignalVis.Send( CFGID::MAXVALUE, Parameter( "LPVisMax" ) );
mSignalVis.Send( CFGID::NUMSAMPLES, 2 * Parameter( "SamplingRate" ) );
</pre>
Finally, to update the display in regular intervals, we add the
following at the
end of <tt>Process</tt>:
<pre>
if( Parameter( "VisualizeLowPass" ) == 1 )
mSignalVis.Send( output );
</pre>
We might also send data to the already existing task log memo window,
adding
another member
<pre>
GenericVisualization mTaskLogVis;
</pre>
initializing it with
<pre>
LPFilter::LPFilter()
: ...
mTaskLogVis( SOURCEID::TASKLOG )
{
...
}
</pre>
and, from inside <tt>Process</tt>, writing some text to it as in
<pre>
if( ( *output )( 0, 0 ) > 10 )
{
ostringstream oss;
oss << "LPFilter: (0,0) entry of output exceeds 10 and is "
<< ( *output )( 0, 0 );
mTaskLogVis.Send( oss.str() );
}
</pre>

Programming Tutorial:Implementing a Signal Processing Filter

2007-05-22T15:54:12Z

Atennissen:

This tutorial shows you how to derive a new filter class from
<tt>GenericFilter</tt>, how to check preconditions, initialize your
filter,
and process data.
It will also show you how to visualize a filter's output signal,
presenting it
to the operator user.

==A simple low pass filter==
We want to implement a low pass filter with a time constant <math>T</math> (given
in units
of a sample's duration), a sequence <math>S_{in,t}</math> as input and a sequence
<math>S_{out,t}</math> as output (where <math>t</math> is an sample index proportional to
time), and obeying

<math>S_{out, 0} = \left( 1-e^{-1/T} \right) S_{in, 0}</math>

<math>S_{out, t} = e^{-1/T} S_{out, t-1} + \left( 1-e^{-1/T} \right) S_{in, t}</math>

==The filter skeleton==

The resulting filter class is to be called <tt>LPFilter</tt>.
We create two new files, <tt>LPFilter.h</tt>, and
<tt>LPFilter.cpp</tt>,
and put a minimal filter declaration into <tt>LPFilter.h</tt>:

<pre>
#ifndef LP_FILTER_H
#define LP_FILTER_H

#include "GenericFilter.h"

class LPFilter : public GenericFilter
{
public:
LPFilter();
~LPFilter();

void Preflight( const SignalProperties&, SignalProperties& ) const;
void Initialize();
void Process( const GenericSignal*, GenericSignal* );
};
#endif // LP_FILTER_H
</pre>
Into <tt>LPFilter.cpp</tt> we put the lines
<pre>
#include "PCHIncludes.h" // Make the compiler's Pre-Compiled Headers feature happy
#pragma hdrstop

#include "LPFilter.h"

#include "MeasurementUnits.h"
#include "BCIError.h"
#include <vector>
#include <cmath>

using namespace std;
</pre>

==The <tt>Process</tt> function==
When implementing a filter, a good strategy is to begin with the
<tt>Process</tt>
function, and to consider the remaining class member functions mere
helpers, mainly
determined by the code of <tt>Process</tt>.
So we convert the filter prescription into the <tt>Process</tt>
code, introducing member variables ''ad hoc'' , ignoring possible
error
conditions, and postponing efficiency considerations:
<pre>
void LPFilter::Process( const GenericSignal* input, GenericSignal* output )
{
// This implements the prescription's second line for all channels:
for( size_t channel = 0; channel < input->Channels(); ++channel )
{
for( size_t sample = 0; sample < input->Elements(); ++sample )
{
mPreviousOutput[ channel ] *= mDecayFactor;
mPreviousOutput[ channel ] +=
( *input )( channel, sample ) * ( 1.0 - mDecayFactor );
( *output )( channel, sample ) = mPreviousOutput[ channel ];
}
}
}
</pre>

==The <tt>Initialize</tt> member function==
As you will notice when comparing <tt>Process</tt> to the equations above, we introduced member variables representing these sub-expressions:

<math>\texttt{mPreviousOutput[ ]}= S_{out, t-1}</math>

<math>\texttt{mDecayFactor} = e^{-1/T}</math>

We introduce these members into the class declaration, adding the
following lines
after the <tt>Process</tt> declaration:
<pre>
private:
float mDecayFactor;
std::vector<float> mPreviousOutput;
</pre>
The next step is to initialize these member variables, introducing
filter
parameters as needed. This is done in the <tt>Initialize</tt> member
function --
we write it down without considering possible error conditions:
<pre>
void LPFilter::Initialize( const SignalProperties& inputProperties,
const SignalProperties& outputProperties )
{
// This will initialize all elements with 0,
// implementing the first line of the filter prescription:
mPreviousOutput.resize( inputProperties.Channels(), 0 );

float timeConstant = Parameter( "LPTimeConstant" );
mDecayFactor = ::exp( -1.0 / timeConstant );
mPreviousOutput.clear();
}
</pre>
Now this version is quite inconvenient for a user going to configure our filter
-- the time constant is given in units of a sample's duration, resulting in a
need to re-configure each time the sampling rate is changed.
A better idea is to let the user choose whether to give the
time constant in seconds or in sample blocks.
To achieve this, there is a utility class <tt>MeasurementUnits</tt>
that has
a member <tt>ReadAsTime()</tt>, returning values in units of sample
blocks which
is the natural time unit in a BCI2000 system.
Writing a number followed by an "s" will allow the user to specify a
time value in
seconds; writing a number without the "s" will be interpreted as sample blocks.
Thus, our user friendly version of <tt>Initialize</tt> reads
<pre>
void LPFilter::Initialize()
{
// Get the time constant in units of a sample block's duration:
float timeConstant = MeasurementUnits::ReadAsTime( Parameter(
"LPTimeConstant" ) );
// Convert it into units of a sample's duration:
timeConstant *= Parameter( "SampleBlockSize" );

mDecayFactor = ::exp( -1.0 / timeConstant );
mPreviousOutput.clear();
}
</pre>
==The <tt>Preflight</tt> function==
Up to now, we have not considered any error conditions that might occur
during
execution of our filter code. Scanning through the <tt>Process</tt>
and
<tt>Initialize</tt> code, we identify a number of implicit
assumptions:

#The time constant is not zero -- otherwise, a division by zero will occur.
#The time constant is not negative -- otherwise, the output signal is no longer guaranteed to be finite, and a numeric overflow may occur.
#Input and output signal pointers are assumed to point to valid locations in memory.
#The output signal is assumed to hold at least as much data as the input signal contains.
The first two assumptions may be violated if a user enters an illegal
value into the LPTimeConstant parameter; we need to make sure that an
error
is reported, and no code is executed that depends on these two
assumptions.
The third assumption will hold if the framework code does what it is
supposed
to do, so we do not need to check for it.
For the last assumption, we request an appropriate output signal from
the
<tt>Preflight</tt> function. Thus, the <tt>Preflight</tt> code reads
<pre>
void LPFilter::Preflight( const SignalProperties& inputProperties,
SignalProperties& outputProperties ) const
{
float LPTimeConstant
= MeasurementUnits::ReadAsTime( Parameter( "LPTimeConstant" ) );
LPTimeConstant *= Parameter( "SampleBlockSize" );
// The PreflightCondition macro will automatically generate an error
// message if its argument evaluates to false.
// However, we need to make sure that its argument is user-readable
// -- this is why we chose a variable name that matches the
parameter
// name.
PreflightCondition( LPTimeConstant > 0 );
// Alternatively, we might write:
if( LPTimeConstant <= 0 )
bcierr << "The LPTimeConstant parameter must be greater 0" << endl;

// Request output signal properties:
outputProperties = inputProperties;
}
</pre>

==Constructor and destructor==
Because we do not explicitly acquire resources, nor perform
asynchronous
operations, there is nothing to be done inside the <tt>LPFilter</tt>
''destructor'' .
Our ''constructor'' will contain initializers for the members we
declared,
and a BCI2000 parameter definition for LPTimeConstant:
<pre>
LPFilter::LPFilter()
: mDecayFactor( 0 ),
mPreviousOutput( 0 )
{
BEGIN_PARAMETER_DEFINITIONS
"Filtering float LPTimeConstant= 16s"
" 16s 0 0 // time constant for the low pass filter in blocks or
seconds",
END_PARAMETER_DEFINITIONS
}

LPFilter::~LPFilter()
{
}
</pre>

==Filter instantiation==
To have our filter instantiated in a signal processing module, we add
a line
containing a <tt>Filter</tt> statement to the module's
<tt>PipeDefinition.cpp</tt>.
This statement expects a string parameter which is used to determine
the filter's
position in the filter chain.
If we want to use the filter in the AR Signal Processing module, and
place it after
the <tt>SpatialFilter</tt>, we add
<pre>
#include "LPFilter.h"
...
Filter( LPFilter, 2.B1 );
</pre>
to the file <tt>SignalProcessing/AR/PipeDefinition.cpp</tt>.
Now, if we compile and link the AR Signal Processing module, we get an
"unresolved
external" linker error that reminds us to add our
<tt>LPFilter.cpp</tt> to that module's project.

==Visualizing filter output==
In order to present the LPFilter's output signal in an operator window, we introduce a member of type
<tt>GenericVisualization</tt>
into our filter class, adding
<pre>
#include "GenericVisualization.h"
...
class LPFilter : public GenericFilter
{
...
private:
...
GenericVisualization mSignalVis;
};
...
</pre>
<tt>GenericVisualization</tt>'s constructor takes a one-byte
visualization
ID as a parameter; we need to get a unique ID in order to get our data
routed
to the correct operator window.
This can be done by adding an entry
<tt>LowPass</tt> at the end of the <tt>SOURCEID</tt> enumeration in
the file
<tt>shared/defines.h</tt>.
Then, in our <tt>.cpp</tt> file, we add
<pre>
#include "defines.h"
</pre>
and change the <tt>LPFilter</tt> constructor to read
<pre>
LPFilter::LPFilter()
: mDecayFactor( 0 ),
mPreviousOutput( 0 ),
mSignalVis( SOURCEID::LowPass )
{
BEGIN_PARAMETER_DEFINITIONS
"Filtering float LPTimeConstant= 16s"
" 16s 0 0 // time constant for the low pass filter in blocks or
seconds",
"Visualize int VisualizeLowPass= 1"
" 1 0 1 // visualize low pass output signal (0=no, 1=yes)",
"Visualize int LPVisMin= -100 0 0 0 "
"// low pass visualization min value",
"Visualize int LPVisMax= 100 0 0 0 "
"// low pass visualization max value",
END_PARAMETER_DEFINITIONS
}
</pre>
where LPVisMin and LPVisMax parameters determine the default scaling
of the
displayed signal; these parameters may even be reversed, resulting in
an inversion
of the displayed signal, so there is no need to check these parameters
from
<tt>Preflight</tt>.
In <tt>Initialize</tt>, we add
<pre>
mSignalVis.Send( CFGID::WINDOWTITLE, "Low Pass" );
mSignalVis.Send( CFGID::graphType, CFGID::polyline );
mSignalVis.Send( CFGID::MINVALUE, Parameter( "LPVisMin" ) );
mSignalVis.Send( CFGID::MAXVALUE, Parameter( "LPVisMax" ) );
mSignalVis.Send( CFGID::NUMSAMPLES, 2 * Parameter( "SamplingRate" ) );
</pre>
Finally, to update the display in regular intervals, we add the
following at the
end of <tt>Process</tt>:
<pre>
if( Parameter( "VisualizeLowPass" ) == 1 )
mSignalVis.Send( output );
</pre>
We might also send data to the already existing task log memo window,
adding
another member
<pre>
GenericVisualization mTaskLogVis;
</pre>
initializing it with
<pre>
LPFilter::LPFilter()
: ...
mTaskLogVis( SOURCEID::TASKLOG )
{
...
}
</pre>
and, from inside <tt>Process</tt>, writing some text to it as in
<pre>
if( ( *output )( 0, 0 ) > 10 )
{
ostringstream oss;
oss << "LPFilter: (0,0) entry of output exceeds 10 and is "
<< ( *output )( 0, 0 );
mTaskLogVis.Send( oss.str() );
}
</pre>

P300 Off-line Analysis Tutorial

2007-05-22T15:38:09Z

Atennissen:

P300 Off-line Analysis Tutorial

2007-05-10T20:32:36Z

Atennissen:

P300 Off-line Analysis Tutorial

2007-05-10T20:25:17Z

Atennissen:

Programming Tutorial:Implementing a Source Module

2007-05-10T19:48:58Z

Atennissen:

Data acquisition modules are factored into code required for any
hardware,
and code required to access a specific hardware.
You provide a function that waits for and reads A/D
data (line 3 in the EEG source pseudo code of [[Modules:Data Acquisition]]),
together with some helper functions that perform initialization and
cleanup tasks.
Together these functions form a class derived from
<tt>GenericADC</tt>.

==Scenario==
Your ''Tachyon Corporation'' A/D card comes with a C-style
software interface
declared in a header file <tt>"TachyonLib.h"</tt> that consists of
three
functions
<pre>
#define TACHYON_NO_ERROR 0
int TachyonStart( int inSamplingRate, int inNumberOfChannels );
int TachyonStop( void );
int TachyonWaitForData( short** outBuffer, int inCount );
</pre>
From the library help file, you learn that <tt>TachyonStart</tt>
configures the
card and starts acquisition to some internal buffer; that
<tt>TachyonStop</tt>
stops acquisition to the buffer, and that <tt>TachyonWaitForData</tt>
will block execution until the specified amount of data has been
acquired, and
that it will return a pointer to a buffer containing the data in its
first argument.
Each of the functions will return zero if everything went well, otherwise
some error value will be given.
Luckily, ''Tachyon Corporation'' gives you just
what you need for a BCI2000 source module, so implementing the ADC
class is
quite straightforward.

==Writing the ADC Header File==
In your class' header file, <tt>"TachyonADC.h"</tt>, you write
<pre>
#ifndef TACHYON_ADC_H
#define TACHYON_ADC_H

#include "GenericADC.h"

class TachyonADC : public GenericADC
{
public:
TachyonADC();
~TachyonADC();

void Preflight( const SignalProperties&, SignalProperties& ) const;
void Initialize();
void Process( const GenericSignal*, GenericSignal* );
void Halt();

private:
int mSourceCh,
mSampleBlockSize,
mSamplingRate;
};
#endif // TACHYON_ADC_H
</pre>

==ADC Implementation==
In the .cpp file, you will need some <tt>#includes</tt>, and a filter
registration:
<pre>
#include "TachyonADC.h"
#include "Tachyon/TachyonLib.h"
#include "BCIError.h"

using namespace std;

RegisterFilter( TachyonADC, 1 );
</pre>
From the constructor, you request parameters and states that your ADC
needs;
from the destructor, you call <tt>Halt</tt> to make sure that your
board stops
acquiring data whenever your class instance gets destructed:
<pre>
TachyonADC::TachyonADC()
: mSourceCh( 0 ),
mSampleBlockSize( 0 ),
mSamplingRate( 0 )
{
BEGIN_PARAMETER_DEFINITIONS
"Source int SourceCh= 64 64 1 128 "
"// this is the number of digitized channels",
"Source int SampleBlockSize= 16 5 1 128 "
"// this is the number of samples transmitted at a time",
"Source int SamplingRate= 128 128 1 4000 "
"// this is the sample rate",
END_PARAMETER_DEFINITIONS
}

TachyonADC::~TachyonADC()
{
Halt();
}
</pre>

==ADC Initialization==
Your <tt>Preflight</tt> function will check whether the board works
with the
parameters requested, and communicate the dimensions of its output
signal:
<pre>
void TachyonADC::Preflight( const SignalProperties&,
SignalProperties& outputProperties )
const
{
if( TACHYON_NO_ERROR !=
TachyonStart( Parameter( "SamplingRate" ), Parameter( "SourceCh" ) ) )
bcierr << "SamplingRate and/or SourceCh parameters are not compatible"
<< " with the A/D card"
<< endl;
TachyonStop();
outputProperties = SignalProperties( Parameter( "SourceCh" ),
Parameter( "SampleBlockSize" ),
SignalType::int16 );
}
</pre>
Here, the last argument of the <tt>SignalProperties</tt> constructor
determines not only the type of the signal propagated to the BCI2000
filters
but also the format of the <tt>dat</tt> file written by the source
module.
For the <tt>Initialize</tt> function, it will only be
called if
<tt>Preflight</tt> did not report any errors. If everything works
fine with
the parameters, you may skip any checks, and write
<pre>
void TachyonADC::Initialize()
{
mSourceCh = Parameter( "SourceCh" );
mSampleBlockSize = Parameter( "SampleBlockSize" );
mSamplingRate = Parameter( "SamplingRate" );
TachyonStart( mSamplingRate, mSourceCh );
}
</pre>
Balancing the <tt>TachyonStart</tt> call in the <tt>Initialize</tt> function,
your <tt>Halt</tt> function should stop all asynchronous activity that
your ADC code initiates:
<pre>
void TachyonADC::Halt()
{
TachyonStop();
}
</pre>

==Data Acquisition==
Note that the function may not return unless the output signal is filled with data, so it is
crucial that <tt>TachyonWaitForData</tt> is a blocking function.
(If your card does not provide such a function, and you need to poll
for data, don't forget to call <tt>Sleep( 0 )</tt> inside your polling loop to
avoid tying up the CPU.)
<pre>
void TachyonADC::Process( const GenericSignal*, GenericSignal* outputSignal )
{
int valuesToRead = mSampleBlockSize * mSourceCh;
short* buffer;
if( TACHYON_NO_ERROR == TachyonWaitForData( &buffer, valuesToRead ) )
{
int i = 0;
for( int channel = 0; channel < mSourceCh; ++channel )
for( int sample = 0; sample < mSampleBlockSize; ++sample )
( *outputSignal )( channel, sample ) = buffer[ i++ ];
}
else
bcierr << "Error reading data" << endl;
}
</pre>

==Finished==
You are done! Use your <tt>TachyonADC.cpp</tt> to replace the
<tt>GenericADC</tt>
descendant in an existing source module, add the
<tt>TachyonADC.lib</tt> shipped
with your card to the project, compile, link, and find the bugs...

Mu Rhythm Off-line Analysis Tutorial

2007-05-10T19:47:24Z

Atennissen:

== Starting an Analysis Session ==

Every recording session has its own history. It is very difficult to say in advance what might happen during the recording. So we will assume that everything was perfect (the subject collaborated, no channel went lost, etc); later on we will consider the main causes of contamination, how to recognize it and what to do.

If the recording session runs smoothly, you should now have in the folder ''\TestData\Data\Mu'', two files named ''ALFAS006R01.dat'' and ''ALFAS006R02.dat'', corresponding to two of the eight runs usually recorded, respectively.

Before you start the analysis you should locate the correct montage file on your hard disk. This is a file that describes the list of channels that were acquired. In this tutorial we will use ''Complete_Montage(suggested choice).mmf'', which is located in the folder ''\TestData\Montage''. If you need to edit the *.mmf file, check its data format.

== Opening Files with Mario ==

After having run mario.exe, press "Select Data Files".

[[Image:Mu Rhy5.jpg]]

A dialog window will ask you to select the dat files. You can either select a single data file, or select multiple files. This time, we will select all files in the dataset.

A green box will surround the Raw Data box in the main window.

As an optional (but recommended) operation, click on the LOAD MONTAGE button and choose the mmf file. This will allow you to see the labels of each channel and allow you to apply spatial filters that depend on the electrode position.

You can load an additional parameters file with choices different from those used during the experiment.

At this point, you can check that Mu is selected in the Analysis menu (indicating that a Mu dataset has been recognized) and click on the LOAD DATA button to confirm your choices. This will enable the EDIT CHANNEL LIST button that you can use to select the channels you want to include in your analysis.

== Selecting Channels ==

When you select the EDIT CHANNEL LIST button, two forms will show you the channel list (valid ones and not-valid ones) and an image showing valid channels and their location.

Clicking on Add and Remove buttons allows you to move a channel from one list to the other, enabling or disabling it.

== Selecting the Spatial Filter ==

Return to the main window, and you can choose which filter to apply for your analysis, selecting from the following filter choices:

:*RAW
:*CAR
:*Large Laplacian
:*Small Laplacian

Common Average Reference (CAR) will be fine for most of the situations.

We hope, soon, to release a user defined solution for any custom analysis.

== Feature Extraction Analysis ==

The Analysis field in the Feature Extraction panel will appear automatically according to the files loaded, while the Feature Extractor field shows the only currently possible choice.

You can view/edit analysis details by clicking on "Set Analysis Details" and "Set F.E. parameters"

This second form reports all the settings for the parametric (autoregressive) spectral estimation stage. Most of the values are set after the corresponding values used on-line (see BCI2000 setup for Mu). Using the settings in the figure, the analysis software will:

:* analyze data recorded at 200 Hz sampling rate
:* remove the mean value
:* sample the spectrum at points starting from 0 Hz to 60 Hz, every 0.2 Hz.
:* Identify an auroregressive model of order 16
:* average these values into 2 Hz wide bins
:* take a 1 s long epoch of data

You can modify these settings according to your aims. Changing the model order, for instance, brings sometimes to interesting results. Remember though that in the online version, spectral estimation is performed in epochs as short as 200 ms (i.e. 40 samples, at 200 Hz sampling rate), so you should avoid using a model order higher than half the samples available in the epoch.
When you are finished, remember to confirm your choices by slecting DONE.

In addition, a button in the Spectral Extimation frame allows you to revert to the original values.

Altogether you have to specify:

:* which data (in each trial) you want to take into account. Mu will only use the part of the trial when the cursor is visible, while MuExtended will take into account all the period when the target is visible. To learn more, see section D2Box Application States
:* If you have made an artifact rejection (or noted on the run sheet during the acquisition which trials contain artifacts), you can instruct the software not to use them
:* Finally, you must decide how the software must extract EEG epochs from the continuous data
The epochs can be partially overlapped. This attenuates the data loss in case the length of a trial is not a multiple of the length of an epoch.

The percentage of overlap can be set both in Mario GUI and in any batch script. It is equal to the value of the ''MU_params.overlapping'' variable and the corresponding GUI field can be found by clickiing on ''Set Analysis Details'' on MARIO main form.

At this point you can start the analysis by clicking on the Evaluate and Plot button.

[[Image:Mu Rhy8.jpg]]

== View Results ==

The first figure that appears is the R-square matrix (channels x frequency bins)
=== R-square Matrix ===

The r-square matrix highlights the most relevant spectral features for the separation of the two classes of EEG - Cursor Up (target 1) and Cursor Down (target 2).

[[Image:Mu Rhy8.jpg]]

Each row of the matrix is related to a single channel, while a column represents a frequency bin (labeled with its central frequency). The color codes the statistical significance of the difference between the two kinds of evoked potentials.

Thus a red color would mean that, on that channel and for that frequency, the "Up" EEG is significantly synchronized with respect to "Down" EEG.

Clicking on a cell of the matrix will open two more windows:

* Power spectral distribution of the selected channel
* Topographic maps at the selected frequency.

You can choose whether to overwrite or to put the most recently evoked figures beside the previous one. Two sets of waveform/topography figures are available, and are linked to the click of the left, the central or right mouse button.
Left Button will create/overwrite a first figure, Right Button will do the same on a second figure, the Central Button will always open a new plot.

=== Power Spectra and Topographic Plots ===

In the lower panel you can find the spectral density of power for both classes of EEG. The Blue line refers to the "Up" condition, while the Red line refers to the "Down" condition.
We can see that at the vertex the "Down" condition is generally more synchronized than the "Up", with maximal difference in the beta band, consistently with what is shown by the R-square matrix. The proportinality between spectral differences and R-square is anyway rough, since r-square is sensitive to the dispersion (variance) of single trials; thus, small differences between spectra could bring to a high r-square, if they were very reproducible.

The peak around 50 Hz is due to mains disturbance; this also allows you to appreciate the leakage introduced by the spectral estimation.

[[Image:Mu_Rhy9.jpg]]

Over the spectral graph, a topographic plot shows the scalp distribution of the r-square.

The color coding is the same as the r-square matrix figure, and values on each channel are interpolated to create a continuous bidimensional map. The higher the number of electrodes, the more accurate is the map. With Surface Laplacian spatial filtering, the number of channels shown on the scalp may not coincide with the whole number of electrodes, since the value of the laplacian is not computed on the border channels.

===Interpretation of the Results===

The first step in the preliminary analysis of P300 BCI data is to find the absolute maximum of r-square. This simple statement must be mediated with a proper knowledge of physiological phenomena. In fact, we do not expect any sensorimotor activity at 3 Hz, so if the absolute maximum is at that frequency, you must suspect that it is actually an artifact. The same holds true if the spatial localization of the peak is far away from the centro-parietal electrodes.

From a practical point of view, it is not important, now, to understand the reasons that different components explain the desynchronization peak on Cz at 17 Hz, so long as we are confident that this component is stable enough to be exploitable during the next session to control the cursor.

The absolute value of R-square is mathematically bound to lie in the interval between 0 and 1. Values above 0.4 allow a rate of missed target on the order of a few percent. Values around 0.1 are promising. Values below 0.03 are possibly due to random fluctuations. All the previous figures refer to analyses made on 240 trials.
''Beware of artifacts!''

During the acquisition, you should be particularly careful to avoid artifacts. While EOG and blink artifacts are confined to very low frequencies, EMG artifacts are mostly on the beta band and could largely overlap with the frequency band that characterizes the mu rhythm.

If contaminated data was acquired, then you have two problems:

:* Realize that EMG is superimposed on the to data
:* Distinguish between spectral modulation introduced by EEG and by EMG

The first task is not as trivial as it might appear. If you did not acquire the data yourself (or even if you did) you might complete the analysis procedure without giving a single glance to the raw data. So you must be particularly careful when you analyze the R-square maps, and always check if the peak you are seeing might be due to an artifact.

Discriminant features between EEG and EMG are both in the frequency distribution and in the spatial distribution.

EMG that strongly affects the recordings is mostly generated by muscles at the forehead or close to the ears/jaws. Thus, their spatial distribution is such that the most responsive channel is one of those at the border of the montage. Of course, due to volume conduction, the effects can be seen even on electrodes on the opposite part of the montage, but they show a degrading pattern.
On the other hand, a peak that shows its maximum on a central channel, can hardly be generated by a muscle or by other non-cephalic source.

The spectrum of EEG is mainly concentrated in the alpha band, with a possible flatter and lower peak in beta. With the exception of the beta peak/plateau, the EEG spectrum decreases almost linearly (if measured in dB) after 12 Hz.
On the other hand, the EMG spectrum becomes significant at about 20 Hz and is still very high at the highest frequencies we usually analyze (60 Hz). A spectrum with a pattern more similar to the latter, may indicate that non-EEG activity is present in the data.

==Improving the Analysis==

The first cause of an unsuccessful analysis is poor quality of the recording. For this reason it is highly recommended that, at least for the first experiments, the subject be highly motivated and cooperative. If this is the case, data of low quality are usually present in one or a few runs. And if the experimenter is careful enough, he/she should have noted the occurrence of strong artifacts on the run sheet.
In this case, the next step is to repeat an unsatisfactory data analysis after having excluded the (putative) bad runs.
To do this, just go back to the file selection dialog, choose LOAD Data again and load only the runs that you believe are clean. The number of runs should not be too low (as a rule of thumb, the data set should contain at least 100 trials), otherwise the r-square statistical analysis would loose sensitivity.

== Analyzing the Screening ==

The screening experiment is not different from a regular training session, from the point of view of data format. You will have four sets (horizontal movement, horizontal imagination, vertical movement, and vertical imagination) of three runs, containing EEG acquired in two conditions (up and down, or left and right).

Start analyzing the vertical movement execution, and mark a few possible responsive features. The analysis on the vertical movement imagination should confirm (though with a lower R-square) those that are actually related to sensorimotor cognitive states.

In the case that no reliable responsive EEG feature is found, the analysis can be repeated on the horizontal dataset.

If both the vertical and horizontal dataset show responsive features, and these are different, the subject should be trained for several sessions on vertical training until he/she decreases the error rate below 10%. At that point, the training of the horizontal modulation can begin, with the aim that, the subject will eventually control both the vertical and the horizontal simultaneously in a two-dimensional task.

==Conclusions==

If you are confident that you have found a significant difference between conditions that is due to EEG rather than an artifact, and that reflects a cognitive process that is likely to be reproduced (or even enhanced with training) in the next session, you have reached your goal.
The next time the same subject practices with the D2Box Application, you will have to change the MUD matrix so that it reflects the feature that you just outlined.

==Troubleshooting==

Some OpenGL drivers may sometimes show defective figures like the following:

[[Image:Defective.jpg]]

Matlab customers can get around this problem using this simple procedure:
:* Select the defective figure window
:* Go to the Matlab Command Window
:* Execute one of the following command line:
:**set(gcf, 'Renderer', 'Painters')
:**set(gcf, 'Renderer', 'zbuffer')

The figure will be a plot using a different renderer (Painters or zBuffer).

Mu Rhythm Off-line Analysis Tutorial

2007-05-10T19:45:38Z

Atennissen:

== Starting an Analysis Session ==

Every recording session has its own history. It is very difficult to say in advance what might happen during the recording. So we will assume that everything was perfect (the subject collaborated, no channel went lost, etc); later on we will consider the main causes of contamination, how to recognize it and what to do.

If the recording session runs smoothly, you should now have in the folder ''\TestData\Data\Mu'', two files named ''ALFAS006R01.dat'' and ''ALFAS006R02.dat'', corresponding to two of the eight runs usually recorded, respectively.

Before you start the analysis you should locate the correct montage file on your hard disk. This is a file that describes the list of channels that were acquired. In this tutorial we will use ''Complete_Montage(suggested choice).mmf'', which is located in the folder ''\TestData\Montage''. If you need to edit the *.mmf file, check its data format.

== Opening Files with Mario ==

After having run mario.exe, press "Select Data Files".

[[Image:Mu Rhy5.jpg]]

A dialog window will ask you to select the dat files. You can either select a single data file, or select multiple files. This time, we will select all files in the dataset.

A green box will surround the Raw Data box in the main window.

As an optional (but recommended) operation, click on the LOAD MONTAGE button and choose the mmf file. This will allow you to see the labels of each channel and allow you to apply spatial filters that depend on the electrode position.

You can load an additional parameters file with choices different from those used during the experiment.

At this point, you can check that Mu is selected in the Analysis menu (indicating that a Mu dataset has been recognized) and click on the LOAD DATA button to confirm your choices. This will enable the EDIT CHANNEL LIST button that you can use to select the channels you want to include in your analysis.

== Selecting Channels ==

When you select the EDIT CHANNEL LIST button, two forms will show you the channel list (valid ones and not-valid ones) and an image showing valid channels and their location.

Clicking on Add and Remove buttons allows you to move a channel from one list to the other, enabling or disabling it.

== Selecting the Spatial Filter ==

Return to the main window, and you can choose which filter to apply for your analysis, selecting from the following filter choices:

:*RAW
:*CAR
:*Large Laplacian
:*Small Laplacian

Common Average Reference (CAR) will be fine for most of the situations.

We hope, soon, to release a user defined solution for any custom analysis.

== Feature Extraction Analysis ==

The Analysis field in the Feature Extraction panel will appear automatically according to the files loaded, while the Feature Extractor field shows the only currently possible choice.

You can view/edit analysis details by clicking on "Set Analysis Details" and "Set F.E. parameters"

This second form reports all the settings for the parametric (autoregressive) spectral estimation stage. Most of the values are set after the corresponding values used on-line (see BCI2000 setup for Mu). Using the settings in the figure, the analysis software will:

:* analyze data recorded at 200 Hz sampling rate
:* remove the mean value
:* sample the spectrum at points starting from 0 Hz to 60 Hz, every 0.2 Hz.
:* Identify an auroregressive model of order 16
:* average these values into 2 Hz wide bins
:* take a 1 s long epoch of data

You can modify these settings according to your aims. Changing the model order, for instance, brings sometimes to interesting results. Remember though that in the online version, spectral estimation is performed in epochs as short as 200 ms (i.e. 40 samples, at 200 Hz sampling rate), so you should avoid using a model order higher than half the samples available in the epoch.
When you are finished, remember to confirm your choices by slecting DONE.

In addition, a button in the Spectral Extimation frame allows you to revert to the original values.

Altogether you have to specify:

:* which data (in each trial) you want to take into account. Mu will only use the part of the trial when the cursor is visible, while MuExtended will take into account all the period when the target is visible. To learn more, see section D2Box Application States
:* If you have made an artifact rejection (or noted on the run sheet during the acquisition which trials contain artifacts), you can instruct the software not to use them
:* Finally, you must decide how the software must extract EEG epochs from the continuous data
The epochs can be partially overlapped. This attenuates the data loss in case the length of a trial is not a multiple of the length of an epoch.

The percentage of overlap can be set both in Mario GUI and in any batch script. It is equal to the value of the ''MU_params.overlapping'' variable and the corresponding GUI field can be found by clickiing on ''Set Analysis Details'' on MARIO main form.

At this point you can start the analysis by clicking on the Evaluate and Plot button.

[[Image:Mu Rhy8.jpg]]

== View Results ==

The first figure that appears is the R-square matrix (channels x frequency bins)
=== R-square Matrix ===

The r-square matrix highlights the most relevant spectral features for the separation of the two classes of EEG - Cursor Up (target 1) and Cursor Down (target 2).

[[Image:Mu Rhy8.jpg]]

Each row of the matrix is related to a single channel, while a column represents a frequency bin (labeled with its central frequency). The color codes the statistical significance of the difference between the two kinds of evoked potentials.

Thus a red color would mean that, on that channel and for that frequency, the "Up" EEG is significantly synchronized with respect to "Down" EEG.

Clicking on a cell of the matrix will open two more windows:

* Power spectral distribution of the selected channel
* Topographic maps at the selected frequency.

You can choose whether to overwrite or to put the most recently evoked figures beside the previous one. Two sets of waveform/topography figures are available, and are linked to the click of the left, the central or right mouse button.
Left Button will create/overwrite a first figure, Right Button will do the same on a second figure, the Central Button will always open a new plot.

=== Power Spectra and Topographic Plots ===

In the lower panel you can find the spectral density of power for both classes of EEG. The Blue line refers to the "Up" condition, while the Red line refers to the "Down" condition.
We can see that at the vertex the "Down" condition is generally more synchronized than the "Up", with maximal difference in the beta band, consistently with what is shown by the R-square matrix. The proportinality between spectral differences and R-square is anyway rough, since r-square is sensitive to the dispersion (variance) of single trials; thus, small differences between spectra could bring to a high r-square, if they were very reproducible.

The peak around 50 Hz is due to mains disturbance; this also allows you to appreciate the leakage introduced by the spectral estimation.

[[Image:Mu_Rhy9.jpg]]

Over the spectral graph, a topographic plot shows the scalp distribution of the r-square.

The color coding is the same as the r-square matrix figure, and values on each channel are interpolated to create a continuous bidimensional map. The higher the number of electrodes, the more accurate is the map. With Surface Laplacian spatial filtering, the number of channels shown on the scalp may not coincide with the whole number of electrodes, since the value of the laplacian is not computed on the border channels.

==Interpretation of the Results==

The first step in the preliminary analysis of P300 BCI data is to find the absolute maximum of r-square. This simple statement must be mediated with a proper knowledge of physiological phenomena. In fact, we do not expect any sensorimotor activity at 3 Hz, so if the absolute maximum is at that frequency, you must suspect that it is actually an artifact. The same holds true if the spatial localization of the peak is far away from the centro-parietal electrodes.

From a practical point of view, it is not important, now, to understand the reasons that different components explain the desynchronization peak on Cz at 17 Hz, so long as we are confident that this component is stable enough to be exploitable during the next session to control the cursor.

The absolute value of R-square is mathematically bound to lie in the interval between 0 and 1. Values above 0.4 allow a rate of missed target on the order of a few percent. Values around 0.1 are promising. Values below 0.03 are possibly due to random fluctuations. All the previous figures refer to analyses made on 240 trials.
''Beware of artifacts!''

During the acquisition, you should be particularly careful to avoid artifacts. While EOG and blink artifacts are confined to very low frequencies, EMG artifacts are mostly on the beta band and could largely overlap with the frequency band that characterizes the mu rhythm.

If contaminated data was acquired, then you have two problems:

:* Realize that EMG is superimposed on the to data
:* Distinguish between spectral modulation introduced by EEG and by EMG

The first task is not as trivial as it might appear. If you did not acquire the data yourself (or even if you did) you might complete the analysis procedure without giving a single glance to the raw data. So you must be particularly careful when you analyze the R-square maps, and always check if the peak you are seeing might be due to an artifact.

Discriminant features between EEG and EMG are both in the frequency distribution and in the spatial distribution.

EMG that strongly affects the recordings is mostly generated by muscles at the forehead or close to the ears/jaws. Thus, their spatial distribution is such that the most responsive channel is one of those at the border of the montage. Of course, due to volume conduction, the effects can be seen even on electrodes on the opposite part of the montage, but they show a degrading pattern.
On the other hand, a peak that shows its maximum on a central channel, can hardly be generated by a muscle or by other non-cephalic source.

The spectrum of EEG is mainly concentrated in the alpha band, with a possible flatter and lower peak in beta. With the exception of the beta peak/plateau, the EEG spectrum decreases almost linearly (if measured in dB) after 12 Hz.
On the other hand, the EMG spectrum becomes significant at about 20 Hz and is still very high at the highest frequencies we usually analyze (60 Hz). A spectrum with a pattern more similar to the latter, may indicate that non-EEG activity is present in the data.

==Improving the Analysis==

The first cause of an unsuccessful analysis is poor quality of the recording. For this reason it is highly recommended that, at least for the first experiments, the subject be highly motivated and cooperative. If this is the case, data of low quality are usually present in one or a few runs. And if the experimenter is careful enough, he/she should have noted the occurrence of strong artifacts on the run sheet.
In this case, the next step is to repeat an unsatisfactory data analysis after having excluded the (putative) bad runs.
To do this, just go back to the file selection dialog, choose LOAD Data again and load only the runs that you believe are clean. The number of runs should not be too low (as a rule of thumb, the data set should contain at least 100 trials), otherwise the r-square statistical analysis would loose sensitivity.

== Analyzing the Screening ==

The screening experiment is not different from a regular training session, from the point of view of data format. You will have four sets (horizontal movement, horizontal imagination, vertical movement, and vertical imagination) of three runs, containing EEG acquired in two conditions (up and down, or left and right).

Start analyzing the vertical movement execution, and mark a few possible responsive features. The analysis on the vertical movement imagination should confirm (though with a lower R-square) those that are actually related to sensorimotor cognitive states.

In the case that no reliable responsive EEG feature is found, the analysis can be repeated on the horizontal dataset.

If both the vertical and horizontal dataset show responsive features, and these are different, the subject should be trained for several sessions on vertical training until he/she decreases the error rate below 10%. At that point, the training of the horizontal modulation can begin, with the aim that, the subject will eventually control both the vertical and the horizontal simultaneously in a two-dimensional task.

==Conclusions==

If you are confident that you have found a significant difference between conditions that is due to EEG rather than an artifact, and that reflects a cognitive process that is likely to be reproduced (or even enhanced with training) in the next session, you have reached your goal.
The next time the same subject practices with the D2Box Application, you will have to change the MUD matrix so that it reflects the feature that you just outlined.

==Troubleshooting==

Some OpenGL drivers may sometimes show defective figures like the following:

[[Image:Defective.jpg]]

Matlab customers can get around this problem using this simple procedure:
:* Select the defective figure window
:* Go to the Matlab Command Window
:* Execute one of the following command line:
:**set(gcf, 'Renderer', 'Painters')
:**set(gcf, 'Renderer', 'zbuffer')

The figure will be a plot using a different renderer (Painters or zBuffer).

Programming Howto:SVN Client Setup

2007-05-10T19:26:10Z

Atennissen:

== Setting up TortoiseSVN to access the BCI2000 code repository ==
To set up TortoiseSVN and download the BCI2000 source code to your computer, follow these steps:
* Download the latest stable version from http://tortoisesvn.net/, and execute the installer program. This page has been written for version 1.40, but should be pretty independent of TortoiseSVN's version number.
* Create or pick an empty folder located on your machine’s harddrive. This will hold your working copy of the BCI2000 source tree, in an automatically created subfolder called "BCI2000."
* Right-click the folder you picked in the last step. From the context menu, choose the "SVN Checkout..." option – a dialog window appears.
* In the dialog window, enter the repository URL: <code><nowiki>http://www.bci2000.org/svn/trunk</nowiki></code>, choose "HEAD revision", and click OK.
* You will be prompted for your user name and password. This account is the same that you use to log into [http://{{SERVERNAME}}/tracproj Trac] and [[special:userlogin|into this Wiki]].

== Checking out older versions ==
If you think that the current version of BCI2000 is not working properly, or would like to work with an older version for some other reason, you may enter a "Revision number" into the checkout dialog.
The "Show Log" button will provide you with an overview of the latest changes and their associated revision numbers.

== Working on Branches ==
Branches are versions of the source code that are developed in parallel to the main code version, e.g. to incorporate new features without affecting the stable version that is intended for end users.
To checkout a branch called "myBranch", the repository URL would be:
<code><nowiki>http://www.bci2000.org/svn/branches/myBranch</nowiki></code>.
Otherwise, the checkout process remains the same.

==Troubleshooting==
* When trying to checkout, update, or commit, you get an error message: "PROPFIND request failed", "OPTIONS request failed", "could not connect to server", or the like.
:Quite likely, you are behind a firewall, and internet access is over a proxy server.
:To configure TortoiseSVN for use with a proxy server, right-click your desktop, choose TortoiseSVN->Settings->Network, check "Enable Proxy" and enter the appropriate information. If unsure, contact your local system administrator.
* You configured TortoiseSVN for use with a proxy server as described above. Now, checking out works fine, however on updates or commits, you get strange errors about failed requests.
:Your proxy server is not forwarding SVN's WebDAV requests correctly.
:To keep the proxy from interfering with the protocol, change your setup to use an encrypted connection:
:*Right-click on your source tree's top folder, choose TortoiseSVN->Relocate.
:*In the "to URL" edit field, modify <code><nowiki>http://</nowiki></code> to read <code><nowiki>https://</nowiki></code>.
:*On the first connection, TortoiseSVN will display a warning message: [[Image:TortoiseCertificateWarning.PNG]]
::Click "Accept permanently" to continue.

==See also==
*[[Using TortoiseSVN]]

[[Category:Howto]] [[Category:Development]] [[Category:Preliminaries]]

Programming Howto:SVN Client Setup

2007-05-10T19:24:30Z

Atennissen:

== Setting up TortoiseSVN to access the BCI2000 code repository ==
To set up TortoiseSVN and download the BCI2000 source code to your computer, follow these steps:
* Download the latest stable version from http://tortoisesvn.net/, and execute the installer program. This page has been written for version 1.40, but should be pretty independent of TortoiseSVN's version number.
* Create or pick an empty folder located on your machine’s harddrive. This will hold your working copy of the BCI2000 source tree, in an automatically created subfolder called "BCI2000."
* Right-click the folder you picked in the last step. From the context menu, choose the "SVN Checkout..." option – a dialog window appears.
* In the dialog window, enter the repository URL: <code><nowiki>http://www.bci2000.org/svn/trunk</nowiki></code>, choose "HEAD revision", and click OK.
* You will be prompted for your user name and password. This account is the same that you use to log into [http://{{SERVERNAME}}/tracproj Trac] and [[special:userlogin|into this Wiki]].

== Checking out older versions ==
If you think that the current version of BCI2000 is not working properly, or would like to work with an older version for some other reason, you may enter a "Revision number" into the checkout dialog.
The "Show Log" button will provide you with an overview of the latest changes and their associated revision numbers.

== Working on Branches ==
Branches are versions of the source code that are developed in parallel to the main code version, e.g. to incorporate new features without affecting the stable version that is intended for end users.
To check out a branch called "myBranch", the repository URL would be:
<code><nowiki>http://www.bci2000.org/svn/branches/myBranch</nowiki></code>.
Otherwise, the checkout process remains the same.

==Troubleshooting==
* When trying to checkout, update, or commit, you get an error message: "PROPFIND request failed", "OPTIONS request failed", "could not connect to server", or the like.
:Quite likely, you are behind a firewall, and internet access is over a proxy server.
:To configure TortoiseSVN for use with a proxy server, right-click your desktop, choose TortoiseSVN->Settings->Network, check "Enable Proxy" and enter the appropriate information. If unsure, contact your local system administrator.
* You configured TortoiseSVN for use with a proxy server as described above. Now, checking out works fine, however on updates or commits, you get strange errors about failed requests.
:Your proxy server is not forwarding SVN's WebDAV requests correctly.
:To keep the proxy from interfering with the protocol, change your setup to use an encrypted connection:
:*Right-click on your source tree's top folder, choose TortoiseSVN->Relocate.
:*In the "to URL" edit field, modify <code><nowiki>http://</nowiki></code> to read <code><nowiki>https://</nowiki></code>.
:*On the first connection, TortoiseSVN will display a warning message: [[Image:TortoiseCertificateWarning.PNG]]
::Click "Accept permanently" to continue.

==See also==
*[[Using TortoiseSVN]]

[[Category:Howto]] [[Category:Development]] [[Category:Preliminaries]]

Programming Reference:Filter Chain

2007-05-09T19:21:26Z

Atennissen:

==The Filter Chain==
As noted in the [[Programming Reference:GenericFilter Class|discussion]] of the <tt>GenericFilter::Process</tt> function, all <tt>GenericFilter</tt> descendants inside a BCI2000
module form a single chain of filters. Each filter's output forms the input of the
subsequent filter.

==Filter Instantiation==
Creating instances of all filter classes inside a module, and building the filter chain, is handled by the framework. However, it needs a hint to determine the sequence in which filters are to be arranged. In general, this hint consists of a single statement placed inside your filter's .cpp file:<pre>
RegisterFilter( MyFilter, 2.C );</pre>
The first argument to this statement is the class name of your filter;
the second argument is a string value (given without quotes) that determines the
relative position of your filter in the filter chain.
This is done by applying the simple rule that the filter positions in the chain match the alphanumeric sorting order of the associated postion strings of the filters.
This scheme allows you to place an additional filter between existing ones without changing the position strings of the existing filters.

==Signal Processing Filter Instantiation==
In principle, the above scheme allows to you add filters to a module's filter chain
without
modification to the existing source code, simply by adding a .cpp file
with a
<tt>RegisterFilter</tt> statement to the project.
However for Signal Processing modules, it is more desirable to
have an
explicit representation of the entire filter chain centralized in one
place.
So, for each individual Signal Processing module there is one file
<tt>PipeDefinition.cpp</tt> that defines the filter chain as a
sequence of
<tt>Filter</tt> statements (see [[Programming Tutorial:Implementing a Signal Processing Filter]] for
an
example).

Technical Reference:Parameter Definition

2007-05-09T19:18:57Z

Atennissen:

This page describes the concept of BCI2000 parameters, in conjunction with their textual representation as a "parameter line".

For information about how to access parameters from code, please refer to [[Programming Reference:Parameters]].
For information about individual parameters, please refer to [[User Reference:Parameters]].

==Parameter Concept==
Parameters are variables that primarily represent user configuration choices. Typical entities encoded by parameters are:
*size and location of the feedback window
*subject ID
*sampling rate
*spatial filtering matrix.

Typically, parameters are constant throughout a run, often throughout a session or an entire experiment.
In a [[BCI2000 data file]], a full set of parameters is stored along with the data, allowing for reconstruction of the system configuration off-line.

As parameters represent user choices, the direction of information flow generally is Parameter Value->BCI2000 Module, i.e. parameter information is used to set BCI2000 modules to a defined state at initialization time.
There are, however, some important exceptions to that rule.
*''Source Modules'' may not be able to control all aspects of data acquisition. Control is limited by the design of the vendor-provided software interface to data acquisition hardware. As a typcial example, consider an EEG amplifier connected through a TCP-based socket interface. Generally, the amplifier will be configured in a separate user interface, and BCI2000 source module parameters such as <tt>SourceCh</tt> (number of channels) or <tt>SamplingRate</tt> must be chosen in accordance with that external UI's settings.
*''System-internal Configuration'' is represented as parameters, and of potential interest to the user, but not user configurable. These parameters are placed in the configuration editor's ''System'' tab. Important examples comprise versioning information (e.g., the <tt>EEGSourceVersion</tt> parameter), others govern the connection between modules (e.g., the <tt>EEGSourceIP</tt> parameter).
*''Automatic Adaptation'' to the subject's brain signals may be reflected by automatically updated parameters. For such parameters, the user specifies initial parameter values that may be overwritten at the end of a run. Unless changed by the user, these modified values will be the next run's initial values, and documented as such in that run's data file. As typical examples, consider the ''Normalizer'' filter's <tt>NormalizerOffsets</tt> and <tt>NormalizerGains</tt> parameters.

==Parameter Lines==
Parameter lines are a human-readable format used to represent individual parameters in:
*[[BCI2000 parameter files]]
*[[BCI2000 data files]]
*[[BCI2000 messages]] sent between modules.

The basic format of a parameter line is
<pre>
Section DataType Name= Value DefaultValue LowRange HighRange // Comment
</pre>
Note that the = sign must follow the <tt>Name</tt> field immediately, without
white space. However, white space ''after'' the = sign is mandatory.

If DataType is ''list, intlist'' or ''floatlist'', the format is as follows:
<pre>
Section DataType Name= (NumValues|Labels) Value(s) DefaultValue LowRange HighRange
// Comment
</pre>
where <tt>Labels</tt> is a list of textual labels that optionally
substitute the number denoted by <tt>NumValues</tt>. A list of labels
is enclosed by <nowiki>{} or []</nowiki>, as in
<tt><nowiki>[low medium high]</nowiki></tt>.
If DataType is ''matrix'' , the format is as follows:
<pre>
Section DataType Name= (NumRows|RowLabels)
(NumColumns|ColumnLabels) Value(s) DefaultValue LowRange
HighRange // Comment
</pre>
where, again, each NumValues entry may be substituted by a list of
textual labels.
For matrices, values are given in column-major order, i.e. listing
values from the first column first, then values from the second column,
and so on, as in
Value(0,0) Value(0,1) ... Value(0,m) Value(1,0) Value(1,1) ... Value(1,m) ...

===Data Types===
The DataType field is not interpreted in a very strict sense.
Rather, parameter values are always stored as strings, and converted into
numerical values only when accessed as such from BCI2000 modules.
For consistency, and to avoid user confusion, the following primitive types
should be specified as appropriate:
{|border="1"
|+ Primitive Parameter Data Types
! Name !! Description
|-
| variant || unspecified type
|-
| int || unlimited range integer value
|-
| float || unlimited range, arbitrary precision float value
|-
| string || any string of characters (see the ''Special characters'' section for details)
|}
A list or matrix type may be formed from these primitive types when concatenated with ''list'' or ''matrix'', as in ''intlist'', ''stringmatrix''.
For a list or matrix with entries of unspecified type, use an unprefixed ''list'' or ''matrix'' rather than ''variantlist'' or ''variantmatrix''.

===Special Characters===
To allow for special characters and
white space
within parameter values and textual labels, an URL-like encoding
scheme is adopted.
In this encoding, a <tt>%</tt> character followed by up to two
hexadecimal digits
represents a byte value in hexadecimal notation which is interpreted
according to
the ASCII-Latin1 character table.
Thus, <tt>%20</tt> represents a space character, and
<tt>%</tt>, <tt>%0</tt>, and <tt>%00</tt> all represent an empty string value;
<tt>%%</tt> represents the <tt>%</tt> character itself.
The line
<pre>
Demo string SomeString= a%20string%20with%20spaces % % %
// White space example
</pre>
defines a parameter ''SomeString'' which contains the value
''a string
with spaces''.
The single <tt>%</tt> characters indicate that the
''DefaultValue'' ,
''LowRange'' and ''HighRange'' fields should be empty
strings.

==Sub-parameters==
Any parameter value may itself be a sub-parameter.
Sub-parameters are represented by a short-form
matrix definition omitting the ''Section'' and ''Name''
fields, enclosed in
a pair of braces:
<pre>
Demo matrix NestedMatrices= 1 2 11 { matrix 2 2 1211 1212 1221 1222 }
// Nested matrix example
</pre>
will define a matrix parameter whose 1,2 entry is a 2x2 matrix.
While the syntax allows for any combination of parameter and
subparameter types,
the current implementation of the parameter editor GUI only
supports matrix-type
sub-parameters within matrices as in the example above.

==Display Format==
Generally, a parameter's <tt>DataType</tt> field will be used to
determine its appropriate display in a parameter editor.
However, often a more user-friendly display may be achieved if
additional information about a parameter's content is available.

To allow for such information, the comment line that is introduced by the
two
slashes (//) may contain a format identifier that is used by the
Operator module
to modify the display of the particular parameter. Format identifiers
are
strictly optional and are introduced as follows:
<tt>(identifier)</tt>.
Currently, the following format identifiers are implemented:

{| border="1"
|+ The currently defined format identifiers
! Identifier !! Description
|-
| <tt>(enumeration)</tt> || a choice from an enumerated set of values
|-
| <tt>(boolean)</tt> || a yes/no choice
|-
| <tt>(inputfile)</tt> || path to a file to be opened for reading
|-
| <tt>(outputfile)</tt> || path to a file to be opened for writing
|-
| <tt>(directory)</tt> || path to a directory
|-
| <tt>(color)</tt> || RGB color
|}

===<tt>(enumeration)</tt>===
The parameter value is presented as a drop down menu, with entries
corresponding to the
possible values listed in the comment. The first part of the comment
appears above
the drop down menu. All interpunction characters present in the
comment are ignored.
The data type of the parameter must be <tt>int</tt>.
All possible values must appear in the comment, and the parameter's
LowRange and HighRange
fields must be consistent with the enumeration. LowRange will usually
be 0, but may be any
integer. For example:
<pre>
Breakfast int BreakfastDrink= 1 1 1 3
// Drink for breakfast: 1 Tea, 2 Coffee, 3 Juice (enumeration)
</pre>
will display a drop down menu with entries "Tea," "Coffee,", and
"Juice."
The menu will be labeled "Drink for breakfast."

===<tt>(boolean)</tt>===
The parameter value is presented as a check box; the first part of the
comment appears
to the right of the check box. LowRange and HighRange must be 0 and 1.
The parameter's data type must be <tt>int</tt>.
To ensure human readability of parameter files, the possible values
and their meaning may
appear in the comment (e. g. <tt>0: no, 1: yes</tt>) but will not
be displayed with the
check box. For example:
<pre>
Breakfast int ServeBreakfast= 1 1 0 1
// Serve breakfast: 0 no, 1 yes (boolean)
</pre>
will display a check box labeled "Serve breakfast."

===<tt>(inputfile)(outputfile)(directory)</tt>===
The parameter value is presented as an edit field. Beside the edit
field, there is a button that opens up a file or directory and selects dialog when clicked.
The parameter's data type must be <tt>string</tt>.
<pre>
Breakfast string WakeupSound= doorbell.wav
// Sound to play in the morning (inputfile)
</pre>

===<tt>(color)</tt>===
The parameter value is presented as an edit field. To the right of the edit
field there is a button that opens up a color selector dialog when clicked.
The parameter's data type must be <tt>string</tt>, with its value
containing the color
in hexadecimal RGB encoding:
<pre>
Breakfast string TableClothColor= 0x00FF00 0xFFFFFF 0x000000 0xFFFFFF
// Color of table cloth to put up for breakfast (color)
</pre>

==Grouping Parameters by Sections==
A user interface may use fields in the parameter <tt>Section</tt> fields to
collect parameters into
groups, e.g., by displaying all parameters with identical section
fields on the same
register tab of a GUI parameter editor dialog window.
In the <tt>Section</tt> field, finer grained grouping may be expressed
by specifying
sub-sections separated by colon characters, e.g., a <tt>Section</tt>
value of
UsrTask:WindowDimensions
will indicate that a parameter belongs to a <tt>WindowDimensions</tt>
subsection of
a section called <tt>UsrTask</tt>. A parameter editor implementation
might display the respective parameter on a register tab called
"UsrTask" and
inside a group box labelled "WindowDimensions".
Although any number of sub-sections may be present in the
<tt>Section</tt> field,
a user interface implementation may ignore sub-section entries below a
level chosen by the implementer.
-----
See also: [[User Reference:Parameters]]

Technical Reference:BCI2000 Messages

2007-05-09T19:17:25Z

Atennissen:

Information transferred between BCI2000 modules is packed into messages.
Each message content corresponds to a BCI2000 data type such as Parameter, State, or Signal, and is wrapped into a layer that allows for routing the message to an appropriate handler.
BCI2000 data types know how to write themselves to, and read themselves from, a data stream.
For example, when the wrapper indicates that a message contains a brain signal, the framework code will route the message to a "brain signal" handler function that, in turn, asks a brain signal object to read itself from the message.
As another example, when the operator module receives a visualization message, the message wrapper layer will not only be used to direct the message to a visualization handler but also to the visualization window to which the message is addressed.

===Protocol Definition===
Each message starts
with a one-byte content descriptor and a one-byte descriptor supplement, followed
by a number that describes the length of the content. (See Figure below)

[[Image:BCI2000_Messages_MessageProtocol.png|center|thumb|400px|Layout of one message in the protocol.]]

The element denoted by "length field(2)" was originally a two-byte integer
field for the content length in little endian format. To allow for messages
longer than 64k, we introduced a backwards-compatible extension: if the length
is below 65535, it will still be transmitted as a two-byte integer in little
endian format. Otherwise, the two bytes will contain the value 65535, and be
followed by a decimal ASCII representation of the length, terminated with a zero
byte. For other one- and two-byte length fields occurring in the protocol, the
same scheme applies, generalized to be a "length field (original number of bytes)". (See Figure below)

[[Image:BCI2000_Messages_LengthField.png|center|thumb|300px|Detailed layout of a length field (m) for a length <math>n \geq 2^{m}-1</math>]]

{| border="1" cellpadding="2"
|+

===Overview of Content Descriptors===
!descriptor !! description
|-
| 1 || status information string
|-
| 2 || system parameter
|-
| 3 || system state
|-
| 4 || visualization data or brain signal
|-
| 5 || state vector
|-
| 6 || system command
|}

===Descriptor=1: Status Information Format===
This section describes the format of the message when the core message is
a status information string (i.e., the message's descriptor is 1). In this
case, the aforementioned content data is a line of ASCII characters in the following format:
xxx: status-line-text
xxx is a three digit number that describes the content of the status
information string.
A first digit of `1' indicates status information, a first digit of `2' indicates successful
operation, a first digit of `3' indicates recoverable errors and a first digit of `4' indicates fatal errors. The two remaining digits define the exact nature of the message, followed by a plain description.
This procedure is used to communicate errors and to convey status
information (e.g.,
the operator module may display the remaining disc space on the machine of the Source module.)

===Descriptor=2: Parameter Format===
For parameter messages, content data is a line of ASCII characters
representing a [[parameter definition]] line.

===Descriptor=3: State Format===
State messages contain a line of ASCII characters representing a
[[state definition]] line.

===Descriptor=4: Visualization and Brain Signal Data Format===
This section describes the format of the message when the core message
is a visualization data/brain signal message (i.e., the descriptor on the message is 4). In this
case, the content descriptor describes the requested visualization type.
The currently defined types are 1 (a graph of ''n'' channels and ''m'' samples), 2 (a text memo), and 255 (visualization configuration).
For brain signals, the content descriptor is 1. (See Figure below)

[[Image:BCI2000_Messages_VisualizationData.png|center|thumb|500px|One message in the protocol of type "visualization data".]]

The following figure illustrates the protocol when the visualization type is 1. The source identifier defines a unique number identifying the process/filter that generated the data. The data type
can be
*0 <tt>(SignalType::int16)</tt> for integers in little endian format.
*1 <tt>(SignalType::float24)</tt> for 3-byte floating-point values: The first two bytes (i.e., A) define the mantissa (signed two-byte integers in little endian format) and the third byte (i.e., B) defines the exponent (signed one-byte integer). The actual floating point value is then calculated as follows: <math>value=A*10^{B}</math>.
*2 <tt>(SignalType::float32)</tt> for 4-byte floating-point values in IEEE 754 format transmitted in little endian byte order.
*3 <tt>(SignalType::int32)</tt> for 4-byte signed integer values transmitted in little endian byte order.

The number of channels and samples are self explanatory.

[[Image:BCI2000_Messages_vistype1(graph).png|center|thumb|600px|One message if the visualization type is 1 (i.e., a graph).]]

The following figure illustrates how the data is transferred.

[[Image:BCI2000_Messages_TransmittedVisualizationDataFormat.png|center|thumb|500px|Graphical representation of the transmitted visualization data format.]]

The following figure illustrates the protocol when the visualization type is 2. The source identifier is a number uniquely identifying the process/filter that generated the data. (0 for brain signals.)
The following ASCII text is zero delimited.

[[Image:BCI2000_Messages_vistype2(memo).png|center|thumb|400px|One message if the visualization type is 2 (i.e., a text memo).]]

The following figure illustrates the protocol when the visualization type is 255. The source identifier is a number identifying the process/filter that generated the data. The different configuration IDs are defined in the CFGID enumeration in the [http://www.bci2000.org/tracproj/browser/trunk/src/shared/defines.h shared/defines.h]
header file.

The ASCII string then contains the configuration option, as defined by the configuration ID. For example, it might contain "128" if the configuration ID is 4. This will configure the graph to contain exactly 128 samples. When the configuration ID is 5 or 6 (axis labels), the ASCII string consists of a sample number (three digits), a space, and the axis label. Thus, one message
configures exactly one axis label. As an example, for an X-axis label, the string "003 4.75 Hz" would result in a graph, in which the third sample is labeled "4.75 Hz."

[[Image:BCI2000_Messages_vistype255(visconfig).png|center|thumb|500px|One message if the visualizationtype is 255 (i.e., visualization configuration).]]

====Brain Signal Format====
The brain signal is transmitted similarly to visualization data (i.e., as described in the Visualization and Brain Signal Data Format above). The visualization type is set to 1 (i.e., graph), source identifier is set to 0. Data type, channels and samples reflect the actual format of data transmitted.

====Control Signal Format====
Control signals are transmitted identically to the Brain Signal.

===Descriptor=5: State Vector===
The state vector is defined by a series of ''StateVectorLength''
subsequent bytes.
The value of a given state within the state vector is determined by
its byte/bit
location and length definition. The bits in the state vector are
always sorted
in ascending order, e.g., for a state with a length of 7 bits,
starting at byte
location 2, bit location 3, bit zero is first (byte 2, bit 3), and the
highest
bit (bit 7) is last (byte 3, bit 1).

===Descriptor=6: System Command===
The system command consists of an ASCII string that may end with a
zero byte (i.e., ASCII code 0).
The nature of these system commands is defined by the specific
implementation of
the modules.

MARIO Technical Documentation

2007-05-09T19:14:20Z

Atennissen:

==MARIO Architecture==
MARIO is an off-line analysis application developed in MATLAB 7.0.2. It is now modular, object-oriented and can be easily integrated with any other software for data analysis and visualization.
It can be used in Mu and P300 analyses and allows three kinds of use: users can simply fill the forms of a graphical interface making any choice with a click of its mouse, run a ready-made script or, write up their own scripts according to their needs.
This set of interfaces allows a wide range of possibilities for a wide range of different analyses.

Internally, the application is composed of 6 main functional modules, each one connected in cascade as in the list below:

*Data import
*Signal Conditioning
*Feature Extraction
*Spectral Extimation
*Statistical Analysis
*Visualization

[[Image:arch_blocks.jpg]]

All these modules are hidden in the graphical user interface but they can be distinguished in the batch scripts. Each one of them can be easily replaced with an improved version, a custom version or a different analysis.

[[Image:Graph.png|thumb|left|Graph of modules]]
Here you can see a simplified version of the functions graph with their relationships (click to enlarge). 

==Data Import Module==

Any script must have a first module in which to load data that the user wants to analyze.
There are 3 main types of files containing different groups of information:

*Data files (.dat/.mat)
*Montage files (.mmf)
*External Parameter files (.prm) – optional

The data files contain all the data of the BCI session (Mu or P300).
These data are saved in different files, one for each run, containing 29 trials.
Internally any file is divided in two main parts: the first part (file header) includes all parameters set by the operator during the on-line experimentation; the second part contains the EEG signal recorded by the whole set of electrodes on the EEG cap.
A special function allows data to be loaded from a Matlab file (.mat).

The montage file stores information about the electrode position on the scalp. It consists
of different sections divided by labels:

#a synthetic name
#the channel labels
#a valid channels list
#the laplacian grid
#the 3-dimensional spatial coordinates of all the electrodes (this section is optional)

These labelled sections can be written in the Montage file without a predefined order.

The user can import data from an additional data file, (a parameters file), that can be used if he wants to replace one or more parameters from the BCI2000 ones. For this, it is enough to copy and paste the selected header string in a new prm file, and change its value.

This module is clearly the same for Mu and P300 Analysis.

==Data Conditioning Module==

The MARIO v.2.0 Data Conditioning module allows users to select from a wide range of spatial filters so as to include a custom filter in the user data analysis. The operator can identify which channels or set of channels will give better results at the end of the statistical analysis.

For a Mu analysis, the user can select from four different spatial filter algorithms:

*RAW
*CAR (Common Average Reference)
*SMALL LAP
*LARGE LAP

The first one, (RAW) does not use a filter and analyzes raw recorded data. A user defined analysis will be available on further versions of MARIO.

The Data Conditioning module also allows the the user to compile/modify a list of valid channels on which to conduct any analysis.

P300 Analysis can now use only two of the above spatial filters: the RAW filter and the CAR one. Any other selection will report an unhandled error.

==Feature Extraction Module==

Feature extraction is one of the most important stages of elaboration; it affects any further analysis.

In a Mu rhythm analysis, any feature can be obtained by arranging some of the 12 BCI2000 states.
The user can now make a choice between two predefined analyses, a simple Mu analysis or an Extended version of the same. The first analysis considers any sample recorded between the cursor appearance on the screen and the end of the trial (when the cursor reaches the right side of the screen).
The MuExteded analysis instead considers any sample recorded since the target appearance (during the first subset of data, the subject does not have any feedback) until the end of trial.
In both choices, the statistical analysis will be conduced between two classes of data: the EEG activity recorded while moving up the cursor (target UP) versus the EEG activity recorded while moving down the cursor (target DOWN).
Either of these choices will produce different R2 values between the corresponding features of the two classes

For a P300 Analysis only two classes are compared and automatically set as frequent events and rare events.

==Spectral Extimation Module ''(for Mu rhythm analysis)''==

During this step, the program evaluates and analyzes the spectrum of recorded data.
To do that, the EEG signal is divided into equal length epochs (These epochs can be distinct or overlapped as a percentage of overlap, which the user can set by using the Graphical User Interface or script.) A spectrum value is evaluated for anyone of these epochs.

At the end of this process, a 3 dimensional matrix (bin × channel × epoch) joined with the one (channel × sample) compiled during a BCI2000 recording session and read by the data import module will be produced.

The algorithm employed to estimate the signal spectrum is the MEM (the same used on-line by BCI2000).

Apart from the percentage of overlap, MARIO allows the user to modify the values of:

#Sampling frequency of recorded data
#Spatial resolution (delta)
#Detrending order (Mean or Linear)
#AR model order
#Low pass filter frequency
#High pass filter frequency
#Filter bandwidth
#Epoch length
#Overlap percentage

MARIO v2.0 also computes a virtual states matrix strictly joined with signal one and derived as an arrangement of the BCI2000 states. These states label spectrum samples as valid or not valid and as belonging to one class or another.

==Statistical Analysis Module==

A statistical analysis (presently, R2) is employed to distinguish between the classes of a BCI2000 task in any trial.

MARIO uses a module that computes the R2 value between two classes; these can be TargetUP and TargetDOWN for a Mu rhythm analysis, or frequent events and rare events for a P300 analysis. These data are taken from the spectra matrix (Mu analysis) or from the samples one (P300 analysis) and the regressor vector is yield from BCI2000 states.

At the end of this analysis, the real index produced (in a range between -1 and 1) is the R2 value multiplied by R2 sign. If the R2 value is near 1, there is an high separability between classes and high performance. If, instead, its value is near 0, it is difficult to distinguish one class from another, and it means low performance.

==Visualization Module==

Mario offers a wide set of visualization graphs that can be combined to have a complete visualization of produced data.
For a Mu rhythm analysis the user can request to visualize:

#a trajectory plot showing the cursor position for any sample in a trial BCI2000 as the user saw it on-line
#a matrix (channel × bin) where the R2 value of any feature is shown in a color tint. A colorbar shows the color range between -1 and 1
#Another panel showing a detail of the previous matrix. The upper topographic plot shows the R2 value for any channel in the selected bin of frequencies; the lower one is the spectrum of the selected channel for all the frequencies.

For a P300 analysis the user can choose from:

#An R2 matrix
#An amplitude waveform graph
#A topographic plot
#An ERP response graph
#A string prediction form.

All these result visualizations can be easily included in any of the user scripts for custom analysis.

Mu Rhythm Off-line Analysis Tutorial

2007-05-09T19:10:36Z

Atennissen:

== Starting an Analysis Session ==

Every recording session has its own history. It is very difficult to say in advance what might happen during the recording. So we will assume that everything was perfect (the subject collaborated, no channel went lost, etc); later on we will consider the main causes of contamination, how to recognize it and what to do.

If the recording session runs smoothly, you should now have in the folder ''\TestData\Data\Mu'', two files named ''ALFAS006R01.dat'' and ''ALFAS006R02.dat'', corresponding to two of the eight runs usually recorded, respectively.

Before you start the analysis you should locate the correct montage file on your hard disk. This is a file that describes the list of channels that were acquired. In this tutorial we will use ''Complete_Montage(suggested choice).mmf'', which is located in the folder ''\TestData\Montage''. If you need to edit the *.mmf file, check its data format.
< the of performances optimize that parameters try will we then online; performed BCI2000 analyses same off-line replicate to first>

== Opening Files with Mario ==

After having run mario.exe, press "Select Data Files".

[[Image:Mu Rhy5.jpg]]

A dialog window will ask you to select the dat files. You can either select a single data file, or select multiple files. This time, we will select all files in the dataset.

A green box will surround the Raw Data box in the main window.

As an optional (but recommended) operation, click on the LOAD MONTAGE button and choose the mmf file. This will allow you to see the labels of each channel and allow you to apply spatial filters that depend on the electrode position.

You can load an additional parameters file with choices different from those used during the experiment.

At this point, you can check that Mu is selected in the Analysis menu (indicating that a Mu dataset has been recognized) and click on the LOAD DATA button to confirm your choices. This will enable the EDIT CHANNEL LIST button that you can use to select the channels you want to include in your analysis.

== Selecting Channels ==

Pushing the the EDIT CHANNEL LIST button, two forms will show you the channels list (valids' and not-valids' one) and an image reassuming valid channels and their location.

Clicking on Add and Remove buttons allows you to move a channel from one list to the other, enabling or disabling it.

== Selecting the Spatial Filter ==

Return to the main window, and you can choose which filter to apply for your analysis, selecting from the following filter choices:

:*RAW
:*CAR
:*Large Laplacian
:*Small Laplacian

Common Average Reference (CAR) will be fine for most of the situations.

We hope, soon, to release a user defined solution for any custom analysis.

== Feature Extraction Analysis ==

The Analysis field in the Feature Extraction panel will appear automatically according to the files loaded, while the Feature Extractor field shows the only currently possible choice.

You can view/edit analysis details by clicking on "Set Analysis Details" and "Set F.E. parameters"

This second form reports all the settings for the parametric (autoregressive) spectral estimation stage. Most of the values are set after the corresponding values used on-line (see BCI2000 setup for Mu). Using the settings in the figure, the analysis software will:

:*data recorded at 200 Hz sampling rate
:* remove the mean value
:* sample the spectrum at points starting from 0 Hz to 60 Hz, every 0.2 Hz.
:* Identify an auroregressive model of order 16
:* average these values into 2 Hz wide bins
:* take a 1 s long epoch of data

You can modify these settings according to your aims. Changing the model order, for instance, brings sometimes to interesting results. Remember though that in the online version, spectral estimation is performed in epochs as short as 200 ms (i.e. 40 samples, at 200 Hz sampling rate), so you should avoid using a model order higher than half the samples available in the epoch.
When you are finished, remember to confirm your choices by slecting DONE.

In addition, a button in the Spectral Extimation frame allows you to revert to the original values.

Altogether you have to specify:

:* which data (in each trial) you want to take into account. Mu will only use the part of the trial when the cursor is visible, while MuExtended will take into account all the period when the target is visible. To learn more, see section D2Box Application States
:* If you have made an artifact rejection (or noted on the run sheet during the acquisition which trials contain artifacts), you can instruct the software not to use them
:* Finally, you must decide how the software must extract EEG epochs from the continuous data
The epochs can be partially overlapped. This attenuates the data loss in case the length of a trial is not a multiple of the length of an epoch.

The percentage of overlap can be set both in Mario GUI and in any batch script. It is equal to the value of the ''MU_params.overlapping'' variable and the corresponding GUI field can be found by clickiing on ''Set Analysis Details'' on MARIO main form.

At this point you can start the analysis by clicking on the Evaluate and Plot button.

[[Image:Mu Rhy8.jpg]]

== View Results ==

The first figure that appears is the R-square matrix (channels x frequency bins)
=== R-square Matrix ===

The r-square matrix highlights the most relevant spectral features for the separation of the two classes of EEG - Cursor Up (target 1) and Cursor Down (target 2).

[[Image:Mu Rhy8.jpg]]

Each row of the matrix is related to a single channel, while a column represents a frequency bin (labeled with its central frequency). The color codes the statistical significance of the difference between the two kinds of evoked potentials.

Thus a red color would mean that, on that channel and for that frequency, the "Up" EEG is significantly synchronized with respect to "Down" EEG.

Clicking on a cell of the matrix will open two more windows:

* Power spectral distribution of the selected channel
* Topographic maps at the selected frequency.

You can choose whether to overwrite or to put the most recently evoked figures beside the previous one. Two sets of waveform/topography figures are available, and are linked to the click of the left, the central or right mouse button.
Left Button will create/overwrite a first figure, Right Button will do the same on a second figure, the Central Button will always open a new plot.

=== Power Spectra and Topographic Plots ===

In the lower panel you can find the spectral density of power for both classes of EEG. The Blue line refers to the "Up" condition, while the Red line refers to the "Down" condition.
We can see that at the vertex the "Down" condition is generally more synchronized than the "Up", with maximal difference in the beta band, consistently with what is shown by the R-square matrix. The proportinality between spectral differences and R-square is anyway rough, since r-square is sensitive to the dispersion (variance) of single trials; thus, small differences between spectra could bring to a high r-square, if they were very reproducible.

The peak around 50 Hz is due to mains disturbance; this also allows you to appreciate the leakage introduced by the spectral estimation.

[[Image:Mu_Rhy9.jpg]]

Over the spectral graph, a topographic plot shows the scalp distribution of the r-square.

The color coding is the same as the r-square matrix figure, and values on each channel are interpolated to create a continuous bidimensional map. The higher the number of electrodes, the more accurate is the map. With Surface Laplacian spatial filtering, the number of channels shown on the scalp may not coincide with the whole number of electrodes, since the value of the laplacian is not computed on the border channels.

The first step in the preliminary analysis of P300 BCI data is to find the absolute maximum of r-square. This simple statement must be mediated with a proper knowledge of physiological phenomena. In fact, we do not expect any sensorimotor activity at 3 Hz, so if the absolute maximum is at that frequency, you must suspect that it is actually an artifact. The same holds true if the spatial localization of the peak is far away from the centro-parietal electrodes.

From a practical point of view, it is not important, now, to understand the reasons different component that explain the desynchrinization peak on Cz at 17 Hz, as far as we are confident that this component is stable enough to be exploitable during the next session to control the cursor.

The absolute value of R-square is mathematically bound to lie in the interval between 0 and 1. Values above 0.4 allow a rate of missed target on the order of a few percent. Values around 0.1 are promising. Values below 0.03 are possibly due to random fluctuations. All the previous figures are referred to analyses made on 240 trials.
''Beware of artifacts!''

During the acquisition, you should be particularly careful to avoid artifacts. While EOG and blink artifacts are confined to very low frequencies, EMG artifacts are mostly on the beta band and could largely overlap with the frequency band that characterizes the mu rhythm.

If contaminated data was acquired, then you have two problems:

:* Realize that EMG is superimposed on the to data
:* Distinguish between spectral modulation introduced by EEG and by EMG

The first task is not as trivial as it might appear. If you did not acquire the data yourself (or even if you did) you might complete the analysis procedure without giving a single glance to the raw data. So you must be particularly careful when you analyze the R-square maps, and always check if the peak you are seeing might be due to an artifact.

Discriminant features between EEG and EMG are both in the frequency distribution and in the spatial distribution.

EMG that strongly affects the recordings is mostly generated by muscles at the forehead or close to the ears/jaws. Thus, their spatial distribution is such that the most responsive channel is one of those at the border of the montage. Of course, due to volume conduction, the effects can be seen even on electrodes on the opposite part of the montage, but they show a degrading pattern.
On the other hand, a peak that shows its maximum on a central channel, can hardly be generated by a muscle or by other non-cephalic source.

The spectrum of EEG is mainly concentrated in the alpha band, with a possible flatter and lower peak in beta. With the exception of the beta peak/plateau, the EEG spectrum decreases almost linearly (if measured in dB) after 12 Hz.
On the other hand, the EMG spectrum becomes significant at about 20 Hz and is still very high at the highest frequencies we usually analyze (60 Hz). A spectrum with a pattern more similar to the latter, may indicate that non-EEG activity is present in the data.

==Improving the Analysis==

The first cause of an unsuccessful analysis is poor quality of the recording. For this reason it is highly recommended that, at least for the first experiments, the subject be highly motivated and cooperative. If this is the case, data of low quality are usually present in one or a few runs. And if the experimenter is careful enough, he/she should have noted the occurrence of strong artifacts on the run sheet.
In this case, the next step is to repeat an unsatisfactory data analysis after having excluded the (putative) bad runs.
To do this, just go back to the file selection dialog, choose LOAD Data again and load only the runs that you believe are clean. The number of runs should not be too low (as a rule of thumb, the data set should contain at least 100 trials), otherwise the r-square statistical analysis would loose sensitivity.

== Analyzing the Screening ==

The screening experiment is not different from a regular training session, from the point of view of data format. You will have four sets (horizontal movement, horizontal imagination, vertical movement, and vertical imagination) of three runs, containing EEG acquired in two conditions (up and down, or left and right).

Start analyzing the vertical movement execution, and mark a few possible responsive features. The analysis on the vertical movement imagination should confirm (though with a lower R-square) those that are actually related to sensorimotor cognitive states.

In the case that no reliable responsive EEG feature is found, the analysis can be repeated on the horizontal dataset.

If both the vertical and horizontal dataset show responsive features, and these are different, the subject should be trained for some session on the vertical training until he/she decreases the false positive below 10%; at that point, the training of the horizontal modulation can begin, with the aim that, at a certain point, the subject can control both the vertical and the horizontal simultaneously in a two-dimensional task.

==Conclusions==

If you are confident that you have found a significant difference between conditions that is due to EEG rather than an artifact, and that reflects a cognitive process that is likely to be reproduced (or even enhanced with training) in the next session, you have reached your goal.
The next time the same subject practices with the D2Box Application, you will have to change the MUD matrix so that it reflects the feature that you just outlined.

==Troubleshooting==

Some OpenGL drivers may sometimes show defective figures like the following:

[[Image:Defective.jpg]]

Matlab customers can get around this problem using this simple procedure:
:* Select the defective figure window
:* Go to the Matlab Command Window
:* Execute one of the following command line:
:**set(gcf, 'Renderer', 'Painters')
:**set(gcf, 'Renderer', 'zbuffer')

The figure will be a plot using a different renderer (Painters or zBuffer).

Mu Rhythm Off-line Analysis Tutorial

2007-05-09T18:57:48Z

Atennissen:

== Starting an analysis session ==

Every recording session has its own history. It is very difficult to say in advance what might happen during the recording. So we will assume that everything was perfect (the subject collaborated, no channel went lost, etc); later on we will consider the main causes of contamination, how to recognize it and what to do.

If the recording session runs smoothly, you should now have in the folder ''\TestData\Data\Mu'', two files named ''ALFAS006R01.dat'' and ''ALFAS006R02.dat'', corresponding to two of the eight runs usually recorded, respectively.

Before you start the analysis you should locate the correct montage file on your hard disk. This is a file that describes the list of channels that were acquired. In this tutorial we will use ''Complete_Montage(suggested choice).mmf'', which is located in the folder ''\TestData\Montage''. If you need to edit the *.mmf file, check its data format.
< the of performances optimize that parameters try will we then online; performed BCI2000 analyses same off-line replicate to first>

== Opening files with Mario ==

After having run mario.exe, press "Select Data Files".

[[Image:Mu Rhy5.jpg]]

A dialog window will ask you to select the dat files. You can either select a single data file, or select multiple files. This time, we will select all files in the dataset.

A green box will surround the Raw Data box in the main window.

As an optional (but recommended) operation, click on the LOAD MONTAGE button and choose the mmf file. This will allow you to see the labels of each channel and allow you to apply spatial filters that depend on the electrode position.

You can load an additional parameters file with choices different from those used during the experiment.

At this point, you can check that Mu is selected in the Analysis menu (indicating that a Mu dataset has been recognized) and click on the LOAD DATA button to confirm your choices. This will enable the EDIT CHANNEL LIST button that you can use to select the channels you want to include in your analysis.

== Selecting Channels ==

Pushing the the EDIT CHANNEL LIST button, two forms will show you the channels list (valids' and not-valids' one) and an image reassuming valid channels and their location.

Clicking on Add and Remove buttons allows you to move a channel from one list to the other, enabling or disabling it.

== Selecting the Spatial Filter ==

Return to the main window, and you can choose which filter to apply for your analysis, selecting from the following filter choices:

:*RAW
:*CAR
:*Large Laplacian
:*Small Laplacian

Common Average Reference (CAR) will be fine for most of the situations.

We hope, soon, to release a user defined solution for any custom analysis.

== Feature Extraction Analysis ==

The Analysis field in the Feature Extraction panel will appear automatically according to the files loaded, while the Feature Extractor field shows the only currently possible choice.

You can view/edit analysis details by clicking on "Set Analysis Details" and "Set F.E. parameters"

This second form reports all the settings for the parametric (autoregressive) spectral estimation stage. Most of the values are set after the corresponding values used on-line (see BCI2000 setup for Mu). Using the settings in the figure, the analysis software will:

:*data recorded at 200 Hz sampling rate
:* remove the mean value
:* sample the spectrum at points starting from 0 Hz to 60 Hz, every 0.2 Hz.
:* Identify an auroregressive model of order 16
:* average these values into 2 Hz wide bins
:* take a 1 s long epoch of data

You can modify these settings according to your aims. Changing the model order, for instance, brings sometimes to interesting results. Remember though that in the online version, spectral estimation is performed in epochs as short as 200 ms (i.e. 40 samples, at 200 Hz sampling rate), so you should avoid using a model order higher than half the samples available in the epoch.
When you are finished, remember to confirm your choices by slecting DONE.

In addition, a button in the Spectral Extimation frame allows you to revert to the original values.

Altogether you have to specify:

:* which data (in each trial) you want to take into account. Mu will only use the part of the trial when the cursor is visible, while MuExtended will take into account all the period when the target is visible. To learn more, see section D2Box Application States
:* If you have made an artifact rejection (or noted on the run sheet during the acquisition which trials contain artifacts), you can instruct the software not to use them
:* Finally, you must decide how the software must extract EEG epochs from the continuous data
The epochs can be partially overlapped. This attenuates the data loss in case the length of a trial is not a multiple of the length of an epoch.

The percentage of overlap can be set both in Mario GUI and in any batch script. It is equal to the value of the ''MU_params.overlapping'' variable and the corresponding GUI field can be found by clickiing on ''Set Analysis Details'' on MARIO main form.

At this point you can start the analysis by clicking on the Evaluate and Plot button.

[[Image:Mu Rhy8.jpg]]

== View results ==

The first figure that appears is the R-square matrix (channels x frequency bins)
=== R-square matrix ===

The r-square matrix highlights the most relevant spectral features for the separation of the two classes of EEG - Cursor Up (target 1) and Cursor Down (target 2).

[[Image:Mu Rhy8.jpg]]

Each row of the matrix is related to a single channel, while a column represents a frequency bin (labeled with its central frequency). The color codes the statistical significance of the difference between the two kinds of evoked potentials.

Thus a red color would mean that, on that channel and for that frequency, the "Up" EEG is significantly synchronized with respect to "Down" EEG.

Clicking on a cell of the matrix will open two more windows:

* Power spectral distribution of the selected channel
* Topographic maps at the selected frequency.

You can choose whether to overwrite or to put the most recently evoked figures beside the previous one. Two sets of waveform/topography figures are available, and are linked to the click of the left, the central or right mouse button.
Left Button will create/overwrite a first figure, Right Button will do the same on a second figure, the Central Button will always open a new plot.

=== Power Spectra and Topographic Plots ===

In the lower panel you can find the spectral density of power for both classes of EEG. The Blue line refers to the "Up" condition, while the Red line refers to the "Down" condition.
We can see that at the vertex the "Down" condition is generally more synchronized than the "Up", with maximal difference in the beta band, consistently with what is shown by the R-square matrix. The proportinality between spectral differences and R-square is anyway rough, since r-square is sensitive to the dispersion (variance) of single trials; thus, small differences between spectra could bring to a high r-square, if they were very reproducible.

The peak around 50 Hz is due to mains disturbance; this also allows you to appreciate the leakage introduced by the spectral estimation.

[[Image:Mu_Rhy9.jpg]]

Over the spectral graph, a topographic plot shows the scalp distribution of the r-square.

The color coding is the same as the r-square matrix figure, and values on each channel are interpolated to create a continuous bidimensional map. The higher the number of electrodes, the more accurate is the map. With Surface Laplacian spatial filtering, the number of channels shown on the scalp may not coincide with the whole number of electrodes, since the value of the laplacian is not computed on the border channels.

The first step in the preliminary analysis of P300 BCI data is to find the absolute maximum of r-square. This simple statement must be mediated with a proper knowledge of physiological phenomena. In fact, we do not expect any sensorimotor activity at 3 Hz, so if the absolute maximum is at that frequency, you must suspect that it is actually an artifact. The same holds true if the spatial localization of the peak is far away from the centro-parietal electrodes.

From a practical point of view, it is not important, now, to understand the reasons different component that explain the desynchrinization peak on Cz at 17 Hz, as far as we are confident that this component is stable enough to be exploitable during the next session to control the cursor.

The absolute value of R-square is mathematically bound to lie in the interval between 0 and 1. Values above 0.4 allow a rate of missed target on the order of a few percent. Values around 0.1 are promising. Values below 0.03 are possibly due to random fluctuations. All the previous figures are referred to analyses made on 240 trials.
''Beware of artifacts!''

During the acquisition, you should be particularly careful to avoid artifacts. While EOG and blink artifacts are confined to very low frequencies, EMG artifacts are mostly on the beta band and could largely overlap with the frequency band that characterizes the mu rhythm.

If contaminated data was acquired, then you have two problems:

:* Realize that EMG is superimposed on the to data
:* Distinguish between spectral modulation introduced by EEG and by EMG

The first task is not as trivial as it might appear. If you did not acquire the data yourself (or even if you did) you might complete the analysis procedure without giving a single glance to the raw data. So you must be particularly careful when you analyze the R-square maps, and always check if the peak you are seeing might be due to an artifact.

Discriminant features between EEG and EMG are both in the frequency distribution and in the spatial distribution.

EMG that strongly affects the recordings is mostly generated by muscles at the forehead or close to the ears/jaws. Thus, their spatial distribution is such that the most responsive channel is one of those at the border of the montage. Of course, due to volume conduction, the effects can be seen even on electrodes on the opposite part of the montage, but they show a degrading pattern.
On the other hand, a peak that shows its maximum on a central channel, can hardly be generated by a muscle or by other non-cephalic source.

The spectrum of EEG is mainly concentrated in the alpha band, with a possible flatter and lower peak in beta. With the exception of the beta peak/plateau, the EEG spectrum decreases almost linearly (if measured in dB) after 12 Hz.
On the other hand, the EMG spectrum becomes significant at about 20 Hz and is still very high at the highest frequencies we usually analyze (60 Hz). A spectrum with a pattern more similar to the latter, may indicate that non-EEG activity is present in the data.

==Improving the analysis==

The first cause of an unsuccessful analysis is poor quality of the recording. For this reason it is highly recommended that, at least for the first experiments, the subject be highly motivated and cooperative. If this is the case, data of low quality are usually present in one or a few runs. And if the experimenter is careful enough, he/she should have noted the occurrence of strong artifacts on the run sheet.
In this case, the next step is to repeat an unsatisfactory data analysis after having excluded the (putative) bad runs.
To do this, just go back to the file selection dialog, choose LOAD Data again and load only the runs that you believe are clean. The number of runs should not be too low (as a rule of thumb, the data set should contain at least 100 trials), otherwise the r-square statistical analysis would loose sensitivity.

== Analyzing the Screening ==

The screening experiment is not different from a regular training session, from the point of view of data format. You will have four sets (horizontal movement, horizontal imagination, vertical movement, and vertical imagination) of three runs, containing EEG acquired in two conditions (up and down, or left and right).

Start analyzing the vertical movement execution, and mark a few possible responsive features. The analysis on the vertical movement imagination should confirm (though with a lower R-square) those that are actually related to sensorimotor cognitive states.

In the case that no reliable responsive EEG feature is found, the analysis can be repeated on the horizontal dataset.

If both the vertical and horizontal dataset show responsive features, and these are different, the subject should be trained for some session on the vertical training until he/she decreases the false positive below 10%; at that point, the training of the horizontal modulation can begin, with the aim that, at a certain point, the subject can control both the vertical and the horizontal simultaneously in a two-dimensional task.

==Conclusions==

If you are confident that you have found a significant difference between conditions that is due to EEG rather than an artifact, and that reflects a cognitive process that is likely to be reproduced (or even enhanced with training) in the next session, you have reached your goal.
The next time the same subject practices with the D2Box Application, you will have to change the MUD matrix so that it reflects the feature that you just outlined.

==Troubleshooting==

Some OpenGL drivers may sometimes show defective figures like the following:

[[Image:Defective.jpg]]

Matlab customers can get around this problem using this simple procedure:
:* Select the defective figure window
:* Go to the Matlab Command Window
:* Execute one of the following command line:
:**set(gcf, 'Renderer', 'Painters');
:**set(gcf, 'Renderer', 'zbuffer')

The figure will be a plot using a different renderer (Painters or zBuffer).

Programming Reference:Debug Output

2007-05-09T17:28:45Z

Atennissen:

When writing your own BCI2000 module, you will sometimes want to report values of variables, execution of a certain function, or other information that is
*irrelevant to the user, but
*helps you check whether your code does what it is supposed to.

Often, programmers use individual log files for debugging output, and review those files while their program runs, or afterwards.

This page describes how the BCI2000 C++ framework allows you to easily display debugging information in the operator module's log window, without bothering about creating your own log file.
Nevertheless, you are free to use your own log file if you feel that this better fits your needs.

==Debugging Stream <tt>bcidbg</tt>==
Similar to the <tt>bcierr</tt> and <tt>bciout</tt> streams used for error handling and user warnings, BCI2000 provides a <tt>std::ostream</tt> derived object that accepts strings and numbers for formatted output.
Like the output of <tt>bcierr</tt> and <tt>bciout</tt>, data from <tt>bcidbg</tt> is directed into the operator module's log window.
Similar to error and warning messages, debugging messages will be time stamped and provided with a function context.

However, there are important differences:
*Unlike for <tt>bcierr</tt>, the framework does not interpret the fact that something was written to the stream.
*<tt>bcidbg</tt> can conditionally '''ignore''' the data inserted into it, according to a user-defined global setting. That way, you need not remove your debugging code, nor devise your own conditional output scheme.
*Messages are formatted unobtrusively, and will not automatically pop up the window.

The <tt>bcidbg</tt> stream is available globally, and used as any other <tt>std::ostream</tt> descendant:
mSomeDataMember = SomeFunction();
bcidbg << "Set mSomeDataMember to " << mSomeDataMember << endl;

Note that, just as for <tt>bcierr</tt> and <tt>bciout</tt>, writing to <tt>bcidbg</tt> will not take effect unless it is flushed by inserting <tt>flush</tt> or <tt>endl</tt>. (The latter will insert a newline character before flushing the stream.)

==The Debug Level==
A ''Debug Level'' concept is used to control the output of debug messages.
Basically, a user-specified debug level is compared to the debug levels of individual messages, and messages with a debug level ''above'' the user-specified debug level will be ''suppressed'' from the output. As the debug level defaults to 0, no debug messages will be visible to an end user unless configured accordingly.

Individual messages are associated with a numerical value, their ''Debug Level'', roughly correlating with their significance. Important and sparse messages are given a low debug level value, less important and probably more frequent messages are given a higher debug level.

===Message Debug Level===
The default message debug level is 1.
bcidbg << "This is an important message on any level of debugging" << endl;
To give a message a higher debug level, put it in brackets after the <tt>bcidbg</tt> name:
bcidbg( 10 ) << "This is a fairly uninteresting message" << endl;
Although there is practically no upper limit to debug level values,
a usual range for debug levels is from 1 to 10.

===Global Debug Level===
The amount of actual debugging output is governed by a global debug level.
In BCI2000, this value is corresponds to the '''DebugLevel''' parameter. This parameter is not normally available, and must be specified from the command line when starting a module:
FeedbackDemo 127.0.0.1 --DebugLevel=10
will start the FeedbackDemo module with a debug level of 10.
Note that the debug level parameter will propagate to the other modules only after "Set Config" has been pressed from the operator module. Thus, other modules must be started with the DebugLevel argument, as well, if you need to view debugging messages from operation phases prior to the Initialization Phase.

----
See also: [[Error Streams]]|[[States of Operation]]

Programming Howto:Using TortoiseSVN

2007-05-09T16:47:52Z

Atennissen:

== Using TortoiseSVN for Day-to-Day Tasks ==

=== Updating to the latest version of the BCI2000 project ===
Once you set up client access as described on the [[SVN Client Setup]] page,
there will be
a folder on your harddisk, probably named "BCI2000", and initially displayed with a
green overlay icon. The green overlay icon indicates that all files below the
folder are unchanged since they were checked out.
To bring an existing BCI2000 source tree up to date, right-click the folder
named "BCI2000", and choose "SVN Update" from the context menu. If you
edited a file, and did not commit your changes, a SVN update operation will
merge possible changes made to the server version into your file (but keeping
your original version as a backup with a different name). If you prefer,
you might consider doing a "commit" prior to an "update".

Note: '''There is no indication''' that someone changed a file on the
server since you downloaded it!
Changes on the server will be unknown to
your local SVN files unless you perform an "SVN update".

=== Committing (i.e., writing back) changes you made ===
If you edit a file on your local hard disk which is under SVN, TortoiseSVN
will display it with a red overlay icon. This indicates that the file's content
differs from the file as it was when you downloaded it from the
SVN server.

Once you consider your changes permanent, it is time to write the file
back to the server. This process is called "committing changes" – to perform
it on all files below a certain folder, right-click that folder, and choose "SVN
Commit...". You will be presented a list of files below that folder from
which you may exclude certain ones, or display a list of differences ("Compare with base")
to the version on the SVN server.
If you try to commit changes of files for which you don’t have write access, you will be prompted for a different user name and password repeatedly.
Please contact an [[administrator]] if you think there is a problem with user rights.

=== Adding new files ===
If there are new files inside your BCI2000 folder which TortoiseCVS does not
know about, they will be displayed without an overlay icon. Those
files or folders may be added to the BCI2000 source tree on the server by
choosing "TortoiseSVN->Add..." from the context menu that appears after right-clicking the respective file or folder.
Added files will be considered as empty on the server, and displayed with a
red overlay icon, until you perform a "SVN Commit" on them. You will
need write access to the respective area of the source tree in order to add
files and folders.

== Comparison with other Versioning Software ==

=== TortoiseSVN vs. MS VisualSourceSafe ===
Although the SVN Server/TortoiseSVN combination serves the same purpose as MS
VisualSourceSafe, there are two major differences that affect you as a user:
* With TortoiseSVN, you directly operate on files that are '''located on your own hard disk''', and you do so from a true Windows Explorer window, right clicking onto a file or folder and choosing the appropriate SVN operation from the context menu. With MS VisualSourceSafe, you use a Windows Explorer-like program window to operate on files located inside a database on a server.
* With MS VisualSourceSafe, files that were checked-out for editing were '''blocked for changes''' as far as other users were concerned. With SVN, there is no exclusive checking out of files. Instead, changes made by different users will be merged into to a combined version – otherwise, contradicting changes must be resolved manually (which is a quite rare condition in practice).

=== SVN vs. CVS ===
SVN and CVS both follow a similar philosophy of non-exclusive editing of files, and a similar terminology. Thus, differences are minor (for a concise discussion, see http://www.pushok.com/soft_svn_vscvs.php).
Especially when switching from TortoiseCVS to TortoiseSVN, you will hardly notice any difference when it comes to everyday tasks.

==See also==
*[[SVN Client Setup]]

[[Category:Howto]] [[Category:Development]] [[Category:Preliminaries]]

User Reference:Normalizer

2007-05-09T16:39:57Z

Atennissen:

==Function==
===Normalizing Transform===
The Normalizer applies a linear transformation to its input signal.
For each channel (index denoted with <math>i</math>, an offset value is subtracted, and the result multiplied with a gain value:

<math>\textrm{output}_i=(\textrm{input}_i-\textrm{NormalizerOffset}_i)\times \textrm{NormalizerGain}_i</math>

===Adaptation===
From the past statistics of its input, the Normalizer estimates offset and gain values adaptively to make its output signal
*zero mean, and
*unit variance.
The Normalizer uses ''data buffers'' to accumulate its past input according to user-defined rules.
These rules are called ''buffer conditions'' because they are given in terms of boolean expressions.
Each data buffer is associated with such a boolean expression. Whenever an expression evaluates to ''true'', the current input will be appended to the associated buffer.
Whenever it comes to updating offset and gain values, the Normalizer will use the content of its buffers to estimate data mean and variance. The offset will then be set to the data mean, and the gain to the inverse square root of the data variance, i.e., the inverse of the data standard deviation.

===Adaptation Rationale===
It may appear crude to use the total data variance for the adaptation -- why not use linear regression on data labels (target codes) to separate into user controlled (task determined) and noise variance? User controlled variance would then correspond to target separation on the feedback screen, which is what we want to normalize in the first place.

However, a closer look reveals that the ''relative size'' of user controlled variance, and noise variance is crucial. When that "signal" variance is small compared to noise variance, we would be ill advised to use it in normalization -- this would only lead to enlarged noise, and an erratically moving cursor on the feedback screen.
In this case, we rather want to normalize by noise variance, to keep the cursor well-behaved. At the same time, total variance approaches noise variance in this limit because signal variance is small.

On the other end of the spectrum, we have a signal variance that is large compared to noise variance. Here, we clearly want normalization by signal variance. However, the total variance will be dominated by signal variance. Thus, in the limit of high signal-to-noise ratio, total variance again is the entity by which we want to normalize.

Thus, no matter whether signal-to-noise ratio is high or low, total data variance is a good choice for normalization.

===Typical Use===
Typically, the Normalizer's input is the output of a classifier, which it transforms into a zero mean/unit variance control signal which is then transmitted to an application module.
Using the zero mean/unit variance property, an application module can then relate entities such as window size, screen update rate, cursor speed, and trial duration.

==Parameters==
For each channel of the Normalizer's input signal, adaptation is treated independently.
Offsets, Gains, and Adaptation kind are represented as list parameters, with each entry in the list corresponding to a signal channel.
Buffer configuration is done in matrix form, with columns corresponding to signal channels, and rows corresponding to multiple buffers.

===NormalizerOffsets, NormalizerGains===
Lists of offset and gain values, with entries corresponding to signal channels. These values will be updated depending on the channel's adaptation configuration in the Adaptation parameter.
===Adaptation===
A list of values that determines the adaptation strategy of an individual channel. Possible values are
*0 for no adaptation,
*1 for adjusting offsets to zero mean,
*2 for additionally adjusting gains to unit variance.
===BufferConditions===
A matrix consisting of [[User Reference:Expression Syntax|boolean expressions]].
Expressions may involve [[States]] and the components of the Normalizer's input signal.
*Each matrix entry represents a data buffer which is a ring buffer of length ''BufferLength.'' Whenever a buffer's expression evaluates to ''true,'' the current value of the input signal will be put into the buffer (overwriting past data once the buffer is filled).
*Buffers in a certain column will buffer data from the corresponding signal channel, and will be used in adaptation of that channel only.
*Within columns, the order of buffers does not affect computation.
*Empty expressions do not have any effect on the computation. Thus, it is possible to have a different number of buffers for different channels.
*A buffer to store data for the first target, and during feedback only, should have an expression such as <code>(Feedback)&&(TargetCode==1)</code>.
===BufferLength===
The maximum length of each data buffer.
*The length is specified in data blocks if given as a raw number, and in seconds if given as a number followed by the character "s".
*All data buffers have the same capacity.
*Once a data buffer is filled, its older entries will be replaced with new data (ring buffer).
*In previous versions of BCI2000, buffer lengths were specified in terms of "past trials". However, this would enforce the notion of a "trial", and not generalize to continuous adaptation.
===UpdateTrigger===
A [[User Reference:Expression Syntax|boolean expression]] that triggers adaptation when changing to ''true'' from ''false''.
Generally, continuous adaptation within trials is not desired. Rather, one wants adaptation to occur at the end of a trial. This is achieved with ''UpdateTrigger'' expressions such as <code>Feedback!=0</code> or <code>TargetCode!=0</code>.

==States==
Buffer condition expressions, and the UpdateTrigger expression may involve any [[State]] present in the system. Expressions are checked for syntactical correctness and whether states are present during the [[Preflight Phase]].

==Examples==
===Trial-based 1D Feedback Task with 3 Targets===
*Only data from the feedback phase should enter into the adaptation.
*To make sure that targets contribute equally to the adaptation, we use a single buffer for each target. We use a 3-rows-by-1-column BufferConditions matrix:
(Feedback)&&(TargetCode==1)
(Feedback)&&(TargetCode==2)
(Feedback)&&(TargetCode==3)
*We want to use data from three previous trials of each target.
*Feedback duration is 2 seconds.We set the buffer length to the equivalent of three feedback durations:
BufferLength= 6s
*Adaptation should happen at the end of each trial, when feedback is finished.We set UpdateTrigger to an expression that changes to ''true'' when feedback ends:
UpdateTrigger= (Feedback==0)

===Trial-based 2D Feedback Task with 4 Targets===
*Leaving everything else as in the previous example, we now have two dimensions corresponding to left-right (channel 1) and up-down (channel 2).
:Target positions are as indicated below:
---------------------------
| ##1## |
|# #|
|2 3|
|# #|
| ##4## |
---------------------------
:We use data from targets 1 and 4 to adjust channel 2, and targets 2 and 3 to adjust channel 1. Accordingly, the BufferConditions matrix is
(Feedback)&&(TargetCode==2) (Feedback)&&(TargetCode==1)
(Feedback)&&(TargetCode==3) (Feedback)&&(TargetCode==4)

===Continuous 1D Control without pre-defined Targets===
*We know that, over a period of 10 minutes, all output values will occur with approximately equal frequency, or at least have a symmetric distribution around zero. This matches the combination of BCI2000 and Dasher or other "devices" expecting statistically balanced input.
:The BufferConditions matrix will have a single entry containing a constant expression:
1
:This way, data will always be buffered.
*There are no trials. We want a continuous adaptation to the values of the last 10 minutes.
:We set the BufferLength parameter to <code>600s</code>, or <code>(10*60)s</code>.
:For continuous adaptation, we enter an ''empty string'' (not a constant 0 expression) for UpdateTrigger.
----
See also: [[User Reference:Expression Syntax]]

Technical Reference:System Design

2007-05-09T16:30:28Z

Atennissen:

==Overview==
While BCIs can differ widely in the nature of the physiological components they
use, the signal processing they perform, the feedback they provide, or
the underlying training and operation paradigm, they all need the same four
elements: EEG data collection, signal processing, an output device and manual or
automatic parameterization and configuration. Therefore, it seems to be a
natural choice to partition the system into four modules with respect to
functionality.
It is conceivable that for certain BCIs, the chosen decomposition might be
overkill, or even unfavorable, but still these modules seem to be the most appropriate
for a variety of systems.

In accordance with this decomposition, BCI2000 consists of four modules that communicate with each other. (See Figure 1.) These modules are called ''Source'', ''Signal Processing'', ''Application'', and ''Operator''. We will
refer to the three modules Source, Signal Processing and Application
together as
''core modules''.
[[Image:BCI2000 SysDes_Modules.png|center|thumb|300px|Fig. 1 The functional modules and their interfaces]]

In a binary distribution, the four modules correspond to executables.
For modules other than the operator module, executable file names vary, reflecting specializations of the generic modules.

{|border="1"
|+ Example Configuration
! Module Name !! Executable File Name !! Notes
|-
| Operator || Operat.exe ||  
|-
| EEG source || gUSBamp.exe || data acquisition from the gUSBamp g.tec amplifier
|-
| Signal Processing || ARSignalProcessing.exe || auto-regressive spectral estimation
|-
| Application || CursorTask.exe || moving a cursor by brain activity
|}

==Core-Operator Communication==
===Introduction===
The same communication protocol is used between each of the three core
modules
and the operator module. Although it can be implemented on top of any
transport
protocol, the communication protocol assumes the reliability of TCP (i.e., the protocol does
not support
acknowledgements or packet sorting or any other means of error
correction).
Communication consists of [[BCI2000 messages|messages]] that are sent and received
asynchronously
between any core module and the operator module.
Below, an overview of message types is given. For details about specific messages, refer to the [[BCI2000 messages]] page.

===Status Information Messages===
[[Type:Status|Status]] messages are used to communicate errors and to convey status
information (e.g., the operator module may display the remaining disc space on the Source
module's machine).

===Parameter Messages===
These messages transport [[Type:Parameter|Parameters]] carrying configuration information.
The operator module receives parameter messages from core modules, which enable it to display parameters in a configuration dialog, and to save parameters to, and load them from a [[parameter file]].

===State Messages===
The core modules and the operator module use messages containing [[Type:State|States]] to
communicate in the system initialization phase,
as well as during system performance and
for system termination.

===Visualization Messages===
[[Type:Visualization|Visualization]] messages are sent from core modules to the operator module, which in turn displays their content to the operator user.
These messages may contain signal data for graphical display, or text to be displayed in a log window.
A core module may also configure details of the display sending configuration messages.

===System Command Messages===
[[Type:System Command|System Commands]] are meta-messages used to control the behavior of individual modules by switching their internal state. Typical system commands are <tt>EndOfParameter</tt> and <tt>EndOfState</tt>, to terminate a list of parameter or state messages.
The nature of these system commands is defined by the specific
implementation of
the modules.

==Inter-Core Communication==
===Introduction===
Unlike the bidirectional communication between core modules and the
operator
module, communication within the core modules is unidirectional. The
initial
setup determines the exact nature of this communication and data is
transmitted
with the same protocol as described above.

===State Vector Messages===
A [[Type:State Vector|State Vector]] is a data structure consisting of a series of ''StateVectorLength''
subsequent bytes, representing an overall system state that is saved into a data file along with each block of data.
The state vector is always transmitted before the
brain
signal or control signal.

===Brain Signal Messages===
From the source to the signal processing module, selected channels from the brain signal are transmitted as 32-bit floating point numbers calibrated into microvolts.
The brain signal format is similar to the data format used for graphic visualization messages.

===Control Signal Messages===
From the signal processing to the application module, signal messages transfer decoded rather than raw brain signals. In both cases, the same kind of message is used.
Typically, control signals consist of two or three channels carrying signals with zero mean and unit variance.

Programming Tutorial:Implementing a Source Module

2007-05-09T16:23:27Z

Atennissen:

Data acquisition modules are factored into code required for any
hardware,
and code required to access a specific hardware.
You provide a function that waits for and reads A/D
data (line 3 in the EEG source pseudo code of [[Modules:Data Acquisition]]),
together with some helper functions that perform initialization and
cleanup tasks.
Together these functions form a class derived from
<tt>GenericADC</tt>.

==Scenario==
Your ''Tachyon Corporation'' A/D card comes with a C-style
software interface
declared in a header file <tt>"TachyonLib.h"</tt> that consists of
three
functions
<pre>
#define TACHYON_NO_ERROR 0
int TachyonStart( int inSamplingRate, int inNumberOfChannels );
int TachyonStop( void );
int TachyonWaitForData( short** outBuffer, int inCount );
</pre>
From the library help file, you learn that <tt>TachyonStart</tt>
configures the
card and starts acquisition to some internal buffer; that
<tt>TachyonStop</tt>
stops acquisition to the buffer, and that <tt>TachyonWaitForData</tt>
will block execution until the specified amount of data has been
acquired, and
that it will return a pointer to a buffer containing the data in its
first argument.
Each of the functions will return zero if everything went well, otherwise
some error value will be given.
Luckily, ''Tachyon Corporation'' gives you just
what you need for a BCI2000 source module, so implementing the ADC
class is
quite straightforward.

==Writing the ADC Header File==
In your class' header file, <tt>"TachyonADC.h"</tt>, you write
<pre>
#ifndef TACHYON_ADC_H
#define TACHYON_ADC_H

#include "GenericADC.h"

class TachyonADC : public GenericADC
{
public:
TachyonADC();
~TachyonADC();

void Preflight( const SignalProperties&, SignalProperties& ) const;
void Initialize();
void Process( const GenericSignal*, GenericSignal* );
void Halt();

private:
int mSourceCh,
mSampleBlockSize,
mSamplingRate;
};
#endif // TACHYON_ADC_H
</pre>

==ADC Implementation==
In the .cpp file, you will need some <tt>#includes</tt>, and a filter
registration:
<pre>
#include "TachyonADC.h"
#include "Tachyon/TachyonLib.h"
#include "BCIError.h"

using namespace std;

RegisterFilter( TachyonADC, 1 );
</pre>
From the constructor, you request parameters and states that your ADC
needs;
from the destructor, you call <tt>Halt</tt> to make sure that your
board stops
acquiring data whenever your class instance gets destructed:
<pre>
TachyonADC::TachyonADC()
: mSourceCh( 0 ),
mSampleBlockSize( 0 ),
mSamplingRate( 0 )
{
BEGIN_PARAMETER_DEFINITIONS
"Source int SourceCh= 64 64 1 128 "
"// this is the number of digitized channels",
"Source int SampleBlockSize= 16 5 1 128 "
"// this is the number of samples transmitted at a time",
"Source int SamplingRate= 128 128 1 4000 "
"// this is the sample rate",
END_PARAMETER_DEFINITIONS
}

TachyonADC::~TachyonADC()
{
Halt();
}
</pre>

==ADC Initialization==
Your <tt>Preflight</tt> function will check whether the board works
with the
parameters requested, and communicate the dimensions of its output
signal:
<pre>
void TachyonADC::Preflight( const SignalProperties&,
SignalProperties& outputProperties )
const
{
if( TACHYON_NO_ERROR !=
TachyonStart( Parameter( "SamplingRate" ), Parameter( "SourceCh" ) ) )
bcierr << "SamplingRate and/or SourceCh parameters are not compatible"
<< " with the A/D card"
<< endl;
TachyonStop();
outputProperties = SignalProperties( Parameter( "SourceCh" ),
Parameter( "SampleBlockSize" ),
SignalType::int16 );
}
</pre>
Here, the last argument of the <tt>SignalProperties</tt> constructor
determines not only the type of the signal propagated to the BCI2000
filters
but also the format of the <tt>dat</tt> file written by the source
module.
For the <tt>Initialize</tt> function, it will only be
called if
<tt>Preflight</tt> did not report any errors. If everything works
fine with
the parameters, you may skip any checks, and write
<pre>
void TachyonADC::Initialize()
{
mSourceCh = Parameter( "SourceCh" );
mSampleBlockSize = Parameter( "SampleBlockSize" );
mSamplingRate = Parameter( "SamplingRate" );
TachyonStart( mSamplingRate, mSourceCh );
}
</pre>
Balancing the <tt>TachyonStart</tt> call in the <tt>Initialize</tt> function,
your <tt>Halt</tt> function should stop all asynchronous activity that
your ADC code initiates:
<pre>
void TachyonADC::Halt()
{
TachyonStop();
}
</pre>

==Data Acquisition==
Note that the function may not return unless the output signal is filled with data, so it is
crucial that <tt>TachyonWaitForData</tt> is a blocking function.
(If your card does not provide such a function, and you need to poll
for data, don't forget to call <tt>Sleep( 0 )</tt> inside your polling loop to
avoid hogging the CPU.)
<pre>
void TachyonADC::Process( const GenericSignal*, GenericSignal* outputSignal )
{
int valuesToRead = mSampleBlockSize * mSourceCh;
short* buffer;
if( TACHYON_NO_ERROR == TachyonWaitForData( &buffer, valuesToRead ) )
{
int i = 0;
for( int channel = 0; channel < mSourceCh; ++channel )
for( int sample = 0; sample < mSampleBlockSize; ++sample )
( *outputSignal )( channel, sample ) = buffer[ i++ ];
}
else
bcierr << "Error reading data" << endl;
}
</pre>

==Finished==
You are done! Use your <tt>TachyonADC.cpp</tt> to replace the
<tt>GenericADC</tt>
descendant in an existing source module, add the
<tt>TachyonADC.lib</tt> shipped
with your card to the project, compile, link, and find the bugs...

Programming Reference:Rapid Development

2007-05-09T16:07:52Z

Atennissen:

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:Demo Application]] may serve as a starting point for a trial-based application.
*The [[Programming Reference:IIRFilter]] filter stub allows you to easily implement IIR filters.

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

==Matlab Integration==
*The [[Programming Reference:MatlabFilter]] lets Matlab scripts act upon BCI2000 data.

Programming Reference:Filter Chain

2007-05-09T16:06:09Z

Atennissen:

==The filter chain==
As noted in the [[Programming Reference:GenericFilter Class|discussion]] of the <tt>GenericFilter::Process</tt> function, all <tt>GenericFilter</tt> descendants inside a BCI2000
module form a single chain of filters. Each filter's output forms the input of the
subsequent filter.

==Filter Instantiation==
Creating instances of all filter classes inside a module, and building the filter chain, is handled by the framework. However, it needs a hint to determine the sequence in which filters are to be arranged. In general, this hint consists of a single statement placed inside your filter's .cpp file:<pre>
RegisterFilter( MyFilter, 2.C );</pre>
The first argument to this statement is the class name of your filter;
the second argument is a string value (given without quotes) that determines the
relative position of your filter in the filter chain.
This is done by applying the simple rule that the filter positions in the chain match the alphanumeric sorting order of the associated postion strings of the filters.
This scheme allows you to place an additional filter between existing ones without changing the position strings of the existing filters.

==Signal Processing Filter Instantiation==
In principle, the above scheme allows to you add filters to a module's filter chain
without
modification to the existing source code, simply by adding a .cpp file
with a
<tt>RegisterFilter</tt> statement to the project.
However for Signal Processing modules, it is more desirable to
have an
explicit representation of the entire filter chain centralized in one
place.
So, for each individual Signal Processing module there is one file
<tt>PipeDefinition.cpp</tt> that defines the filter chain as a
sequence of
<tt>Filter</tt> statements (see [[Programming Tutorial:Implementing a Signal Processing Filter]] for
an
example).

MARIO Technical Documentation

2007-05-09T15:29:54Z

Atennissen:

==MARIO architecture==
MARIO is an off-line analysis application developed in MATLAB 7.0.2. It is now modular, object-oriented and can be easily integrated with any other software for data analysis and visualization.
It can be used in Mu and P300 analyses and allows three kinds of use: users can simply fill the forms of a graphical interface making any choice with a click of its mouse, run a ready-made script or, write up their own scripts according to their needs.
This set of interfaces allows a wide range of possibilities for a wide range of different analyses.

Internally, the application is composed of 6 main functional modules, each one connected in cascade as in the list below:

*Data import
*Signal Conditioning
*Feature Extraction
*Spectral Extimation
*Statistical Analysis
*Visualization

[[Image:arch_blocks.jpg]]

All these modules are hidden in the graphical user interface but they can be distinguished in the batch scripts. Each one of them can be easily replaced with an improved version, a custom version or a different analysis.

[[Image:Graph.png|thumb|left|Graph of modules]]
Here you can see a simplified version of the functions graph with their relationships (click to enlarge). 

==Data Import Module==

Any script must have a first module in which to load data that the user wants to analyze.
There are 3 main types of files containing different groups of information:

*Data files (.dat/.mat)
*Montage files (.mmf)
*External Parameter files (.prm) – optional

The data files contain all the data of the BCI session (Mu or P300).
These data are saved in different files, one for each run, containing 29 trials.
Internally any file is divided in two main parts: the first part (file header) includes all parameters set by the operator during the on-line experimentation; the second part contains the EEG signal recorded by the whole set of electrodes on the EEG cap.
A special function allows data to be loaded from a Matlab file (.mat).

The montage file stores information about the electrode position on the scalp. It consists
of different sections divided by labels:

#a synthetic name
#the channel labels
#a valid channels list
#the laplacian grid
#the 3-dimensional spatial coordinates of all the electrodes (this section is optional)

These labelled sections can be written in the Montage file without a predefined order.

The user can import data from an additional data file, (a parameters file), that can be used if he wants to replace one or more parameters from the BCI2000 ones. For this, it is enough to copy and paste the selected header string in a new prm file, and change its value.

This module is clearly the same for Mu and P300 Analysis.

==Data Conditioning Module==

The MARIO v.2.0 Data Conditioning module allows users to select from a wide range of spatial filters so as to include a custom filter in the user data analysis. The operator can identify which channels or set of channels will give better results at the end of the statistical analysis.

For a Mu analysis, the user can select from four different spatial filter algorithms:

*RAW
*CAR (Common Average Reference)
*SMALL LAP
*LARGE LAP

The first one, (RAW) does not use a filter and analyzes raw recorded data. A user defined analysis will be available on further versions of MARIO.

The Data Conditioning module also allows the the user to compile/modify a list of valid channels on which to conduct any analysis.

P300 Analysis can now use only two of the above spatial filters: the RAW filter and the CAR one. Any other selection will report an unhandled error.

==Feature Extraction Module==

Feature extraction is one of the most important stages of elaboration; it affects any further analysis.

In a Mu rhythm analysis, any feature can be obtained by arranging some of the 12 BCI2000 states.
The user can now make a choice between two predefined analyses, a simple Mu analysis or an Extended version of the same. The first analysis considers any sample recorded between the cursor appearance on the screen and the end of the trial (when the cursor reaches the right side of the screen).
The MuExteded analysis instead considers any sample recorded since the target appearance (during the first subset of data, the subject does not have any feedback) until the end of trial.
In both choices, the statistical analysis will be conduced between two classes of data: the EEG activity recorded while moving up the cursor (target UP) versus the EEG activity recorded while moving down the cursor (target DOWN).
Either of these choices will produce different R2 values between the corresponding features of the two classes

For a P300 Analysis only two classes are compared and automatically set as frequent events and rare events.

==Spectral Extimation Module ''(for Mu rhythm analysis)''==

During this step, the program evaluates and analyzes the spectrum of recorded data.
To do that, the EEG signal is divided into equal length epochs (These epochs can be distinct or overlapped as a percentage of overlap, which the user can set by using the Graphical User Interface or script.) A spectrum value is evaluated for anyone of these epochs.

At the end of this process, a 3 dimensional matrix (bin × channel × epoch) joined with the one (channel × sample) compiled during a BCI2000 recording session and read by the data import module will be produced.

The algorithm employed to estimate the signal spectrum is the MEM (the same used on-line by BCI2000).

Apart from the percentage of overlap, MARIO allows the user to modify the values of:

#Sampling frequency of recorded data
#Spatial resolution (delta)
#Detrending order (Mean or Linear)
#AR model order
#Low pass filter frequency
#High pass filter frequency
#Filter bandwidth
#Epoch length
#Overlap percentage

MARIO v2.0 also computes a virtual states matrix strictly joined with signal one and derived as an arrangement of the BCI2000 states. These states label spectrum samples as valid or not valid and as belonging to one class or another.

==Statistical Analysis Module==

A statistical analysis (presently, R2) is employed to distinguish between the classes of a BCI2000 task in any trial.

MARIO uses a module that computes the R2 value between two classes; these can be TargetUP and TargetDOWN for a Mu rhythm analysis, or frequent events and rare events for a P300 analysis. These data are taken from the spectra matrix (Mu analysis) or from the samples one (P300 analysis) and the regressor vector is yield from BCI2000 states.

At the end of this analysis, the real index produced (in a range between -1 and 1) is the R2 value multiplied by R2 sign. If the R2 value is near 1, there is an high separability between classes and high performance. If, instead, its value is near 0, it is difficult to distinguish one class from another, and it means low performance.

==Visualization Module==

Mario offers a wide set of visualization graphs that can be combined to have a complete visualization of produced data.
For a Mu rhythm analysis the user can request to visualize:

#a trajectory plot showing the cursor position for any sample in a trial BCI2000 as the user saw it on-line
#a matrix (channel × bin) where the R2 value of any feature is shown in a color tint. A colorbar shows the color range between -1 and 1
#Another panel showing a detail of the previous matrix. The upper topographic plot shows the R2 value for any channel in the selected bin of frequencies; the lower one is the spectrum of the selected channel for all the frequencies.

For a P300 analysis the user can choose from:

#An R2 matrix
#An amplitude waveform graph
#A topographic plot
#An ERP response graph
#A string prediction form.

All these result visualizations can be easily included in any of the user scripts for custom analysis.

MARIO Technical Documentation

2007-05-09T15:28:25Z

Atennissen:

==MARIO architecture==
MARIO is an off-line analysis application developed in MATLAB 7.0.2. It is now modular, object-oriented and can be easily integrated with any other software for data analysis and visualization.
It can be used in Mu and P300 analyses and allows three kinds of use: users can simply fill the forms of a graphical interface making any choice with a click of its mouse, run a ready-made script or, write up their own scripts according to their needs.
This set of interfaces allows a wide range of possibilities for a wide range of different analyses.

Internally, the application is composed of 6 main functional modules, each one connected in cascade as in the list below:

*Data import
*Signal Conditioning
*Feature Extraction
*Spectral Extimation
*Statistical Analysis
*Visualization

[[Image:arch_blocks.jpg]]

All these modules are hidden in the graphical user interface but they can be distinguished in the batch scripts. Each one of them can be easily replaced with an improved version, a custom version or a different analysis.

[[Image:Graph.png|thumb|left|Graph of modules]]
Here you can see a simplified version of the functions graph with their relationships (click to enlarge). 

==Data Import Module==

Any script must have a first module in which to load data that the user wants to analyze.
There are 3 main types of files containing different groups of information:

*Data files (.dat/.mat)
*Montage files (.mmf)
*External Parameter files (.prm) – optional

The data files contain all the data of the BCI session (Mu or P300).
These data are saved in different files, one for each run, containing 29 trials.
Internally any file is divided in two main parts: the first part (file header) includes all parameters set by the operator during the on-line experimentation; the second part contains the EEG signal recorded by the whole set of electrodes on the EEG cap.
A special function allows data to be loaded from a Matlab file (.mat).

The montage file stores information about the electrode position on the scalp. It consists
of different sections divided by labels:

#a synthetic name
#the channel labels
#a valid channels list
#the laplacian grid
#the 3-dimensional spatial coordinates of all the electrodes (this section is optional)

These labelled sections can be written in the Montage file without a predefined order.

The user can import data from an additional data file, (a parameters file), that can be used if he wants to replace one or more parameters from the BCI2000 ones. For this, it is enough to copy and paste the selected header string in a new prm file, and change its value.

This module is clearly the same for Mu and P300 Analysis.

==Data Conditioning Module==

The MARIO v.2.0 Data Conditioning module allows users to select from a wide range of spatial filters so as to include a custom filter in the user data analysis. The operator can identify which channels or set of channels will give better results at the end of the statistical analysis.

For a Mu analysis, the user can select from four different spatial filter algorithms:

*RAW
*CAR (Common Average Reference)
*SMALL LAP
*LARGE LAP

The first one (RAW) does not use a filter and analyzes raw recorded data. A user defined analysis will be available on further versions of MARIO.

The Data Conditioning module also allows the the user to compile/modify a list of valid channels on which to conduct any analysis.

P300 Analysis can now use only two of the above spatial filters: the RAW filter and the CAR one. Any other selection will report an unhandled error.

==Feature Extraction Module==

Feature extraction is one of the most important stages of elaboration; it affects any further analysis.

In a Mu rhythm analysis, any feature can be obtained by arranging some of the 12 BCI2000 states.
The user can now make a choice between two predefined analyses, a simple Mu analysis or an Extended version of the same. The first analysis considers any sample recorded between the cursor appearance on the screen and the end of the trial (when the cursor reaches the right side of the screen).
The MuExteded analysis instead considers any sample recorded since the target appearance (during the first subset of data, the subject does not have any feedback) until the end of trial.
In both choices, the statistical analysis will be conduced between two classes of data: the EEG activity recorded while moving up the cursor (target UP) versus the EEG activity recorded while moving down the cursor (target DOWN).
Either of these choices will produce different R2 values between the corresponding features of the two classes

For a P300 Analysis only two classes are compared and automatically set as frequent events and rare events.

==Spectral Extimation Module ''(for Mu rhythm analysis)''==

During this step, the program evaluates and analyzes the spectrum of recorded data.
To do that, the EEG signal is divided into equal length epochs (These epochs can be distinct or overlapped as a percentage of overlap, which the user can set by using the Graphical User Interface or script.) A spectrum value is evaluated for anyone of these epochs.

At the end of this process, a 3 dimensional matrix (bin × channel × epoch) joined with the one (channel × sample) compiled during a BCI2000 recording session and read by the data import module will be produced.

The algorithm employed to estimate the signal spectrum is the MEM (the same used on-line by BCI2000).

Apart from the percentage of overlap, MARIO allows the user to modify the values of:

#Sampling frequency of recorded data
#Spatial resolution (delta)
#Detrending order (Mean or Linear)
#AR model order
#Low pass filter frequency
#High pass filter frequency
#Filter bandwidth
#Epoch length
#Overlap percentage

MARIO v2.0 also computes a virtual states matrix strictly joined with signal one and derived as an arrangement of the BCI2000 states. These states label spectrum samples as valid or not valid and as belonging to one class or another.

==Statistical Analysis Module==

A statistical analysis (presently, R2) is employed to distinguish between the classes of a BCI2000 task in any trial.

MARIO uses a module that computes the R2 value between two classes; these can be TargetUP and TargetDOWN for a Mu rhythm analysis, or frequent events and rare events for a P300 analysis. These data are taken from the spectra matrix (Mu analysis) or from the samples one (P300 analysis) and the regressor vector is yield from BCI2000 states.

At the end of this analysis, the real index produced (in a range between -1 and 1) is the R2 value multiplied by R2 sign. If the R2 value is near 1, there is an high separability between classes and high performance. If, instead, its value is near 0, it is difficult to distinguish one class from another, and it means low performance.

==Visualization Module==

Mario offers a wide set of visualization graphs that can be combined to have a complete visualization of produced data.
For a Mu rhythm analysis the user can request to visualize:

#a trajectory plot showing the cursor position for any sample in a trial BCI2000 as the user saw it on-line
#a matrix (channel × bin) where the R2 value of any feature is shown in a color tint. A colorbar shows the color range between -1 and 1
#Another panel showing a detail of the previous matrix. The upper topographic plot shows the R2 value for any channel in the selected bin of frequencies; the lower one is the spectrum of the selected channel for all the frequencies.

For a P300 analysis the user can choose from:

#An R2 matrix
#An amplitude waveform graph
#A topographic plot
#An ERP response graph
#A string prediction form.

All these result visualizations can be easily included in any of the user scripts for custom analysis.

MARIO Technical Documentation

2007-05-09T15:26:23Z

Atennissen:

==MARIO architecture==
MARIO is an off-line analysis application developed in MATLAB 7.0.2. It is now modular, object-oriented and can be easily integrated with any other software for data analysis and visualization.
It can be used in Mu and P300 analyses and allows three kinds of use: users can simply fill the forms of a graphical interface making any choice with a click of its mouse, run a ready-made script or, write up their own scripts according to their needs.
This set of interfaces allows a wide range of possibilities for a wide range of different analyses.

Internally, the application is composed of 6 main functional modules, each one connected in cascade as in the list below:

*Data import
*Signal Conditioning
*Feature Extraction
*Spectral Extimation
*Statistical Analysis
*Visualization

[[Image:arch_blocks.jpg]]

All these modules are hidden in the graphical user interface but they can be distinguished in the batch scripts. Each one of them can be easily replaced with an improved version, a custom version or a different analysis.

[[Image:Graph.png|thumb|left|Graph of modules]]
Here you can see a simplified version of the functions graph with their relationships (click to enlarge). 

==Data Import Module==

Any script must have a first module in which to load data that the user wants to analyze.
There are 3 main types of files containing different groups of information:

*Data files (.dat/.mat)
*Montage files (.mmf)
*External Parameter files (.prm) – optional

The data files contain all the data of the BCI session (Mu or P300).
These data are saved in different files, one for each run, containing 29 trials.
Internally any file is divided in two main parts: the first part (file header) includes all parameters set by the operator during the on-line experimentation; the second part contains the EEG signal recorded by the whole set of electrodes on the EEG cap.
A special function allows data to be loaded from a Matlab file (.mat).

The montage file stores information about the electrode position on the scalp. It consists
of different sections divided by labels:

#a synthetic name
#the channel labels
#a valid channels list
#the laplacian grid
#the 3-dimensional spatial coordinates of all the electrodes (this section is optional)

These labelled sections can be written in the Montage file without a predefined order.

The user can import data from an additional data file, (a parameters file), that can be used if he wants to replace one or more parameters from the BCI2000 ones. For this, it is enough to copy and paste the selected header string in a new prm file, and change its value.

This module is clearly the same for Mu and P300 Analysis.

==Data Conditioning Module==

The MARIO v.2.0 Data Conditioning module allows users to select from a wide range of spatial filters so as to include a custom filter in the user data analysis. The operator can identify which channels or set of channels will give better results at the end of the statistical analysis.

For a Mu analysis, the user can select from four different spatial filter algorithms:

*RAW
*CAR (Common Average Reference)
*SMALL LAP
*LARGE LAP

The first one (RAW) does not use a filter and analyzes raw recorded data. A user defined analysis will be available on further versions of MARIO.

The Data Conditioning module also allows the the user to compile/modify a list of valid channels on which to conduct any analysis.

P300 Analysis can now use only two of the above spatial filters: the RAW filter and the CAR one. Any other selection will report an unhandled error.

==Feature Extraction Module==

Feature extraction is one of the most important stages of elaboration; it affects any further analysis.

In a Mu rhythm analysis, any feature can be obtained by arranging some of the 12 BCI2000 states.
The user can now make a choice between two predefined analyses, a simple Mu analysis or an Extended version of the same. The first analysis considers any sample recorded between the cursor appearance on the screen and the end of the trial (when the cursor reaches the right side of the screen).
The MuExteded analysis instead considers any sample recorded since the target appearance (during the first subset of data, the subject does not have any feedback) until the end of trial.
In both choices, the statistical analysis will be conduced between two classes of data: the EEG activity recorded while moving up the cursor (target UP) versus the EEG activity recorded while moving down the cursor (target DOWN).
Either of these choices will produce different R2 values between the corresponding features of the two classes

For a P300 Analysis only two classes are compared and automatically set as frequent events and rare events.

==Spectral Extimation Module ''(for Mu rhythm analysis)''==

During this step, the program evaluates and analyzes the spectrum of recorded data.
To do that, the EEG signal is divided into equal length epochs (These epochs can be distinct or overlapped as a percentage of overlap, which the user can set by using the Graphical User Interface or script.) A spectrum value is evaluated for anyone of these epochs.

At the end of this process, a 3 dimensional matrix (bin × channel × epoch) joined with the one (channel × sample) compiled during a BCI2000 recording session and read by the data import module will be produced.

The algorithm employed to estimate the signal spectrum is the MEM (the same used on-line by BCI2000).

Apart from the percentage of overlap, MARIO allows the user to modify the values of:

#Sampling frequency of recorded data
#Spatial resolution (delta)
#Detrending order (Mean or Linear)
#AR model order
#Low pass filter frequency
#High pass filter frequency
#Filter bandwidth
#Epoch length
#Overlap percentage

MARIO v2.0 also computes a virtual states matrix strictly joined with signal one and derived as an arrangement of the BCI2000 states. These states label spectrum samples as valid or not valid and as belonging to one class or another.

==Statistical Analysis Module==

A statistical analysis (presently, R2) is employed to distinguish between the classes of a BCI2000 task in any trial.

MARIO uses a module that computes the R2 value between two classes; these can be TargetUP and TargetDOWN for a Mu rhythm analysis, or frequent events and rare events for a P300 analysis. These data are taken from the spectra matrix (Mu analysis) or from the samples one (P300 analysis) and the regressor vector is yield from BCI2000 states.

At the end of this analysis, the real index produced (in a range between -1 and 1) is the R2 value multiplied by R2 sign. If the R2 value is near 1, there is an high separability between classes and high performance. If, instead, its value is near 0, it is difficult to distinguish one class from another, and it means low performance.

==Visualization Module==

Mario offers a wide set of visualization graphs that can be combined to have a complete visualization of produced data.
For a Mu rhythm analysis user can request to visualize:

#a trajectory plot showing the cursor position for any sample in a trial BCI2000 as user saw it on-line
#a matrix (channel × bin) where the R2 value of any feature is shown in a color tint. A colorbar shows the color range between -1 and 1
#Another panel showing a detail of the previous matrix. The upper topographic plot shows the R2 value for any channel in the selected bin of frequencies; the lower one is the spectrum of the selected channel for all the frequencies.

For a P300 analysis user can choose from:

#An R2 matrix
#An amplitude waveform graph
#A topographic plot
#An ERP response graph
#A string prediction form.

All these result visualizations can be easily included in any of user scripts for custom analysis.

Programming Reference:Localization

2007-05-09T14:21:16Z

Atennissen:

== '''Introduction''' ==
As BCI2000 modules are being used in various countries, there emerges some need to adapt user interface elements to regional customs. Most notably, text that gives information to the subject requires translation into the subject's native language, as often a knowledge of English cannot be assumed. Even with a knowledge of Englisn, reading text in a foreign language is a distracting factor that makes the already demanding task of operating a BCI even more difficult.

This document explains the approach taken to manage localized (translated) user interface strings in BCI2000 application modules, trying to meet the following goals:

*'''Flexibility:''' For the end user (operator), it should be possible to add translations into a language that are not provided inside an application module, and to modify translations he does not feel to be appropriate. This should be achievable without making changes to the source code and recompiling the application module.
*'''Separability:''' For the user, switching languages should be done at a central place, i.e., by changing a single parameter. For the programmer, adding localization capabilities to existing modules should be possible with minimal changes to existing code. When writing new application modules, there should be no need to consider localization issues in advance.
*'''Documentation:''' Documenting and providing a collection of existing translations into various languages should be possible inside a module's source code.

== '''Strategies''' ==

For a number of text values that have always been set from parameters (such as the Speller module's <tt>Goal</tt> parameter that holds the text the user is told to spell in copy spelling mode), localization is not an issue because the user may just change the value as seems appropriate.

The remaining text items, according to the way they are specified, fall into two categories:

# C string literals in <tt>*.cpp</tt> source files, and
# text fields in GUI resource files (such as Borland <tt>*.dfm</tt> files).

For both categories, translations are kept in a single matrix type parameter that uses string labels, i.e., row and column titles. Each column title represents the native English version of a text; row titles represent languages for which translations exist. The user chooses amongst languages by specifying the desired language in a second parameter; the BCI2000 framework will then use this table to look up a text's translation, matching the text itself against column labels, and
the target language against row labels. If no match is found, it will leave the text unchanged.

For string literals in <tt>*.cpp</tt> files, the strategy is to simply put a function layer around the string, i.e., to send it through a function that checks for a translation and exchanges the text if there is a match. Introducing localizability into existing code implies only a very small amount of change compared to, e.g., introducing a separate parameter for each string. In the former case, one needs only wrap the string literal into a function call in-place; in the latter case, one would have to add a parameter line to a possibly remote filter class constructor, read that parameter from inside that filter's <tt>Initialize()</tt> call, and put it into the object that actually holds the string which might require introduction of additional accessor functions.

For strings specified in GUI resource files, the strategy is to supply a function that, very generally, examines string properties of GUI objects, replacing them with their localized versions if applicable.
This function needs to be called explicitly from inside the <tt>Initialize()</tt> function of the <tt>GenericFilter</tt> descendant that determines the GUI object's behavior (in most cases, this is the application module's <tt>TTask</tt> class).

== '''Implementation''' ==

The implementation is centered around a <tt>Localization</tt> class declared in <tt>Application/shared/Localization.h</tt>.

=== '''Interface to the operator user''' ===

The <tt>Localization</tt> class adds two parameters to the system that govern its localization
behavior:
'''*''' <tt>Language</tt> defines the language into which strings are translated; if its value matches one of the <tt>LocalizedStrings</tt> row labels, translations will be taken from that row; otherwise, strings will not be translated. A value of <tt>Default</tt> results in all strings keeping their original values.
'''*''' <tt>LocalizedStrings</tt> defines string translations. Strings that do not appear as a column label will not be translated. Also, strings with an empty translation entry in <tt>LocalizedStrings</tt> will not be translated.

==='''Interface to the programmer'''===

The <tt>LocalizedStrings</tt> parameter is empty by default. Although a user may add translations in desired languages to the empty matrix by manually using the matrix editor of the operator module, translations will preferably be provided in a filter constructor by listing them as in the following example:

#include "Localization.h"
...
TTask::TTask()
{
...
LANGUAGES "Italian",
"French",
BEGIN_LOCALIZED_STRINGS
"Yes",
"Si",
"Oui",
"No",
"No",
"Non",
END_LOCALIZED_STRINGS
...
}

If the <tt>LocalizedStrings</tt> matrix was empty before the <tt>TTask</tt> constructor gets called, it will have these entries after execution of the constructor:

{|
|
|Yes
|No
|-
|Italian
|Si
|No
|-
|French
|Oui
|Non
|}

There may be any number of translation tables inside filter constructors, with their entries being added to the existing ones, or overriding entries that already exist.

Once entered, the translations contained in <tt>LocalizedStrings</tt> are applied via two mechanisms:

*The function <tt>LocalizableString()</tt> takes a string as an argument and returns the appropriate entry from <tt>LocalizedStrings</tt>, or the unmodified string if no entry can be found. For example, instead of
<tt>TellUser( "Well done!" );</tt> one would write <tt>#include "Localization.h" ... TellUser( LocalizableString( "Well done!" ) ); </tt>to have a translation for "Well done!" looked up in <tt>LocalizedStrings</tt>.

* The function <tt>ApplyLocalizations()</tt> takes a pointer to a GUI object (usually a VCL <tt>TForm*</tt>) and translates all localizable text contained within it. This function must be called during <tt>GenericFilter:: Initialize</tt> for each GUI object generated from a resource file.

==='''Further implementation details'''===

'''*''' You should not use <tt>LocalizableString()</tt> on string constants used before the first call to <tt>GenericFilter::Initialize()</tt> or for initializing static or global objects of any kind because localization information used will not be available at global initialization time, and local static variables, once initialized, will not be updated appropriately.

'''*''' Language names are case-insensitive. You may use any string for a language name but as a convention we suggest its most common English name, as in <tt>Italian, Dutch, French, German</tt>, with international country abbreviations as optional regional qualifiers as in <tt>EnglishUS, EnglishGB, GermanA, GermanCH</tt> if necessary.

[[Image:table.png|center|thumb|300px|table]]

'''*''' Encoding of non-ASCII characters follows the UTF8 convention. To ensure platform independent readability of source code files, there are macros that define HTML character names to their UTF8 encoded strings. This allows you to write

<tt>"Sm" oslash "rrebr" oslash "d"</tt>

for "Smørrebrød" (cf. table 1).

Programming Reference:Error Handling

2007-05-08T20:31:23Z

Atennissen:

=='''Handling Errors'''==

==='''Types of Errors'''===

We assume that all errors we need to consider fall into one of the following categories, each of which implies a different type of approach to error avoidance/error handling:

*Parameter Setup Errors

*Runtime Errors

*Logic (Programming) Errors

==='''Parameter Setup Errors'''===

===='''Definition of the Term'''====
This category covers anything a user can do wrong by using a program with parameters that are out of range, inconsistent, or otherwise erroneous (e.g., by specifying an output file at a location where the user has no write permission).

Parameter setup errors, when unhandled, become runtime errors.

===='''Strategies'''====

As a guideline for approaching Parameter Setup Errors we adopt the following principle: "Whatever a
user does from within an application program should never make that application crash."

In BCI 2000, this translates into a thorough parameter check done by each module before any parameter settings are actually applied to the system.

Parameter checking should comprise

*Range and Consistency checks, whereby ranges generally depend on the values of other parameters;

*Signal property checks: Does the output signal of one filter meet the next filter's requirements for its input signal?

*Resource availability checks:

-Are needed system resources available? (E.g., is it possible to open a required sound output device?)

-Are auxiliary files (e.g., media files) available and readable?

-Do output files have legal file names? Are output files writeable? (We could even check whether
there is enough space left to write the EEG file, but this is not practical because a
concurrent process might use up the space while our system runs.)

In each of these cases, the user should get appropriate feedback guiding her towards fixing the problem.

Whenever the system tries to fix a parameter setup error by using some default set of parameters, it should do so only if

*it presents the user with a warning that tells her what it did and why it did so, and if

*the automatically fixed parameters are treated as if changed by the user, i.e. with a parameter check performed on them.

Otherwise, people may unknowingly using a system that doesn't do what they want it to, or have
a system that creates new parameter inconsistencies when trying to fix others.

===='''User Interface Details'''====

The user interface for Parameter Setup Error handling is, along with the parameter setup dialog, part of the operator module. A first implementation of a GUI based user interface consists in a floating, non-modal error window popping up from the operator module that presents a list of error related textual messages to the user, allowing for browsing error messages
while changing respective parameters via the parameter setup dialog. After the next parameter check, the operator module will close that window or replace its contents based on the result of the check.
Parameter checking occurs when the user clicks the "SetConfig" button in the operator main window, followed by actually applying parameters if the check was successful.

==='''Runtime Errors'''===

===='''Definition of the Term'''====

This category covers everything that can go wrong in the course of running an application program,
insofar as that malfunction is due to a lack of resources in the underlying system required for proper operation (i.e., not due to a programming error). Assuming that parameter checking has been implemented properly as outlined above, we can narrow the term `Runtime Error' to cases for which the following statement holds: A runtime error occurs whenever the system runs out of resources that were still available during parameter checking.

Typical reasons for this kind of error are

*the system runs out of disk space while recording data,

*files being moved, trashed, or locked by a concurrent process,

*a network connection becomes unavailable.

Runtime errors, when unhandled, become logic errors because the code implies assumptions that no longer hold once a runtime error has occurred.

===='''Strategies'''====

In a properly designed and implemented system, runtime errors, in the restricted sense described above, will not occur frequently. However, as they are caused by undesired circumstances outside the scope of the application program itself, it seems important to provide information to the user that is as detailed as possible in order to enable her to prevent this type of situation in the future, and to make her aware of the fact that the application program depends on her willingness to provide a smooth operating environment. That being said, it seems appropriate to simply abort execution altogether, while trying to avoid a loss of the data acquired up to that time.

===='''User Interface Details'''====

In general, it is desirable to have runtime errors displayed along with the user interface of the operator module. However, as this requires a working connection between the module where the error occurs, and the operator module, this may not always be possible. Therefore, in addition to an operator-based error reporting interface, each module should have a less demanding mechanism to provide error information to the user, e.g., a local log file.

==='''Logic Errors'''===

===='''Definition of the Term'''====

Logic, or programming, errors in general can be due to a programmer who, in his or her code, implicitly or explicitly makes assumptions that do not always hold.

===='''Strategies'''====

Programming errors are not supposed to occur at all in a tested version of an application. Therefore, instead of trying to 'handle' them, it is important to make them show up as close to their point of origin in the code as possible, by frequently and explicitly checking whether
implicit assumptions actually hold, and aborting execution with an error message if this is not the case.

Aside from that, writing code as explicit, general, and simple as possible greatly reduces the possibility of making logic errors in the first place.

===='''User Interface Details'''====

As programming errors are errors about which a user can do nothing, simply aborting the program or module with an error message seems appropriate.

=='''Implementation Details'''==

==='''Interface to the Programmer'''===

===='''Reporting Errors'''====

For a simple and general way to provide user communication and a means of error reporting to a module's programmer, there exist two global objects derived from <tt>std::ostream</tt>, one named
<tt>bciout</tt> and the other named <tt>bcierr</tt>, analogous to <tt>std::cout</tt> and <tt>std::cerr</tt>, where <tt>bciout</tt> is used to transfer general messages and warnings while <tt>bcierr</tt> takes actual errors.
A code example then looks like this:

using namespace std;
...
ofstream outputStream( fileName );
if( !outputStream.is_open() )
{
bcierr << "Cannot open the file \""
<< fileName
<< "\" for output"
<< endl;
}

Furthermore, for handling runtime errors from which it is difficult to recover, a programmer may program an exception that will abort execution and eventually lead to an error message being sent to the operator module (for framework related details see the section entitled "Implementation on the Framework Side"):

...
if( ernie.find( bert ) != ernie.end() )
throw "Ernie just ate Bert. "
"I don't know how to tell the story.";
tellMyStory( bert.begin(), ernie.end() );
...

===='''Checking Parameters'''====

Checking parameters is done in a separate member function of the filter base class which, similar to the member function that does the actual processing, takes input and output signal representatives as parameters, thus allowing for signal property checking.

For the actual implementation, its declaration is as follows:

<tt>void GenericFilter::Preflight ( const SignalProperties& inSignalProperties, SignalProperties& outSignalProperties ) const;</tt>

For a filter class derived from <tt>GenericFilter</tt>, this function is supposed to perform
parameter checking as described in the "Strategies" section. Instead of returning an error value, it writes possible error messages into <tt>bcierr</tt>. Furthermore, it communicates dimensions of its output signal which it guarantees not to exceed, and it does so by adjusting the properties of the second SignalProperties object in its argument list, e.g.

<tt>outSignalProperties
= SignalProperties( inSignalProperties.Channels(), 1 );</tt>

or

<tt>outSignalProperties = SignalProperties( 0, 0 );</tt>

if it declares not to use its output signal.

The <tt>const</tt> declaration for its <tt>this</tt> pointer prohibits initialization functionality from <tt>GenericFilter::Initialize()</tt> entering into <tt>Preflight()</tt>; this is unwanted because it would corrupt the idea of performing a ''complete'' parameter check before actually ''altering'' the state of a filter object.

A necessary condition for a correct implementation of the <tt>Preflight()</tt> function is that any parameter, as well as any state that will be accessed during the processing phase, be accessed
from <tt>Preflight()</tt> at least once. For parameters and states defined by the filter itself (i.e. inside its constructor), range and accessibility checks are automatically performed by the framework; parameters and states defined by other filters must be explicitly accessed from <tt>Preflight()</tt>. If a <tt>GenericFilter</tt> descendant fails to access an externally defined parameter or state during <tt>Preflight()</tt>, the first access during the processing phase will result in a runtime error.

===='''Accessing Environment Objects'''====

We consider parameters and states part of the bci2000 "environment". <tt>GenericFilter</tt> descendants have access to that environment, analgous to the concept of environment variables found in some operating systems. Internally, access to the environment is mediated through a mix-in-class named <tt>Environment</tt> that provides accessor symbols to a filter programmer.

'''Low Level Access to Environment Objects''' is provided by the following symbols:

*<tt>Parameters</tt> syntactically behaves like a <tt>PARAMLIST*</tt>,

*<tt>States</tt> behaves like a <tt>STATELIST*</tt>,

*and <tt>Statevector</tt> behaves like a <tt>STATEVECTOR*</tt>.

As an example,

float myParameterValue = 0.0;
PARAM* param = Parameters->GetParamPtr( "MyParameter" );
if( param )
myParameterValue = atof( param->GetValue() );
else
bcierr << "Could not access \"MyParameter\"" << endl;

Unlike true pointers, these symbols cannot be assigned any values, cannot be assigned to variables, or have other manipulating operators applied. For example, the lines

<tt>delete Parameters;
Parameters = new PARAMLIST;
PARAMLIST* someParamlistPointer = Parameters;</tt>

will all result in compiler errors. (In the current (preliminary) implementation, assignments from these symbols, as in the last example, are allowed to ease the transition process.)

'''Convenient Access to Environment Objects''' is possible through a number of symbols which offer built-in checking and error reporting:

*{<tt>Parameter(Name[, Index 1[, Index 2]])</tt>}

This symbol stands for the value of the named parameter. Indices may be given in numerical or textual form; if omitted, they default to 0. The type of the symbol <tt>Parameter()</tt> may be numerical or a string type, depending on its use.(If the compiler complains about ambiguities, use explicit typecasts as in the second example.) If a parameter with the given name does not exist, an error message is written into <tt>bcierr</tt>. If the specified indices do not exist, no error is reported. In both cases, on read access, the string constant <tt>"0"</tt> resp. the number 0 is returned.
(If the compiler complains about ambiguities, use explicit typecasts as in the second example.)

Examples:

<tt>int myValue = Parameter( "MyParam" );
string myOtherValue = ( const char* )Parameter( "MyOtherParam" );
Parameter( "My3rdParam", 2, 3 ) = my3rdValue;</tt>

*<tt>OptionalParameter(Default Value, Name[, Index 1[, Index 2]])</tt>

This symbol behaves like the symbol <tt>Parameter()</tt> but will not report an error if the parameter does not exist. Instead, it will return the default value given in its first argument. Assignments to this symbol are not possible.

*<tt>State(Name)

</tt> This symbol allows for reading a state's value from the state vector and setting a state's value in the state vector. Trying to access a state that is not accessible will result in an error reported via <tt>bcierr</tt>.

Examples:

<tt>short currentStateOfAffairs = State( "OfAffairs" );
State( "OfAffairs" ) = nextStateOfAffairs;</tt>

*<tt>OptionalState(Default Value, Name)

</tt> Analagous to <tt>OptionalParameter()</tt>, this symbol does not report an error if the specified state does not exist but returns the given default value. Assignments to this symbol are not possible.

*<tt>PreflightCondition(Condition)</tt>

This symbol is meant to be used inside implementations of <tt>GenericFilter::Preflight()</tt>. If the boolean condition given as its argument is false, it will output an error message into <tt>bcierr</tt> containing the condition given in its argument.

Example:

<tt>PreflightCondition( Parameter( "TransmitCh" ) <= Parameter( "SourceCh" ) );</tt>

If TransmitCh is greater than SourceCh, a message will be sent to <tt>bcierr</tt> and displayed to the user, stating:

<tt>Condition not fulfilled:
Parameter( "TransmitCh" ) <= Parameter( "SourceCh" )</tt>

(In future versions, the error may be reported in natural language form generated from the boolean expression.)

==='''Implementation on the Framework Side'''===

The behaviour of the operator module in response to an error message that arrives from one of the modules depends on its context, i.e., on the execution phase the system is in. That way, no additional programming interface elements visible to a filter/module programmer are needed to implement an error handling scheme as described in the "Handling Errors"section.

During the '''preflight phase,''' errors are {Parameter Setup Errors}. A module's framework code behind <tt>bcierr</tt> just collects error messages; on return from the preflight function, it
sends those messages to the operator module which then, from the contents of the message (i.e., whether it was empty or not), determines whether the preflight was successful; on not receiving any message after some timeout it assumes a broken connection or a crashed module.

(For now, a simple timeout scheme with a fixed timeout interval of 5s seems appropriate. In the future, one might consider a module requesting additional timeout periods if it expects lengthy calculations.)

During all '''other phases,''' the code behind <tt>bcierr</tt> immediately (i.e., on flushing the <tt>std::ostream</tt>) sends its message buffer to a log file as well as to the operator module, indicating a {Runtime Error} to the operator module which will, in turn, halt the system,shut down the other modules, and display the message to the user.

In addition, the top level exception handling code of each module contains similar functionality,
sending an exception's associated description string into a log file and to the operator module, if possible, then quitting the module in which the exception occurred. This not only ensures
a proper general handling of exceptions within the framework but also allows a programmer to handle {Runtime Errors} by raising her own exceptions, eliminating the need to take care of the error
condition in the code following the detection of an error.

Programming Reference:Debug Output

2007-05-08T19:58:16Z

Atennissen:

When writing your own BCI2000 module, you will sometimes want to report values of variables, execution of a certain function, or other information that is
*irrelevant to the user, but
*helps you check whether your code does what it is supposed to.

Often, programmers use individual log files for debugging output, and review those files while their program runs, or afterwards.

This page describes how the BCI2000 C++ framework allows you to easily display debugging information in the operator module's log window, without bothering about creating your own log file.
Nevertheless, you are free to use your own log file if you feel that this better fits your needs.

==Debugging Stream <tt>bcidbg</tt>==
Similar to the <tt>bcierr</tt> and <tt>bciout</tt> streams used for error handling and user warnings, BCI2000 provides a <tt>std::ostream</tt> derived object that accepts strings and numbers for formatted output.
Like the output of <tt>bcierr</tt> and <tt>bciout</tt>, data from <tt>bcidbg</tt> is directed into the operator module's log window.
Similar to error and warning messages, debugging messages will be time stamped and provided with a function context.

However, there are important differences:
*Unlike for <tt>bcierr</tt>, the framework does not interpret the fact that something was written to the stream.
*<tt>bcidbg</tt> can conditionally '''ignore''' the data inserted into it, according to a user-defined global setting. That way, you need not remove your debugging code, nor devise your own conditional output scheme.
*Messages are formatted unobtrusively, and will not automatically pop up the window.

The <tt>bcidbg</tt> stream is available globally, and used as any other <tt>std::ostream</tt> descendant:
mSomeDataMember = SomeFunction();
bcidbg << "Set mSomeDataMember to " << mSomeDataMember << endl;

Note that, just as for <tt>bcierr</tt> and <tt>bciout</tt>, writing to <tt>bcidbg</tt> will not take effect unless it is flushed by inserting <tt>flush</tt> or <tt>endl</tt>. (The latter will insert a newline character before flushing the stream.)

==The Debug Level==
A ''Debug Level'' concept is used to control the output of debug messages.
Basically, a user-specified debug level is compared to the debug levels of individual messages, and messages with a debug level ''above'' the user-specified debug level will be ''suppressed'' from the output. As the debug level defaults to 0, no debug messages will be visible to an end user unless configured accordingly.

Individual messages are associated with a numerical value, their ''Debug Level'', roughly correlating with their significance. Important and sparse messages are given a low debug level value, less important and probably more frequent messages are given a higher debug level.

===Message Debug Level===
The default message debug level is 1.
bcidbg << "This is an important message on any level of debugging" << endl;
To give a message a higher debug level, put it in brackets after the <tt>bcidbg</tt> name:
bcidbg( 10 ) << "This is a fairly uninteresting message" << endl;
Although there is practically no upper limit to debug level values,
a usual range for debug levels is from 1 to 10.

===Global Debug Level===
The amount of actual debugging output is governed by a global debug level.
In BCI2000, this value is corresponds to the '''DebugLevel''' parameter. This parameter is not normally available, and must be specified from the command line when starting a module:
FeedbackDemo 127.0.0.1 --DebugLevel=10
will start the FeedbackDemo module with a quite verbose debug level of 10.
Note that the debug level parameter will propagate to the other modules only after "Set Config" has been pressed from the operator module. Thus, other modules must be started with the DebugLevel argument, as well, if you need to view debugging messages from operation phases prior to the Initialization Phase.

----
See also: [[Error Streams]]|[[States of Operation]]

Technical Reference:App Connector

2007-05-08T19:37:18Z

Atennissen:

==Introduction==
The BCI2000 external application interface provides a bi-directional link to exchange
information with external processes running on the same machine, or on a different machine
over a local network.
Via the external application interface, read/write access to BCI2000 [[state vector]] information and [[control signal]]s is possible. An external application may
read the <tt>ResultCode</tt> state to access the classification result, set the
<tt>TargetCode</tt> state to control the user's task, or get access to the
control signal that is calculated by SignalProcessing so as to control an
external output device (such as a robotic arm or a web browser). Multiple
instances of BCI2000 running on separate machines may share sequencing and
control signal information, allowing for interactive applications such as games.

===Scope===
The scope of this interface is to provide access to internal BCI2000 information
for cases in which the generation of a full-fledged [[BCI2000 module]] is
impractical. Such a case might be the control of external applications that
practically do not allow full incorporation into the BCI2000 framework (such as
the Dasher system for efficient low-bandwidth spelling).

This interface is
''NOT'' intended to replace the existing BCI2000 framework for BCI2000
communication. The advantages of writing modules that are fully integrated into
the BCI2000 framework are that their configuration is achieved through the same
interface as other BCI2000 configuration, that this configuration is stored in
the data file along with all other system parameters, and that the state of the
module at any given time is encoded in event markers that are also stored in the
data file. In contrast, control of an external device using the External
Application Interface implies that the configuration of the external device has
to be done outside of BCI2000, that this corresponding configuration is not
stored along with the data file, and that the internal state of the output
device is not saved together with the brain signals. This will make it more
difficult to reconstruct what exactly was going on during an experimental
session. It is thus important to keep this in mind when using this
possibility.

===Design===
The design of the external application interface aims at simplicity, and at minimal
interference with the timing of the signal flow through the BCI2000 system. With
this in mind, a connection-less, UDP based transmission protocol was chosen
rather than one based on TCP. This comes at the cost of a possible loss, or
reordering of protocol messages. To keep the probability for such losses as low
as possible, and their consequences as local as possible, messages have been
designed to be short, self-contained, and redundantly encoded in a human
readable fashion.

The connectionless nature of UDP implies that there is no ''server'' or ''client'' in the asymmetric sense that applies for TCP connections. Rather, processes write to local or remote UDP ports, and read from local UDP ports, whenever applicable.
Thus, for bi-directional communication between machine A running BCI2000 and machine B running the external application, there will be two UDP ports involved:
* a port on machine B into which BCI2000 writes out its messages to the external application, and
* a port on machine A into which the external application writes its messages to BCI2000.
In most cases, both BCI2000 and the external application will run on the same machine, i.e., A and B will refer to the same machine, and both ports will be local. Still, they are distinct ports.

For communication involving a large number of network nodes, or unreliable connections, we suggest
using local UDP communication, in conjunction with locally executed TCP/IP server processes that forward messages to a TCP connection between the two remote machines.

==Description==
For each block of data processed by the BCI2000 system, two types of information are sent out
and may be received from the external application interface:
*the BCI2000 internal state as defined by the values of the entries of its state vector data structure, and
*the BCI2000 control signals.

For the definition of and details about states and the control signal, please refer to the BCI2000
project outline document.
Sending data occurs immediately after the task filter of the application module processes the data;
receiving occurs immediately before the task filter.
This ensures that changes resulting from user choices are sent out immediately, and that
received information will immediately be available to the task filter.
IP addresses and ports used are user-configurable. Sending and receiving need not use the same address and port.

==Protocol==
Messages consist of a name and a value, separated by white space
and terminated with a single newline (<code>'\n'==0x0a</code>) character.
Names may identify
*BCI2000 states by name -- then followed by an integer value in decimal ASCII representation;
*Signal elements in the form <tt>Signal(<channel>,<element>)</tt> -- then followed by a float value in decimal ASCII representation.

==Examples==
<pre>
Running 0\n
ResultCode 2\n
Signal(1,2) 1e-8\n
</pre>
Note that the first example will switch BCI2000 into a suspended state.
While the system is in that state, no communication is possible over the application protocol.

==Parameterization from within BCI2000==
BCI2000 reads data from a local IP socket specified by the
<tt>ConnectorInputAddress</tt> parameter, and writes data out into the socket specified by the
<tt>ConnectorOutputAddress</tt> parameter.
Sockets are specified by an address/port combination.
Addresses may be host names, or numerical IP addresses. Address and port are separated by
a colon as in
<pre>
localhost:5000
134.2.103.151:20321
</pre>
For incoming values, messages are filtered by name using a list of allowed names
present in the <tt>ConnectorInputFilter</tt> parameter.
To allow signal messages, allowed signal elements must be specified including their
indices.
To allow all names, enter an asterisk (*) as the only list entry.

==Examples==
===BCI2000 example code===
* A simple few-line program that uses AppConnector information from BCI2000 to control the state of the parallel port is found at [http://{{SERVERNAME}}/tracproj/browser/trunk/src/AppConnectorApplications/ParallelSwitch/ParallelSwitch.cpp BCI2000/src/AppConnectorApplications/ParallelSwitch/].
* A GUI application that allows to interactively play with BCI2000 states is found at [http://{{SERVERNAME}}/tracproj/browser/trunk/src/AppConnectorApplications/AppConnectorExample BCI2000/src/AppConnectorApplications/AppConnectorExample] (a compiled executable is [http://{{SERVERNAME}}/tracproj/browser/trunk/tools/AppConnectorExample here]).
* A minimum C++ program forwarding BCI2000 AppConnector messages to stdout (using the BCI2000 <code>TCPStream</code> class) reads
<pre>
#include <iostream>
#include "SockStream.h"

using namespace std;

int main( int argc, char** argv )
{
const char* address = "localhost:5000";
if( argc > 1 )
address = argv[ 1 ];

receiving_udpsocket socket( address );
sockstream connection( socket );
string line;
// Print each line of BCI2000 input to stdout.
while( getline( connection, line ) )
cout << line << endl;

return 0;
}
</pre>

===An external application reading information from BCI2000, running locally===
* Set the <tt>ConnectorOutputAddress</tt> parameter to a local address above 1024, such as <code>localhost:5000</code>.
* In the external application, create a UDP socket and bind it to BCI2000's output port, i.e. <code>localhost:5000</code>.
* Read from that socket as you would from a TCP socket.
===An external application reading information from BCI2000, running on a remote machine===
* Set the <tt>ConnectorOutputAddress</tt> parameter to a remote address above 1024, such as <code>134.2.102.151:20321</code>.
* In the external program, create a UDP socket, and bind it to the remote machine's external address, i.e. <code>134.2.102.151:20321</code> rather than <code>localhost:20321</code>.
* Read from that socket as you would from a TCP socket.
===An external application sending information to BCI2000, running locally===
* Set the <tt>ConnectorInputAddress</tt> parameter to a local address above 1024, such as <code>localhost:5001</code>.
* Set the <tt>ConnectorInputFilter</tt> to <code>*</code> (a single asterisk).
* In the external application, create a UDP socket and bind it to BCI2000's input port, i.e. <code>localhost:5001</code>.
* Write to that socket whenever appropriate, without waiting for a connection to be established.
===An external application sending information to BCI2000, running on a remote machine===
* Set the <tt>ConnectorInputAddress</tt> parameter to the local machine's external address, and a port above 1024, such as <code>bci2000machine.yourdomain.org:20320</code>.
* In the external program, create a UDP socket and bind it to the BCI2000 machine's external address, i.e. <code>bci2000machine.yourdomain.org:20320</code>.
* Write to that socket whenever appropriate, without waiting for a connection to be established.

User Reference:SpatialFilter

2007-05-08T17:57:46Z

Atennissen:

==Function==
The SpatialFilter computes an instantaneous linear transformation of its input.
This linear transformation is described by a transformation matrix, and applied for each sample separately, not linking data across different points in time.

Typically, the SpatialFilter's input is the unfiltered brain signal from the source module.

==Parameters==
[[Image:SpatialFilter.png|right|256px]]
''SpatialFilter'' is a matrix defining the linear transformation applied to the filter's input signal.
In this matrix, columns represent input channels, and rows represent output channels.
Each matrix element defines a weight with which the respective input channel (column) enters into the respective output channel (row).

If the spatial filter is an identity filter -- not modifying its input --, then the SpatialFilter matrix is a unit matrix (square matrix with ones on the main diagonal, and all other elements zero).

In a typical EEG experiment with fixed montage, you might want column labels to reflect the respective electrode location, simplifying the task of further modifications to the spatial filter.

==States==
None.

==Examples==
===Linked Mastoids===
Physical reference is to the left mastoid (A1). The right mastoid (A2) is recorded vs A1 on channel 1. All other electrodes are recorded vs A1 as well, and use the remaining channels.
In your spatial filter, you will want to re-reference all channels against "linked mastoids", i.e. against the mean of A1 and A2.

In the spatial filter matrix, you want to subtract half of the A2 channel from each of the remaining channels:
{| border="1" cellspacing="0" style="text-align:center"
|+ Linked Mastoids
!   !! A2 !! Fz !! Cz !! Pz !! ...
|-
! Fz'
| -1/2 || 1 || 0 || 0 || rowspan="3" | ...
|-
! Cz'
| -1/2 || 0 || 1 || 0
|-
! Pz'
| -1/2 || 0 || 0 || 1
|-
|   || colspan="5" | ...
|}

===Common Average Reference===
Signals are to be re-referenced against the average of all channels.
To achieve this, begin with an identity matrix, and subtract a matrix of all ones, divided by the number <math>N</math> of input channels:
{| border="1" cellspacing="0" style="text-align:center"
|+ Common Average Reference
!   !! Fz !! Cz !! Pz !! Oz !! ...
|-
! Fz'
| 1-1/N || 1/N || 1/N || 1/N || rowspan="4" | ...
|-
! Cz'
| 1/N || 1-1/N || 1/N || 1/N
|-
! Pz'
| 1/N || 1/N || 1-1/N || 1/N
|-
! Oz'
| 1/N || 1/N || 1/N || 1-1/N
|-
|   || colspan="5" | ...
|}

User Reference:Filters

2007-05-08T17:53:27Z

Atennissen:

''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="4" | Signal Processing
! colspan="3" | Application
|-
| rowspan="2" |
{| border="0" style="text-align:center"
| colspan="2" | DataIOFilter
|-
| ADC || FileWriter
|}
| rowspan="2" | AlignmentFilter
| rowspan="2" | TransmissionFilter
| rowspan="2" | SpatialFilter
| ARFilter || rowspan="2" | LinearClassifier || rowspan="2" | Normalizer
| rowspan="2" | ConnectorInput
| CursorTask
| rowspan="2" | ConnectorOutput
|-
| P3TemporalFilter
| P3AVTask, P3SpellerTask
|}

==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 [[Data Formats]].
In addition to managing the operation of ADC and FileWriter filters, the DataIOFilter handles signal calibration into physical units (generally, <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:AlignmentFilter]]: Temporal alignment.
*[[User Reference:TransmissionFilter]]: Subset selection for online processing.
===ADC Filters===
*[[User Reference:RandomNumberADC]]: A random 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.
*[[User Reference:DAS_ADC]]: Interface to MeasurementComputing AD cards.
*[[User Reference:DTADC]]: Interface to Data Translation boards.
*[[User Reference:NIADC]]: Interface to National Instruments boards.
*[[User Reference:NeuroscanADC]]: Neuroscan Acquire socket protocol client.
*[[User Reference:RDAClientADC]]: Brain Vision RDA socket protocol client.
*[[Contributions:ADCs]]: Contributed code interfacing to other hardware.
===FileWriter Filters===
*[[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
===General Filters===
*[[User Reference:SpatialFilter]]: Instantaneous (i.e., sample-wise) linear transformation of brain signal input.
*[[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.
*[[User Reference:LowPassFilter]]: Temporal low-pass filtering at any stage of processing.
===Specific Filters===
*[[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.
===Offline 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.

==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:P3AVTask]]: Sequential presentation of stimuli.
*[[User Reference:P3Speller]]: A P300 speller matrix application.
===External Interfacing Filters===
*[[User Reference:ConnectorOutput]]: Reports state information to a UDP socket.
*[[User Reference:ConnectorInput]]: Sets state information according to input from a UDP socket.
*[[UserReference:KeystrokeFilter]]: Translates state information into simulated keyboard input.
===Internationalization===
*[[User Reference:Localization]]: Translating subject-visible messages.

Technical Reference:States of Operation

2007-05-08T17:44:39Z

Atennissen:

This page describes the states of operation that apply to a BCI2000 system as a whole.
These are different from concept of [[State definition|BCI2000 States]] which are saved to data files on a per-data block basis.

Driven by user interaction from the operator module, the system cycles through five phases of operation:
Startup, Initialization, Suspended, Running, Termination.

===State Diagram===

Startup -> Initialization <-> Suspended -> Termination
^
|
v
Running

==System Startup==
===Introduction===
Since the
system is a
distributed system of encapsulated modules, this procedure ensures a
proper and
well defined information flow at start-up.
Each module publishes its requests for parameters and states to
the Operator module, which configures those and sends them back.
After Data Acquisition receives all parameters and states, it tries to
connect
to Signal Processing and -- upon successful connection -- sends a
positive status
message to the Operator.
In the same way, Signal Processing connects to the Application and the
Application module connects to the Data Acquisition module.
After the Operator receives status messages from all three core
modules, the
system is fully initialized and is triggered to start, as soon as the
Operator
sends the state <tt>Running</tt> with a value of 1 to the Data
Acquisition module.

===Startup Sequence===
The operator module must be started first. Since in most cases the IP
address of
the operator module can be more easily statically defined, its IP
address and
port number(s) have to be provided to the core modules.
The operator module listens on ports 4000
(for Source), 4001 (for Signal Processing), and 4002 (for Application)
and
waits for the respective core module to connect. Each can connect to
its
assigned port on the operator module in any order. Upon start-up,
each core
module opens a listening socket on an arbitrary port number.

===Publishing Phase===
Upon connection, each core module publishes its parameters to the
operator module as a sequence of [[BCI2000 messages|parameter messages]].
After
publishing its
parameters, each core module publishes the states it requests as
a sequence of [[BCI2000 messages|state messages]].
At this time, the operator module ignores
every
field except ''Name'' and ''Length'' , which it needs to
construct the
state vector.
For this and all subsequent communication, the modules use the [[BCI2000 messages]]
protocol. Following the last
state, each core module sends a system command containing the string
<tt>EndOfState</tt>.
On receiving this command from all core modules, the operator module
processes the received parameters and states. It
creates a
list of all parameters and all states and creates the state vector
(duplicate
parameters or states are ignored), and ends
this initial publishing phase.
In order to maintain integrity throughout operation, no parameters or
states
should be added to or removed from the system beyond this point.

==System Initialization==
===Information Phase===
At this point, the operator module
may modify
the value of the parameters and states (depending on the
investigator's input or
the parameter file). The operator module then uses the same channel on
which it
received data from the core modules to send back to all core modules a
list of
all system-wide parameters and system-wide states (in any order).
Since the IP
address and port number on which the core modules listen for data from
other
core modules are published in system parameters as described, each
module now
knows where to send its data. The connections from the core modules to
the
operator module remain open (all subsequent traffic will go through
these
connections).
As in the publishing phase, the Information Phase ends when a system
command
<tt>EndOfState</tt> is sent.

===Preflight Phase===
In the preflight phase, each core module declares whether it can process data with the
received parameters and states, and reports the properties of its output signal.

The operator module opens the preflight phase by sending an empty [[BCI2000 messages|signal message]] to the source module.
The source module then reports its output signal properties to the signal processing module by sending it an appropriate signal message that acts as a template for further signal messages.
The signal processing module, in turn, sends a signal template to the application module.

During the preflight phase, modules indicate errors by sending descriptions
into an error channel.
If any errors are indicated during the preflight phase, the module will not initiate the initialization phase; the operator module will display the errors, prompting the user to fix the problems detected, and not offer the "Start" option.

===Initialization Phase===
Each core module uses the information in the received parameters to
configure and
initialize its operation. It also opens an active (i.e., client)
connection
to the other core module it must connect to, i.e., Source opens a
connection to Signal Processing, Signal Processing to Application and
Application to Source.
Each core module sends a [[BCI2000 messages|status message]]
to the
operator that indicates either successful or failed initialization.
The
Initialization Phase ends when all core modules indicate successful
configuration.

==System is Suspended==
At the end of the Initialization Phase, the system is fully
configured. All
parameters and states (and positions thereof in the state vector) are
defined.
The system is suspended when ''Running'' is 0. Any module shall
disregard a
change in parameters if the system is not suspended. Data flows
through the
system and it is up to each module to decide how to process these
data. The
Application, for example, might give visual feedback that indicates
that the
system is suspended. As long as operation is suspended (i.e.,
''Running''
is 0), any module might update system parameters and send them back to
the
Operator.

==System is Running==
During system operation, the Operator module must send states only to
the Source
module; Signal Processing and Application must disregard any state
that the
Operator does send to them.
The system is started when the Operator module sets the state
''Running''
to 1 and sends it to the Source module.

==System Termination==
To each of the three core modules, the operator module indicates
system termination
by closing the connection to that module.

When a core module loses connection to the two other core modules it
is connected
to, it will send an error message to the operator, and then quit.
The operator module, in turn, will close the connections to the
remaining core
modules.

----
See also:

Programming Reference:GenericFilter Class

2007-05-07T20:08:04Z

Atennissen:

==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 [[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 0 0 // This is not automatically range-checked",
END_PARAMETER_DEFINITIONS

BEGIN_STATE_DEFINITIONS
"MyState 1 0 0 0",
END_STATE_DEFINITIONS
} </pre>

===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>, <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& inputProperties,
SignalProperties& outputProperties ) const
{
PreflightCondition( Parameter( "MyOtherParam" ) > 0.0 );
PreflightCondition( inputProperties.Channels() > 0 );
PreflightCondition( inputProperties.MaxElements( 0 ) > 0 );
outputProperties = inputProperties;
} </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>.
*<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()
{
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* inputSignal,
GenericSignal* outputSignal )
{
if( ( *inputSignal )( 0, 0 ) > mMyOtherParam )
++mCount;
*outputSignal = *inputSignal;
} </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. By default, <tt>StartRun</tt> calls <tt>Initialize</tt> to make sure that intermittent parameter changes are applied. If you provide your own <tt>StartRun</tt> function, you will probably want to call <tt>Initialize</tt> from there as well.
*<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>

Programming Reference:Errors and Warnings

2007-05-07T19:47:55Z

Atennissen:

==Output Streams==
There are two output channels available to any code inside a BCI2000
module.
Technically, these channels are global objects derived from the STL's
<tt>std::ostream</tt> class. As such, they work much like the global
<tt>std::cout</tt> and <tt>std::cerr</tt> output streams available
inside a
C++ command line program, except that their output will be sent to the
operator
module's log window rather than a terminal window.

==Writing into Error and Warning Streams==
The names of these output streams are <tt>bciout</tt> and
<tt>bcierr</tt>,
declared in <tt>shared/BCIError.h</tt>, and while writing output to
<tt>bciout</tt> has no side effects, writing to <tt>bcierr</tt> has
side effects that depend on the system's phase of operation:
In preflight phase, the side effect will be a preflight failure, and the system will not start
unless reconfigured with correct parameters; otherwise, the side effect will
be system termination after error display.

Note that writing into <tt>bcierr</tt> or <tt>bciout</tt> has no effect before the stream's output buffer is flushed by inserting <tt>endl</tt> or <tt>flush</tt>:
bcierr << "Display this immediately!" << endl;

==Convenience Macros==
For the <tt>Preflight</tt> function, there is also a macro
<tt>PreflightCondition</tt> available that is intended to make
checking
for conditions more convenient:
PreflightCondition( Parameter( "MyFirstParam" ) >= 3 );
will result in a message
"A necessary condition is violated: Parameter( "MyFirstParam" ) >= 3"
in the operator window if <tt>MyFirstParam</tt>'s value is below 3.

==Throwing Exceptions==
Finally, in case of a non-recoverable error, you may also throw an
exception
of type <tt>const char*</tt> in order to report an error in the
operator window,
and to terminate the BCI2000 system after the error has been
displayed:
throw __FUNC__ ": Disk space is exhausted";
-----
See also: [[Error Handling]] for a more detailed discussion of error reporting facilities.

Technical Reference:Parameter Definition

2007-05-07T19:43:53Z

Atennissen:

This page describes the concept of BCI2000 parameters, in conjunction with their textual representation as a "parameter line".

For information about how to access parameters from code, please refer to [[Programming Reference:Parameters]].
For information about individual parameters, please refer to [[User Reference:Parameters]].

==Parameter Concept==
Parameters are variables that primarily represent user configuration choices. Typical entities encoded by parameters are:
*size and location of the feedback window
*subject ID
*sampling rate
*spatial filtering matrix.

Typically, parameters are constant throughout a run, often throughout a session or an entire experiment.
In a [[BCI2000 data file]], a full set of parameters is stored along with the data, allowing for reconstruction of the system configuration off-line.

As parameters represent user choices, the direction of information flow generally is Parameter Value->BCI2000 Module, i.e. parameter information is used to set BCI2000 modules to a defined state at initialization time.
There are, however, some important exceptions to that rule.
*''Source Modules'' may not be able to control all aspects of data acquisition. Control is limited by the design of the vendor-provided software interface to data acquisition hardware. As a typcial example, consider an EEG amplifier connected through a TCP-based socket interface. Generally, the amplifier will be configured in a separate user interface, and BCI2000 source module parameters such as <tt>SourceCh</tt> (number of channels) or <tt>SamplingRate</tt> must be chosen in accordance with that external UI's settings.
*''System-internal Configuration'' is represented as parameters, and of potential interest to the user, but not user configurable. These parameters are placed in the configuration editor's ''System'' tab. Important examples comprise versioning information (e.g., the <tt>EEGSourceVersion</tt> parameter), others govern the connection between modules (e.g., the <tt>EEGSourceIP</tt> parameter).
*''Automatic Adaptation'' to the subject's brain signals may be reflected by automatically updated parameters. For such parameters, the user specifies initial parameter values that may be overwritten at the end of a run. Unless changed by the user, these modified values will be the next run's initial values, and documented as such in that run's data file. As typical examples, consider the ''Normalizer'' filter's <tt>NormalizerOffsets</tt> and <tt>NormalizerGains</tt> parameters.

==Parameter Lines==
Parameter lines are a human-readable format used to represent individual parameters in:
*[[BCI2000 parameter files]]
*[[BCI2000 data files]]
*[[BCI2000 messages]] sent between modules.

The basic format of a parameter line is
<pre>
Section DataType Name= Value DefaultValue LowRange HighRange // Comment
</pre>
Note that the = sign must follow the <tt>Name</tt> field immediately, without
white space. However, white space ''after'' the = sign is mandatory.

If DataType is ''list, intlist'' or ''floatlist'', the format is as follows:
<pre>
Section DataType Name= (NumValues|Labels) Value(s) DefaultValue LowRange HighRange
// Comment
</pre>
where <tt>Labels</tt> is a list of textual labels that optionally
substitute the number denoted by <tt>NumValues</tt>. A list of labels
is enclosed by <nowiki>{} or []</nowiki>, as in
<tt><nowiki>[low medium high]</nowiki></tt>.
If DataType is ''matrix'' , the format is as follows:
<pre>
Section DataType Name= (NumRows|RowLabels)
(NumColumns|ColumnLabels) Value(s) DefaultValue LowRange
HighRange // Comment
</pre>
where, again, each NumValues entry may be substituted by a list of
textual labels.
For matrices, values are given in column-major order, i.e. listing
values from the first column first, then values from the second column,
and so on, as in
Value(0,0) Value(0,1) ... Value(0,m) Value(1,0) Value(1,1) ... Value(1,m) ...

===Data Types===
The DataType field is not interpreted in a very strict sense.
Rather, parameter values are always stored as strings, and converted into
numerical values only when accessed as such from BCI2000 modules.
For consistency, and to avoid user confusion, the following primitive types
should be specified as appropriate:
{|border="1"
|+ Primitive Parameter Data Types
! Name !! Description
|-
| variant || unspecified type
|-
| int || unlimited range integer value
|-
| float || unlimited range, arbitrary precision float value
|-
| string || any string of characters (see the ''Special characters'' section for details)
|}
A list or matrix type may be formed from these primitive types when concatenated with ''list'' or ''matrix'', as in ''intlist'', ''stringmatrix''.
For a list or matrix with entries of unspecified type, use an unprefixed ''list'' or ''matrix'' rather than ''variantlist'' or ''variantmatrix''.

===Special characters===
To allow for special characters and
white space
within parameter values and textual labels, an URL-like encoding
scheme is adopted.
In this encoding, a <tt>%</tt> character followed by up to two
hexadecimal digits
represents a byte value in hexadecimal notation which is interpreted
according to
the ASCII-Latin1 character table.
Thus, <tt>%20</tt> represents a space character, and
<tt>%</tt>, <tt>%0</tt>, and <tt>%00</tt> all represent an empty string value;
<tt>%%</tt> represents the <tt>%</tt> character itself.
The line
<pre>
Demo string SomeString= a%20string%20with%20spaces % % %
// White space example
</pre>
defines a parameter ''SomeString'' which contains the value
''a string
with spaces''.
The single <tt>%</tt> characters indicate that the
''DefaultValue'' ,
''LowRange'' and ''HighRange'' fields should be empty
strings.

==Sub-parameters==
Any parameter value may itself be a sub-parameter.
Sub-parameters are represented by a short-form
matrix definition omitting the ''Section'' and ''Name''
fields, enclosed in
a pair of braces:
<pre>
Demo matrix NestedMatrices= 1 2 11 { matrix 2 2 1211 1212 1221 1222 }
// Nested matrix example
</pre>
will define a matrix parameter whose 1,2 entry is a 2x2 matrix.
While the syntax allows for any combination of parameter and
subparameter types,
the current implementation of the parameter editor GUI only
supports matrix-type
sub-parameters within matrices as in the example above.

==Display Format==
Generally, a parameter's <tt>DataType</tt> field will be used to
determine its appropriate display in a parameter editor.
However, often a more user-friendly display may be achieved if
additional information about a parameter's content is available.

To allow for such information, the comment line that is introduced by the
two
slashes (//) may contain a format identifier that is used by the
Operator module
to modify the display of the particular parameter. Format identifiers
are
strictly optional and are introduced as follows:
<tt>(identifier)</tt>.
Currently, the following format identifiers are implemented:

{| border="1"
|+ The currently defined format identifiers
! Identifier !! Description
|-
| <tt>(enumeration)</tt> || a choice from an enumerated set of values
|-
| <tt>(boolean)</tt> || a yes/no choice
|-
| <tt>(inputfile)</tt> || path to a file to be opened for reading
|-
| <tt>(outputfile)</tt> || path to a file to be opened for writing
|-
| <tt>(directory)</tt> || path to a directory
|-
| <tt>(color)</tt> || RGB color
|}

===<tt>(enumeration)</tt>===
The parameter value is presented as a drop down menu, with entries
corresponding to the
possible values listed in the comment. The first part of the comment
appears above
the drop down menu. All interpunction characters present in the
comment are ignored.
The data type of the parameter must be <tt>int</tt>.
All possible values must appear in the comment, and the parameter's
LowRange and HighRange
fields must be consistent with the enumeration. LowRange will usually
be 0, but may be any
integer. For example:
<pre>
Breakfast int BreakfastDrink= 1 1 1 3
// Drink for breakfast: 1 Tea, 2 Coffee, 3 Juice (enumeration)
</pre>
will display a drop down menu with entries "Tea," "Coffee,", and
"Juice."
The menu will be labeled "Drink for breakfast."

===<tt>(boolean)</tt>===
The parameter value is presented as a check box; the first part of the
comment appears
to the right of the check box. LowRange and HighRange must be 0 and 1.
The parameter's data type must be <tt>int</tt>.
To ensure human readability of parameter files, the possible values
and their meaning may
appear in the comment (e. g. <tt>0: no, 1: yes</tt>) but will not
be displayed with the
check box. For example:
<pre>
Breakfast int ServeBreakfast= 1 1 0 1
// Serve breakfast: 0 no, 1 yes (boolean)
</pre>
will display a check box labeled "Serve breakfast."

===<tt>(inputfile)(outputfile)(directory)</tt>===
The parameter value is presented as an edit field. Beside the edit
field, there is a button that opens up a file or directory and selects dialog when clicked.
The parameter's data type must be <tt>string</tt>.
<pre>
Breakfast string WakeupSound= doorbell.wav
// Sound to play in the morning (inputfile)
</pre>

===<tt>(color)</tt>===
The parameter value is presented as an edit field. To the right of the edit
field there is a button that opens up a color selector dialog when clicked.
The parameter's data type must be <tt>string</tt>, with its value
containing the color
in hexadecimal RGB encoding:
<pre>
Breakfast string TableClothColor= 0x00FF00 0xFFFFFF 0x000000 0xFFFFFF
// Color of table cloth to put up for breakfast (color)
</pre>

==Grouping Parameters by Sections==
A user interface may use fields in the parameter <tt>Section</tt> fields to
collect parameters into
groups, e.g., by displaying all parameters with identical section
fields on the same
register tab of a GUI parameter editor dialog window.
In the <tt>Section</tt> field, finer grained grouping may be expressed
by specifying
sub-sections separated by colon characters, e.g., a <tt>Section</tt>
value of
UsrTask:WindowDimensions
will indicate that a parameter belongs to a <tt>WindowDimensions</tt>
subsection of
a section called <tt>UsrTask</tt>. A parameter editor implementation
might display the respective parameter on a register tab called
"UsrTask" and
inside a group box labelled "WindowDimensions".
Although any number of sub-sections may be present in the
<tt>Section</tt> field,
a user interface implementation may ignore sub-section entries below a
level chosen by the implementer.
-----
See also: [[User Reference:Parameters]]

User Reference:Expression Syntax

2007-05-07T18:14:10Z

Atennissen:

BCI2000 contains an ''expression parser'' that evaluates user-defined mathematical expressions at run-time.
Expression syntax tries to be intuitive and is based on C and Matlab notation.

===Syntactic Elements===
===="Real" Numbers====
Numbers may be given as literals in decimal or scientific notation:
100, 1e2, 100.0, (1000/10)
all refer to the same number. Complex numbers are not supported.

====Operators====
;Arithmetic operators:
:<pre> ^ unary- * / + -</pre>
:Unlike C but consistent with Matlab, <code>a^b</code> evaluates to the b-th power of a.

;Comparison operators:
:<pre> < > <= >= == != ~=</pre>
:Note that a single equals sign is not a valid operator. For the "not equal" operator, the C version (!=) is supported along with the Matlab version (~=).

;Logical operators:
:<pre> ! ~ && ||</pre>
:Again, ! and ~ are synonymous to match both C and Matlab conventions. When mixing boolean and numerical expression, values need to be converted back and forth between numbers and logical values. As usual, zero is treated as ''false'', and nonzero values are treated as ''true''. Reversely, ''false'' is converted into the number 0, and ''true'' is converted into 1. There are no literals for ''true'' and ''false''; use 0 and 1 instead.

;Condition operator
:<pre> <condition>?<if-expr>:<else-expr></pre>
:As in C, the ternary condition operator ?: allows for if-then-else-like constructs. If ''condition'' is true, it evaluates to ''if-expr'', and to ''else-expr'' otherwise.

;Precedence
:Operator precedence follows the order of appearance in the above list. As usual, braces ( ) may be used to override operator precedence.

====States====
Expressions may involve BCI2000 [[States]]. These are referred to by name as in
<pre>TargetCode==ResultCode</pre>
or
<pre>(TargetCode-1)*ResultCode</pre>

====Signal Values====
Depending on context, expressions may involve signal values:
<pre>10*Signal(0,3)</pre>
Here, "Signal" refers to the filter's input signal, and indices are ''zero-based''.

===Examples===
*An expression that evaluates to the ResultCode state only if that equals the TargetCode state (i.e., in case of a successful trial):
(ResultCode==TargetCode)?ResultCode:0
*A mapping of TargetCode values to arbitrary numbers:
(TargetCode==0)?3:(TargetCode==1)?-4:(TargetCode==2)?18:0

===Caveats===
*There is no integer arithmetic. All evaluation is done in floating point, even if only integers are involved. As a result, comparisons may fail unexpectedly, or boolean conversion may always yield true:
:<pre> x^2-(3/7+4/5)*x+(4/5)*(3/7)==(x-4/5)*(x-3/7)</pre>
:should be ''true'' independently of x but will always evaluate to ''false'' due to roundoff errors.
:In most cases, a numerically robust reformulation of the expression should resolve the problem.

*Sometimes, operator precedence or behavior may not match your intuition. When in doubt, use brackets:
:<pre>(TargetCode^(-3))/5</pre>
:rather than
:<pre>TargetCode^-3/5</pre>
:which is equivalent but may be misunderstood as
:<pre>TargetCode^(-3/5)</pre>

Technical Reference:State Definition

2007-05-07T18:04:20Z

Atennissen:

This page describes the concept of BCI2000 states, in conjunction with their textual representation as a "state line".

For information about how to access state values from code, please refer to [[Programming Reference:States]].
For information about individual parameters, please refer to [[User Reference:States]].

==State Concept==
States are variables that represent the internal state of a BCI2000 system as it is evolving over time in response to:
*brain signal input
*user interaction through the operator interface
*trial sequencing by the application module.

Typical entities encoded by states are:
*whether the system is running or suspended
*the time when a block of data was recorded
*stimulus or task being presented
*the classification result
*the state of an external marker (trigger) to be saved for off-line analysis.

Typically, state values change once per block of data, or once per trial.
In a [[BCI2000 data file]], the full set of states is stored along with the data, allowing for reconstruction of on-line system state off-line.

==State Vector==
In a BCI2000 system, a collection of states is maintained as a ''State List''.
For each state present in that state list, its value is kept as a range of bits in a bit vector called ''State Vector''.
BCI2000 modules and filters may read and write state values during processing.
The state vector's content is saved, in its binary form, into [[BCI2000 data files]] per-block.
Using the ByteLocation, BitLocation, and Length fields from the state definitions present in a file, a state's value may be read from the data file.

A state vector is a narrowly packed bit field in '''big endian''' ordering.
This implies that, for a state containing more than a single bit, '''less''' significant bits are placed at '''higher''' bit and byte locations.

As an example, consider a state vector consisting of a 1-bit state "Running", and a 16-bit state "SourceTime". This will result in a three-byte state vector layout like this:
{|border="1" cellspacing="0" cellpadding="1"
!colspan="8"|State Vector Byte 1
!colspan="8"|State Vector Byte 2
!colspan="8"|State Vector Byte 3
|-
!7!!6!!5!!4!!3!!2!!1!!0
!7!!6!!5!!4!!3!!2!!1!!0
!7!!6!!5!!4!!3!!2!!1!!0
|-
!Running!!colspan="16"|SourceTime!!colspan="7"|unused
|-
!0
!15!!14!!13!!12!!11!!10!!9!!8!!7!!6!!5!!4!!3!!2!!1!!0
!colspan="7"| 
|}

==State Lines==
State lines are a human-readable format used to represent individual states in
*[[BCI2000 data files]],
*[[BCI2000 messages]] sent between modules.
Core modules and the operator module use this format to communicate in the system initialization phase, as well as during system performance and for system termination.

The format of a state line is
<pre>
Name Length Value ByteLocation BitLocation CRLF
</pre>
where <tt>Length</tt> refers to the number of bits used to represent the state's value,
and <tt>ByteLocation</tt> and <tt>BitLocation</tt> refer to its position in a [[State Vector]], with <tt>BitLocation</tt> ranging from 0 to 7.

Depending on the context of a state line, one or more of its fields may be ignored:
*In a State message sent from the operator module to a core module, Length, ByteLocation, and BitLocation will be ignored.
*In a State line contained in a data file, the Value field matches the state's value stored with the first block of data samples.

Generally, the Value field specifies an ''initial value'' of a state. Actual values are stored in the [[State Vector]] data structure.
-----
See also: [[User Reference:States]]

Programming Reference:Signals

2007-05-07T16:47:43Z

Atennissen:

==Signals==
Many classes in both Data Acquisition and Signal Processing work on
signals, i.e., continuously flowing data organized in channels and samples.
The <tt>GenericSignal</tt> class contains floating point data
organized as a matrix of channels and "elements" (a generalized
notion
of samples -- e.g., spectrally analyzed data might contain the
spectrum of
each channel as a list of "elements").

==Signal Properties==
Sometimes, the number of channels, elements, and bytes
required
for storing values, are referred to as "Signal Properties".
There is a separate class, <tt>SignalProperties</tt>, for expressing
those
values, and determining whether a given signal "fits" into another
one, i.e.,
whether the values contained in one signal may be copied into another
signal without loss of information.
<tt>GenericSignal</tt> uses a <tt>SignalProperties</tt> member to
maintain
information about its properties.

Programming Reference:Environment Class

2007-05-07T16:42:33Z

Atennissen:

==Your code's <tt>Environment</tt>==
In each BCI2000 module, there exist system wide parameters and states
as
described in the project outline document.
In this implementation, access to parameters and states is mediated
through
a class <tt>Environment</tt>. This class provides functions for
convenient access
to parameters and states, and transparently handles a number of error
conditions
that might occur.
The services provided by the <tt>Environment</tt> class interface are
available
to all classes that inherit from it. For <tt>GenericFilter</tt>
descendants, this
is automatically the case; for other classes, you need to explicitly
state
the inheritance as in
<pre>
#include "Environment.h"
...
MyClass : private Environment
{
...
};
</pre>

==Access to Parameters and States==
From any code inside <tt>MyClass</tt>, you may then read or set
parameter and state values simply by writing
<pre>
int numberOfItems = Parameter( "NumberOfItems" );
float listValue = Parameter( "ListParam" )( index );
float matrixValue = Parameter( "MatrixParam" )( index1, index2 );
float nestedMatrixValue
= Parameter( "NestedMatrices" )( index1, index2 )( index3, index4 );
short feedbackState = State( "Feedback" );
State( "Feedback" ) = 0;
</pre>
If you try accessing a parameter or state that does not exist, an
appropriate
error message will be sent to <tt>bcierr</tt>, so you don't need to
handle
this type of error explicitly.
For a greater independence between modules, it is sometimes desirable
to
read a parameter or state if it exists, and use a default value
otherwise.
You achieve this by writing <pre>int numberOfItems = OptionalParameter( defaultValue, "NumberOfItems" );
short itiState = OptionalState( 0, "IntertrialInterval" );
</pre>

==Working around Borland VCL Inheritance Restrictions==
Due to some non-standard conventions in Borland's VCL library, you
cannot create a VCL class such as a <tt>TForm</tt> descendant that
also
inherits from <tt>Environment</tt> -- the compiler will report an
error
if you try.
As a work-around, you might declare an <tt>Environment</tt> subclass
''inside'' your VCL <tt>TForm</tt> child declaration,
and create a single instance <tt>mEnv</tt> of this subclass as a
member
of your class, using it to access the <tt>Environment</tt> functions
as in
<pre>
MyForm : public TForm
{
...
private:
class MyFormEnvironment : private Environment
{
public:
MyFormEnvironment( MyForm& parent );
void Preflight() const;
void Initialize();
} mEnv;
};

...

MyForm::MyFormEnvironment( MyForm& parent )
: mParent( parent )
{
BEGIN_PARAMETER_DEFINITIONS
"UsrTask int MyParam= 1 1 0 5 // my parameter",
END_PARAMETER_DEFINITIONS
}

...

void
MyForm::Initialize()
{
mEnv.Initialize();
}

void
MyForm::MyFormEnvironment::Initialize()
{
mParent.mMyParam = Parameter( "MyParam" );
}
</pre>
This should work in situations where your code's class model is
centered around
VCL form classes.
When writing new code, you might consider basing your class model on
functionality, and use VCL forms merely for input and output --
instantiating,
populating, and deleting them as you need them, such that the BCI2000
<tt>Environment</tt> interfacing is done from your own classes,
independently
of the VCL's special requirements.
-----
See also: [[Error Handling]]

Technical Reference:Parameter File

2007-05-07T16:35:57Z

Atennissen:

In BCI2000, [[Parameter Definition|parameters]] are variables describing system configuration.
Parameter files (extension <tt>.prm</tt>) contain collections of parameter values.
As each parameter file may contain a subset of all parameters available in a BCI2000 system, it is possible to factor out individual aspects of configuration into separate parameter files ("fragments") which may then be combined together as needed.

Parameters have a human readable representation as a [[Parameter Definition]] line.
Parameter files represent collections of parameter values in the form of sequences of such definition lines, separated by Windows/DOS line separator codes.

Thus, parameter files may be modified using a standard text editor (although it will generally be easier to use the parameter editor dialog of the operator module).
----
See also: [[Data file]]

Mu Rhythm Off-line Analysis Tutorial

2007-05-07T16:34:18Z

Atennissen:

== Starting an analysis session ==

Every recording session has its own history. It is very difficult to say in advance what might happen during the recording. So we will assume that everything was perfect (the subject collaborated, no channel went lost, etc); later on we will consider the main causes of contamination, how to recognize it and what to do.

If the recording session run smoothly, in the folder ''\TestData\Data\Mu'' you should now have two files named ''ALFAS006R01.dat'' and ''ALFAS006R02.dat'', corresponding to two of the eight runs usually recorded, respectively.

Before you start the analysis you should locate on your hard disk the correct montage file. This is a file that describes the list of channels that were acquired. In this tutorial we will use ''Complete_Montage(suggested choice).mmf'', which is located in the folder ''\TestData\Montage''. If you need to edit the *.mmf file, check its data format.
< the of performances optimize that parameters try will we then online; performed BCI2000 analyses same off-line replicate to first>

== Opening files with Mario ==

After having run mario.exe, press "Select Data Files".

[[Image:Mu Rhy5.jpg]]

A dialog window will ask you to select the dat files. You can either select a single data file, or select multiple files. This time, we will select all files in the dataset.

A green box will surround the Raw Data box in the main window.

As an optional (but recommended) operation, push the LOAD MONTAGE button and choose the mmf file. This will allow you to see the labels of each channel the following steps, and to allow to apply spatial filters that depend on the electrode position.

At least you can load an additional parameters file according to different choices from those carried out during the experimentation.

At this point, you can check that Mu is selected in the Analysis menu (indicating that a Mu dataset has been recognized) and push the LOAD DATA button to confirm your choices. This will enable the EDIT CHANNEL LIST button you can use to select the channels you want to include in your analysis.

== Selecting Channels ==

Pushing the the EDIT CHANNEL LIST button, two forms will show you the channels list (valids' and not-valids' one) and an image reassuming valid channels and their location.

Clicking on Add and Remove buttons you can move whichever channel from one list to the other enabling or disabling it.

== Selecting the Spatial Filter ==

Coming back to main window, you can therefore choose which filter to apply for your elaborations, selecting it between the possible supplied solutions.

You can choose from:

:*RAW
:*CAR
:*Large Laplacian
:*Small Laplacian

Common Average Reference (CAR) will be fine for most the situations.

We hope to release soon an user defined solution for any custom analysis.

== Feature Extraction Analysis ==

The Analysis field in the Feature Extraction panel will appear automatically according to loaded files while the Feature Extractor field shows currently the only possible choice.

You can view/edit analysis details by pushing "Set Analysis Details" and "Set F.E. parameters"

This second form reports all the settings for the parametric (autoregressive) spectral estimation stage. Most of the values are set after the corresponding values used on-line (see BCI2000 setup for Mu). With settings as the ones reported in figure, the analysis software will:

:*data recorded at 200 Hz sampling rate;
:* remove the mean value;
:* sample the spectrum at points starting from 0 Hz to 60 Hz, every 0.2 Hz.;
:* Identify an auroregressive model of order 16;
:* average these values into 2 Hz wide bins;
:* take a 1 s long epoch of data.

You can modify these settings according to your aims. Changing the model order, for instance, brings sometimes to interesting results. Remember though that in the online version, spectral estimation is performed in epochs as short as 200 ms (i.e. 40 samples, at 200 Hz sampling rate), so you should avoid using model order higher than half the samples available in the epoch.
When you are done, remember to confirm your choices by pushing DONE. It will make the program accept changes.

Moreover, a button in the Spectral Extimation frame allows you to revert the values to the original.

Altogether you have to specify:

:* which data (in each trial) you want to take into account. Mu will only use the part of the trial when the cursor is visible, while MuExtended will take into account all the period when the target is visible. To learn more, see section D2Box Application States ;
:* If you have made an artifact rejection (or noted on the run sheet during the acquisition which trials contain artifacts), you can instruct the software not to use them;
:* Finally, you must decide how the software must extract EEG epochs from the continuous data.
The epochs can be partially overlapped. This attenuates the data loss in case the length of a trial is not a multiple of the length of an epoch.

The percentage of overlap can be set both in Mario GUI and in any batch script. It's equal to the value of the ''MU_params.overlapping'' variable and the corresponding GUI field can be found by pressing ''Set Analysis Details'' on MARIO main form.

At this point you can start the analysis by pressing the Evaluate and Plot button.

[[Image:Mu Rhy8.jpg]]

== View results ==

The first figure that appears is the R-square matrix (channels x frequency bins)
=== R-square matrix ===

The r-square matrix highlights the most relevant spectral features for the separation of the two classes of EEG - Cursor Up (target 1) and Cursor Down (target 2).

[[Image:Mu Rhy8.jpg]]

Each row of the matrix is related to a single channel, while a column represents a frequency bin (labeled with its central frequency). The color codes the statistical significance of the difference between the two kind of evoked potentials.

Thus a red color would mean that, on that channel and for that frequency, the "Up" EEG is significantly synchronized with respect to "Down" EEG.

Clicking on a cell of the matrix will open two more windows:

* Power spectral distribution of the selected channel
* Topographic maps at the selected frequency.

You can choose whether to overwrite or to put the most recently evoked figures beside the previous one. Two sets of waveform/topography figures are available, and are linked to the click of the left, the central or right mouse button.
Left Button will create/overwrite a first figure, Right Button will do the same on a second figure, the Central Button will always open a new plot.

=== Power Spectra and Topographic Plots ===

In the lower panel you can find the spectral density of power for both classes of EEG. Blue line refers to "Up" condition, while Red line to "Down".
We can see that at the vertex the "Down" condition is generally more synchronized than the "Up", with maximal difference in the beta band, consistently with what is shown by the R-square matrix. The proportinality between spectral differences and R-square is anyway rough, since r-square is sensitive to the dispersion (variance) of single trials; thus, small differences between spectra could bring to a high r-square, if they were very reproducible.

The peak around 50 Hz is due to mains disturbance; this also allows to appreciate the leakage introduced by the spectral estimation.

[[Image:Mu_Rhy9.jpg]]

Over the spectral graph, a topografic plot shows the scalp distribution of the r-square.

The color coding is the same as the r-square matrix figure, and values on each channel are interpolated to create a continuous bidimensional map. The higher the number of electrodes, the more accurate is the map. The number of channels shown on the scalp may not coincide with the whole number of electrodes in case of a Surface Laplacian spatial filtering, since in that case the value of the laplacian is not computed on the border channels.
Interpretation of the results

The first step in the preliminary analysis of P300 BCI data is to find the absolute maximum of r-square. This simple statement must be mediated with a proper knowledge of physiological phenomena. In fact, we do not expect any sensorimotor activity at 3 Hz, so if the absolute maximum is at that frequency, you must suspect that it is actually an artifact. The same holds if the spatial localization of the peak is far away from the centro-parietal electrodes.

From a practical point of view, it is not important now to understand the reasons different component that explain the desynchrinization peak on Cz at 17 Hz, as far as we are confident that this component is stable enough to be exploitable during the next session to control the cursor.

The absolute value of R-square is mathematically bound to lie in the interval between 0 and 1. Values above 0.4 allow a rate of missed target in the order of a few percent. Values around 0.1 are promising. Values below 0.03 are possibly due to random fluctuations. All the previous figures are referred to analyses made on 240 trials.
''Beware of artifacts!''

During the acquisition, you should be particularly careful to avoid artifacts. While EOG and blink artifacts are confined to very low frequencies, EMG artifacts are mostly on the beta band and could largely overlap with the frequency band that characterize the mu rhythm.

If contaminated data was acquired, then you have two problems:

:* Realize that EMG is superimposed to data
:* Distinguish between spectral modulation introduced by EEG and by EMG

The first task is not as trivial as it might appear. If you did not acquire the data yourself (or even if you did) you might complete the analysis procedure without giving a single glance to the raw data. So you must be particularly careful when you analyze the R-square maps, and always wonder whether the peak you are seeing might be due to an artifact.

Discriminant features between EEG and EMG are both in the frequency distribution and in the spatial distribution.

EMG that strongly affects the recordings is mostly generated by muscles at the forehead or close to the ears/jaws. Thus their spatial distribution is such that the most responsive channel is one of those at the border of the montage. Of course, due to volume conduction, the effects can be seen even on electrodes on the opposite part of the montage, but they show a degrading pattern.
On the other hand, a peak that shows its maximum on a central channel, can hardly be generated by a muscle or by other non-cephalic source.

The spectrum of EEG is mainly concentrated in the alpha band, with a possible flatter and lower peak in beta. With the exception of the beta peak/plateau, the EEG spectrum decreases almost linearly (if measured in dB) after 12 Hz.
On the other hand, EMG spectrum becomes significant at about 20 Hz and is still very high at the highest frequencies we usually analyze (60 Hz). A spectrum with a pattern more similar to the latter, must induce the suspect that non-EEG activity is present in the data.

==Improving the analysis==

The first cause of an unsuccessful analysis is a poor quality of the recording. For this reason it is highly recommended that, at least for the first experiments, the subject be highly motivated and cooperative. If this is the case, data of low quality are usually present in one or a few runs. And if the experimenter is careful enough, he/she should have noted down the occurrence of strong artifacts on the run sheet.
In this hypothesis, the following step is to repeat an unsatisfactory data analysis after having excluded the (putative) bad runs.
To do this, just go back to the file selection dialog, choose LOAD Data again and load only the runs that you believe are clean. The number of runs should not be too low (as a rule of thumb, the data set should contain at least 100 trials), otherwise the r-square statistical analysis would loose sensitivity.

== Analyzing the Screening ==

The screening experiment is not different from a regular training session, from the point of view of data format. You will have four sets (horizontal movement, horizontal imagination, vertical movement, and vertical imagination) of three runs, containing EEG acquired in two conditions (up and down, or left and right).

Start analyzing the vertical movement execution, and mark a few possible responsive features. The analysis on vertical movement imagination should confirm (though with a lower R-square) those that are actually related to sensorimotor cognitive states.

In the hypothesis that no reliable responsive EEG feature is found, the analysis can be repeated on the horizontal dataset.

If both the vertical and horizontal dataset show responsive features, and these are different, the subject should be trained for some session on the vertical training until he/she decreases the false positive below 10%; at that point the training of the horizontal modulation can begin, with the aim that at a certain point the subject can control both the vertical and the horizontal simultaneously in a two-dimensional task.

==Conclusions==

If you are confident that you have found a significant difference between conditions that is due to EEG rather than an artifact, and that reflects a cognitive process that is likely to be reproduced (or even enhanced with training) in the next session, you have reached your goal.
Next time the same subject practices with the D2Box Application, you will have to change the MUD matrix so that it reflects the feature that you just outlined.

==Troubleshooting==

Some OpenGL drivers may sometimes show defective figures like the following:

[[Image:Defective.jpg]]

Matlab customers can get around this problem using this simple procedure:
:* Select the defective figure window
:* Go to the Matlab Command Window
:* Execute one of the following command line:
:**set(gcf, 'Renderer', 'Painters');
:**set(gcf, 'Renderer', 'zbuffer')

The figure will be a plot using a different renderer (Painters or zBuffer).

MARIO Technical Documentation

2007-05-07T16:15:22Z

Atennissen:

==MARIO architecture==
MARIO is an off-line analysis application developed in MATLAB 7.0.2. It is now modular, object-oriented and can be easily integrated with any other software for data analysis and visualization.
It can be used in Mu and P300 analyses and allows two kinds of use: users can simply fill the forms of a graphical interface making any choice with a click of its mouse, run a ready-made script or, at least, write up their own scripts according to their needs.
This set of interfaces allows a wide range of possibilities for a wide range of different analyses.

Internally, the application is composed of 6 main functional modules, each one connected in cascade as in the list below:

*Data import
*Signal Conditioning
*Feature Extraction
*Spectral Extimation
*Statistical Analysis
*Visualization

[[Image:arch_blocks.jpg]]

All these modules are hidden in the graphical user interface but they can be distinguished in the batch scripts. Each one of them can be easily replaced with an improved version, a custom version or a different analysis.

[[Image:Graph.png|thumb|left|Graph of modules]]
Here you can see a simplified version of the functions graph with their relationships (click to enlarge). 

==Data Import Module==

Any script must have a first module to load data that theuser wants to analyze.
There are 3 main types of files containing different groups of information:

*Data files (.dat/.mat)
*Montage files (.mmf)
*External Parameter files (.prm) – optional

The data files contain all the data of the BCI session (Mu or P300).
These data are saved in different files, one for each run, containing 29 trials.
Internally any file is divided in two main parts: the first part (file header) includes all parameters set by the operator during the on-line experimentation; the second part contains the EEG signal recorded by the whole set of electrodes on the EEG cap.
A special function allows at least to load data from a Matlab file (.mat).

The montage file stores information about the electrode position on the scalp. It can be
drawn up writing in different sections divided by labels:

#a synthetic name
#the channel labels
#a valid channels list
#the laplacian grid
#the 3-dimensional spatial coordinates of all the electrodes (this section is optional)

This information is divided by labels and can be written in the Montage file without a predefined order.

At least, user can import data from an additional data file, a parameters file, that can be used if he want to replace one or more parameters from the BCI2000 ones. In this chance is enough to copy and paste in a new prm file the header string selected, changing its value.

This module is clearly the same for Mu and P300 Analysis.

==Data Conditioning Module==

The MARIO v.2.0 Data Conditioning module allows users to select from a wide range of spatial filters such as to include custom filter in user data analysis. So the operator can identify which channels or set of channels can give better results at the end of the statistical analysis.

For a Mu analysis, the user can select from four different spatial filter algorithms:

*RAW
*CAR (Common Average Reference)
*SMALL LAP
*LARGE LAP

The first one (RAW) does not use a filter and analyzes raw recorded data. Every other selection agrees with the choice to employ any spatial filter. An user defined analysis will be available on further versions of MARIO.

The Data Conditioning module also allows the user to compile/modify a list of valid channels on which any analysis will be conduced.

P300 Analysis can now use only two of the above spatial filters: the RAW filter and the CAR one. Any other selection will report an unhandled error.

==Feature Extraction Module==

Feature extraction is one of the most important stages of elaboration; it affects any further analysis.

In a Mu rhythm analysis, any feature can be obtained arranging some of the 12 BCI2000 states.
User can now make a choice between two predefined analysis, a simple Mu analysis or an Extended version of the same. The first analysis considers any sample recorded between the cursor appearance on the screen and the end of the trial (when the cursor reaches the right side of the screen).
The MuExteded analysis instead considers any sample recorded since the target appearance (during the first subset of data subject didn’t have any feedback) till the end of trial.
In both choices, the statistical analysis will be conduced between two classes of data: the EEG activity recorded while moving up the cursor (target UP) versus the EEG activity recorded while moving down the cursor (target DOWN).
Anyone of these choice will produce different R2 values between the corresponding features of the two classes

For a P300 Analysis the classes compared are only two and automatically set as frequent events and rare events.

==Spectral Extimation Module ''(just for Mu rhythm analysis)''==

During this step, the program evaluates the spectrum of recorded data; any further analysis will be done on it.
To do that, EEG signal is divided into equal length epoch (that can be distinct or overlapped of a percentage of overlap that user can set by Graphical User Interface or script) and a spectrum value is evaluated for anyone of these.

At the end of this process, a 3 dimensional matrix (bin × channel × epoch) joined with the one (channel × sample) compiled during a BCI2000 recording session and read by the data import module will be produced.

The algorithm employed to estimate the signal spectrum is the MEM (the same used on-line by BCI2000).

Apart from the percentage of overlap MARIO allows the user to modify the values of:

#Sampling frequency of recorded data;
#Spatial resolution (delta);
#Detrending order (Mean or Linear);
#AR model order;
#Low pass filter frequency;
#High pass filter frequency;
#Filter bandwidth;
#Epoch length;
#Overlap percentage.

MARIO v2.0 also computes a virtual states matrix strictly joined with signal one and derived as a arrangement of the BCI2000 states. These states label spectrum samples as valid or not and as belonging to one class or another.

Since that, every further analysis on BCI2000 data can be done.

==Statistical Analysis Module==

At least, a statistical analysis (at present the R2) is employed to distinguish between the class of a BCI2000 task in any trial.

MARIO uses a module that computes the R2 value between two classes that can be TargetUP and TargetDOWN for a Mu rhythm analysis, such as frequent and rare events for a P300 analysis. These data are taken from the spectra matrix (Mu analysis) or from the samples one (P300 analysis) and the regressor vector is yield from BCI2000 states.

At the end of this analysis, the real index (in a range between -1 and 1) produced is the R2 value multiplied by R2 sign. If the R2 value is near 1 it means there is an high separability between classes and high performances. If instead its value is near 0, it’s difficult to distinguish a class from another, and it means low performances.

==Visualization Module==

Mario offers a wide set of visualization graphs that can be combined to have a complete visualization of produced data.
For a Mu rhythm analysis user can request to visualize:

#a trajectory plot shows the cursor position for any sample in a trial BCI2000 as user saw it on-line;
#a matrix (channel × bin) shows as a colour tint the R2 value of any feature. A colorbar shows the colour range between -1 and 1;
#Another panel shows a detail of the previous matrix. The upper topographic plot shows the R2 value for any channel in the selected bin of frequencies; the lower one is the spectrum of the selected channel for all the frequencies.

For a P300 analysis user can choose between:

#A R2 matrix
#An amplitude waveform graph
#A topographic plot
#An ERP response graph
#A string prediction form.

All these result visualizations can be easily included in any of user scripts for custom analysis.

Programming Reference:Cpp Coding Style

2007-05-07T15:49:21Z

Atennissen:

== Line Formatting ==
* No tab characters (please configure your editor to insert spaces instead).
* Indentation in steps of 2 or 3 space characters.
* Opening braces have their own line, aligned with the previous line; corresponding closing braces are placed on their own lines, at the same character position as the opening brace.
* For function definitions, return types appear on their own line, such that the function name is first in its line.

== Naming ==
* '''ALL_UPPERCASE_NAMES''' are reserved for preprocessor macros.
* '''CamelCase''' (uppercase letters inside words) is used to indicate word boundaries.
* Class names and namespaces begin with uppercase letters: '''MyNameSpace''', '''TheClass'''.
* Local variables and function arguments begin with lowercase letters: '''theCounter''', '''inSomeInput'''.
* Data members of true classes are private, and accessed via '''Accessor Functions'''.
** '''Setters''' use the prefix "Set" followed by the property's name, or directly the name of the property: '''SetValue()'''. Setter functions should also return a non-const reference to the data object itself rather than '''void''', this allows for chaining as in <code>float result = MyComputation().SetOrder( 5 ).SetDepth( 10 ).EvaluateAt( 4 );</code>
** '''Getters''' use the name of the property: '''Value()'''. Omitting the "Get" prefix allows the programmer to treat getters and reference accessors identically, as far as read access is concerned.
** '''Reference Accessors''' use the name of the property, and are provided in a doubly ''const'' and a ''non-const'' version. This is important to allow const access from const object references, and to discriminate between read and write accesses (note the ''mPossiblyChanged'' flag): <code>const int& Value() const { return mValue; }</code> <code>int& Value() { mPossiblyChanged = true; return mValue; }</code>

=== Name prefixes ===
Prefixes should carry information about the scope and usage of a variable but not its type.
* '''m''' for class data members,
* '''s''' for static class members and static variables,
* '''g''' for globals,
* '''c''' for constants,
* '''p''' for pointers,
* '''fp''' for function pointers,
* '''in''' for function input arguments,
* '''out''' for function output arguments,
* '''io''' for function arguments used for input and output.

==Variable Declaration==
* Always use the narrowest possible scope for a name to avoid side effects.
* Always initialize variables (at declaration resp. constructor).

==Memory Allocation==
* Allocate from the '''stack''' rather than the '''heap''' unless there is a good reason to use the '''new''' operator. This avoids memory leaks.
* Use STL containers rather than allocating arrays with '''new[]'''. This eliminates a number of possible errors (initialization, allocation, deallocation).

==Pointers and References==
* Use references rather than pointers wherever possible.

==Control Flow==
* Avoid '''goto''', '''break''' outside '''switch'''-'''case''' blocks, and multiple '''return''' statements.

== Example Function ==

void
MyClass::MyFunction( const SomeClass& inTheInput, int& outTheResult )
{
outTheResult = mSomeDataMember;
for( int i = 0; i < inTheInput.NumIterations(); ++i )
{
int k = 4;
while( --k > 0 )
outTheResult -= k;
}
}

[[Category:Development]]

Programming Reference:BCI2000 Source Code

2007-05-07T15:43:54Z

Atennissen:

==Version Management==
The BCI2000 source code is managed with the help of [http://subversion.tigris.org/ Subversion], an open-source cross-platform versioning tool widely used in various kinds of projects.

Subversion (SVN) uses the HTTP-based [http://en.wikipedia.org/wiki/WebDAV WebDAV] protocol, so even web browsers may be used as clients, although a true SVN client software is required to access all features of the versioning system.

==Browsing the Source Code Repository Online==
Online viewing, and comparison of different versions of all source code files, is possible with a web browser (http://{{SERVERNAME}}/tracproj/browser).
(If you get a message about "viewing privileges", click the "login" link at the top right to log in.)

== TortoiseSVN Client ==
For Win32 platforms, we recommend [http://www.tortoisesvn.org TortoiseSVN], a comfortable-to-use SVN client integrated into the Explorer shell.

=="How to---" Pages==
The following pages provide detailed instructions on the setup and use of TortoiseSVN:
* [[SVN Client Setup]],
* [[Using TortoiseSVN]].

==Directory Layout==
The SNV directory layout matches that of the BCI2000 binary distribution:

{|border="1" cellspacing="0"
!batch
|batch files for online modules
|-
!data
|online data output
|-
!doc
|information
|-
!parms
|online parameter files
|-
!prog
|online system executables
|-
!tools
|off-line analysis tools
|-
!src
|source code
|}

Different from the binary distibution, there is a separate directory tree under ''src''.
Below ''src'', there should be no end-user executables, compiled LaTeX files, or pdf files converted from editable formats.
Rather, their source files should go below ''src'', and their end-user versions go into either ''prog''/''doc'' or the appropriate end-user directory below ''tools''.
In all makefiles or project files that are relevant for the binary distribution, the compiled output is directed into the appropriate executable directory (''prog'' or ''tools/mytool'').

==Coding Style Guidelines==
We maintain a loose set of guidelines/rules that is aimed at readability and maintenance efficiency.
These rules are not obligatory but we ask contributors to consider them before handing in their code.
* [[Cpp Coding Style]]
* [[Matlab Coding Style]]

[[Category:Development]]

Administrators

2007-05-07T15:07:23Z

Atennissen:

==Administrator Role==
Administrators are responsible for setup and maintenance of software and user accounts.
Although new user accounts may be [[Creating_a_User_Account|created]] by existing users, it may be necessary to contact an administrator to:
* get more than the default set of user privileges,
* disable/remove a user account,
* reset a user's password.

==Personnel==
The BCI2000 server is administered by [[Gerwin Schalk]] and [[Jürgen Mellinger]].

[[Category:Roles]] [[Category:Administration]]

Technical Reference:BCI2000 Messages

2007-04-25T16:00:19Z

Atennissen:

Information transferred between BCI2000 modules is packed into messages.
Each message content corresponds to a BCI2000 data type such as Parameter, State, or Signal, and is wrapped into a layer that allows for routing the message to an appropriate handler.
BCI2000 data types know how to write themselves to, and read themselves from, a data stream.
For example, when the wrapper indicates that a message contains a brain signal, the framework code will route the message to a "brain signal" handler function that, in turn, asks a brain signal object to read itself from the message.
As another example, when the operator module receives a visualization message, the message wrapper layer will not only be used to direct the message to a visualization handler but also to the visualization window to which the message is addressed.

===Protocol Definition===
Each message starts
with a one-byte content descriptor and a one-byte descriptor supplement, followed
by a number that describes the length of the content. (See Figure below)

[[Image:BCI2000_Messages_MessageProtocol.png|center|thumb|400px|Layout of one message in the protocol.]]

The element denoted by "length field(2)" was originally a two-byte integer
field for the content length in little endian format. To allow for messages
longer than 64k, we introduced a backwards-compatible extension: if the length
is below 65535, it will still be transmitted as a two-byte integer in little
endian format. Otherwise, the two bytes will contain the value 65535, and be
followed by a decimal ASCII representation of the length, terminated with a zero
byte. For other one- and two-byte length fields occurring in the protocol, the
same scheme applies, generalized to be a "length field (original number of bytes)". (See Figure below)

[[Image:BCI2000_Messages_LengthField.png|center|thumb|300px|Detailed layout of a length field (m) for a length <math>n \geq 2^{m}-1</math>]]

{| border="1" cellpadding="2"
|+

===Overview of content descriptors===
!descriptor !! description
|-
| 1 || status information string
|-
| 2 || system parameter
|-
| 3 || system state
|-
| 4 || visualization data or brain signal
|-
| 5 || state vector
|-
| 6 || system command
|}

===Descriptor=1: Status Information Format===
This section describes the format of the message when the core message is
a status information string (i.e., the message's descriptor is 1). In this
case, the aforementioned content data is a line of ASCII characters in the following format:
xxx: status-line-text
xxx is a three digit number that describes the content of the status
information string.
A first digit of `1' indicates status information, a first digit of `2' indicates successful
operation, a first digit of `3' indicates recoverable errors and a first digit of `4' indicates fatal errors. The two remaining digits define the exact nature of the message, followed by a plain description.
This procedure is used to communicate errors and to convey status
information (e.g.,
the operator module may display the remaining disc space on the machine of the Source module.)

===Descriptor=2: Parameter Format===
For parameter messages, content data is a line of ASCII characters
representing a [[parameter definition]] line.

===Descriptor=3: State Format===
State messages contain a line of ASCII characters representing a
[[state definition]] line.

===Descriptor=4: Visualization and Brain Signal Data Format===
This section describes the format of the message when the core message
is a visualization data/brain signal message (i.e., the descriptor on the message is 4). In this
case, the content descriptor describes the requested visualization type.
The currently defined types are 1 (a graph of ''n'' channels and ''m'' samples), 2 (a text memo), and 255 (visualization configuration).
For brain signals, the content descriptor is 1. (See Figure below)

[[Image:BCI2000_Messages_VisualizationData.png|center|thumb|500px|One message in the protocol of type "visualization data".]]

The following figure illustrates the protocol when the visualization type is 1. The source identifier defines a unique number identifying the process/filter that generated the data. The data type
can be
*0 <tt>(SignalType::int16)</tt> for integers in little endian format.
*1 <tt>(SignalType::float24)</tt> for 3-byte floating-point values: The first two bytes (i.e., A) define the mantissa (signed two-byte integers in little endian format) and the third byte (i.e., B) defines the exponent (signed one-byte integer). The actual floating point value is then calculated as follows: <math>value=A*10^{B}</math>.
*2 <tt>(SignalType::float32)</tt> for 4-byte floating-point values in IEEE 754 format transmitted in little endian byte order.
*3 <tt>(SignalType::int32)</tt> for 4-byte signed integer values transmitted in little endian byte order.

The number of channels and samples are self explanatory.

[[Image:BCI2000_Messages_vistype1(graph).png|center|thumb|600px|One message if the visualization type is 1 (i.e., a graph).]]

The following figure illustrates how the data is transferred.

[[Image:BCI2000_Messages_TransmittedVisualizationDataFormat.png|center|thumb|500px|Graphical representation of the transmitted visualization data format.]]

The following figure illustrates the protocol when the visualization type is 2. The source identifier is a number uniquely identifying the process/filter that generated the data. (0 for brain signals.)
The following ASCII text is zero delimited.

[[Image:BCI2000_Messages_vistype2(memo).png|center|thumb|400px|One message if the visualization type is 2 (i.e., a text memo).]]

The following figure illustrates the protocol when the visualization type is 255. The source identifier is a number identifying the process/filter that generated the data. The different configuration IDs are defined in the CFGID enumeration in the [http://www.bci2000.org/tracproj/browser/trunk/src/shared/defines.h shared/defines.h]
header file.

The ASCII string then contains the configuration option, as defined by the configuration ID. For example, it might contain "128" if the configuration ID is 4. This will configure the graph to contain exactly 128 samples. When the configuration ID is 5 or 6 (axis labels), the ASCII string consists of a sample number (three digits), a space, and the axis label. Thus, one message
configures exactly one axis label. As an example, for an X-axis label, the string "003 4.75 Hz" would result in a graph, in which the third sample is labeled "4.75 Hz."

[[Image:BCI2000_Messages_vistype255(visconfig).png|center|thumb|500px|One message if the visualizationtype is 255 (i.e., visualization configuration).]]

====Brain Signal Format====
The brain signal is transmitted similarly to visualization data (i.e., as described in the Visualization and Brain Signal Data Format above). The visualization type is set to 1 (i.e., graph), source identifier is set to 0. Data type, channels and samples reflect the actual format of data transmitted.

====Control Signal Format====
Control signals are transmitted identically to the Brain Signal.

===Descriptor=5: State Vector===
The state vector is defined by a series of ''StateVectorLength''
subsequent bytes.
The value of a given state within the state vector is determined by
its byte/bit
location and length definition. The bits in the state vector are
always sorted
in ascending order, e.g., for a state with a length of 7 bits,
starting at byte
location 2, bit location 3, bit zero is first (byte 2, bit 3), and the
highest
bit (bit 7) is last (byte 3, bit 1).

===Descriptor=6: System Command===
The system command consists of an ASCII string that may end with a
zero byte (i.e., ASCII code 0).
The nature of these system commands is defined by the specific
implementation of
the modules.

Technical Reference:BCI2000 Messages

2007-04-25T15:48:40Z

Atennissen:

Information transferred between BCI2000 modules is packed into messages.
Each message content corresponds to a BCI2000 data type such as Parameter, State, or Signal, and is wrapped into a layer that allows for routing the message to an appropriate handler.
BCI2000 data types know how to write themselves to, and read themselves from, a data stream.
For example, when the wrapper indicates that a message contains a brain signal, the framework code will route the message to a "brain signal" handler function that, in turn, asks a brain signal object to read itself from the message.
As another example, when the operator module receives a visualization message, the message wrapper layer will not only be used to direct the message to a visualization handler but also to the visualization window to which the message is addressed.

===Protocol Definition===
Each message starts
with a one-byte content descriptor and a one-byte descriptor supplement, followed
by a number that describes the length of the content. (See Figure 1.1)

[[Image:BCI2000_Messages_MessageProtocol.png|center|thumb|400px|Fig. 1.1 Layout of one message in the protocol.]]

The element denoted by "length field(2)" was originally a two-byte integer
field for the content length in little endian format. To allow for messages
longer than 64k, we introduced a backwards-compatible extension: if the length
is below 65535, it will still be transmitted as a two-byte integer in little
endian format. Otherwise, the two bytes will contain the value 65535, and be
followed by a decimal ASCII representation of the length, terminated with a zero
byte. For other one- and two-byte length fields occurring in the protocol, the
same scheme applies, generalized to be a "length field (original number of bytes)". (See Figure 1.2)

[[Image:BCI2000_Messages_LengthField.png|center|thumb|300px|Fig 1.2. Detailed layout of a length field (m) for a length <math>n \geq 2^{m}-1</math>]]

{| border="1" cellpadding="2"
|+

===Overview of content descriptors===
!descriptor !! description
|-
| 1 || status information string
|-
| 2 || system parameter
|-
| 3 || system state
|-
| 4 || visualization data or brain signal
|-
| 5 || state vector
|-
| 6 || system command
|}

===Descriptor=1: Status Information Format===
This section describes the format of the message when the core message is
a status information string (i.e., the message's descriptor is 1). In this
case, the aforementioned content data is a line of ASCII characters in the following format:
xxx: status-line-text
xxx is a three digit number that describes the content of the status
information string.
A first digit of `1' indicates status information, a first digit of `2' indicates successful
operation, a first digit of `3' indicates recoverable errors and a first digit of `4' indicates fatal errors. The two remaining digits define the exact nature of the message, followed by a plain description.
This procedure is used to communicate errors and to convey status
information (e.g.,
the operator module may display the remaining disc space on the machine of the Source module.)

===Descriptor=2: Parameter Format===
For parameter messages, content data is a line of ASCII characters
representing a [[parameter definition]] line.

===Descriptor=3: State Format===
State messages contain a line of ASCII characters representing a
[[state definition]] line.

===Descriptor=4: Visualization and Brain Signal Data Format===
This section describes the format of the message when the core message
is a visualization data/brain signal message (i.e., the descriptor on the message is 4). In this
case, the content descriptor describes the requested visualization type.
The currently defined types are 1 (a graph of ''n'' channels and ''m'' samples), 2 (a text memo), and 255 (visualization configuration).
For brain signals, the content descriptor is 1. (See Figure 6.1)

[[Image:BCI2000_Messages_VisualizationData.png|center|thumb|500px|Fig. 6.1 One message in the protocol of type "visualization data".]]

Figure 6.2 illustrates the protocol when the visualization type is 1. The source identifier defines a unique number identifying the process/filter that generated the data. The data type
can be
*0 <tt>(SignalType::int16)</tt> for integers in little endian format.
*1 <tt>(SignalType::float24)</tt> for 3-byte floating-point values: The first two bytes (i.e., A) define the mantissa (signed two-byte integers in little endian format) and the third byte (i.e., B) defines the exponent (signed one-byte integer). The actual floating point value is then calculated as follows: <math>value=A*10^{B}</math>.
*2 <tt>(SignalType::float32)</tt> for 4-byte floating-point values in IEEE 754 format transmitted in little endian byte order.
*3 <tt>(SignalType::int32)</tt> for 4-byte signed integer values transmitted in little endian byte order.

The number of channels and samples are self explanatory.

[[Image:BCI2000_Messages_vistype1(graph).png|center|thumb|600px|Fig. 6.2 One message if the visualization type is 1 (i.e., a graph).]]

Figure 6.3 illustrates how the data is transferred.

[[Image:BCI2000_Messages_TransmittedVisualizationDataFormat.png|center|thumb|500px|Graphical representation of the transmitted visualization data format.]]

Figure 6.4 illustrates the protocol when the visualization type is 2. The source identifier is a number uniquely identifying the process/filter that generated the data. (0 for brain signals.)
The following ASCII text is zero delimited.

[[Image:BCI2000_Messages_vistype2(memo).png|center|thumb|400px|Fig. 6.4 One message if the visualization type is 2 (i.e., a text memo).]]

Figure 6.5 illustrates the protocol when the visualization type is 255. The source identifier is a number identifying the process/filter that generated the data. The different configuration IDs are defined in the CFGID enumeration in the [http://www.bci2000.org/tracproj/browser/trunk/src/shared/defines.h shared/defines.h]
header file.

The ASCII string then contains the configuration option, as defined by the configuration ID. For example, it might contain "128" if the configuration ID is 4. This will configure the graph to contain exactly 128 samples. When the configuration ID is 5 or 6 (axis labels), the ASCII string consists of a sample number (three digits), a space, and the axis label. Thus, one message
configures exactly one axis label. As an example, for an X-axis label, the string "003 4.75 Hz" would result in a graph, in which the third sample is labeled "4.75 Hz."

[[Image:BCI2000_Messages_vistype255(visconfig).png|center|thumb|500px|Fig. 6.5 One message if the visualizationtype is 255 (i.e., visualization configuration).]]

====Brain Signal Format====
The brain signal is transmitted similarly to visualization data (i.e., as described in Section 6). The visualization type is set to 1 (i.e., graph), source identifier is set to 0. Data type, channels and samples reflect the actual format of data transmitted.

====Control Signal Format====
Control signals are transmitted identically to the Brain Signal.

===Descriptor=5: State Vector===
The state vector is defined by a series of ''StateVectorLength''
subsequent bytes.
The value of a given state within the state vector is determined by
its byte/bit
location and length definition. The bits in the state vector are
always sorted
in ascending order, e.g., for a state with a length of 7 bits,
starting at byte
location 2, bit location 3, bit zero is first (byte 2, bit 3), and the
highest
bit (bit 7) is last (byte 3, bit 1).

===Descriptor=6: System Command===
The system command consists of an ASCII string that may end with a
zero byte (i.e., ASCII code 0).
The nature of these system commands is defined by the specific
implementation of
the modules.

Technical Reference:State Definition

2007-04-25T14:41:36Z

Atennissen:

This page describes the concept of BCI2000 states, in conjunction with their textual representation as a "state line".

For information about how to access state values from code, please refer to [[Programming Reference:States]].
For information about individual parameters, please refer to [[User Reference:States]].

==State Concept==
States are variables that represent the internal state of a BCI2000 system, as it is evolving over time in response to:
*brain signal input
*user interaction through the operator interface
*trial sequencing by the application module.

Typical entities encoded by states are:
*whether the system is running or suspended
*the time when a block of data was recorded
*stimulus or task being presented
*the classification result
*the state of an external marker (trigger) to be saved for off-line analysis.

Typically, state values change once per block of data, or once per trial.
In a [[BCI2000 data file]], the full set of states is stored along with the data, allowing for reconstruction of on-line system state off-line.

==State Vector==
In a BCI2000 system, a collection of states is maintained as a ''State List''.
For each state present in that state list, its value is kept as a range of bits in a bit vector called ''State Vector''.
BCI2000 modules and filters may read and write state values during processing.
The state vector's content is saved, in its binary form, into [[BCI2000 data files]] per-block.
Using the ByteLocation, BitLocation, and Length fields from the state definitions present in a file, a state's value may be read from the data file.

A state vector is a narrowly packed bit field in '''big endian''' ordering.
This implies that, for a state containing more than a single bit, '''less''' significant bits are placed at '''higher''' bit and byte locations.

As an example, consider a state vector consisting of a 1-bit state "Running", and a 16-bit state "SourceTime". This will result in a three-byte state vector layout like this:
{|border="1" cellspacing="0" cellpadding="1"
!colspan="8"|State Vector Byte 1
!colspan="8"|State Vector Byte 2
!colspan="8"|State Vector Byte 3
|-
!7!!6!!5!!4!!3!!2!!1!!0
!7!!6!!5!!4!!3!!2!!1!!0
!7!!6!!5!!4!!3!!2!!1!!0
|-
!Running!!colspan="16"|SourceTime!!colspan="7"|unused
|-
!0
!15!!14!!13!!12!!11!!10!!9!!8!!7!!6!!5!!4!!3!!2!!1!!0
!colspan="7"| 
|}

==State Lines==
State lines are a human-readable format used to represent individual states in
*[[BCI2000 data files]],
*[[BCI2000 messages]] sent between modules.
Core modules and operator module use this format to communicate in the system initialization phase, as well as during system performance and for system termination.

The format of a state line is
<pre>
Name Length Value ByteLocation BitLocation CRLF
</pre>
where <tt>Length</tt> refers to the number of bits used to represent the state's value,
and <tt>ByteLocation</tt> and <tt>BitLocation</tt> refer to its position in a [[State Vector]], with <tt>BitLocation</tt> ranging from 0..7.

Depending on the context of a state line, one or more of its fields may be ignored:
*In a State message sent from the operator module to a core module, Length, ByteLocation, and BitLocation will be ignored.
*In a State line contained in a data file, the Value field matches the state's value stored with the first block of data samples.

Generally, the Value field specifies an ''initial value'' of a state. Actual values are stored in the [[State Vector]] data structure.
-----
See also: [[User Reference:States]]