BCI2000 Wiki - User contributions [en]

User Reference:Normalizer

2009-03-03T04:54:54Z

Jhuggins: /* Adaptation */

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

One may suggest that the adaptation time may affect the accuracy of the cursor movement in mu rhythm experiments. However, the following reference shows that computing the normalization parameters either during or at the end of the trials leaded to similar results. Hence, in the current version of bci2000, adaptation is accomplished at the end of each trial and using a Moving Average Algorithm.

Ramoser H, Wolpaw JR, Pfurtscheller G, "EEG-based communication: evaluation of alternative signal prediction methods". Biomed Tech (Berl); 42(9) : 226-33, Sep, 1997.

'''Abstract'''-Individuals can learn to control the amplitude of EEG activity in specific frequency bands over sensorimotor cortex and use it to move a cursor to a target on a computer screen. For one-dimensional (i.e., vertical) cursor movement, a linear equation translates the EEG activity into cursor movement. To translate an individual's EEG control into cursor control as effectively as possible, the intercept in this equation, which determines whether upward or downward movement occurs, should be set so that top and bottom targets are equally accessible. The present study compares alternative methods for using an individual's previous performance to select the intercept for subsequent trials. In offline analyses, five different intercept selection methods were applied to EEG data collected while trained subjects were moving the cursor to targets at the top or bottom edge of the screen. In the first two methods-moving average, and weighted sum-a single intercept was selected for the entire 1-2 sec period of each trial. In the other three methods-blocked moving average, blocked weighted sum, and blocked recursive sum (a variation of the weighted sum)-an intercept was selected for each 200-ms segment of the trial. The results from these methods were compared in regard to their balance between upward and downward movements and their consistency of performance across trials. For all subjects combined, the five methods performed similarly. However, performance across subjects was more consistent for the moving average, blocked moving average, and blocked recursive sum methods than for the weighted sum and blocked weighted sum methods. Due to its consistent performance and its computational simplicity, the moving average method, using the five most recent pairs of top and bottom trials, appears to be the method of choice.

