User Reference:P3SpellerTask

Function

The P3SpellerTask filter implements Donchin's matrix speller paradigm (Sellers, Donchin, Schalk, 2004). Such a matrix speller presents a matrix of options; rows and columns of that matrix are flashed to elicit an evoked response (ERP) whenever the user's attended matrix element is flashed. From ERP classification results, the speller then derives which of the matrix elements was attended to, and executes the action corresponding to that matrix element. Typically, this action will consist in adding a character to a text window.

Both the P3SpellerTask and the StimulusPresentationTask rely on an underlying component, the StimulusTask, to manage stimulus presentation timeline and state variables.

Timeline

Parameters

WindowBackgroundColor

The window's background color, given as an RGB value. For convenience, RGB values may be entered in hexadecimal notation, e.g. 0xff0000 for red.

PreRunDuration

The duration of the pause preceding the first sequence. Given in sample blocks, or in time units when immediately followed with 's', 'ms', or similar.

PostRunDuration

Duration of the pause following last sequence. Given in sample blocks, or in time units when immediately followed with 's', 'ms', or similar.

PreSequenceDuration

Duration of the pause preceding sequences (or sets of intensifications). Given in sample blocks, or in time units when immediately followed with 's', 'ms', or similar.

In free or copy mode, the PreSequenceDuration and PostSequenceDuration parameters may not go below twice the value of the StimulusDuration parameters, in order to allow for presentation of FocusOn and Result announcement stimuli.

PostSequenceDuration

Duration of the pause following sequences (or sets of intensifications). Given in sample blocks, or in time units when immediately followed with 's', 'ms', or similar.

When used in conjunction with the P3TemporalFilter, this value needs to be larger than the EpochLength parameter. This allows classification to complete before the next sequence of stimuli is presented.

StimulusDuration

For visual stimuli, the duration of stimulus presentation. For auditory stimuli, the maximum duration, i.e. playback of audio extending above the specified duration will be muted. Given in sample blocks, or in time units when immediately followed with 's', 'ms', or similar.

EarlyOffsetExpression

Allows the specification of an Expression that is constantly monitored during stimulus presentation. When the value of the Expression transitions from zero to non-zero, the stimulus is aborted early, even if the StimulusDuration has not yet elapsed. For example, set this Expression to KeyDown==32 and start your source module with the --LogKeyboard=1 flag: then the subject will be able to advance the stimulus sequence manually by pressing the space key.

ISIMinDuration, ISIMaxDuration

Minimum and maximum duration of the inter-stimulus interval. During the inter-stimulus interval, the screen is blank, and audio is muted.

Actual inter-stimulus intervals vary randomly between minimum and maximum value, with uniform probability for all intermediate values. Given in sample blocks, or in time units when immediately followed with 's', 'ms', or similar. Note that temporal resolution is limited to a single sample block.

InterpretMode

An enumerated value selecting on-line classification of evoked responses:

• 0: no target is announced "attended", and no classification is performed;
• 1: online or free mode: classification is performed, but no "attended target" is defined;
• 2: copy mode: "attended" targets are defined, classification is performed.

DisplayResults

Switches result display of copy/free spelling on or off. In the P3Speller, setting DisplayResults to 'off' will disable execution of all speller commands (such as switching matrices) as well.

MinimumEvidence

NOTE: If you are using your own classifier, this feature will not work properly unless your classifier's output matches certain criteria. Make sure to read these notes on how to use a different classifier.

By default, target selection is performed without considering the actual amount of evidence that favors the selected target over other targets. Although the selected target will always be a target with maximum classification score (i.e., evidence), other targets may have the same or a similar score. It may be useful to omit classification in such situations altogether, by specifying a minimum amount of evidence that must exist in favor of the selected target, when compared to the next-best target. When used together with the AccumulateEvidence option, this allows to dynamically control the number of stimulus presentations, by simply repeating stimulus sequences until a sufficient amount of evidence has been collected.

