Mellinger: /* Location */

2008-08-19T12:52:03Z

Location

← Older revision		Revision as of 12:52, 19 August 2008
Line 1:		Line 1:
	==Location==		==Location==
	<tt>BCI2000/src/shared//modules/application/utils~~/TrialStatistics~~</tt>		<tt>BCI2000/src/shared//modules/application/utils</tt>

	==Synopsis==		==Synopsis==

Mellinger at 17:11, 14 August 2008

2008-08-14T17:11:35Z

New page

==Location==
<tt>BCI2000/src/shared//modules/application/utils/TrialStatistics</tt>

==Synopsis==
The <tt>TrialStatistics</tt> class provides bookkeeping for trial outcomes in form of a frequency matrix recording target and result of each trial.

The <tt>TrialStatistics</tt> class is a descendant of the [[Programming Reference:EnvironmentExtension Class|<tt>EnvironmentExtension</tt>]] class.

==Properties==
===int Hits (r)===
The number of trials where the result matched the target.
===int Total (r)===
The total number of trials recorded.
===int Invalid (r)===
The number of trials recorded as "invalid". Invalid trials do not enter into performance computation.
===float Bits (r)===
The amount of information transferred since the last reset, given in bits. See the notes below for details.

==Events==
===Initialize===
During system initialization, <tt>TrialStatistics</tt> uses the [[User_Reference:CursorTask#NumberTargets|NumberTargets]] parameter to determine the size of its internal frequency matrix.

==Methods==
===Reset()===
Resets the invalid trials counter, and all entries of the frequency matrix to 0.
===Update(int TargetCode, int ResultCode)===
Adds the outcome of a trial to the frequency matrix.
===UpdateInvalid()===
Increments the invalid trials counter.

==Remarks==
The ''Bits()'' function computes the amount of information transferred through
a noisy channel when for each combination of input and output symbols
(target and result codes) the number of occurrences is given in form of
the elements of a frequency matrix.

The computation uses the formula for information transfer through a noisy channel as given in
Shannon, A Mathematical Theory of Communication, in: The Bell System Technical Journal, Vol. 27, 1948, section 16:
<math>
H = - \sum_{i,j}{P_i p_{ij}} \log\sum_i{P_i p_{ij}}
+ \sum_{i,j}{P_i (p_{ij} \log{p_{ij}})}
</math>
where <math>H</math> is the information transferred per symbol, <math>P_i</math> is a probability distribution over input symbols, and noise is represented as a ``transition matrix'' <math>p_{ij}</math> that contains the probability for output <math>j</math> if the input is <math>i</math>.

In the expression, the first term represents the entropy of the distribution of output symbols
(result codes); the second term represents the reduction of this entropy
introduced by noise, and is given as the negative of the entropy for each
<math>p_{ij}</math> row: <math>\sum_j p_{ij}\log p_{ij}</math>, weighted by the probability <math>P_i</math> for the occurrence of its input symbol, i.e. for its actual occurrence during transmission.

We consider the elements of the frequency matrix as an estimate
for <math>N P_i p_{ij}</math> where <math>N</math> is the number of symbols transferred, i.e. the number of trials, and the relative frequencies of target codes as an estimate for the <math>P_i</math>. From this, we compute the total number of bits transferred, i.e. Shannon's expression multiplied by <math>N</math>.

==Limitations==
Shannon's expression is based on assumptions that are likely to be violated in practice, most notably
*the assumption that successive input symbols (target codes) are independent of each other -- this is clearly violated by obtaining target codes from a block randomization scheme, implying an over-estimate of the bit rate, but also
*the assumption that noise affects successive input independently is not necessarily fulfilled, especially in the presence of an adaptive algorithm.

==See also==
[[Programming Reference:ApplicationBase Class]], [[Programming Reference:EnvironmentExtension Class]]

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

Programming Reference:TrialStatistics Class - Revision history

Mellinger: /* Location */

Mellinger at 17:11, 14 August 2008