===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 quantity 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 quantities 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 adaptation strategy individually for each 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 [[BCI2000 Glossary#State|state variables]] 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 its oldest data once the buffer is filled).
*Columns correspond to control signal channels. 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>.

For continuous adaptation, specify an empty string in the ''UpdateTrigger'' parameter.

==States==
Buffer condition expressions, and the UpdateTrigger expression may involve any [[BCI2000 Glossary#State|state]] present in the system. Expressions are checked for syntactical correctness and whether referred-to states are present during the [[Technical Reference:States of Operation|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 (see below). Depending on which control signal should be adapted on, these conditions need to be entered in the first, second, or third column of the matrix (corresponding to x, y, and z direction when used with the [[User Reference:CursorTask|CursorTask]] application module).
(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)
*To achieve continuous movement in, say, the x direction we need a constant normalizer output on that channel. To be consistent with the [[User Reference:CursorTask#FeedbackDuration|task module's FeedbackDuration parameter]], this output should be constant +2 in order for the cursor to cross the entire screen during a trial, and +1 when cursor movement begins at the screen's center. This corresponds to the following settings for the channel in question:
Adaptation= 0
NormalizerOffset= -1
NormalizerGain= 1 or 2, respectively.

===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===
*For this example, 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]], [[BCI2000 Glossary#Control Signal]], [[User Reference:LinearClassifier]]

[[Category:Filters]][[Category:Signal Processing]]

User Reference:Normalizer

2009-03-03T04:54:30Z

Jhuggins: /* Adaptation */

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

One may suggest that the adaptation time may affect the accuracy of the cursor movement in mu rhythm experiments. However, the following reference shows that computing the normalization parameters either during or at the end of the trials leaded to similar results. Hence, in the current version of bci2000, adaptation is accomplished at the end of each trial and using a Moving Average Algorithm.

Ramoser H, Wolpaw JR, Pfurtscheller G, "EEG-based communication: evaluation of alternative signal prediction methods". Biomed Tech (Berl); 42(9) : 226-33, Sep, 1997.

'''''''Abstract'''''''-Individuals can learn to control the amplitude of EEG activity in specific frequency bands over sensorimotor cortex and use it to move a cursor to a target on a computer screen. For one-dimensional (i.e., vertical) cursor movement, a linear equation translates the EEG activity into cursor movement. To translate an individual's EEG control into cursor control as effectively as possible, the intercept in this equation, which determines whether upward or downward movement occurs, should be set so that top and bottom targets are equally accessible. The present study compares alternative methods for using an individual's previous performance to select the intercept for subsequent trials. In offline analyses, five different intercept selection methods were applied to EEG data collected while trained subjects were moving the cursor to targets at the top or bottom edge of the screen. In the first two methods-moving average, and weighted sum-a single intercept was selected for the entire 1-2 sec period of each trial. In the other three methods-blocked moving average, blocked weighted sum, and blocked recursive sum (a variation of the weighted sum)-an intercept was selected for each 200-ms segment of the trial. The results from these methods were compared in regard to their balance between upward and downward movements and their consistency of performance across trials. For all subjects combined, the five methods performed similarly. However, performance across subjects was more consistent for the moving average, blocked moving average, and blocked recursive sum methods than for the weighted sum and blocked weighted sum methods. Due to its consistent performance and its computational simplicity, the moving average method, using the five most recent pairs of top and bottom trials, appears to be the method of choice.

===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 quantity 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 quantities 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 adaptation strategy individually for each 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 [[BCI2000 Glossary#State|state variables]] 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 its oldest data once the buffer is filled).
*Columns correspond to control signal channels. 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>.

For continuous adaptation, specify an empty string in the ''UpdateTrigger'' parameter.

==States==
Buffer condition expressions, and the UpdateTrigger expression may involve any [[BCI2000 Glossary#State|state]] present in the system. Expressions are checked for syntactical correctness and whether referred-to states are present during the [[Technical Reference:States of Operation|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 (see below). Depending on which control signal should be adapted on, these conditions need to be entered in the first, second, or third column of the matrix (corresponding to x, y, and z direction when used with the [[User Reference:CursorTask|CursorTask]] application module).
(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)
*To achieve continuous movement in, say, the x direction we need a constant normalizer output on that channel. To be consistent with the [[User Reference:CursorTask#FeedbackDuration|task module's FeedbackDuration parameter]], this output should be constant +2 in order for the cursor to cross the entire screen during a trial, and +1 when cursor movement begins at the screen's center. This corresponds to the following settings for the channel in question:
Adaptation= 0
NormalizerOffset= -1
NormalizerGain= 1 or 2, respectively.

===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===
*For this example, 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]], [[BCI2000 Glossary#Control Signal]], [[User Reference:LinearClassifier]]

[[Category:Filters]][[Category:Signal Processing]]

User Reference:Normalizer

2009-03-03T04:54:12Z

Jhuggins: /* Adaptation */

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

One may suggest that the adaptation time may affect the accuracy of the cursor movement in mu rhythm experiments. However, the following reference shows that computing the normalization parameters either during or at the end of the trials leaded to similar results. Hence, in the current version of bci2000, adaptation is accomplished at the end of each trial and using a Moving Average Algorithm.

Ramoser H, Wolpaw JR, Pfurtscheller G, "EEG-based communication: evaluation of alternative signal prediction methods". Biomed Tech (Berl); 42(9) : 226-33, Sep, 1997.

'''''Abstract'''''-Individuals can learn to control the amplitude of EEG activity in specific frequency bands over sensorimotor cortex and use it to move a cursor to a target on a computer screen. For one-dimensional (i.e., vertical) cursor movement, a linear equation translates the EEG activity into cursor movement. To translate an individual's EEG control into cursor control as effectively as possible, the intercept in this equation, which determines whether upward or downward movement occurs, should be set so that top and bottom targets are equally accessible. The present study compares alternative methods for using an individual's previous performance to select the intercept for subsequent trials. In offline analyses, five different intercept selection methods were applied to EEG data collected while trained subjects were moving the cursor to targets at the top or bottom edge of the screen. In the first two methods-moving average, and weighted sum-a single intercept was selected for the entire 1-2 sec period of each trial. In the other three methods-blocked moving average, blocked weighted sum, and blocked recursive sum (a variation of the weighted sum)-an intercept was selected for each 200-ms segment of the trial. The results from these methods were compared in regard to their balance between upward and downward movements and their consistency of performance across trials. For all subjects combined, the five methods performed similarly. However, performance across subjects was more consistent for the moving average, blocked moving average, and blocked recursive sum methods than for the weighted sum and blocked weighted sum methods. Due to its consistent performance and its computational simplicity, the moving average method, using the five most recent pairs of top and bottom trials, appears to be the method of choice.

===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 quantity 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 quantities 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 adaptation strategy individually for each 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 [[BCI2000 Glossary#State|state variables]] 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 its oldest data once the buffer is filled).
*Columns correspond to control signal channels. 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>.

For continuous adaptation, specify an empty string in the ''UpdateTrigger'' parameter.

==States==
Buffer condition expressions, and the UpdateTrigger expression may involve any [[BCI2000 Glossary#State|state]] present in the system. Expressions are checked for syntactical correctness and whether referred-to states are present during the [[Technical Reference:States of Operation|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 (see below). Depending on which control signal should be adapted on, these conditions need to be entered in the first, second, or third column of the matrix (corresponding to x, y, and z direction when used with the [[User Reference:CursorTask|CursorTask]] application module).
(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)
*To achieve continuous movement in, say, the x direction we need a constant normalizer output on that channel. To be consistent with the [[User Reference:CursorTask#FeedbackDuration|task module's FeedbackDuration parameter]], this output should be constant +2 in order for the cursor to cross the entire screen during a trial, and +1 when cursor movement begins at the screen's center. This corresponds to the following settings for the channel in question:
Adaptation= 0
NormalizerOffset= -1
NormalizerGain= 1 or 2, respectively.

===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===
*For this example, 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]], [[BCI2000 Glossary#Control Signal]], [[User Reference:LinearClassifier]]

[[Category:Filters]][[Category:Signal Processing]]

User Reference:Normalizer

2009-03-03T04:53:21Z

Jhuggins: /* Adaptation */

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

One may suggest that the adaptation time may affect the accuracy of the cursor movement in mu rhythm experiments. However, the following reference shows that computing the normalization parameters either during or at the end of the trials leaded to similar results. Hence, in the current version of bci2000, adaptation is accomplished at the end of each trial and using a Moving Average Algorithm.

Ramoser H, Wolpaw JR, Pfurtscheller G, "EEG-based communication: evaluation of alternative signal prediction methods". Biomed Tech (Berl); 42(9) : 226-33, Sep, 1997.

Individuals can learn to control the amplitude of EEG activity in specific frequency bands over sensorimotor cortex and use it to move a cursor to a target on a computer screen. For one-dimensional (i.e., vertical) cursor movement, a linear equation translates the EEG activity into cursor movement. To translate an individual's EEG control into cursor control as effectively as possible, the intercept in this equation, which determines whether upward or downward movement occurs, should be set so that top and bottom targets are equally accessible. The present study compares alternative methods for using an individual's previous performance to select the intercept for subsequent trials. In offline analyses, five different intercept selection methods were applied to EEG data collected while trained subjects were moving the cursor to targets at the top or bottom edge of the screen. In the first two methods-moving average, and weighted sum-a single intercept was selected for the entire 1-2 sec period of each trial. In the other three methods-blocked moving average, blocked weighted sum, and blocked recursive sum (a variation of the weighted sum)-an intercept was selected for each 200-ms segment of the trial. The results from these methods were compared in regard to their balance between upward and downward movements and their consistency of performance across trials. For all subjects combined, the five methods performed similarly. However, performance across subjects was more consistent for the moving average, blocked moving average, and blocked recursive sum methods than for the weighted sum and blocked weighted sum methods. Due to its consistent performance and its computational simplicity, the moving average method, using the five most recent pairs of top and bottom trials, appears to be the method of choice.

===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 quantity 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 quantities 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 adaptation strategy individually for each 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 [[BCI2000 Glossary#State|state variables]] 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 its oldest data once the buffer is filled).
*Columns correspond to control signal channels. 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>.

For continuous adaptation, specify an empty string in the ''UpdateTrigger'' parameter.

==States==
Buffer condition expressions, and the UpdateTrigger expression may involve any [[BCI2000 Glossary#State|state]] present in the system. Expressions are checked for syntactical correctness and whether referred-to states are present during the [[Technical Reference:States of Operation|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 (see below). Depending on which control signal should be adapted on, these conditions need to be entered in the first, second, or third column of the matrix (corresponding to x, y, and z direction when used with the [[User Reference:CursorTask|CursorTask]] application module).
(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)
*To achieve continuous movement in, say, the x direction we need a constant normalizer output on that channel. To be consistent with the [[User Reference:CursorTask#FeedbackDuration|task module's FeedbackDuration parameter]], this output should be constant +2 in order for the cursor to cross the entire screen during a trial, and +1 when cursor movement begins at the screen's center. This corresponds to the following settings for the channel in question:
Adaptation= 0
NormalizerOffset= -1
NormalizerGain= 1 or 2, respectively.

===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===
*For this example, 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]], [[BCI2000 Glossary#Control Signal]], [[User Reference:LinearClassifier]]

[[Category:Filters]][[Category:Signal Processing]]

User Reference:Normalizer

2009-03-03T04:52:15Z

Jhuggins: /* Adaptation */

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

One may suggest that the adaptation time may affect the accuracy of the cursor movement in mu rhythm experiments. However, the following reference shows that computing the normalization parameters either during or at the end of the trials leaded to similar results. Hence, in the current version of bci2000, adaptation is accomplished at the end of each trial and using a Moving Average Algorithm.

Ramoser H, Wolpaw JR, Pfurtscheller G,

EEG-based communication: evaluation of alternative signal prediction methods.

Biomed Tech (Berl). 1997 Sep;42(9):226-33.

Individuals can learn to control the amplitude of EEG activity in specific frequency bands over sensorimotor cortex and use it to move a cursor to a target on a computer screen. For one-dimensional (i.e., vertical) cursor movement, a linear equation translates the EEG activity into cursor movement. To translate an individual's EEG control into cursor control as effectively as possible, the intercept in this equation, which determines whether upward or downward movement occurs, should be set so that top and bottom targets are equally accessible. The present study compares alternative methods for using an individual's previous performance to select the intercept for subsequent trials. In offline analyses, five different intercept selection methods were applied to EEG data collected while trained subjects were moving the cursor to targets at the top or bottom edge of the screen. In the first two methods-moving average, and weighted sum-a single intercept was selected for the entire 1-2 sec period of each trial. In the other three methods-blocked moving average, blocked weighted sum, and blocked recursive sum (a variation of the weighted sum)-an intercept was selected for each 200-ms segment of the trial. The results from these methods were compared in regard to their balance between upward and downward movements and their consistency of performance across trials. For all subjects combined, the five methods performed similarly. However, performance across subjects was more consistent for the moving average, blocked moving average, and blocked recursive sum methods than for the weighted sum and blocked weighted sum methods. Due to its consistent performance and its computational simplicity, the moving average method, using the five most recent pairs of top and bottom trials, appears to be the method of choice.

===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 quantity 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 quantities 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 adaptation strategy individually for each 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 [[BCI2000 Glossary#State|state variables]] 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 its oldest data once the buffer is filled).
*Columns correspond to control signal channels. 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>.

For continuous adaptation, specify an empty string in the ''UpdateTrigger'' parameter.

==States==
Buffer condition expressions, and the UpdateTrigger expression may involve any [[BCI2000 Glossary#State|state]] present in the system. Expressions are checked for syntactical correctness and whether referred-to states are present during the [[Technical Reference:States of Operation|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 (see below). Depending on which control signal should be adapted on, these conditions need to be entered in the first, second, or third column of the matrix (corresponding to x, y, and z direction when used with the [[User Reference:CursorTask|CursorTask]] application module).
(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)
*To achieve continuous movement in, say, the x direction we need a constant normalizer output on that channel. To be consistent with the [[User Reference:CursorTask#FeedbackDuration|task module's FeedbackDuration parameter]], this output should be constant +2 in order for the cursor to cross the entire screen during a trial, and +1 when cursor movement begins at the screen's center. This corresponds to the following settings for the channel in question:
Adaptation= 0
NormalizerOffset= -1
NormalizerGain= 1 or 2, respectively.

===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===
*For this example, 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]], [[BCI2000 Glossary#Control Signal]], [[User Reference:LinearClassifier]]

[[Category:Filters]][[Category:Signal Processing]]

User Reference:Normalizer

2009-03-03T04:51:50Z

Jhuggins: /* Adaptation */

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

One may suggest that the adaptation time may affect the accuracy of the cursor movement in mu rhythm experiments. However, the following reference shows that computing the normalization parameters either during or at the end of the trials leaded to similar results. Hence, in the current version of bci2000, adaptation is accomplished at the end of each trial and using a Moving Average Algorithm.

Ramoser H, Wolpaw JR, Pfurtscheller G,
EEG-based communication: evaluation of alternative signal prediction methods.
Biomed Tech (Berl). 1997 Sep;42(9):226-33.

Individuals can learn to control the amplitude of EEG activity in specific frequency bands over sensorimotor cortex and use it to move a cursor to a target on a computer screen. For one-dimensional (i.e., vertical) cursor movement, a linear equation translates the EEG activity into cursor movement. To translate an individual's EEG control into cursor control as effectively as possible, the intercept in this equation, which determines whether upward or downward movement occurs, should be set so that top and bottom targets are equally accessible. The present study compares alternative methods for using an individual's previous performance to select the intercept for subsequent trials. In offline analyses, five different intercept selection methods were applied to EEG data collected while trained subjects were moving the cursor to targets at the top or bottom edge of the screen. In the first two methods-moving average, and weighted sum-a single intercept was selected for the entire 1-2 sec period of each trial. In the other three methods-blocked moving average, blocked weighted sum, and blocked recursive sum (a variation of the weighted sum)-an intercept was selected for each 200-ms segment of the trial. The results from these methods were compared in regard to their balance between upward and downward movements and their consistency of performance across trials. For all subjects combined, the five methods performed similarly. However, performance across subjects was more consistent for the moving average, blocked moving average, and blocked recursive sum methods than for the weighted sum and blocked weighted sum methods. Due to its consistent performance and its computational simplicity, the moving average method, using the five most recent pairs of top and bottom trials, appears to be the method of choice.

===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 quantity 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 quantities 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 adaptation strategy individually for each 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 [[BCI2000 Glossary#State|state variables]] 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 its oldest data once the buffer is filled).
*Columns correspond to control signal channels. 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>.

For continuous adaptation, specify an empty string in the ''UpdateTrigger'' parameter.

==States==
Buffer condition expressions, and the UpdateTrigger expression may involve any [[BCI2000 Glossary#State|state]] present in the system. Expressions are checked for syntactical correctness and whether referred-to states are present during the [[Technical Reference:States of Operation|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 (see below). Depending on which control signal should be adapted on, these conditions need to be entered in the first, second, or third column of the matrix (corresponding to x, y, and z direction when used with the [[User Reference:CursorTask|CursorTask]] application module).
(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)
*To achieve continuous movement in, say, the x direction we need a constant normalizer output on that channel. To be consistent with the [[User Reference:CursorTask#FeedbackDuration|task module's FeedbackDuration parameter]], this output should be constant +2 in order for the cursor to cross the entire screen during a trial, and +1 when cursor movement begins at the screen's center. This corresponds to the following settings for the channel in question:
Adaptation= 0
NormalizerOffset= -1
NormalizerGain= 1 or 2, respectively.

===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===
*For this example, 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]], [[BCI2000 Glossary#Control Signal]], [[User Reference:LinearClassifier]]

[[Category:Filters]][[Category:Signal Processing]]

User Reference:SpatialFilter

2009-02-02T13:47:45Z

Jhuggins: /* SpatialFilterType */

==Function==
The SpatialFilter computes an instantaneous linear transformation of its input. Typically, the SpatialFilter's input is the unfiltered brain signal from the source module. The linear transformation that is applied by the spatial filter is described by a transformation matrix, and applied for each sample separately, not linking data across different points in time. This linear transformation can be parameterized in three different ways as described below.

==Parameters==
===SpatialFilterType===
This parameter defines the method that will be used to design the spatial filter. Choices are:
;0 None
:No spatial filtering is performed; the input signal is copied to the output signal, and the spatial filter matrix is ignored.
;1 Full Matrix
:The linear transformation applied to the input signal is defined by the ''SpatialFilter'' matrix parameter. This is the is also the default, and matches behavior in previous versions of BCI2000.
;2 Sparse Matrix
:The sparse matrix filter uses the ''SpatialFilter'' matrix parameter to define non-zero matrix entries. Each non-zero entry is given by an input channel, output channel, and weight for that channel.
;3 Common Average Reference (CAR)
:The common average reference spatial filter calculates the mean of all channels, and subtracts this value from the selected output channels. This filter's output channels may be defined by the ''SpatialFilterCAROutput'' parameter.

===SpatialFilter===
====Full Matrix Filter Type====
[[Image:SpatialFilter.png|right|256px]]
The full matrix filter uses the SpatialFilter parameter to define 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.
Also, specifying ''row labels'' to identify output channels allows you to use those labels in configuration of further stages of processing, such as the [[User Reference:LinearClassifier|LinearClassifier]].

====Sparse Matrix Filter Type====
The sparse matrix filter uses the SpatialFilter parameter to define the relationship between input channels and output channels with a given weight. In this case, the SpatialFilter matrix must have 3 columns, and a row for each input/output relationship. The first column contains the input channel, the third column defines the weight that the input channel is multiplied by before being assigned to the output channel, which is defined in the second column.

When specifying input channels in the first column, you may use [[User Reference:DataIOFilter#ChannelNames|channel names]]. In order to assign labels to output channels in sparse representation, use arbitrary labels in the (third) output channel column.

See the example below for more information on how to use the sparse matrix.

===SpatialFilterCAROutput===
This parameter is a list of channels that define which channels should be output from the common average reference spatial filter, and the order in which they should appear. That is, the location of the channel in this list determines the output channel position. For example, if input channels 6, 7, 10, and 12 should be passed to the output of the spatial filter as channels 3, 4, 1, and 2, then this parameter should be set to:

<code>10 12 6 7</code>

Rather than numbers, channel names may be specified as defined in the [[User Reference:DataIOFilter#ChannelNames|ChannelNames]] parameter:

<code>C3 C4 CP3 CP4 Cz</code>

It is important to note that '''all''' channels passed to the spatial filter (typically defined in the [[User Reference:Parameters#TransmitChList|TransmitChList parameter]]) are used in the CAR calculation, but only a subset of these channels are actually output and passed to the next step in the signal processing chain.

If this parameter is left blank, then all input channels are passed to the output, and the number of input channels equals the number of output channels.

==States==
None.

==Examples==
===Linked Mastoids (Full Matrix)===
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" | ...
|}

===Sparse Matrix===
In this example, the mean of channels 1-4 are passed to output channel 1, and the negative mean of channels 10-14 are passed to output channel 2. The SpatialFilter matrix definition is given below.

{| border="1" cellspacing="0" cellpadding="3" style="text-align:center"
|+ Sparse Matrix
!   !! In !! Out !! Wt
|-
! 1
| 1 || 1 || .25
|-
! 2
| 2 || 1 || .25
|-
! 3
| 3 || 1 || .25
|-
! 4
| 4 || 1 || .25
|-
! 5
| 10 || 2 || -.2
|-
! 6
| 11 || 2 || -.2
|-
! 7
| 12 || 2 || -.2
|-
! 8
| 13 || 2 || -.2
|-
! 9
| 14 || 2 || -.2
|-
|}

This results in: 
<code>OutCh(1) = 0.25*InCh(1) + 0.25*InCh(2) + 0.25*InCh(3) + 0.25*InCh(4)</code> 
<code>OutCh(2) = (-0.25)*InCh(10) + (-0.25)*InCh(11) + (-0.25)*InCh(12) + (-0.25)*InCh(13)</code>

===Large Laplacian (Sparse Matrix)===
In this example, the spatial filter computes Large-Laplacian filtered versions of channels ''C3'' and ''C4'' by re-referencing them to the mean of their mid-range neighbors ''Cz'', ''P3/4'', ''T7/8'', and ''F3/4'': 

<code>C3'=C3-(Cz+P3+T7+F3)/4</code> 
<code>C4'=C4-(Cz+P4+T8+F4)/4</code>

Using channel names, the filter specification will be independent of the order and exact set of input channels, provided that all required channels are available and labeled correctly.

{| border="1" cellspacing="0" cellpadding="3" style="text-align:center"
|+ Sparse Matrix
!   !! In !! Out !! Wt
|-
! 1
| C3 || C3 || 1
|-
! 2
| Cz || C3 || -.25
|-
! 3
| P3 || C3 || -.25
|-
! 4
| T7 || C3 || -.25
|-
! 5
| F3 || C3 || -.25
|-
! 6
| C4 || C4 || 1
|-
! 7
| Cz || C4 || -.25
|-
! 8
| P4 || C4 || -.25
|-
! 9
| T8 || C4 || -.25
|-
! 10
| F4 || C4 || -.25
|}

==Performance Notes==
Each spatial filter type uses a different algorithm to compute the linear transformation, and can therefore have implications on CPU load and performance. In the following, <math>N</math> denotes the filter's number of input channels, and <math>M \leq N</math> denotes its number of output channels.

===None===
No computations are actually done, but input data is being copied into the filter's output, resulting in a complexity <math>O(N)</math>.

===CAR===
The common-average reference has a complexity of <math>O(N+M)</math>, providing the next best performance in most circumstances. It is possible to create a CAR using either the full-matrix or sparse matrix options; however, the CAR method only calculates the mean value once per sample, and subtracts it only from the selected output channels. In order to implement a CAR in a full-matrix, the mean must be recalculated for ''every'' output channel, which is not as efficient, particularly for high channel count systems.

===Sparse Matrix===
The sparse matrix method performance is determined completely by the number of elements (rows) in the ''SpatialFilter'' matrix. In the best case, a single channel is multiplied by the weight and assigned to the specified output channel; this would take far less CPU time than the CAR method, and possibly the "none" option as well.

In a realistic scenario, all <math>N</math> input channels will be used to calculate <math>M \leq N</math> output channels; thus, complexity is between <math>O(N)</math> and <math>O(N*M)</math>, with <math>O(N^2)</math> in the worst case.

Sparse matrix worst-case performance will be close to that of an <math>N\times N</math> "full" spatial filter matrix. Thus, for spatial filter configurations that depend on electrode/sensor locations such as Laplacian filtering, filter definition in terms of a sparse matrix using [[User_Reference:DataIOFilter#ChannelNames|channel labels]] appears most advantageous.

===Full Matrix===
Full matrix representation is the most general way to specify a spatial filter, and recommended for situations not allowed for by the remaining spatial filter types.
Compared to those, it is associated with a number of disadvantages:
*Complexity is <math>O(N^2)</math>. In situations with large sampling rates and/or a large number of channels, this may result in real-time problems due to high CPU load.
*[[User_Reference:DataIOFilter#ChannelNames|Channel labels]] are not preserved across the filter. Due to the filter's general nature, no relation between input and output channel names can be inferred, and all output labels must be specified manually.
*The filter's specification depends on the order of input channels, which makes it interdependent with the [[User Reference:Parameters#TransmitChList|''TransmitChList'' parameter]].

==See also==
[[User Reference:LinearClassifier]], [[User Reference:DataIOFilter#ChannelNames]]

[[Category:Filters]][[Category:Signal Processing]]