Setting MinimumEvidence to 0 or to a negative number will result in default behavior, i.e. there will be a target selection each time classification scores are received from the SignalProcessing module. For values greater 0, the amount of selection errors will become smaller as the value of MinimumEvidence is increased; this increases the amount of information contained in each selection. At the same time, it becomes more and more unlikely that a selection will occur at all within a certain amount of time; this decreases the amount of information transmitted per time (information flow, or bitrate). In between, a certain value will correspond to an optimal compromise between selection errors, and selection duration. At this point, the flow of information is maximized.

The meaning of the actual number entered into the MinimumEvidence parameter is relative to the amount of within-class variance present in the classification score. An evidence of 0 means a 50:50 chance for correct classification. Increasing the evidence value by two standard deviations corresponds to an improvement by a factor of roughly 88:12, four standard deviations correspond to (88:12)^2=(98:2) ... etc, approaching perfect classification as evidence increases towards infinity.

In classifier training, classifier weights may be normalized such that within-class variance is 1 (this is done by BCI2000Analysis, and recent versions of the P300Classifier tool). In this case, you may use the following equations to convert between the MinimumEvidence parameter $\eta$, and the correct classification chance $\chi$:

$\chi =\frac{50}{50}{\left(\frac{88}{12}\right)}^{\eta /2}$.

For large $\chi$, this relationship may be approximated and expressed in terms of error probability $p$:

$\eta \approx -\frac{{\log }_{10}p}{{\log }_{10}e}=-2.3{\log }_{10}p\text{<mrow data-mjx-texclass="ORD">for</mrow>}p\le 5\mathrm{\%}$.

Thus, the evidence value roughly corresponds to twice the number of leading zeros in the desired error probability, if classifier weights are normalized. Some values are provided in the following table:

Selection Error	Evidence
5%	3
1%	4.6
0.5%	5.3
0.1%	6.9
0.05%	7.6
0.01%	9.2

AccumulateEvidence

By default, only those classification scores are used which have been received from the signal processing module immediately prior to classification. When AccumulateEvidence is set, classification scores are accumulated until a selection is actually performed. Typically, accumulated classification scores will have higher evidence values, such that a selection threshold set with MinimumEvidence will be eventually crossed after scores have been accumulated for some time.

This allows for dynamically choosing the number of stimulus repetitions in a P300 paradigm, by setting the number of stimulus repetitions to 1, and setting the MinimumEvidence parameter to a value greater zero.

In addition, accumulated overall evidence will not increase if there is no consistent evidence in favor of a certain target. Thus, it is possible to operate a P300 BCI in a quasi-asynchronous mode by using AccumulateEvidence, and choosing a MinimumEvidence value that is large enough to make accidental selection unlikely. In this configuration, no selection will be made unless the BCI user is actually concentrating on a target for a number of stimulus presentations, resulting in consistently accumulating evidence for that target.

NOTE: If you are using your own classifier, this feature will not work properly unless your classifier's output matches certain criteria. Make sure to read these notes on how to use a different classifier.

PhotoDiodePatch

Display a photo diode patch on the stimulus window. Recording from a photo diode located on that patch will allow triggering on actual stimulus delivery (see User_Reference:P3TemporalFilter#OnsetExpression).

PhotoDiodePatchHeight

Photo diode patch height in relative coordinates (between 0 and 1).

PhotoDiodePatchWidth

Photo diode patch width in relative coordinates (between 0 and 1).

PhotoDiodePatchLeft

Photo diode patch left position in relative coordinates (between 0 and 1).

PhotoDiodePatchTop

Photo diode patch top position in relative coordinates (between 0 and 1).

PhotoDiodePatchShape

Photo diode patch shape: 0 rectangle, 1 ellipse.

PhotoDiodePatchActiveColor

Photo diode patch color when active (RGB color in format 0xrrggbb).

PhotoDiodePatchInactiveColor

Photo diode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

PhotoDiodePatchExpression

Photo diode patch expression, determines active state by evaluating to nonnull. Defaults to StimulusBegin>0.

  "Application:Sequencing int NumberOfSequences= 15 15 1 % // "
     "number of sequences in a set of intensifications",

  "Application:Speller%20Targets matrix TargetDefinitions= "
     "36 "
     "{Display Enter Display%20Size Icon%20File Sound%20File} "
     "A A 1 % % "  "B B 1 % % "  "C C 1 % % "  "D D 1 % % "  "E E 1 % % "  "F F 1 % % "
     "G G 1 % % "  "H H 1 % % "  "I I 1 % % "  "J J 1 % % "  "K K 1 % % "  "L L 1 % % "
     "M M 1 % % "  "N N 1 % % "  "O O 1 % % "  "P P 1 % % "  "Q Q 1 % % "  "R R 1 % % "
     "S S 1 % % "  "T T 1 % % "  "U U 1 % % "  "V V 1 % % "  "W W 1 % % "  "X X 1 % % "
     "Y Y 1 % % "  "Z Z 1 % % "  "1 1 1 % % "  "2 2 1 % % "  "3 3 1 % % "  "4 4 1 % % "
     "5 5 1 % % "  "6 6 1 % % "  "7 7 1 % % "  "8 8 1 % % "  "9 9 1 % % "  "_ %20 1 % % "
     "% % % // speller target properties",
  "Application:Speller%20Targets intlist NumMatrixColumns= 1 "
     "6 6 1 % // display matrices' column number(s)",
  "Application:Speller%20Targets intlist NumMatrixRows= 1 "
     "6 6 0 % // display matrices' row number(s)",

  "Application:Audio%20Stimuli int AudioStimuliOn= 0 "
     "0 0 1 // Audio Stimuli Mode (0=no, 1=yes) (boolean)",
  "Application:Audio%20Stimuli matrix AudioStimuliRowsFiles= "
     "{ 1 2 3 4 5 6 } " // row labels
     "{ filename } " // filename
     "./voice/1.wav "
     "./voice/2.wav "
     "./voice/3.wav "
     "./voice/4.wav "
     "./voice/5.wav "
     "./voice/6.wav "
     " // audio stimuli rows files ",
  "Application:Audio%20Stimuli matrix AudioStimuliColsFiles= "
     "{ 1 2 3 4 5 6 } " // column labels
     "{ filename } " // filename
     "./voice/a.wav "
     "./voice/b.wav "
     "./voice/c.wav "
     "./voice/d.wav "
     "./voice/e.wav "
     "./voice/f.wav "
     " // audio stimuli column files ",

  "Application:Speller%20Targets floatlist TargetWidth= 1 5 0 0 100 // "
     "target width in percent of screen width",
  "Application:Speller%20Targets floatlist TargetHeight= 1 5 0 0 100 // "
     "target height in percent of screen height",
  "Application:Speller%20Targets floatlist TargetTextHeight= 1 10 0 0 100 // "
     "height of target labels in percent of screen height",
  "Application:Speller%20Targets stringlist BackgroundColor= 1 0x000000 "
     "0x505050 % % // target background color (color)",
  "Application:Speller%20Targets stringlist TextColor= 1 0x000000 "
     "0x505050 % % // text color (color)",
  "Application:Speller%20Targets stringlist TextColorIntensified= 1 0x0000FF "
     "0x505050 % % // intensified text color (color)",
  "Application:Speller%20Targets intlist IconHighlightMode= 1 1 "
     "1 0 2 // icon highlight method "
       "0: Show/Hide, "
       "1: Intensify, "
       "2: Grayscale, "
       "3: Invert, "
       "4: Dim "
       "   (enumeration)",
  "Application:Speller%20Targets floatlist IconHighlightFactor= 1 0.5 "
     "0.5 0 % // scale factor for highlighted icon pixel values",

  "Application:Speller int FirstActiveMenu= 1 "
     "1 1 % // Index of first active menu",
  "Application:Speller float StatusBarSize= 10 0 0 100 // "
     "size of status bar in percent of screen height",
  "Application:Speller float StatusBarTextHeight= 8 0 0 100 // "
     "size of status bar text in percent of screen height",
  "Application:Speller string TextToSpell= % % % % // "
   " character or string to spell in offline copy mode",
  "Application:Speller string TextResult= % % % % // "
     "user spelling result",
  "Application:Speller int TestMode= 0 0 0 1 // "
     "select targets by clicking on their associated stimuli (0=no, 1=yes) (boolean)",
  "Application:Speller string DestinationAddress= % % % % // "
     "network address for speller output in IP:port format",

  "Application:Text%20Window int TextWindowEnabled= 0 "
     "0 0 1 // Show Text Window (0=no, 1=yes) (boolean)",
  "Application:Text%20Window int TextWindowLeft= 640 0 0 % // "
     "Text Window X location",
  "Application:Text%20Window int TextWindowTop= 0 0 0 % // "
     "Text Window Y location",
  "Application:Text%20Window int TextWindowWidth= 512 512 0 % // "
     "Text Window Width",
  "Application:Text%20Window int TextWindowHeight= 512 512 0 % // "
     "Text Window Height",
  "Application:Text%20Window string TextWindowFontName= Courier % % % // "
     "Text Window Font Name",
  "Application:Text%20Window int TextWindowFontSize= 10 4 1 % // "
     "Text Window Font Size",
  "Application:Text%20Window string TextWindowFilePath= % % % % // "
     "Path for Saved Text File (directory)",

States

PreStimulusTime

A 16-bit time stamp in the same format as the SourceTime state. This time stamp is set immediately before the application module is going to update the stimulus/feedback display. Note that a data block is saved together with the state vector that existed immediately after it was acquired. Thus, PreStimulusTime will be the prestimulus time of the block prior to the current block.

StimulusTime

A 16-bit time stamp in the same format as the SourceTime state. This time stamp is set immediately after the application module has updated the stimulus/feedback display. Note that a data block is saved together with the state vector that existed immediately after it was acquired. Thus, StimulusTime will be the stimulus time of the block prior to the current block.

PresentationRequested

This 32-bit state contains a list of ids for all presentations that have been requested during the current block. The list ends with a value of 2^31. A 32-bit presentation id is formed by combining the 16-bit SourceTime state of the presentation request's data block in the most significant bits, with the time difference between that source time stamp and the time when the presentation request happened, in the least significant bits:

PresentationID = SourceTime << 8 | (RequestTime - SourceTime) & 0xff

This definition makes presentation ids unique within the range of a minute, and allows to extract the value of the request's time stamp from its id.

PresentationDisplayed

This 32-bit state contains a list of ids for all presentations that have been displayed during the current block. The list ends with a value of 2^31. Presentation ids appear in the PresentationRequested state when presentation is requested, and subsequently in the PresentationDisplayed state when presentation has occurred.

PresentationTime

A 16-bit time stamp in the same format as the SourceTime state. For each id occurring in the PresentationDisplayed state, this state contains the time stamp of the respective update to video memory. From this point in time, up to two additional frame durations may be required before the display's surface actually shows a difference in signal. This depends on the internals of the display, and cannot be determined from software.

PresentationFrame

A 12-bit state that contains, for each id occurring in the PresentationDisplayed state, the frame number of the respective update to video memory. Frame numbers have an arbitrary offset, and wrap around at a value of 2^11.

AudioBufferTime

A 16-bit time stamp in the same format as the SourceTime state. For each audio presentation that has occurred during the current block, this state contains the time stamp when non-zero audio data were about to enter the system's audio buffer.

AudioPresentationTime

A 16-bit time stamp in the same format as the SourceTime state. For each audio presentation that has occurred during the current block, this state contains the estimated time stamp when non-zero audio data were being played from the system's speakers or headphones. The estimate takes the length of the system's audio buffers into account but will not be able to detect external sources of delays, such as additional audio processing steps.

StimulusCode

The numerical ID of the stimulus being presented (16 bit).

StimulusType

This state is 1 during presentation of an attended stimulus, and 0 otherwise. The notion of an "attended" stimulus requires data recording in copy mode.

StimulusBegin

This state is 1 during the first block of stimulus presentation, and 0 otherwise.

PhaseInSequence

This state is 1 during pre-sequence, 2 during sequence and 3 during post-sequence (see Timeline).

PauseApplication

While this state is set to 1, no task processing occurs, i.e. the task is paused, and may be resumed by setting PauseApplication to 0.

  "SelectedTarget 7 0 0 0",
  "SelectedRow    3 0 0 0",
  "SelectedColumn 3 0 0 0",

See also

User Reference:StimulusPresentationTask