FEP VisuomotorJoystickTask: Difference between revisions
No edit summary |
No edit summary |
||
| (7 intermediate revisions by the same user not shown) | |||
| Line 3: | Line 3: | ||
'''FEP_VisuomotorJoystickTask''' is a BCI2000 application module implementing a center-out visuomotor reaching task designed to investigate how participants adapt their behavior when the relationship between their actions and sensory consequences changes unexpectedly. | '''FEP_VisuomotorJoystickTask''' is a BCI2000 application module implementing a center-out visuomotor reaching task designed to investigate how participants adapt their behavior when the relationship between their actions and sensory consequences changes unexpectedly. | ||
Participants control a cursor using a USB HID joystick and repeatedly move from a central starting location to peripheral targets. The joystick-to-cursor mapping is treated as | Participants control a cursor using a USB HID joystick and repeatedly move from a central starting location to peripheral targets. The joystick-to-cursor mapping is treated as an environmental state: on a given trial, joystick movement may produce either a normal cursor movement or an inverted cursor movement. In the default legacy design the mapping is hidden. An optional predictive-cue design can instead present a probabilistic green or red mapping cue during center hold, and an independently configurable information-seeking feature can let the participant reveal the actual current-trial mapping. | ||
The task was developed in the context of the '''Free Energy Principle (FEP)''' and related theories of predictive processing and active inference. In this framework, an agent maintains an internal model of the causes of its sensory observations and uses incoming evidence to update that model. When observations conflict with the agent's expectations, the agent may need to revise its estimate of the current hidden state. | The task was developed in the context of the '''Free Energy Principle (FEP)''' and related theories of predictive processing and active inference. In this framework, an agent maintains an internal model of the causes of its sensory observations and uses incoming evidence to update that model. When observations conflict with the agent's expectations, the agent may need to revise its estimate of the current hidden state. | ||
The present task operationalizes this problem using a simple visuomotor environment. | The present task operationalizes this problem using a simple visuomotor environment. In the legacy design, the hidden state is the current joystick-to-cursor mapping. Participants first accumulate experience with particular mappings and mapping frequencies, creating different histories of prior exposure. The mapping can then change without warning, requiring the participant to infer from the resulting cursor behavior that the current sensorimotor relationship has changed. In the optional predictive-cue design, the mapping remains uncertain rather than wholly hidden: a configurable-validity cue predicts Normal or Reversed control but may be invalid. | ||
The task therefore allows behavioral measurements to be related to three major features of inference: | The task therefore allows behavioral measurements to be related to three major features of inference: | ||
| Line 14: | Line 14: | ||
* '''Unexpected state changes''': Mapping changes may occur between trials without an explicit visual cue. | * '''Unexpected state changes''': Mapping changes may occur between trials without an explicit visual cue. | ||
* '''Behavioral updating''': Reaction time, movement time, total time, and cursor trajectory may be examined following mapping switches and across subsequent trials. | * '''Behavioral updating''': Reaction time, movement time, total time, and cursor trajectory may be examined following mapping switches and across subsequent trials. | ||
* '''Predictive evidence''': When enabled, trial-wise color cues provide configurable, sometimes-invalid evidence about the upcoming mapping. | |||
* '''Voluntary information seeking''': When enabled, participants may reveal the actual current-trial mapping during center hold, optionally at a point cost. | |||
The experiment also includes a | The experiment also includes a configurable visual sensory-reliability manipulation. On selected trials, Gaussian spatial noise perturbs the displayed cursor without changing the task-logic cursor position. High reliability has no visual noise; Medium and Low reliability use configurable noise amplitudes. This is a visual-feedback noise manipulation, not a cursor-gain manipulation. | ||
Importantly, the software does not itself compute free energy, prediction error, posterior probability, Bayesian belief, or another formal FEP quantity. Instead, it creates a controlled hidden-state visuomotor task whose behavioral and neural data may be used to investigate questions motivated by those theories. | Importantly, the software does not itself compute free energy, prediction error, posterior probability, Bayesian belief, or another formal FEP quantity. Instead, it creates a controlled hidden-state visuomotor task whose behavioral and neural data may be used to investigate questions motivated by those theories. | ||
| Line 24: | Line 26: | ||
* Unannounced mapping changes between trials. | * Unannounced mapping changes between trials. | ||
* Six sequential experimental block roles with different mapping frequencies. | * Six sequential experimental block roles with different mapping frequencies. | ||
* | * High, Medium, and Low visual sensory-reliability conditions with configurable Gaussian cursor noise (disabled by default). | ||
* An optional six-block predictive-cue design with configurable mapping probabilities, cue accuracy, color assignment, sequence seed, and biased-block counterbalancing. | |||
* Predictive-cue instruction animations and guided Normal/Reversed practice when the predictive design is enabled. | |||
* An optional points system with configurable initial-direction, trajectory-deviation, and information-cost deductions. | |||
* Optional voluntary purchase of current-trial mapping information during center hold. | |||
* Mapping-switch, prior-condition, and trials-since-switch state logging. | * Mapping-switch, prior-condition, and trials-since-switch state logging. | ||
* A | * A two-page legacy participant introduction, or predictive-cue instruction animations when those animations are enabled. | ||
* A Normal-mapping | * A Normal-mapping free-movement sandbox in legacy operation, or optional guided alternating Normal/Reversed practice in predictive-cue operation. | ||
* Reaction-time, movement-time, total-time, cursor, joystick, target, mapping, and | * Reaction-time, movement-time, total-time, displayed and true cursor, joystick (when logging is enabled), target, mapping, predictive cue, reliability, noise, information-purchase, point-performance, and researcher-control states in the BCI2000 data stream. | ||
* Experimenter controls for resetting, skipping, pausing, and resuming the task. | |||
The participant is not | Mapping switches are not announced as switch events. In legacy operation the mapping remains hidden unless current-trial information is purchased. In predictive-cue operation a color predicts the mapping but does not guarantee it, and a persistent on-screen key explains the color assignment. The participant is not shown block identity, block transitions, numerical mapping probabilities, cue-validity labels, or sensory-reliability labels. Visual noise may nevertheless be perceptible. | ||
==Location== | ==Location== | ||
Upon completion of an SVN update or checkout of the relevant source tree, the current FEP Visuomotor Joystick Task is located in: | |||
<pre> | <pre> | ||
| Line 50: | Line 57: | ||
* <code>FEP_VisuomotorJoystickTask.h</code> | * <code>FEP_VisuomotorJoystickTask.h</code> | ||
* <code>CMakeLists.txt</code> | * <code>CMakeLists.txt</code> | ||
Optional-feature example parameter overlays are provided as: | |||
* <code>PredictiveCuesExample.prm</code> | |||
* <code>RewardInformationExample.prm</code> | |||
The application is included from: | The application is included from: | ||
| Line 57: | Line 69: | ||
</pre> | </pre> | ||
The CMake target is: | The current CMake target is: | ||
<pre> | <pre> | ||
FEP_VisuomotorJoystickTask_custom | |||
</pre> | </pre> | ||
The Windows executable is: | The module uses <code>NOBUNDLE</code> in its <code>bci2000_add_application_module</code> declaration. Its Windows executable is typically named: | ||
<pre> | <pre> | ||
FEP_VisuomotorJoystickTask_custom.exe | |||
</pre> | </pre> | ||
A separate <code>src/custom/FEP_VisuomotorJoystickTask_pacing_test/</code> diagnostic module is also included in the custom build. That module is for investigating a rendering/pacing issue and is not the experimental task. | |||
==Versioning== | ==Versioning== | ||
| Line 83: | Line 97: | ||
Contact: speer@wustl.edu | Contact: speer@wustl.edu | ||
===Version | ===Revision History=== | ||
====New version: 17 November 2026 — source revision <code>7b90a64</code>==== | |||
This revision adds the optional predictive-cue six-block design. Green/red center cues predict Normal or Reversed control with configurable conditional accuracy; the actual mapping, cue prediction, validity, block Normal probability, cue visibility/onset, and effective cue seed are recorded. Predictive operation adds dedicated trial-count and mapping-probability parameters, optional counterbalancing of the two biased block configurations, animated cue instructions, guided alternating Normal/Reversed practice, a persistent cue key, and predictive fields in the researcher diagnostics. The same revision includes the independently configurable points and information-seeking systems introduced after the prior documentation: current-trial mapping may be revealed during center hold, completed trials may be scored from initial-direction, trajectory, and information-cost deductions, and trial/cumulative points and supporting measurements are recorded. Predictive cues, points, information seeking, and sensory-reliability noise are each disabled by default. | |||
The current documented source revision is Git commit <code>7b90a64</code>. This commit identifier is the implementation revision number; the module still does not declare an independent semantic or numeric application version. | |||
====Version: 5 November 2026 — points and information seeking==== | |||
This implementation revision added independently configurable point-reward and voluntary information-seeking systems, a second participant introduction page, fixed-point point/performance states, and optional trial and cumulative point feedback. It removed the center-hold purchase prompt; the introduction explains purchasing instead. These systems are disabled by default. | |||
The inspected build was produced using: | ====New version: 19 October 2026==== | ||
This updated version replaces the earlier Normal/High cursor-gain manipulation with configurable High/Medium/Low visual sensory reliability; introduces temporally correlated Gaussian cursor noise and separate true-versus-displayed cursor states; adds researcher controls for skipping trials, blocks, introduction, and sandbox and for pausing/resuming; adds associated BCI2000 event and reliability states; provides configurable cursor and target diameters; and redesigns the diagnostic window to show real-time timings and run averages. The experimental mapping and six block roles remain in place. The current build uses the <code>FEP_VisuomotorJoystickTask_custom</code> target. | |||
No independent semantic version identifier is declared in the module. The current FEP task is maintained under <code>src/custom</code> and is tracked by the surrounding Git repository. | |||
An earlier inspected BCI2000 build was produced using: | |||
* BCI2000 framework 3.6.9535 | * BCI2000 framework 3.6.9535 | ||
| Line 94: | Line 122: | ||
* Release x64 configuration | * Release x64 configuration | ||
These values refer to | These values refer to an inspected BCI2000 build containing the module, not to an independently verified revision number of the current FEP task. | ||
==Scientific Motivation== | ==Scientific Motivation== | ||
| Line 110: | Line 138: | ||
* Target position. | * Target position. | ||
* The sensory consequences of each movement. | * The sensory consequences of each movement. | ||
* A green/red mapping prediction during center hold when predictive cues are enabled. | |||
* The actual mapping text after an optional information purchase, when information seeking is enabled and used. | |||
The participant is not directly told: | The participant is not directly told: | ||
* Which joystick-to-cursor mapping is currently active. | * Which joystick-to-cursor mapping is currently active in uncued legacy trials; predictive cues provide uncertain evidence rather than certainty. | ||
* Whether the mapping has changed. | * Whether the mapping has changed. | ||
* The probability of a mapping occurring. | * The numerical probability of a mapping occurring. | ||
* The current experimental block. | * The current experimental block. | ||
* Whether | * Whether visual sensory reliability has changed. | ||
In legacy operation the current mapping therefore acts as a hidden environmental state that must be inferred from the relationship between action and observed cursor movement. Predictive cues and purchased mapping information are optional experimental sources of evidence about that state. | |||
For example, after many Normal trials, a participant may expect the cursor to move in the same direction as the joystick. If the next trial unexpectedly uses the Inverted mapping, the observed cursor movement conflicts with that expectation. Subsequent behavior can then be examined to determine how rapidly the participant adjusts to the new mapping. | For example, after many Normal trials, a participant may expect the cursor to move in the same direction as the joystick. If the next trial unexpectedly uses the Inverted mapping, the observed cursor movement conflicts with that expectation. Subsequent behavior can then be examined to determine how rapidly the participant adjusts to the new mapping. | ||
| Line 141: | Line 171: | ||
* Across successive trials following a switch. | * Across successive trials following a switch. | ||
* Under different histories of Normal and Inverted mapping exposure. | * Under different histories of Normal and Inverted mapping exposure. | ||
* Under | * Under High, Medium, and Low visual sensory reliability (when enabled). | ||
* Following valid versus invalid predictive cues and under different block mapping probabilities (when predictive cues are enabled). | |||
* With versus without voluntary mapping-information purchase (when information seeking is enabled). | |||
The task can therefore be used to investigate how prior experience influences behavioral adaptation to unexpected changes in sensorimotor contingencies. | The task can therefore be used to investigate how prior experience influences behavioral adaptation to unexpected changes in sensorimotor contingencies. | ||
| Line 160: | Line 192: | ||
These quantities, if used, must be estimated during offline behavioral or neural analysis. | These quantities, if used, must be estimated during offline behavioral or neural analysis. | ||
===Predictive Cues=== | |||
The optional predictive-cue design changes the task from a completely uncued hidden-state problem into inference from probabilistic evidence. During center hold, the center marker becomes green or red. The color predicts Normal or Reversed control according to <code>CueColorAssignment</code>, but the prediction is valid only at the configured <code>CueAccuracyPercent</code>. Validity is allocated separately within actual Normal and actual Inverted trials, so cue accuracy is conditional on mapping rather than merely an overall proportion. | |||
The participant sees a persistent key identifying the green and red meanings during the experiment, but is not shown whether a particular cue is valid, the numerical cue accuracy, or the block's numerical Normal probability. This permits comparison of behavior following valid and invalid evidence and across balanced, Normal-biased, and Inverted-biased mapping contexts. | |||
===Information Seeking and Point Tradeoff=== | |||
The independently optional information-seeking system allows participants to reveal the actual current-trial mapping during center hold. When the points system is also enabled, this information has a configurable point cost. A participant may preserve the full potential trial value and act using prior experience, predictive evidence, and cursor feedback, or spend points to display <code>NORMAL</code> or <code>REVERSED</code> before target onset. | |||
The application records purchase behavior and point performance, but it does not compute information value, expected utility, risk preference, epistemic value, or an active-inference policy. Those quantities require offline analysis. | |||
==Functional Description== | ==Functional Description== | ||
| Line 181: | Line 225: | ||
|} | |} | ||
In the legacy design the current mapping is not automatically indicated. Predictive operation provides a possibly invalid mapping prediction during center hold. A successful information purchase displays the actual mapping. Neither feature changes the mapping transformation itself. | |||
Unlike the earlier USBHIDJoystickTask, the FEP task does not use the terms '''Automatic''' and '''Controlled''' in its implementation. | Unlike the earlier USBHIDJoystickTask, the FEP task does not use the terms '''Automatic''' and '''Controlled''' in its implementation. | ||
| Line 198: | Line 242: | ||
* Performance as a function of trials since the previous switch. | * Performance as a function of trials since the previous switch. | ||
* Effects of different mapping-frequency contexts. | * Effects of different mapping-frequency contexts. | ||
* Effects of | * Effects of High, Medium, and Low visual sensory reliability when the manipulation is enabled. | ||
* Differences between true and displayed cursor trajectories under visual noise. | |||
==Experiment Structure== | ==Experiment Structure== | ||
| Line 204: | Line 249: | ||
Each run proceeds in the following order: | Each run proceeds in the following order: | ||
# | # Participant introduction (unless skipped by the researcher): two text pages in legacy operation, or two animated cue pages and a timed practice-transition page when predictive cues and introduction animation are enabled. | ||
# Joystick sandbox. | # Joystick sandbox: free movement in legacy operation, or guided cue practice when predictive cues and guided sandbox are enabled. | ||
# Experimental block 1, if enabled. | # Experimental block 1, if enabled. | ||
# Experimental block 2, if enabled. | # Experimental block 2, if enabled. | ||
| Line 214: | Line 259: | ||
# Experiment completion. | # Experiment completion. | ||
Experimental block transitions are not announced to the participant. | Experimental block transitions are not announced to the participant. Skipping the introduction using the researcher window enters the experiment directly and also bypasses the sandbox. Trial and block skipping can change which trials are actually performed. The active trial-count family is selected by <code>EnablePredictiveCues</code>; the inactive family does not contribute trials. | ||
Each experimental trial proceeds as follows: | Each experimental trial proceeds as follows: | ||
| Line 220: | Line 265: | ||
# The participant returns the cursor to the center. | # The participant returns the cursor to the center. | ||
# The participant holds the cursor within the center region. | # The participant holds the cursor within the center region. | ||
# In predictive-cue operation, the center is colored during the hold to predict the mapping. | |||
# During the hold, the participant may optionally purchase the actual mapping when information seeking is enabled. | |||
# A yellow warning cue appears. | # A yellow warning cue appears. | ||
# A pre-target delay occurs. | # A pre-target delay occurs. | ||
| Line 225: | Line 272: | ||
# The participant moves the cursor toward the target. | # The participant moves the cursor toward the target. | ||
# The target is acquired. | # The target is acquired. | ||
# A | # Point-performance values are finalized when the points system is enabled. | ||
# A feedback interval occurs; optional point feedback is displayed. | |||
# The task advances to the next trial. | # The task advances to the next trial. | ||
==Introduction== | ==Introduction== | ||
The introduction | The introduction behavior depends on the predictive-cue settings. | ||
===Legacy Text Introduction=== | |||
< | When predictive cue animation is not active, page 1 is titled <code>HOW TO PLAY</code> and explains joystick control, returning to and holding in the gray center circle, and moving to the target. Page 2 is generated from the enabled optional features. It explains potential points and straight/accurate movement when rewards are enabled, explains green/red predictions when predictive cues are enabled without animation, and explains optional current-trial mapping purchase when information seeking is enabled. If none of those systems is enabled, it simply instructs the participant to complete each trial by moving to the target. | ||
Page 1 ends with <code>Press the joystick button to continue.</code>; page 2 ends with <code>Press the joystick button to practice.</code>. Separate rising button presses are required, so holding the button cannot advance through both pages. | |||
===Predictive Animated Introduction=== | |||
When <code>EnablePredictiveCues=1</code> and <code>EnableIntroductionAnimation=1</code>, two animated pages replace the legacy text pages. One page demonstrates the green cue and the other the red cue. Each identifies the mapping predicted by that color, animates cursor movement and—when configured—a joystick illustration, and requires a rising joystick-button press to advance. The examples alternate between diagonal and rightward targets when looping. After the two cue pages, a <code>Time to practice</code> screen advances automatically after <code>IntroductionPracticeScreenDurationMs</code>. | |||
During either introduction form: | |||
During | |||
* <code>Introduction=1</code> | * <code>Introduction=1</code> | ||
* <code>TutorialPhase=1</code> | * <code>TutorialPhase=1</code> | ||
* <code>TaskPhase=0</code> | * <code>TaskPhase=0</code> | ||
* The progress bar is hidden. | * The progress bar is hidden. | ||
A rising press of <code>JoystickButtons1</code> advances | The legacy text pages hide the cursor, center, warning, target, and cross. The animated pages instead draw the demonstration cursor, center cue, target, cross, and optional joystick illustration. | ||
A rising press of <code>JoystickButtons1</code> advances each eligible introduction page. The experimenter may instead select <code>SKIP INTRODUCTION</code> (with confirmation), which enters the experiment directly and bypasses the sandbox. There is no state that identifies the individual introduction page. | |||
The participant is not told about: | The participant is not told about: | ||
* | * The actual current-trial mapping. Predictive instruction pages do teach the cue-to-mapping meanings when enabled, and purchased information may reveal the actual mapping later. | ||
* Mapping switches. | * Mapping switches. | ||
* | * Changes in visual sensory reliability. | ||
* Experimental blocks. | * Experimental blocks. | ||
* Prior conditions. | * Prior conditions. | ||
| Line 271: | Line 311: | ||
==Sandbox== | ==Sandbox== | ||
After the introduction, the participant enters a free-movement sandbox. | After the introduction, the participant enters either a free-movement sandbox or guided predictive-cue practice. | ||
===Legacy Free-Movement Sandbox=== | |||
The participant sees: | The participant sees: | ||
| Line 299: | Line 341: | ||
* <code>TaskCondition=0</code> | * <code>TaskCondition=0</code> | ||
* Normal direct mapping is used. | * Normal direct mapping is used. | ||
* | * There is no gain manipulation; the sandbox uses direct Normal mapping without visual noise. | ||
* No targets are generated. | * No targets are generated. | ||
* No experimental timing phases occur. | * No experimental timing phases occur. | ||
| Line 308: | Line 350: | ||
# A new joystick-button press occurs. | # A new joystick-button press occurs. | ||
Because continuation uses rising-edge detection, the participant must release the button after leaving the introduction screen before pressing it again to leave the sandbox. | Because continuation uses rising-edge detection, the participant must release the button after leaving the introduction screen before pressing it again to leave the sandbox. The researcher can also select <code>SKIP SANDBOX</code> to enter the experiment. | ||
===Guided Predictive-Cue Sandbox=== | |||
When <code>EnablePredictiveCues=1</code> and <code>EnableGuidedSandbox=1</code>, the sandbox instead runs <code>GuidedSandboxTrials</code> practice trials (default 3) to a fixed rightward black target. Practice mappings alternate Normal, Reversed, Normal, and so forth. Each trial uses the normal center-hold, yellow warning, pre-target delay, target-visible, and feedback phases. During center hold, the center color predicts the practice mapping and on-screen text repeats the color meaning. Reversed practice uses the same anchored inversion and return-to-anchor behavior as the experiment. | |||
Guided practice is not an experimental block: <code>Introduction=1</code>, <code>TutorialPhase=2</code>, <code>TaskBlock=0</code>, <code>TaskTrial=0</code>, and cue states remain 0. <code>TaskPhase</code> does reflect phases 1 through 6 during guided practice. After all practice targets are acquired, the participant must return to center and press the joystick button to begin the experiment. <code>SKIP SANDBOX</code> bypasses the remaining practice. | |||
When the sandbox finishes: | When the sandbox finishes: | ||
| Line 319: | Line 367: | ||
==Experimental Blocks== | ==Experimental Blocks== | ||
The task contains six | The task contains two alternative six-block designs selected by <code>EnablePredictiveCues</code>. It is 0 by default, which preserves the legacy design and its random-number-generator behavior. | ||
===Legacy Six-Block Design=== | |||
There is no <code>ExperimentMode</code> parameter. | There is no <code>ExperimentMode</code> parameter. | ||
| Line 409: | Line 459: | ||
If no candidate satisfies the constraints after 64 attempts, the final generated sequence is used. | If no candidate satisfies the constraints after 64 attempts, the final generated sequence is used. | ||
After the mapping sequence is generated, sensory-reliability conditions are assigned separately using a dedicated random generator. Rather than an independent shuffle, the assignment algorithm attempts to counterbalance reliability categories across Normal/Inverted mappings and mapping-switch/non-switch trials while preserving the configured counts. Reliability assignment does not alter the mapping order. See [[#Sensory Reliability|Sensory Reliability]]. | |||
===Predictive-Cue Six-Block Design=== | |||
When <code>EnablePredictiveCues=1</code>, the six legacy trial-count parameters above are inactive and the following design is used: | |||
{| class="wikitable" | |||
! Block | |||
! Trial-count parameter | |||
! Default trials | |||
! Default Normal probability | |||
! Cue | |||
|- | |||
| 1 | |||
| <code>PredictiveBlock1Trials</code> | |||
| 20 | |||
| 100% | |||
| None | |||
|- | |||
| 2 | |||
| <code>PredictiveBlock2Trials</code> | |||
| 10 | |||
| 0% (100% Reversed) | |||
| None | |||
|- | |||
| 3 | |||
| <code>CuedBlock3Trials</code> | |||
| 40 | |||
| <code>CuedBlock3NormalProbabilityPercent</code> (50%) | |||
| Predictive | |||
|- | |||
| 4 | |||
| <code>CuedBlock4Trials</code> | |||
| 40 | |||
| <code>CuedBlock4NormalProbabilityPercent</code> (75%) | |||
| Predictive | |||
|- | |||
| 5 | |||
| <code>CuedBlock5Trials</code> | |||
| 40 | |||
| <code>CuedBlock5NormalProbabilityPercent</code> (25%) | |||
| Predictive | |||
|- | |||
| 6 | |||
| <code>CuedBlock6Trials</code> | |||
| 40 | |||
| <code>CuedBlock6NormalProbabilityPercent</code> (50%) | |||
| Predictive | |||
|} | |||
The Normal count in each cued block is <code>round(trials * NormalProbabilityPercent / 100)</code>; remaining trials are Reversed. For each actual mapping separately, the valid-cue count is <code>round(mappingCount * CueAccuracyPercent / 100)</code>. A valid cue predicts the actual mapping and an invalid cue predicts the opposite mapping. Rounding means small blocks may not realize the percentages exactly. | |||
The sequence generator uses a dedicated <code>std::mt19937</code> seeded by <code>CueRandomSeed</code>. It evaluates up to 512 shuffled candidates, penalizing long mapping runs, long predicted-cue runs, strict mapping alternation, and strict cue alternation. It stops early when both maximum run lengths are at most 3 and neither sequence strictly alternates; otherwise it uses the best scored candidate. This algorithm is separate from the legacy 64-attempt pseudorandomization. | |||
When <code>CounterbalanceBiasedBlockOrder=1</code>, the complete configured block-4 and block-5 definitions—their trial counts and Normal probabilities—are swapped before assignment to physical block roles 4 and 5. Blocks 3 and 6 are not swapped. Disabled predictive blocks retain no trials, and <code>TaskBlock</code> may therefore skip role numbers. | |||
===Predictive-Cue Display and Timing=== | |||
Blocks 1 and 2 have no predictive cue. In blocks 3 through 6, entering <code>HoldingCenter</code> changes the center marker to the cue color. The cue disappears when the task leaves center hold; the later yellow warning does not retain the cue color. A persistent upper-left key shows the configured green and red mapping meanings throughout the experimental stage, including uncued blocks 1 and 2. | |||
<code>CueOnsetTimeMs</code> is measured from trial start to the first entry into center hold. If center hold is broken and restarted, the onset time is not replaced. Manual trial reset clears it, while pause compensation shifts its internal timestamp. Cue display does not alter the center-hold duration or mapping. | |||
==Prior Conditions== | ==Prior Conditions== | ||
| Line 420: | Line 530: | ||
! Value | ! Value | ||
! Name | ! Name | ||
! | ! Legacy-design meaning | ||
|- | |- | ||
| 0 | | 0 | ||
| Line 440: | Line 550: | ||
The mapping used on the preceding trial may be determined offline from the previous trial's <code>TaskCondition</code>. | The mapping used on the preceding trial may be determined offline from the previous trial's <code>TaskCondition</code>. | ||
In predictive-cue operation, fixed blocks 1 and 2 use <code>PriorCondition=0</code>. Cued blocks are classified from their configured Normal percentage: exactly 50% gives <code>Balanced</code> (3), greater than 50% gives <code>StrongNormal</code> (2), and less than 50% gives <code>HiddenMixed</code> (1). Thus the legacy names are retained even for an Inverted-biased predictive block; use <code>BlockNormalProbability</code> for the explicit percentage. | |||
==Joystick Input== | ==Joystick Input== | ||
| Line 450: | Line 562: | ||
* <code>JoystickYpos</code> | * <code>JoystickYpos</code> | ||
* <code>JoystickButtons1</code> | * <code>JoystickButtons1</code> | ||
<code>JoystickButtons1</code> advances the introduction and exits the completed sandbox. Information purchasing uses the one-based state selected by <code>InformationPurchaseButton</code>, forming a name such as <code>JoystickButtons2</code>. It may be the same as <code>JoystickButtons1</code>. The selected state must exist during preflight. | |||
Joystick X and Y values normally range from 0 through 32767. | Joystick X and Y values normally range from 0 through 32767. | ||
| Line 480: | Line 594: | ||
</pre> | </pre> | ||
The mapping transformation used for target-directed movement is activated at target onset. | The mapping transformation used for target-directed movement is activated at target onset. The code defines no <code>HighCursorGain</code> parameter, no <code>CursorGainCondition</code> state, and no high-gain movement condition in this version. | ||
===Anchor Capture=== | ===Anchor Capture=== | ||
| Line 490: | Line 604: | ||
* Current cursor X position. | * Current cursor X position. | ||
* Current cursor Y position. | * Current cursor Y position. | ||
* Current mapping direction | * Current mapping direction (<code>+1</code> for Normal or <code>-1</code> for Inverted). | ||
These values form the anchor for transformed movement. | These values form the anchor for transformed movement. Because joystick displacement relative to the anchor is initially zero, activating the transformed mapping does not cause an immediate cursor jump. | ||
===Normal Mapping=== | |||
With Normal mapping, the cursor follows the joystick directly: | |||
<pre> | <pre> | ||
| Line 506: | Line 617: | ||
</pre> | </pre> | ||
===Inverted Mapping | ===Inverted Mapping=== | ||
After target onset on an Inverted trial: | |||
<pre> | <pre> | ||
| Line 515: | Line 626: | ||
</pre> | </pre> | ||
Both axes are inverted. | Both axes are inverted. Cursor coordinates are constrained to the normalized range <code>[0, 1]</code>. While returning from a preceding anchored Inverted trial, that preceding transformation may remain active until the joystick returns to its stored anchor. | ||
The cursor position resulting from mapping and clipping, but before sensory noise, is called the <b>true cursor</b>. Sensory noise perturbs only the <b>displayed cursor</b>. | |||
For a Normal | ==Sensory Reliability== | ||
The current implementation manipulates visual sensory reliability using trial-wise Gaussian spatial noise added to the displayed cursor. This replaces the cursor-gain manipulation described in earlier versions. Sensory reliability is disabled by default (<code>EnableSensoryReliability=0</code>). | |||
===Reliability Conditions=== | |||
{| class="wikitable" | |||
! <code>SensoryReliabilityCondition</code> | |||
! Condition | |||
! Visual-noise standard deviation | |||
! Description | |||
|- | |||
| 0 | |||
| High | |||
| 0 pixels | |||
| Noise-free visual cursor | |||
|- | |||
| 1 | |||
| Medium | |||
| <code>MediumReliabilityNoiseStd</code> (default 5 pixels) | |||
| Gaussian cursor-position noise | |||
|- | |||
| 2 | |||
| Low | |||
| <code>LowReliabilityNoiseStd</code> (default 15 pixels) | |||
| Larger Gaussian cursor-position noise | |||
|} | |||
The noise standard deviations are specified in reference-display pixels, normalized using the task's nominal 1000 by 750 coordinate system. Noise affects only the cursor during the <code>TargetVisible</code> phase; the target, center marker, warning marker, cross, and joystick input are not perturbed. | |||
===Enabling Reliability by Block=== | |||
When <code>EnableSensoryReliability=0</code>, all trials use High reliability and no visual noise is applied, regardless of the requested proportions or block list. Therefore, <code>SensoryReliabilityCondition=0</code> does not by itself establish that reliability manipulation was enabled. | |||
When enabled, reliability conditions are assigned only within the numbered blocks listed in <code>SensoryReliabilityBlocks</code>, which defaults to blocks 4, 5, and 6. Blocks not listed always use High reliability. The block list may instead select any subset of the six block roles. A block disabled by setting its trial count to zero has no trials to assign. | |||
===Reliability Assignment and Counterbalancing=== | |||
For each enabled block, counts for High, Medium, and Low trials are calculated from the configured proportions by taking their floors and distributing remaining trials according to the largest fractional remainders. The result matches the block's total trial count. | |||
The application then uses a dedicated <code>std::mt19937</code> generator to assign those conditions in a randomized trial order. The selection score favors counterbalancing reliability across (1) Normal versus Inverted mapping and (2) mapping-switch versus non-switch trials, subject to the remaining required condition counts. Thus reliability assignment is not a wholly independent shuffle of the mapping sequence. Exact balance in small blocks or uneven sequences is not guaranteed. | |||
Reliability is assigned after the Normal/Inverted mapping sequence has been built and does not change that sequence. Only mapping changes, not reliability changes, generate <code>MappingSwitch</code> events. The dedicated noise/assignment seed is distinct from BCI2000's mapping/target random-number generator. | |||
The configured proportions default to 0.34 High, 0.33 Medium, and 0.33 Low, and their sum must equal 1 within <code>1e-6</code>. Low-reliability noise SD must be at least Medium-reliability noise SD. | |||
===Temporally Correlated Visual Noise=== | |||
X and Y noise are generated from independent Gaussian innovations and evolved over processing updates as: | |||
<pre> | <pre> | ||
a = exp(-elapsedSeconds / correlationTimeSeconds) | |||
noiseX = a * previousNoiseX + SD * sqrt(1 - a*a) * N_X(0,1) | |||
noiseY = a * previousNoiseY + SD * sqrt(1 - a*a) * N_Y(0,1) | |||
</pre> | |||
The temporal correlation time is set by <code>SensoryNoiseCorrelationTimeMs</code> (default 100 ms); a value of zero produces independent innovations on each update. Each trial's noise generator is initialized from the effective seed and trial/block identity. Noise begins at zero at target onset, so the process builds up rather than beginning with stationary variance. Noise is cleared when the task leaves the target-visible phase and on trial reset or skip. | |||
The displayed cursor is calculated as: | |||
<pre> | |||
displayedX = clamp(trueX + noiseX / 1000, 0, 1) | |||
displayedY = clamp(trueY + noiseY / 750, 0, 1) | |||
</pre> | </pre> | ||
=== | The true cursor is used for center detection and target-hit detection. Movement onset is detected from joystick movement. Therefore a displayed cursor that appears to touch the target is not necessarily counted as a hit, and a true cursor that reaches the target can register a hit despite noise displacing the displayed cursor away from it. | ||
===Noise Seeds and State Encoding=== | |||
<code>SensoryNoiseSeed</code> defaults to 1. Setting it to 0 selects an automatically generated effective seed, recorded in <code>SensoryNoiseSeedEffective</code> and reported in the BCI2000 operator log. | |||
Noise values are stored as positive integer states with an offset to represent negative noise; the configured SD is stored in hundredths of a pixel: | |||
<pre> | <pre> | ||
noiseX_pixels = (SensoryNoiseX - 1073741824) / 100 | |||
noiseY_pixels = (SensoryNoiseY - 1073741824) / 100 | |||
noiseSD_pixels = SensoryNoiseStd / 100 | |||
</pre> | |||
The recorded <code>TrueCursorX/Y</code> and <code>CursorX/Y</code> coordinates are quantized to the task's 0–1023 range. The noise states represent the generated visual perturbation before final boundary clipping; consequently, the difference between displayed and true coordinates may not equal the encoded noise exactly near display edges. | |||
<b>Important:</b> <code>TrueCursorX/Y</code> is post-mapping, pre-noise position, not a pre-mapping/raw joystick trajectory. The raw joystick trajectory is available from logged joystick input states. | |||
==Information Seeking== | |||
Information seeking is disabled by default (<code>EnableInformationSeeking=0</code>) and is independent of predictive cues, sensory reliability, and the points system. | |||
===Availability and Trigger=== | |||
A purchase is accepted only while all of the following are true: | |||
* The task is in the experimental stage and <code>TaskPhase=2</code> (<code>HoldingCenter</code>). | |||
* The true/task-logic cursor remains inside the center tolerance. | |||
* A rising edge occurs on the <code>JoystickButtonsN</code> state selected by <code>InformationPurchaseButton</code>. | |||
* The configured purchase window has not expired. | |||
* No information has already been purchased for the trial. | |||
<code>InformationPurchaseWindowMs=0</code> permits purchasing throughout an uninterrupted center hold. A nonzero value is measured from entry into <code>HoldingCenter</code>. Leaving and re-entering center starts a new hold and purchase-window timer unless a purchase already occurred. A purchase does not reset, pause, or extend center hold. Presses during other phases, tutorial/sandbox operation, or pause are not purchases. A held button cannot create repeated purchases. | |||
</ | ===Revealed Information=== | ||
Only <code>InformationType=0</code> is implemented. It reveals the actual mapping already assigned to the current trial as <code>NORMAL</code> or <code>REVERSED</code>; it is not inferred from the previous trial and remains correct even when a predictive cue is invalid. The text appears in the top display area until target onset. A nonzero <code>InformationDisplayDurationMs</code> may hide it sooner. | |||
Published values 1 (future trials) and 2 (block mapping) are reserved but rejected by preflight. <code>InformationHorizonTrials</code> is also reserved and has no runtime effect. <code>ShowInformationPurchaseHint</code> is a deprecated compatibility parameter with no runtime effect; no center-hold purchase prompt is drawn. | |||
<code>InformationPurchaseTimeMs</code> is relative to experimental trial start, not center-hold onset. It can therefore include waiting-for-center time. Compensated pause duration is excluded. | |||
== | ===Interaction with Reset, Skip, and Points=== | ||
A manual reset repeats the same trial and preserves an existing purchase, revealed mapping, purchase time, and point cost; it does not charge twice. A skipped trial or block awards no points and clears trial-specific information accounting when the next trial becomes active. When information seeking is enabled without points, purchases and their states still work and <code>TrialInformationCost</code> is recorded, but no trial or cumulative points are calculated. | |||
==Points System== | |||
The default | The points system is disabled by default (<code>EnableRewardSystem=0</code>). When enabled, each successfully acquired, non-skipped trial begins with <code>BaseTrialReward</code> potential points and is scored as: | ||
<pre> | <pre> | ||
TrialReward = max( | |||
0, | |||
BaseTrialReward | |||
- applied initial-direction penalty | |||
- applied trajectory penalty | |||
- purchased-information cost) | |||
</pre> | </pre> | ||
The default base value is 10 points; initial-direction and trajectory penalties default to 3 points each, and information cost defaults to 2 points. Parameter values may be fractional. State encodings use hundredths of a point. | |||
===Initial-Direction Penalty=== | |||
Initial direction is measured from participant-visible displayed-cursor displacement. Measurement starts at the target-onset cursor anchor and ends after <code>InitialDirectionWindowMs</code> from detected movement onset, or at the latest available displayed position if the target is acquired sooner. Error is the unsigned 0–180 degree angle between that displacement and the anchor-to-target vector. Zero displacement is treated as 180 degrees. The penalty applies only when error is strictly greater than <code>InitialDirectionThresholdDeg</code> (default 45 degrees). | |||
===Trajectory Penalty=== | |||
After movement onset, each displayed-cursor sample contributes its perpendicular distance from the ideal normalized center-to-target line, divided by center-to-target distance. <code>TrajectoryDeviation</code> is the arithmetic sample mean. The penalty applies only when this mean is strictly greater than <code>TrajectoryDeviationThreshold</code> (default 0.20). Because both performance metrics use the displayed cursor, sensory noise can affect point penalties even though target-hit logic uses the true cursor. The trajectory metric is a processing-sample mean, not a path-length-weighted integral. | |||
===Feedback and Cumulative Points=== | |||
At target acquisition, point values are finalized and immediately added to <code>CumulativeReward</code>. During Feedback, the top text area displays <code>+ N points</code>, with unnecessary trailing zeros removed. When rewards are enabled, Feedback lasts the greater of <code>FeedbackSeconds</code> and <code>RewardFeedbackDurationMs / 1000</code>; with defaults this is 1 second. No additional task phase is introduced. | |||
When <code>ShowCumulativeReward=1</code>, the participant display also shows <code>Total: N points</code>. The cumulative state is maintained even when that display is disabled, persists across ordinary trials, and resets at run start. Skipped and unfinished trials do not award points. | |||
==Return-to-Anchor Behavior== | ==Return-to-Anchor Behavior== | ||
After an Inverted | After an Inverted trial, the previous transformed mapping may temporarily remain active while the participant returns the joystick toward its previous anchor. | ||
The stored transformation is released once both joystick axes are within 8 task-coordinate units of the previous joystick anchor. | The stored transformation is released once both joystick axes are within 8 task-coordinate units of the previous joystick anchor. | ||
| Line 585: | Line 778: | ||
Normal direct mapping is then restored for ordinary centering. | Normal direct mapping is then restored for ordinary centering. | ||
This behavior reduces abrupt cursor jumps between transformed target movement and subsequent centering. | This behavior reduces abrupt cursor jumps between transformed target movement and subsequent centering. It is also engaged when an in-progress Inverted trial is skipped or when an Inverted trial is reset during target-visible movement. Skipping an entire block does not explicitly engage this return path, so direct mapping may be restored immediately in that case. | ||
==Mapping Switches== | ==Mapping Switches== | ||
| Line 595: | Line 788: | ||
</pre> | </pre> | ||
Mapping switches occur only at trial boundaries. Changes in sensory reliability alone do not produce mapping-switch events. | |||
They do not occur: | They do not occur: | ||
| Line 632: | Line 823: | ||
Because the first experimental trial also begins at 0, <code>TrialsSinceMappingSwitch==0</code> by itself does not identify a switch. | Because the first experimental trial also begins at 0, <code>TrialsSinceMappingSwitch==0</code> by itself does not identify a switch. | ||
Use <code>MappingSwitch</code> or a transition in <code>TaskCondition</code> to identify mapping changes. | Use <code>MappingSwitch</code> or a transition in <code>TaskCondition</code> to identify mapping changes. When skip controls are used, event states can be stale or missing for a processing block; compare adjacent trials and consult the skip-state guidance below. | ||
===Example=== | ===Example=== | ||
| Line 711: | Line 902: | ||
* Are black. | * Are black. | ||
* Are visually identical across all mapping conditions. | * Are visually identical across all mapping conditions. | ||
* Are visually identical across | * Are visually identical across reliability conditions. | ||
* Are not determined by mapping condition. | * Are not determined by mapping condition. | ||
* Are not determined by | * Are not determined by reliability condition. | ||
* Are not determined by mapping-switch status. | * Are not determined by mapping-switch status. | ||
* May repeat. | * May repeat. | ||
| Line 725: | Line 916: | ||
* After each completed non-final trial. | * After each completed non-final trial. | ||
Resetting a trial does not generate a new target. | Resetting a trial does not generate a new target. Advancing after a skipped trial generates a new target; skipping the remaining trials of a block may consume multiple target generations and change the subsequent target sequence. | ||
==Trial Phases== | ==Trial Phases== | ||
| Line 750: | Line 941: | ||
| HoldingCenter | | HoldingCenter | ||
| Required uninterrupted center hold | | Required uninterrupted center hold | ||
| Cursor, | | Cursor, center, cross; the center is the predictive cue color on cued trials. Purchased mapping text may appear. No purchase prompt is shown. | ||
|- | |- | ||
| 3 | | 3 | ||
| Warning | | Warning | ||
| Warning interval | | Warning interval | ||
| Cursor, yellow warning marker, cross | | Cursor, yellow warning marker, cross; unexpired purchased mapping text may remain | ||
|- | |- | ||
| 4 | | 4 | ||
| PreTargetDelay | | PreTargetDelay | ||
| Delay immediately before target appearance | | Delay immediately before target appearance | ||
| Cursor, gray center, cross | | Cursor, gray center, cross; unexpired purchased mapping text may remain | ||
|- | |- | ||
| 5 | | 5 | ||
| Line 770: | Line 961: | ||
| Feedback | | Feedback | ||
| Post-acquisition interval | | Post-acquisition interval | ||
| Cursor and cross | | Cursor and cross; <code>+ N points</code> when rewards are enabled | ||
|- | |- | ||
| 7 | | 7 | ||
| Line 795: | Line 986: | ||
TargetHit == 1 | TargetHit == 1 | ||
</pre> | </pre> | ||
Center and target-hit testing use the true, pre-noise cursor, not the displayed noisy cursor. During a skip operation, <code>TaskPhase</code> and related trial states may remain stale because the normal state-update path is bypassed. In particular, a skip directly to completion may not record <code>TaskPhase=7</code>. | |||
==Participant Display== | ==Participant Display== | ||
| Line 801: | Line 994: | ||
* A light background. | * A light background. | ||
* A black cursor. | * A black cursor (diameter configurable with <code>CursorDiameterPixels</code>). | ||
* A black central cross. | * A black central cross. | ||
* A gray center marker. | * A gray center marker. | ||
* A larger yellow warning marker. | * A larger yellow warning marker. | ||
* A black peripheral target. | * A black peripheral target (diameter configurable with <code>TargetDiameterPixels</code>). | ||
* An experimental progress indicator. | * An experimental progress indicator. | ||
* Introduction and sandbox instructions. | * Introduction and sandbox instructions in dark text on the light participant-window background. | ||
* Predictive cue instruction animations and an optional joystick illustration. | |||
* A persistent green/red cue key during predictive-cue experiments. | |||
* Optional purchased-mapping text, trial point feedback, and cumulative points. | |||
* An experiment-completion message. | * An experiment-completion message. | ||
The participant receives no | The participant receives no mapping-switch event, validity label, reliability label, <code>PriorCondition</code>, block/trial number, block transition, or numerical mapping probability. Predictive cues provide probabilistic mapping information when enabled, and purchased information provides the actual mapping when requested. Noise under Medium and Low reliability may be perceptible as cursor jitter during target-visible movement. | ||
The target remains black across conditions. | The target remains black across all mapping and reliability conditions. There is no explicit success-color cue; the target disappears after successful acquisition. The completion text is the literal string <code>" ended "</code> shown in white. | ||
The target diameter affects both its drawing and the radius used for target-hit testing. The cursor diameter affects its appearance only; it does not change the center tolerance or the target-hit radius. | |||
==Diagnostic Window== | ==Diagnostic Window== | ||
| Line 835: | Line 1,022: | ||
is displayed to the experimenter. | is displayed to the experimenter. | ||
During experimental trials | ===Displayed Information=== | ||
During experimental trials, the visible metrics panel displays: | |||
* Current task stage. | * Current task stage. | ||
* Original block number. | * Original block role number (<code>Block: N / 6</code>), even if some blocks were disabled. | ||
* | * Trial number within the current block and block trial count. | ||
* | * Overall trial number and total configured active trials. | ||
* Current Normal or Inverted mapping. | * Current Normal or Inverted mapping. | ||
* Current | * Current High, Medium, or Low reliability condition. | ||
* | * Configured visual-noise standard deviation for that trial, in pixels. | ||
* Current task phase. | * Current task phase. | ||
* | * Real-time reaction time, movement time, and total time. | ||
* | * Cumulative overall, Normal-mapping, and Reversed-mapping averages of reaction time, movement time, and total time. | ||
* When predictive cues are enabled: predicted mapping, cue validity, block Normal probability, and configured cue accuracy. | |||
* | |||
<code>PriorCondition</code> | The visible panel does <b>not</b> show target angle or coordinates, joystick coordinates, cursor coordinates, mapping-switch flag, trials-since-switch counter, movement-started status, <code>PriorCondition</code>, information-purchase status, point totals, direction/trajectory metrics, penalty flags, or a separate reset/status message. Run averages are divided by mapping, not by reliability, cue validity, or purchase status. A separate diagnostic text label exists internally but is hidden and not populated. | ||
===Diagnostic Controls=== | ===Diagnostic Controls=== | ||
{| class="wikitable" | |||
! Control | |||
< | ! Availability | ||
RESET CURRENT | ! Effect | ||
</ | ! Confirmation | ||
|- | |||
| <code>RESET CURRENT TRIAL</code> | |||
| Experiment phases 1–5; shown as <code>RESET UNAVAILABLE</code> otherwise | |||
| Restarts the same trial and emits <code>TrialReset</code> | |||
| No | |||
|- | |||
| <code>SKIP TRIAL</code> | |||
| Experiment phases 1–5, not paused | |||
| Abandons the current trial and advances; emits <code>TrialSkipped</code> | |||
| No | |||
|- | |||
| <code>SKIP CURRENT BLOCK</code> | |||
| Experiment phases 1–5, not paused | |||
| Advances past the remaining trials of the block; emits <code>ConditionSkipped</code> | |||
| Yes | |||
|- | |||
| <code>SKIP INTRODUCTION</code> | |||
| Introduction stage, not paused | |||
| Enters the experiment directly, bypassing sandbox; emits <code>IntroductionSkipped</code> | |||
| Yes | |||
|- | |||
| <code>SKIP SANDBOX</code> | |||
| Sandbox stage, not paused | |||
| Enters the experiment; emits <code>SandboxSkipped</code> | |||
| No | |||
|- | |||
| <code>PAUSE</code> / <code>RESUME</code> | |||
| All stages/phases except Finished | |||
| Freezes task-phase progression and resumes with adjusted internal timestamps; uses <code>TaskPaused</code> | |||
| No | |||
|} | |||
There is no diagnostic Continue button for the introduction or sandbox. | There is no separate diagnostic Continue button for the introduction or sandbox. Those stages normally advance using a rising joystick-button press, or may be bypassed using the skip controls. | ||
==Trial Reset== | ==Trial Reset== | ||
| Line 899: | Line 1,109: | ||
* Clears timing states. | * Clears timing states. | ||
* Resets baseline accumulation. | * Resets baseline accumulation. | ||
* Clears visual-noise state. | |||
* Clears predictive-cue onset/visibility timing but keeps the same preassigned cue and validity. | |||
* Clears initial-direction, trajectory, penalty, and unfinalized trial-point measurements. | |||
* Preserves any information already purchased for that same trial, including revealed mapping, cost, and timestamp. | |||
* Keeps the same target. | * Keeps the same target. | ||
* Keeps the same mapping. | * Keeps the same mapping. | ||
* Keeps the same | * Keeps the same sensory-reliability condition. | ||
* Keeps the same block number. | * Keeps the same block number. | ||
* Keeps the same trial number. | * Keeps the same trial number. | ||
| Line 908: | Line 1,122: | ||
* Does not rebuild or reshuffle the experimental sequence. | * Does not rebuild or reshuffle the experimental sequence. | ||
<code>TrialReset</code> lasts for one processing block. | <code>TrialReset</code> lasts for one processing block. Resetting an Inverted trial during target-visible movement also enables the return-to-anchor behavior. A reset request is not processed while paused; requests pending at the time of a pause are deferred until processing resumes. A preserved purchase is not charged a second time. | ||
==Skipping Trials, Blocks, and Tutorial Stages== | |||
===Skip Trial=== | |||
<code>SKIP TRIAL</code> is available during experimental phases before Feedback. It emits a one-processing-block <code>TrialSkipped</code> pulse, clears current movement, cue-onset, information, and point accounting, does not count or award points for the abandoned trial, and advances to the next trial or finishes the run. A new target is generated on each non-final advance. Skipping an Inverted trial engages the return-to-anchor behavior. | |||
===Skip Current Block=== | |||
<code>SKIP CURRENT BLOCK</code> requires confirmation and is available during experimental phases before Feedback. It emits <code>ConditionSkipped</code>, advances through all remaining trials in the current block, and starts the next enabled block or finishes the run. It does not register those abandoned trials as completed measurements or award points. The operation calls the normal advancement routine repeatedly, consuming target-generation random-number draws. Unlike single-trial skip, it does not explicitly engage return-to-anchor for the interrupted Inverted trial. | |||
===Skip Introduction and Sandbox=== | |||
<code>SKIP INTRODUCTION</code>, after confirmation, emits <code>IntroductionSkipped</code> and enters the experimental phase directly, also bypassing the sandbox. <code>SKIP SANDBOX</code> emits <code>SandboxSkipped</code> and enters the experimental phase from the sandbox. Both are available only in their corresponding stage when not paused. | |||
===Pause and Resume=== | |||
<code>PAUSE</code> is available during introduction, sandbox, and experimental phases, including Feedback, but not Finished. While paused, <code>TaskPaused</code> is held at 1, phase progression and cursor rendering updates stop, and joystick states continue to be sampled. On resumption, internal phase, target-onset, movement-onset, center-hold, information-display/purchase, predictive-cue-onset, sensory-noise, and introduction-animation timestamps are shifted by the pause duration. Skip controls are disabled while paused; a button press made while paused is not a purchase, and holding it through resume creates no new rising edge. | |||
===State-Logging Caveats During Skips=== | |||
The skip-handling branches return early from <code>Process()</code> before the usual end-of-block state publication. Consequently, <code>TaskTrial</code>, <code>TaskBlock</code>, <code>TaskCondition</code>, <code>TaskPhase</code>, <code>TrialsSinceMappingSwitch</code>, and other trial states may show the preceding values on the skip processing block. They normally update on a later ordinary processing block. <code>MappingSwitch</code> can be stale or fail to pulse on the skip block. If a skip ends the run, the usual <code>TaskPhase=7</code> update may never be recorded. Do not rely on a single isolated processing block to reconstruct skip transitions; inspect adjacent samples, skip event states, and trial/block identifiers. These behaviors are analysis considerations of the current implementation, not intended additional task conditions. | |||
==Timing Measurements== | ==Timing Measurements== | ||
| Line 970: | Line 1,206: | ||
Timing values are expressed in rounded milliseconds. | Timing values are expressed in rounded milliseconds. | ||
Timing states remain populated through the Feedback phase. | Timing states remain populated through the Feedback phase. When a target is reached without a detected movement onset, reaction and movement times are recorded as 0 and excluded from the corresponding run averages, while total time is still recorded. Paused durations are excluded through adjustment of internal timestamps when resuming. | ||
==Parameters== | ==Parameters== | ||
| Line 1,020: | Line 1,256: | ||
|} | |} | ||
At least one trial must be configured across the six block parameters. | At least one trial must be configured across the six block parameters. A count of zero disables that block without renumbering the remaining block roles. | ||
= | The preceding six parameters are used only when <code>EnablePredictiveCues=0</code>. When predictive cues are enabled, at least one trial must instead be configured across the predictive trial-count parameters. | ||
===Predictive-Cue Design=== | |||
Type: | {| class="wikitable" | ||
! Parameter | |||
! Type | |||
! Default | |||
! Range | |||
! Description | |||
|- | |||
| <code>EnablePredictiveCues</code> | |||
| Integer | |||
| 0 | |||
| 0-1 | |||
| Select predictive-cue design; 0 preserves legacy design | |||
|- | |||
| <code>CueAccuracyPercent</code> | |||
| Integer | |||
| 80 | |||
| 0-100 | |||
| Valid-cue percentage calculated separately within each actual mapping | |||
|- | |||
| <code>CueColorAssignment</code> | |||
| Integer | |||
| 0 | |||
| 0-1 | |||
| 0: green=Normal, red=Reversed; 1: green=Reversed, red=Normal | |||
|- | |||
| <code>CueRandomSeed</code> | |||
| Integer | |||
| 1 | |||
| 0-2147483647 | |||
| Dedicated predictive-sequence seed; 0 chooses and records an automatic seed | |||
|- | |||
| <code>CounterbalanceBiasedBlockOrder</code> | |||
| Integer | |||
| 0 | |||
| 0-1 | |||
| Swap complete configured block-4 and block-5 definitions | |||
|- | |||
| <code>PredictiveBlock1Trials</code> | |||
| Integer | |||
| 20 | |||
| 0-10000 | |||
| Uncued 100% Normal familiarization trials | |||
|- | |||
| <code>PredictiveBlock2Trials</code> | |||
| Integer | |||
| 10 | |||
| 0-10000 | |||
| Uncued 100% Reversed familiarization trials | |||
|- | |||
| <code>CuedBlock3Trials</code>, <code>CuedBlock4Trials</code>, <code>CuedBlock5Trials</code>, <code>CuedBlock6Trials</code> | |||
| Integer | |||
| 40 each | |||
| 0-10000 | |||
| Trial counts for predictive blocks 3 through 6 | |||
|- | |||
| <code>CuedBlock3NormalProbabilityPercent</code> | |||
| Integer | |||
| 50 | |||
| 0-100 | |||
| Configured Normal percentage for block 3 | |||
|- | |||
| <code>CuedBlock4NormalProbabilityPercent</code> | |||
| Integer | |||
| 75 | |||
| 0-100 | |||
| Configured Normal percentage for block 4 | |||
|- | |||
| <code>CuedBlock5NormalProbabilityPercent</code> | |||
| Integer | |||
| 25 | |||
| 0-100 | |||
| Configured Normal percentage for block 5 | |||
|- | |||
| <code>CuedBlock6NormalProbabilityPercent</code> | |||
| Integer | |||
| 50 | |||
| 0-100 | |||
| Configured Normal percentage for block 6 | |||
|- | |||
| <code>EnableIntroductionAnimation</code> | |||
| Integer | |||
| 1 | |||
| 0-1 | |||
| Use animated predictive-cue instruction pages | |||
|- | |||
| <code>IntroductionAnimationDurationMs</code> | |||
| Integer | |||
| 2500 | |||
| 1-60000 | |||
| Cursor/joystick movement duration per animated example | |||
|- | |||
| <code>IntroductionCueDisplayDurationMs</code> | |||
| Integer | |||
| 800 | |||
| 0-60000 | |||
| Cue-only interval before animated movement | |||
|- | |||
| <code>IntroductionAnimationPauseMs</code> | |||
| Integer | |||
| 750 | |||
| 0-60000 | |||
| Pause between animated examples | |||
|- | |||
| <code>IntroductionAnimationLoop</code> | |||
| Integer | |||
| 1 | |||
| 0-1 | |||
| Continuously loop examples | |||
|- | |||
| <code>IntroductionShowJoystickIllustration</code> | |||
| Integer | |||
| 1 | |||
| 0-1 | |||
| Show animated joystick graphic | |||
|- | |||
| <code>IntroductionPracticeScreenDurationMs</code> | |||
| Integer | |||
| 2000 | |||
| 0-60000 | |||
| Automatic <code>Time to practice</code> screen duration | |||
|- | |||
| <code>EnableGuidedSandbox</code> | |||
| Integer | |||
| 1 | |||
| 0-1 | |||
| Use guided predictive-cue practice | |||
|- | |||
| <code>GuidedSandboxTrials</code> | |||
| Integer | |||
| 3 | |||
| 1-20 | |||
| Number of guided practice trials | |||
|} | |||
===Task Timing and Display=== | |||
< | {| class="wikitable" | ||
1. | ! Parameter | ||
</ | ! Type | ||
! Default | |||
! Range | |||
! Description | |||
|- | |||
| <code>CenterHoldSeconds</code> | |||
| Float | |||
| 3.0 | |||
| 0.0-60.0 | |||
| Required uninterrupted center-hold duration in seconds | |||
|- | |||
| <code>WarningSeconds</code> | |||
| Float | |||
| 0.5 | |||
| 0.0-60.0 | |||
| Yellow warning interval in seconds | |||
|- | |||
| <code>PreTargetDelaySeconds</code> | |||
| Float | |||
| 0.5 | |||
| 0.0-60.0 | |||
| Delay between warning and target onset in seconds | |||
|- | |||
| <code>FeedbackSeconds</code> | |||
| Float | |||
| 0.5 | |||
| 0.0-60.0 | |||
| Feedback interval following target acquisition, in seconds | |||
|- | |||
| <code>CursorDiameterPixels</code> | |||
| Float | |||
| 16.0 | |||
| 1.0-1000.0 | |||
| Cursor drawing diameter in nominal reference pixels | |||
|- | |||
| <code>TargetDiameterPixels</code> | |||
| Float | |||
| 36.0 | |||
| 1.0-1000.0 | |||
| Target drawing and hit-test diameter in nominal reference pixels | |||
|- | |||
| <code>StimulusDisplay</code> | |||
| Integer | |||
| 0 | |||
| 0 through number of detected displays | |||
| Physical monitor for participant stimuli; 0 uses default BCI2000 placement | |||
|} | |||
On Windows, the application enumerates available monitors for <code>StimulusDisplay</code>. <code>CursorDiameterPixels</code> affects cursor appearance only; <code>TargetDiameterPixels</code> also changes the hit-test radius. | |||
===Sensory Reliability Configuration=== | |||
{| class="wikitable" | |||
! Parameter | |||
! Type | |||
! Default | |||
! Range | |||
! Description | |||
|- | |||
| <code>EnableSensoryReliability</code> | |||
| Integer | |||
| 0 | |||
| 0-1 | |||
| Enable trial-wise visual-reliability noise; 0 disables it | |||
|- | |||
| <code>MediumReliabilityNoiseStd</code> | |||
| Float | |||
| 5.0 | |||
| 0.0-1000.0 | |||
| Gaussian noise SD in pixels for Medium reliability | |||
|- | |||
| <code>LowReliabilityNoiseStd</code> | |||
| Float | |||
| 15.0 | |||
| 0.0-1000.0 | |||
| Gaussian noise SD in pixels for Low reliability | |||
|- | |||
| <code>HighReliabilityProportion</code> | |||
| Float | |||
| 0.34 | |||
| 0.0-1.0 | |||
| Target High-reliability trial proportion in enabled blocks | |||
|- | |||
| <code>MediumReliabilityProportion</code> | |||
| Float | |||
| 0.33 | |||
| 0.0-1.0 | |||
| Target Medium-reliability trial proportion in enabled blocks | |||
|- | |||
| <code>LowReliabilityProportion</code> | |||
| Float | |||
| 0.33 | |||
| 0.0-1.0 | |||
| Target Low-reliability trial proportion in enabled blocks | |||
|- | |||
| <code>SensoryNoiseCorrelationTimeMs</code> | |||
| Float | |||
| 100.0 | |||
| 0.0-60000.0 | |||
| Temporal correlation time constant of noise, in milliseconds; zero gives independent innovations | |||
|- | |||
| <code>SensoryNoiseSeed</code> | |||
| Integer | |||
| 1 | |||
| 0-2147483647 | |||
| Dedicated condition-assignment and noise seed; zero automatically selects a seed | |||
|- | |||
| <code>SensoryReliabilityBlocks</code> | |||
| List | |||
| 4 5 6 (BCI2000 definition: <code>3 4 5 6</code>, where 3 is the list length) | |||
| Entries 1-6; no duplicates | |||
| Block role numbers in which reliability conditions may be assigned; an empty list means all trials are High reliability | |||
|} | |||
=== | ===Points and Information Seeking=== | ||
{| class="wikitable" | |||
! Parameter | |||
! Type | |||
! Default | |||
! Range | |||
! Description | |||
|- | |||
| <code>EnableRewardSystem</code> | |||
| Integer | |||
| 0 | |||
| 0-1 | |||
| Enable point calculation and feedback | |||
|- | |||
| <code>BaseTrialReward</code> | |||
| Float | |||
| 10.0 | |||
| 0.0-100000.0 | |||
| Potential points per completed trial | |||
|- | |||
| <code>InitialDirectionPenalty</code> | |||
| Float | |||
| 3.0 | |||
| 0.0-100000.0 | |||
| Points deducted when direction error exceeds threshold | |||
|- | |||
| <code>TrajectoryPenalty</code> | |||
| Float | |||
| 3.0 | |||
| 0.0-100000.0 | |||
| Points deducted when mean trajectory deviation exceeds threshold | |||
|- | |||
| <code>InitialDirectionThresholdDeg</code> | |||
| Float | |||
| 45.0 | |||
| 0.0-180.0 | |||
| Maximum initial angular error without penalty | |||
|- | |||
| <code>InitialDirectionWindowMs</code> | |||
| Integer | |||
| 150 | |||
| 0-60000 | |||
| Displayed-cursor measurement window after movement onset | |||
|- | |||
| <code>TrajectoryDeviationThreshold</code> | |||
| Float | |||
| 0.20 | |||
| 0.0-100.0 | |||
| Maximum mean deviation as a fraction of center-to-target distance | |||
|- | |||
| <code>RewardFeedbackDurationMs</code> | |||
| Integer | |||
| 1000 | |||
| 0-60000 | |||
| Requested point-feedback duration | |||
|- | |||
| <code>ShowCumulativeReward</code> | |||
| Integer | |||
| 0 | |||
| 0-1 | |||
| Show cumulative points when rewards are enabled | |||
|- | |||
| <code>EnableInformationSeeking</code> | |||
| Integer | |||
| 0 | |||
| 0-1 | |||
| Enable optional current-trial mapping purchase | |||
|- | |||
| <code>InformationCost</code> | |||
| Float | |||
| 2.0 | |||
| 0.0-100000.0 | |||
| Recorded point cost; deducted when rewards are also enabled | |||
|- | |||
| <code>InformationType</code> | |||
| Integer | |||
| 0 | |||
| Published 0-2; only 0 accepted | |||
| 0 reveals current-trial mapping; 1 and 2 are reserved | |||
|- | |||
| <code>InformationHorizonTrials</code> | |||
| Integer | |||
| 5 | |||
| 1-10000 | |||
| Reserved for unimplemented type 1; no runtime effect | |||
|- | |||
| <code>InformationDisplayDurationMs</code> | |||
| Integer | |||
| 0 | |||
| 0-60000 | |||
| Mapping-text duration; 0 means until target onset | |||
|- | |||
| <code>InformationPurchaseButton</code> | |||
| Integer | |||
| 1 | |||
| 1-32 | |||
| One-based <code>JoystickButtonsN</code> state used to purchase | |||
|- | |||
| <code>InformationPurchaseWindowMs</code> | |||
| Integer | |||
| 0 | |||
| 0-60000 | |||
| Purchase window after entering center hold; 0 means entire hold | |||
|- | |||
| <code>ShowInformationPurchaseHint</code> | |||
| Integer | |||
| 0 | |||
| 0-1 | |||
| Deprecated compatibility parameter; no runtime effect | |||
|} | |||
===Parameter Validation=== | |||
Preflight requires at least one configured trial in the active legacy or predictive design; cue accuracy and predictive block probabilities in 0-100; positive animation duration and guided-practice count; finite, nonnegative reward/cost/threshold/duration values; initial-direction threshold no greater than 180; <code>InformationType=0</code>; positive information horizon; a valid existing selected <code>JoystickButtonsN</code> purchase state; and a maximum possible cumulative point value that fits the 32-bit fixed-point state. It also requires finite and nonnegative reliability values, Low-reliability SD not less than Medium, reliability proportions summing to 1 within <code>1e-6</code>, valid unduplicated reliability-block numbers, positive cursor and target diameters, nonnegative task durations, and a valid selected display. | |||
< | <code>HighCursorGain</code> is no longer a parameter in this version. There is no <code>ExperimentMode</code> or <code>ResultsFile</code> parameter. | ||
</ | |||
==States== | |||
=== | |||
The following states are declared by the FEP task. Widths and initial values refer to their published definitions; runtime values may change immediately on <code>StartRun()</code> or during <code>Process()</code>. | |||
{| class="wikitable" | {| class="wikitable" | ||
| Line 1,123: | Line 1,645: | ||
| 10 bit | | 10 bit | ||
| 512 | | 512 | ||
| | | Displayed horizontal cursor position, after mapping, sensory noise, and clipping (0-1023) | ||
|- | |- | ||
| <code>CursorY</code> | | <code>CursorY</code> | ||
| 10 bit | | 10 bit | ||
| 512 | | 512 | ||
| | | Displayed vertical cursor position, after mapping, sensory noise, and clipping (0-1023) | ||
|- | |- | ||
| <code>TaskPhase</code> | | <code>TaskPhase</code> | ||
| 3 bit | | 3 bit | ||
| 0 | | 0 | ||
| Current task phase | | Current task phase (0-7) | ||
|- | |- | ||
| <code>TaskCondition</code> | | <code>TaskCondition</code> | ||
| 1 bit | | 1 bit | ||
| 0 | | 0 | ||
| 0 Normal, 1 Inverted | | 0 Normal, 1 Inverted mapping | ||
|- | |- | ||
| <code>TargetAngle</code> | | <code>TargetAngle</code> | ||
| Line 1,148: | Line 1,670: | ||
| 10 bit | | 10 bit | ||
| 512 | | 512 | ||
| Horizontal target coordinate | | Horizontal target coordinate (0-1023) | ||
|- | |- | ||
| <code>TargetY</code> | | <code>TargetY</code> | ||
| 10 bit | | 10 bit | ||
| 512 | | 512 | ||
| Vertical target coordinate | | Vertical target coordinate (0-1023) | ||
|- | |- | ||
| <code>TaskBlock</code> | | <code>TaskBlock</code> | ||
| 8 bit | | 8 bit | ||
| 0 | | 0 | ||
| Current experimental block role | | Current original experimental block role (1-6; 0 before experiment) | ||
|- | |- | ||
| <code>TaskTrial</code> | | <code>TaskTrial</code> | ||
| 16 bit | | 16 bit | ||
| 0 | | 0 | ||
| Overall experimental trial number | | Overall 1-based experimental trial number (0 before experiment) | ||
|- | |- | ||
| <code>MovementStarted</code> | | <code>MovementStarted</code> | ||
| 1 bit | | 1 bit | ||
| 0 | | 0 | ||
| | | Level flag indicating detected movement onset during the trial | ||
|- | |- | ||
| <code>TargetHit</code> | | <code>TargetHit</code> | ||
| 1 bit | | 1 bit | ||
| 0 | | 0 | ||
| | | One-processing-block target-acquisition pulse | ||
|- | |- | ||
| <code>TrialReset</code> | | <code>TrialReset</code> | ||
| 1 bit | | 1 bit | ||
| 0 | | 0 | ||
| | | One-processing-block manual-reset pulse | ||
|- | |||
| <code>TrialSkipped</code> | |||
| 1 bit | |||
| 0 | |||
| One-processing-block trial-skip pulse | |||
|- | |||
| <code>ConditionSkipped</code> | |||
| 1 bit | |||
| 0 | |||
| One-processing-block current-block-skip pulse | |||
|- | |||
| <code>IntroductionSkipped</code> | |||
| 1 bit | |||
| 0 | |||
| One-processing-block introduction-skip pulse | |||
|- | |||
| <code>SandboxSkipped</code> | |||
| 1 bit | |||
| 0 | |||
| One-processing-block sandbox-skip pulse | |||
|- | |||
| <code>TaskPaused</code> | |||
| 1 bit | |||
| 0 | |||
| Level flag: 1 while paused; 0 otherwise | |||
|- | |- | ||
| <code>MappingSwitch</code> | | <code>MappingSwitch</code> | ||
| 1 bit | | 1 bit | ||
| 0 | | 0 | ||
| | | One-processing-block mapping-change event during normal progression; see skip caveats | ||
|- | |- | ||
| <code>TrialsSinceMappingSwitch</code> | | <code>TrialsSinceMappingSwitch</code> | ||
| 16 bit | | 16 bit | ||
| 0 | | 0 | ||
| | | Consecutive non-switch trial transitions since the most recent mapping change | ||
|- | |- | ||
| <code>PriorCondition</code> | | <code>PriorCondition</code> | ||
| 2 bit | | 2 bit | ||
| 0 | | 0 | ||
| Current block-level prior context | | Current block-level prior-frequency context (0-3) | ||
|- | |- | ||
| <code>Introduction</code> | | <code>Introduction</code> | ||
| 1 bit | | 1 bit | ||
| 0 | | 0 | ||
| 1 during introduction or sandbox | | 1 during introduction or sandbox; 0 during experiment | ||
|- | |- | ||
| <code>TutorialPhase</code> | | <code>TutorialPhase</code> | ||
| Line 1,213: | Line 1,755: | ||
| 32 bit | | 32 bit | ||
| 0 | | 0 | ||
| Reaction time in milliseconds | | Reaction time in rounded milliseconds | ||
|- | |- | ||
| <code>MovementTimeMs</code> | | <code>MovementTimeMs</code> | ||
| 32 bit | | 32 bit | ||
| 0 | | 0 | ||
| Movement time in milliseconds | | Movement time in rounded milliseconds | ||
|- | |- | ||
| <code>TotalTimeMs</code> | | <code>TotalTimeMs</code> | ||
| 32 bit | | 32 bit | ||
| 0 | | 0 | ||
| | | Target-onset to acquisition time in rounded milliseconds | ||
|- | |||
| <code>SensoryReliabilityCondition</code> | |||
| 2 bit | |||
| 0 | |||
| 0 High, 1 Medium, 2 Low reliability | |||
|- | |||
| <code>TrueCursorX</code> | |||
| 10 bit | |||
| 512 | |||
| Post-mapping, pre-noise horizontal task-logic cursor position (0-1023) | |||
|- | |||
| <code>TrueCursorY</code> | |||
| 10 bit | |||
| 512 | |||
| Post-mapping, pre-noise vertical task-logic cursor position (0-1023) | |||
|- | |||
| <code>SensoryNoiseX</code> | |||
| 31 bit | |||
| 1073741824 | |||
| X noise encoded as 1073741824 + round(100 * noise pixels) | |||
|- | |||
| <code>SensoryNoiseY</code> | |||
| 31 bit | |||
| 1073741824 | |||
| Y noise encoded as 1073741824 + round(100 * noise pixels) | |||
|- | |||
| <code>SensoryNoiseStd</code> | |||
| 18 bit | |||
| 0 | |||
| Configured noise SD encoded as round(100 * pixels) | |||
|- | |||
| <code>SensoryNoiseSeedEffective</code> | |||
| 32 bit | |||
| 1 | |||
| Effective noise and reliability-assignment seed | |||
|- | |||
| <code>InformationPurchased</code> | |||
| 1 bit | |||
| 0 | |||
| Level value: 1 after a successful purchase on the current trial | |||
|- | |||
| <code>InformationPurchaseTimeMs</code> | |||
| 32 bit | |||
| 0 | |||
| Purchase time in milliseconds relative to trial start | |||
|- | |||
| <code>InformationRevealedMapping</code> | |||
| 2 bit | |||
| 0 | |||
| 0 none, 1 Normal, 2 Inverted/Reversed | |||
|- | |||
| <code>TrialInformationCost</code> | |||
| 32 bit | |||
| 0 | |||
| Information cost in hundredths of a point | |||
|- | |||
| <code>InitialDirectionErrorDeg</code> | |||
| 15 bit | |||
| 0 | |||
| Initial angular error in hundredths of a degree | |||
|- | |||
| <code>InitialDirectionPenaltyApplied</code> | |||
| 1 bit | |||
| 0 | |||
| 1 when direction error strictly exceeds threshold | |||
|- | |||
| <code>TrajectoryDeviation</code> | |||
| 32 bit | |||
| 0 | |||
| Mean normalized deviation in millionths of center-to-target distance | |||
|- | |||
| <code>TrajectoryPenaltyApplied</code> | |||
| 1 bit | |||
| 0 | |||
| 1 when mean trajectory deviation strictly exceeds threshold | |||
|- | |||
| <code>TrialReward</code> | |||
| 32 bit | |||
| 0 | |||
| Final trial points in hundredths of a point | |||
|- | |||
| <code>CumulativeReward</code> | |||
| 32 bit | |||
| 0 | |||
| Run-total points in hundredths of a point | |||
|- | |||
| <code>CueMapping</code> | |||
| 2 bit | |||
| 0 | |||
| Predicted mapping: 0 none, 1 Normal, 2 Inverted/Reversed | |||
|- | |||
| <code>CueValidity</code> | |||
| 2 bit | |||
| 0 | |||
| 0 not applicable, 1 invalid, 2 valid | |||
|- | |||
| <code>CueReliability</code> | |||
| 7 bit | |||
| 0 | |||
| Configured cue accuracy percentage for the current block (0-100) | |||
|- | |||
| <code>CueVisible</code> | |||
| 1 bit | |||
| 0 | |||
| 1 while a predictive cue is displayed during center hold | |||
|- | |||
| <code>CueOnsetTimeMs</code> | |||
| 32 bit | |||
| 0 | |||
| First cue-onset time in milliseconds relative to trial start | |||
|- | |||
| <code>BlockNormalProbability</code> | |||
| 7 bit | |||
| 0 | |||
| Configured block-level Normal percentage (0-100); realized counts may differ by rounding | |||
|- | |||
| <code>CueRandomSeedEffective</code> | |||
| 32 bit | |||
| 1 | |||
| Effective predictive-sequence seed | |||
|} | |} | ||
| Line 1,233: | Line 1,895: | ||
|- | |- | ||
| <code>JoystickXpos</code> | | <code>JoystickXpos</code> | ||
| Raw horizontal joystick position | | Raw horizontal joystick position supplied through BCI2000 input logging | ||
|- | |- | ||
| <code>JoystickYpos</code> | | <code>JoystickYpos</code> | ||
| Raw vertical joystick position | | Raw vertical joystick position supplied through BCI2000 input logging | ||
|- | |- | ||
| <code>JoystickButtons1</code> | | <code>JoystickButtons1</code> | ||
| Joystick button used to advance | | Joystick button used to advance introduction pages and exit the sandbox | ||
|- | |||
| <code>JoystickButtonsN</code> selected by <code>InformationPurchaseButton</code> | |||
| Configured rising-edge input for information purchase during center hold | |||
|} | |} | ||
The application also accesses | The application also accesses BCI2000's standard <code>Running</code> state when ending the experiment. Joystick logging must be configured separately using <code>LogJoystick</code>. | ||
===States Not Present in the Current Implementation=== | ===States Not Present in the Current Implementation=== | ||
The | The task does not define <code>DisplayedCursorX</code>, <code>DisplayedCursorY</code>, an exact state named <code>SensoryReliability</code>, <code>PracticeTrial</code>, <code>TaskBlockType</code>, or <code>CursorGainCondition</code>. Instead, displayed coordinates use <code>CursorX/Y</code>, pre-noise coordinates use <code>TrueCursorX/Y</code>, and visual reliability is recorded through <code>SensoryReliabilityCondition</code> and the sensory-noise states. | ||
===State Lifecycle and Encoding Notes=== | |||
<code>TargetX/Y</code> have published initial values of 512 but are explicitly set to 0 during introduction/sandbox. <code>TaskTrial</code> is 1-based once experimental trials begin. Pulse states normally clear on the following processing block, whereas <code>TaskPaused</code> is held at 1 throughout a pause and <code>MovementStarted</code> remains high from movement detection until trial advancement. | |||
<code> | Trial-specific information, performance, point, and cue-onset states reset when advancing to a new trial. <code>CumulativeReward</code> resets only at run start. Purchase states update on the accepted button-edge block. Performance and point states finalize with <code>TargetHit</code> and remain through Feedback. Manual reset preserves purchase states but clears performance and unfinalized points. Point-performance states remain zero when rewards are disabled, although <code>TrialInformationCost</code> may still be nonzero after a purchase. Cue mapping, validity, reliability, visibility, and onset states are zero during introduction/sandbox and in legacy operation; <code>BlockNormalProbability</code> and <code>CueRandomSeedEffective</code> are still published during legacy experiments. | ||
Noise states use fixed-point encoding described in [[#Noise Seeds and State Encoding|Noise Seeds and State Encoding]]. State publication immediately after skip operations has known limitations described in [[#State-Logging Caveats During Skips|State-Logging Caveats During Skips]]. | |||
==Cursor Coordinates== | |||
<code>CursorX</code> and <code>CursorY</code> represent the final displayed cursor position including mapping inversion, return-to-anchor transformation, any applied Gaussian visual noise, and display-boundary clipping. | |||
<code>TrueCursorX</code> and <code>TrueCursorY</code> record the separate <b>post-mapping, pre-noise</b> cursor trajectory. This is the trajectory used for center detection and target-hit detection. It does not represent untransformed joystick input. | |||
The | The participant-visible drawing is positioned using the displayed cursor. Both true and displayed coordinates are recorded as 10-bit states over the range 0-1023. Encoded noise samples are recorded separately. The diagnostic window does not currently show either cursor coordinate pair. | ||
The application does not record an independent pre-mapping cursor state. When enabled, <code>JoystickXpos/Ypos</code> provide the underlying joystick samples needed to reconstruct a raw joystick-equivalent trajectory offline. | |||
==Data Recording== | ==Data Recording== | ||
The task records its behavioral variables as synchronized BCI2000 states in the standard <code>.dat</code> file. | The task records its behavioral variables as synchronized BCI2000 states in the standard <code>.dat</code> file, subject to the configured BCI2000 recording and joystick-logging settings. | ||
Recorded information includes: | Recorded information includes: | ||
* | * Displayed and true cursor trajectories (<code>CursorX/Y</code> and <code>TrueCursorX/Y</code>). | ||
* Joystick trajectory | * Joystick trajectory when external joystick logging is enabled. | ||
* | * Task phase, Normal/Inverted mapping, prior context, and mapping-switch history. | ||
* | * Sensory-reliability condition, actual generated noise, configured noise SD, and effective seed. | ||
* | * Predictive cue mapping, validity, configured cue accuracy, visibility/onset, block Normal probability, and effective cue seed. | ||
* | * Information purchase, purchase time, revealed mapping, and point cost. | ||
* | * Initial-direction error, trajectory deviation, penalty flags, trial points, and cumulative points. | ||
* | * Target angle and coordinates, experimental block, and trial number. | ||
* Movement onset, target acquisition, and reaction/movement/total timing. | |||
* Movement onset | * Trial reset, trial skip, block skip, introduction skip, sandbox skip, and pause status. | ||
* Introduction/sandbox status and experiment completion as represented by task states. | |||
* Trial | |||
* Introduction | |||
The application passes signal channels through unchanged | The application passes signal channels through unchanged: | ||
<pre> | <pre> | ||
| Line 1,309: | Line 1,955: | ||
</pre> | </pre> | ||
=== | ===Operator Logging=== | ||
The | The application writes <code>bciout</code> messages for task startup and shutdown, effective sensory-noise and predictive-cue seeds, predictive-block realized mapping/validity counts, per-block High/Medium/Low reliability distributions split by Normal/Inverted mapping and switch status, and trial-completion results including trial, block, mapping, reliability, reaction time, and movement time. These are diagnostic/operator messages rather than a separate structured task-results file. | ||
===Secondary Output=== | |||
There is no <code>ResultsFile</code> parameter. | The current implementation does not write an application-specific CSV file, JSON file, text results file, or database. There is no <code>ResultsFile</code> parameter. | ||
==Offline Analysis Notes== | ==Offline Analysis Notes== | ||
The table below gives common event and measurement identifications. When reset, skip, or pause controls are used, inspect adjacent processing blocks and the recorded configuration instead of relying solely on one state sample. | |||
{| class="wikitable" | {| class="wikitable" | ||
| Line 1,336: | Line 1,981: | ||
|- | |- | ||
| Active experimental trial | | Active experimental trial | ||
| <code>Introduction == 0</code>, <code>TaskTrial | | <code>Introduction == 0</code>, <code>TaskTrial > 0</code>, and <code>TaskPhase</code> from 1 through 6 | ||
|- | |- | ||
| Target onset | | Target onset | ||
| Line 1,353: | Line 1,998: | ||
| <code>TaskCondition == 1</code> | | <code>TaskCondition == 1</code> | ||
|- | |- | ||
| Normal | | Predicted mapping | ||
| <code> | | <code>CueMapping</code>: 0 none, 1 Normal, 2 Inverted/Reversed | ||
|- | |||
| Valid/invalid predictive cue | |||
| <code>CueValidity</code>: 1 invalid, 2 valid; 0 not applicable | |||
|- | |||
| Cue visible | |||
| <code>CueVisible == 1</code>; onset relative to trial start is <code>CueOnsetTimeMs</code> | |||
|- | |||
| Configured cue accuracy | |||
| <code>CueReliability</code> percent | |||
|- | |||
| Block Normal probability | |||
| <code>BlockNormalProbability</code> percent | |||
|- | |||
| High reliability | |||
| <code>SensoryReliabilityCondition == 0</code> | |||
|- | |||
| Medium reliability | |||
| <code>SensoryReliabilityCondition == 1</code> | |||
|- | |||
| Low reliability | |||
| <code>SensoryReliabilityCondition == 2</code> | |||
|- | |||
| Reliability globally disabled | |||
| Verify <code>EnableSensoryReliability == 0</code> in recorded parameters; all trials then use condition 0 | |||
|- | |||
| Configured visual-noise SD | |||
| <code>SensoryNoiseStd / 100</code> pixels | |||
|- | |||
| Actual X visual noise | |||
| <code>(SensoryNoiseX - 1073741824) / 100</code> pixels | |||
|- | |||
| Actual Y visual noise | |||
| <code>(SensoryNoiseY - 1073741824) / 100</code> pixels | |||
|- | |||
| Pre-noise task-logic cursor trajectory | |||
| <code>TrueCursorX</code> and <code>TrueCursorY</code> | |||
|- | |- | ||
| | | Displayed cursor trajectory | ||
| <code> | | <code>CursorX</code> and <code>CursorY</code> | ||
|- | |- | ||
| Mapping switch | | Mapping switch | ||
| <code>MappingSwitch == 1</code> | | <code>MappingSwitch == 1</code> (subject to skip-operation caveats) | ||
|- | |- | ||
| Trials since switch | | Trials since switch | ||
| <code>TrialsSinceMappingSwitch</code> | | <code>TrialsSinceMappingSwitch</code> (subject to skip-operation caveats) | ||
|- | |- | ||
| Previous mapping | | Previous mapping | ||
| Line 1,385: | Line 2,066: | ||
| Joystick trajectory | | Joystick trajectory | ||
| <code>JoystickXpos</code> and <code>JoystickYpos</code> | | <code>JoystickXpos</code> and <code>JoystickYpos</code> | ||
|- | |- | ||
| Reaction time | | Reaction time | ||
| Line 1,397: | Line 2,075: | ||
| Total time | | Total time | ||
| <code>TotalTimeMs</code> | | <code>TotalTimeMs</code> | ||
|- | |||
| Information purchased | |||
| <code>InformationPurchased == 1</code>; onset is its rising transition and exact relative time is <code>InformationPurchaseTimeMs</code> | |||
|- | |||
| Revealed mapping | |||
| <code>InformationRevealedMapping</code>: 0 none, 1 Normal, 2 Inverted/Reversed | |||
|- | |||
| Information point cost | |||
| <code>TrialInformationCost / 100</code> | |||
|- | |||
| Initial direction error | |||
| <code>InitialDirectionErrorDeg / 100</code> degrees | |||
|- | |||
| Initial-direction penalty | |||
| <code>InitialDirectionPenaltyApplied == 1</code> | |||
|- | |||
| Mean normalized trajectory deviation | |||
| <code>TrajectoryDeviation / 1000000</code> | |||
|- | |||
| Trajectory penalty | |||
| <code>TrajectoryPenaltyApplied == 1</code> | |||
|- | |||
| Trial points | |||
| <code>TrialReward / 100</code> | |||
|- | |||
| Cumulative points | |||
| <code>CumulativeReward / 100</code> | |||
|- | |- | ||
| Manual reset | | Manual reset | ||
| <code>TrialReset == 1</code> | | <code>TrialReset == 1</code> | ||
|- | |||
| Trial skipped | |||
| <code>TrialSkipped == 1</code> | |||
|- | |||
| Current block skipped | |||
| <code>ConditionSkipped == 1</code> | |||
|- | |||
| Introduction skipped | |||
| <code>IntroductionSkipped == 1</code> | |||
|- | |||
| Sandbox skipped | |||
| <code>SandboxSkipped == 1</code> | |||
|- | |||
| Task paused | |||
| <code>TaskPaused == 1</code> | |||
|- | |- | ||
| Experiment completion | | Experiment completion | ||
| <code>TaskPhase == 7</code> | | <code>TaskPhase == 7</code> in ordinary progression; may be absent for skip-to-finish | ||
|} | |} | ||
===Event-Like States=== | ===Event-Like States=== | ||
The following | The following are designed to be one-processing-block event flags: <code>MappingSwitch</code>, <code>TargetHit</code>, <code>TrialReset</code>, <code>TrialSkipped</code>, <code>ConditionSkipped</code>, <code>IntroductionSkipped</code>, and <code>SandboxSkipped</code>. <code>MovementStarted</code> instead remains high from movement onset through the rest of the trial and Feedback. <code>TaskPaused</code> is a level state held at 1 throughout a pause. | ||
===Analysis Considerations=== | |||
<code> | * Use <code>CursorX/Y</code> for what the participant saw and <code>TrueCursorX/Y</code> for the cursor that determined hits and centering. Visual noise and display clipping can make the two disagree. | ||
* Divide cursor-state coordinates by 1023 to recover normalized coordinates. Use the provided noise-state offset and scale to recover noise in pixels. | |||
* Use the recorded parameter <code>EnableSensoryReliability</code> to distinguish a disabled manipulation from genuine High-reliability trials. | |||
* Confirm <code>EnablePredictiveCues</code>, <code>EnableRewardSystem</code>, and <code>EnableInformationSeeking</code> before interpreting zero-valued cue, point, or purchase states. | |||
* Predictive <code>CueValidity</code> describes whether the prediction matches the current actual mapping; it is not the same as sensory reliability. | |||
* Purchase time is relative to trial start and may include waiting-for-center time. A purchase preserved across manual reset belongs to one experimental trial and should not be counted twice. | |||
* Direction and trajectory metrics use the displayed cursor and may include sensory noise; hit logic uses <code>TrueCursorX/Y</code>. | |||
* Reconstruct prior mapping by inspecting previous trials; <code>PriorCondition</code> is a block context rather than a previous-trial label or inferred belief. | |||
* Check skip pulses and neighboring trial/block values when deriving event onsets. Mapping-switch pulses, trial identifiers, and <code>TaskPhase</code> may be stale or missing on early-return skip processing blocks. | |||
* Paused intervals should be identified from <code>TaskPaused</code>, and internal timing measurements exclude pause duration on resume. | |||
* If target acquisition occurs without a detected movement onset, reaction and movement timing states are zero but total time is recorded; such zero values should not automatically be interpreted as physiologically instantaneous responses. | |||
* Raw joystick reconstruction requires external input logging; the application itself does not activate <code>LogJoystick</code>. | |||
==Differences from USBHIDJoystickTask== | ==Differences from USBHIDJoystickTask== | ||
| Line 1,444: | Line 2,173: | ||
* Ordered-start condition. | * Ordered-start condition. | ||
* <code>TaskBlockType</code>. | * <code>TaskBlockType</code>. | ||
* Green versus red condition-specific targets | * Green versus red condition-specific targets and legacy automatic/controlled condition instructions. Predictive mode teaches probabilistic cue meanings instead, while targets remain black. | ||
* Condition-specific practice trials. | * Condition-specific practice trials. | ||
* <code>PracticeTrial</code>. | * <code>PracticeTrial</code>. | ||
| Line 1,459: | Line 2,186: | ||
* Six predefined experimental block roles. | * Six predefined experimental block roles. | ||
* Hidden Normal and Inverted mappings. | * Hidden Normal and Inverted mappings in the legacy design, with optional probabilistic or purchased mapping information. | ||
* Unannounced mapping switches. | * Unannounced mapping switches. | ||
* <code>MappingSwitch</code>. | * <code>MappingSwitch</code>. | ||
* <code>TrialsSinceMappingSwitch</code>. | * <code>TrialsSinceMappingSwitch</code>. | ||
* <code>PriorCondition</code>. | * <code>PriorCondition</code>. | ||
* <code> | * <code>SensoryReliabilityCondition</code> and configurable High/Medium/Low visual sensory reliability. | ||
* <code> | * Configurable Gaussian cursor noise and correlation time. | ||
* | * Separate <code>TrueCursorX/Y</code> and displayed <code>CursorX/Y</code> logging. | ||
* A | * <code>SensoryNoiseX/Y</code>, <code>SensoryNoiseStd</code>, and <code>SensoryNoiseSeedEffective</code>. | ||
* Researcher controls for skipping trial, block, introduction, and sandbox, and pausing/resuming. | |||
* <code>TrialSkipped</code>, <code>ConditionSkipped</code>, <code>IntroductionSkipped</code>, <code>SandboxSkipped</code>, and <code>TaskPaused</code> states. | |||
* Configurable <code>CursorDiameterPixels</code> and <code>TargetDiameterPixels</code> parameters. | |||
* Diagnostic real-time timing values and run averages. | |||
* A legacy Normal-mapping sandbox and optional predictive guided practice. | |||
* Black targets across all mapping conditions. | * Black targets across all mapping conditions. | ||
* Normal-dominant and approximately balanced mapping contexts. | * Normal-dominant and approximately balanced mapping contexts. | ||
* Optional probabilistic green/red mapping cues with valid/invalid trial logging. | |||
* Dedicated predictive sequence generation, mapping probabilities, cue seed, cue key, and counterbalancing. | |||
* Animated predictive-cue instruction pages and guided alternating Normal/Reversed practice. | |||
* Optional point-based performance feedback and cumulative point display. | |||
* Voluntary current-trial mapping information during center hold. | |||
* Information-purchase, direction/trajectory, penalty, and point states. | |||
==Known Limitations and Analysis Considerations== | ==Known Limitations and Analysis Considerations== | ||
| Line 1,476: | Line 2,214: | ||
* <code>PriorCondition</code> represents experimental block context rather than an inferred participant belief. | * <code>PriorCondition</code> represents experimental block context rather than an inferred participant belief. | ||
* Participant surprise or expectation is not measured directly by the application. | * Participant surprise or expectation is not measured directly by the application. | ||
* | * In the legacy design, blocks 4 and 6 use similar approximately balanced mapping-generation rules but occur after different preceding mapping histories. | ||
* | * Legacy mapping pseudorandomization constraints are attempted but are not guaranteed if all 64 candidates fail. Predictive design evaluates up to 512 candidates and uses the best scored candidate if none meets its early-stop criteria. | ||
* | * Reliability manipulation is disabled by default; <code>SensoryReliabilityCondition=0</code> by itself does not show that reliability was enabled. | ||
* | * Reliability is assigned with a counterbalancing heuristic across mapping and switch status, not by a wholly independent shuffle. | ||
* | * Gaussian noise affects the displayed cursor only during target-visible movement; it does not change the cursor position used for center and target-hit detection. | ||
* The display may visually disagree with the target-hit decision because logic uses the true pre-noise cursor. | |||
* The correlated noise process begins at zero at target onset rather than stationary variance. | |||
* The true cursor is separately recorded, but no independent pre-mapping/untransformed cursor trajectory is recorded. | |||
* The diagnostic window does not show target, joystick, cursor, switch, trials-since-switch, point, purchase, or free-form status fields; run averages are divided by Normal/Reversed mapping, not by reliability or cue validity. | |||
* <code>TargetDiameterPixels</code> changes target-hit radius; <code>CursorDiameterPixels</code> changes only cursor appearance. | |||
* Skip operations can result in stale or missing per-block values for <code>MappingSwitch</code>, <code>TaskPhase</code>, and trial/block identifiers. Skip-to-finish may not publish <code>TaskPhase=7</code>. | |||
* A block skip during Inverted target-visible movement does not explicitly preserve the anchored return mapping. | |||
* Pausing is allowed during introduction, sandbox, and feedback, and the timing system compensates for pause duration on resume. | |||
* Physical display geometry depends on the configured participant monitor and BCI2000 window dimensions. | * Physical display geometry depends on the configured participant monitor and BCI2000 window dimensions. | ||
* No application-specific CSV, JSON, text results file, or database is generated. | |||
* Predictive mapping and cue-validity percentages are rounded to integer trial counts, so small blocks may not realize exact percentages. | |||
* <code>PriorCondition</code> retains legacy category names in predictive mode; an Inverted-biased block is labeled <code>HiddenMixed</code>. Use <code>BlockNormalProbability</code> for the explicit percentage. | |||
* Cue visibility is limited to <code>HoldingCenter</code>; the cue is gone during Warning and PreTargetDelay, although the persistent color key remains. | |||
* Only current-trial purchased information (<code>InformationType=0</code>) is implemented. Values 1 and 2 are rejected, <code>InformationHorizonTrials</code> is reserved, and <code>ShowInformationPurchaseHint</code> has no effect. | |||
* Information purchasing is available only during center hold, not Warning or PreTargetDelay. | |||
* Point metrics use displayed cursor samples and processing-block timing; trajectory deviation is a sample mean rather than a path-length-weighted integral. | |||
* No unsuccessful-trial timeout exists, and points are awarded only at target acquisition. | |||
* Point feedback may lengthen Feedback beyond <code>FeedbackSeconds</code>. | |||
* No state distinguishes individual introduction pages. | |||
==References== | ==References== | ||
Friston, K. The free-energy principle: a unified brain theory?. Nat Rev Neurosci 11, 127–138 (2010). https://doi.org/10.1038/nrn2787 | |||
==See also== | ==See also== | ||
* [[VisuomotorJoystickTask|Visuomotor Joystick Task]] | |||
* [[User Reference:Logging Input|Logging Input]] | * [[User Reference:Logging Input|Logging Input]] | ||
* [[User Reference:Logging Input#LogJoystick|LogJoystick]] | * [[User Reference:Logging Input#LogJoystick|LogJoystick]] | ||
| Line 1,497: | Line 2,252: | ||
* [[Technical Reference:BCI2000 File Format|BCI2000 File Format]] | * [[Technical Reference:BCI2000 File Format|BCI2000 File Format]] | ||
* [[Programming Reference:ApplicationBase Class|ApplicationBase Class]] | * [[Programming Reference:ApplicationBase Class|ApplicationBase Class]] | ||
* [[Category:User Application]] | |||
Latest revision as of 22:43, 17 November 2026
Synopsis
FEP_VisuomotorJoystickTask is a BCI2000 application module implementing a center-out visuomotor reaching task designed to investigate how participants adapt their behavior when the relationship between their actions and sensory consequences changes unexpectedly.
Participants control a cursor using a USB HID joystick and repeatedly move from a central starting location to peripheral targets. The joystick-to-cursor mapping is treated as an environmental state: on a given trial, joystick movement may produce either a normal cursor movement or an inverted cursor movement. In the default legacy design the mapping is hidden. An optional predictive-cue design can instead present a probabilistic green or red mapping cue during center hold, and an independently configurable information-seeking feature can let the participant reveal the actual current-trial mapping.
The task was developed in the context of the Free Energy Principle (FEP) and related theories of predictive processing and active inference. In this framework, an agent maintains an internal model of the causes of its sensory observations and uses incoming evidence to update that model. When observations conflict with the agent's expectations, the agent may need to revise its estimate of the current hidden state.
The present task operationalizes this problem using a simple visuomotor environment. In the legacy design, the hidden state is the current joystick-to-cursor mapping. Participants first accumulate experience with particular mappings and mapping frequencies, creating different histories of prior exposure. The mapping can then change without warning, requiring the participant to infer from the resulting cursor behavior that the current sensorimotor relationship has changed. In the optional predictive-cue design, the mapping remains uncertain rather than wholly hidden: a configurable-validity cue predicts Normal or Reversed control but may be invalid.
The task therefore allows behavioral measurements to be related to three major features of inference:
- Prior experience: Different experimental blocks expose participants to different frequencies of Normal and Inverted mappings.
- Unexpected state changes: Mapping changes may occur between trials without an explicit visual cue.
- Behavioral updating: Reaction time, movement time, total time, and cursor trajectory may be examined following mapping switches and across subsequent trials.
- Predictive evidence: When enabled, trial-wise color cues provide configurable, sometimes-invalid evidence about the upcoming mapping.
- Voluntary information seeking: When enabled, participants may reveal the actual current-trial mapping during center hold, optionally at a point cost.
The experiment also includes a configurable visual sensory-reliability manipulation. On selected trials, Gaussian spatial noise perturbs the displayed cursor without changing the task-logic cursor position. High reliability has no visual noise; Medium and Low reliability use configurable noise amplitudes. This is a visual-feedback noise manipulation, not a cursor-gain manipulation.
Importantly, the software does not itself compute free energy, prediction error, posterior probability, Bayesian belief, or another formal FEP quantity. Instead, it creates a controlled hidden-state visuomotor task whose behavioral and neural data may be used to investigate questions motivated by those theories.
The current implementation includes:
- Normal and inverted joystick-to-cursor mappings.
- Unannounced mapping changes between trials.
- Six sequential experimental block roles with different mapping frequencies.
- High, Medium, and Low visual sensory-reliability conditions with configurable Gaussian cursor noise (disabled by default).
- An optional six-block predictive-cue design with configurable mapping probabilities, cue accuracy, color assignment, sequence seed, and biased-block counterbalancing.
- Predictive-cue instruction animations and guided Normal/Reversed practice when the predictive design is enabled.
- An optional points system with configurable initial-direction, trajectory-deviation, and information-cost deductions.
- Optional voluntary purchase of current-trial mapping information during center hold.
- Mapping-switch, prior-condition, and trials-since-switch state logging.
- A two-page legacy participant introduction, or predictive-cue instruction animations when those animations are enabled.
- A Normal-mapping free-movement sandbox in legacy operation, or optional guided alternating Normal/Reversed practice in predictive-cue operation.
- Reaction-time, movement-time, total-time, displayed and true cursor, joystick (when logging is enabled), target, mapping, predictive cue, reliability, noise, information-purchase, point-performance, and researcher-control states in the BCI2000 data stream.
- Experimenter controls for resetting, skipping, pausing, and resuming the task.
Mapping switches are not announced as switch events. In legacy operation the mapping remains hidden unless current-trial information is purchased. In predictive-cue operation a color predicts the mapping but does not guarantee it, and a persistent on-screen key explains the color assignment. The participant is not shown block identity, block transitions, numerical mapping probabilities, cue-validity labels, or sensory-reliability labels. Visual noise may nevertheless be perceptible.
Location
Upon completion of an SVN update or checkout of the relevant source tree, the current FEP Visuomotor Joystick Task is located in:
src/custom/FEP_VisuomotorJoystickTask/
The main implementation is contained in:
FEP_VisuomotorJoystickTask.cpp
with the corresponding header and build configuration in:
FEP_VisuomotorJoystickTask.hCMakeLists.txt
Optional-feature example parameter overlays are provided as:
PredictiveCuesExample.prmRewardInformationExample.prm
The application is included from:
src/custom/CMakeLists.txt
The current CMake target is:
FEP_VisuomotorJoystickTask_custom
The module uses NOBUNDLE in its bci2000_add_application_module declaration. Its Windows executable is typically named:
FEP_VisuomotorJoystickTask_custom.exe
A separate src/custom/FEP_VisuomotorJoystickTask_pacing_test/ diagnostic module is also included in the custom build. That module is for investigating a rendering/pacing issue and is not the experimental task.
Versioning
Author
Alexander Speer
Friedman Lab, Department of Neurosurgery
Washington University in St. Louis
Developed in the Friedman Lab.
Contact: speer@wustl.edu
Revision History
New version: 17 November 2026 — source revision 7b90a64
This revision adds the optional predictive-cue six-block design. Green/red center cues predict Normal or Reversed control with configurable conditional accuracy; the actual mapping, cue prediction, validity, block Normal probability, cue visibility/onset, and effective cue seed are recorded. Predictive operation adds dedicated trial-count and mapping-probability parameters, optional counterbalancing of the two biased block configurations, animated cue instructions, guided alternating Normal/Reversed practice, a persistent cue key, and predictive fields in the researcher diagnostics. The same revision includes the independently configurable points and information-seeking systems introduced after the prior documentation: current-trial mapping may be revealed during center hold, completed trials may be scored from initial-direction, trajectory, and information-cost deductions, and trial/cumulative points and supporting measurements are recorded. Predictive cues, points, information seeking, and sensory-reliability noise are each disabled by default.
The current documented source revision is Git commit 7b90a64. This commit identifier is the implementation revision number; the module still does not declare an independent semantic or numeric application version.
Version: 5 November 2026 — points and information seeking
This implementation revision added independently configurable point-reward and voluntary information-seeking systems, a second participant introduction page, fixed-point point/performance states, and optional trial and cumulative point feedback. It removed the center-hold purchase prompt; the introduction explains purchasing instead. These systems are disabled by default.
New version: 19 October 2026
This updated version replaces the earlier Normal/High cursor-gain manipulation with configurable High/Medium/Low visual sensory reliability; introduces temporally correlated Gaussian cursor noise and separate true-versus-displayed cursor states; adds researcher controls for skipping trials, blocks, introduction, and sandbox and for pausing/resuming; adds associated BCI2000 event and reliability states; provides configurable cursor and target diameters; and redesigns the diagnostic window to show real-time timings and run averages. The experimental mapping and six block roles remain in place. The current build uses the FEP_VisuomotorJoystickTask_custom target.
No independent semantic version identifier is declared in the module. The current FEP task is maintained under src/custom and is tracked by the surrounding Git repository.
An earlier inspected BCI2000 build was produced using:
- BCI2000 framework 3.6.9535
- BCI2000 source revision 9535
- Visual Studio 2022 / MSVC 19.35
- Release x64 configuration
These values refer to an inspected BCI2000 build containing the module, not to an independently verified revision number of the current FEP task.
Scientific Motivation
Free Energy Principle
The Free Energy Principle proposes that biological agents maintain internal models of the causes of their sensory inputs and continually update those models in order to reduce discrepancies between predicted and observed sensory states.
A useful way to interpret the present task is as a hidden-state inference problem.
The participant directly observes:
- Joystick movement.
- Cursor movement.
- Target position.
- The sensory consequences of each movement.
- A green/red mapping prediction during center hold when predictive cues are enabled.
- The actual mapping text after an optional information purchase, when information seeking is enabled and used.
The participant is not directly told:
- Which joystick-to-cursor mapping is currently active in uncued legacy trials; predictive cues provide uncertain evidence rather than certainty.
- Whether the mapping has changed.
- The numerical probability of a mapping occurring.
- The current experimental block.
- Whether visual sensory reliability has changed.
In legacy operation the current mapping therefore acts as a hidden environmental state that must be inferred from the relationship between action and observed cursor movement. Predictive cues and purchased mapping information are optional experimental sources of evidence about that state.
For example, after many Normal trials, a participant may expect the cursor to move in the same direction as the joystick. If the next trial unexpectedly uses the Inverted mapping, the observed cursor movement conflicts with that expectation. Subsequent behavior can then be examined to determine how rapidly the participant adjusts to the new mapping.
Why the Task Was Developed
The task was designed to create an experimentally controlled situation in which prior experience and new sensory evidence can come into conflict.
Several aspects of the experiment make this possible.
First, the frequency of Normal and Inverted mappings changes across blocks. This changes the participant's recent history of mapping exposure.
Second, mapping changes are not announced. Participants therefore cannot simply follow an explicit instruction telling them which mapping to use.
Third, the task records the exact trials on which the mapping changes and the number of trials that have occurred since the most recent switch.
This makes it possible to compare behavior:
- Before and after an unexpected mapping change.
- On switch versus non-switch trials.
- Across successive trials following a switch.
- Under different histories of Normal and Inverted mapping exposure.
- Under High, Medium, and Low visual sensory reliability (when enabled).
- Following valid versus invalid predictive cues and under different block mapping probabilities (when predictive cues are enabled).
- With versus without voluntary mapping-information purchase (when information seeking is enabled).
The task can therefore be used to investigate how prior experience influences behavioral adaptation to unexpected changes in sensorimotor contingencies.
Implementation Versus Theory
The current application implements the experimental manipulations required for this type of analysis, but it does not contain an explicit computational model of the participant.
In particular, the software does not calculate:
- Variational free energy.
- Prediction error.
- Posterior probability.
- Belief distributions.
- Bayesian surprise.
- Learning rate.
- Adaptation score.
These quantities, if used, must be estimated during offline behavioral or neural analysis.
Predictive Cues
The optional predictive-cue design changes the task from a completely uncued hidden-state problem into inference from probabilistic evidence. During center hold, the center marker becomes green or red. The color predicts Normal or Reversed control according to CueColorAssignment, but the prediction is valid only at the configured CueAccuracyPercent. Validity is allocated separately within actual Normal and actual Inverted trials, so cue accuracy is conditional on mapping rather than merely an overall proportion.
The participant sees a persistent key identifying the green and red meanings during the experiment, but is not shown whether a particular cue is valid, the numerical cue accuracy, or the block's numerical Normal probability. This permits comparison of behavior following valid and invalid evidence and across balanced, Normal-biased, and Inverted-biased mapping contexts.
Information Seeking and Point Tradeoff
The independently optional information-seeking system allows participants to reveal the actual current-trial mapping during center hold. When the points system is also enabled, this information has a configurable point cost. A participant may preserve the full potential trial value and act using prior experience, predictive evidence, and cursor feedback, or spend points to display NORMAL or REVERSED before target onset.
The application records purchase behavior and point performance, but it does not compute information value, expected utility, risk preference, epistemic value, or an active-inference policy. Those quantities require offline analysis.
Functional Description
Mapping Conditions
The FEP task uses two joystick-to-cursor mappings:
TaskCondition
|
Mapping | Description |
|---|---|---|
| 0 | Normal | Joystick displacement moves the cursor in the corresponding direction. |
| 1 | Inverted | Joystick displacement moves the cursor in the opposite direction on both axes. |
In the legacy design the current mapping is not automatically indicated. Predictive operation provides a possibly invalid mapping prediction during center hold. A successful information purchase displays the actual mapping. Neither feature changes the mapping transformation itself.
Unlike the earlier USBHIDJoystickTask, the FEP task does not use the terms Automatic and Controlled in its implementation.
Behavioral Measurements
The task records information that may be used to examine:
- Reaction time.
- Movement time.
- Total target-acquisition time.
- Cursor trajectory.
- Initial movement direction.
- Trajectory curvature.
- Performance immediately following a mapping switch.
- Performance as a function of trials since the previous switch.
- Effects of different mapping-frequency contexts.
- Effects of High, Medium, and Low visual sensory reliability when the manipulation is enabled.
- Differences between true and displayed cursor trajectories under visual noise.
Experiment Structure
Each run proceeds in the following order:
- Participant introduction (unless skipped by the researcher): two text pages in legacy operation, or two animated cue pages and a timed practice-transition page when predictive cues and introduction animation are enabled.
- Joystick sandbox: free movement in legacy operation, or guided cue practice when predictive cues and guided sandbox are enabled.
- Experimental block 1, if enabled.
- Experimental block 2, if enabled.
- Experimental block 3, if enabled.
- Experimental block 4, if enabled.
- Experimental block 5, if enabled.
- Experimental block 6, if enabled.
- Experiment completion.
Experimental block transitions are not announced to the participant. Skipping the introduction using the researcher window enters the experiment directly and also bypasses the sandbox. Trial and block skipping can change which trials are actually performed. The active trial-count family is selected by EnablePredictiveCues; the inactive family does not contribute trials.
Each experimental trial proceeds as follows:
- The participant returns the cursor to the center.
- The participant holds the cursor within the center region.
- In predictive-cue operation, the center is colored during the hold to predict the mapping.
- During the hold, the participant may optionally purchase the actual mapping when information seeking is enabled.
- A yellow warning cue appears.
- A pre-target delay occurs.
- A peripheral target appears.
- The participant moves the cursor toward the target.
- The target is acquired.
- Point-performance values are finalized when the points system is enabled.
- A feedback interval occurs; optional point feedback is displayed.
- The task advances to the next trial.
Introduction
The introduction behavior depends on the predictive-cue settings.
Legacy Text Introduction
When predictive cue animation is not active, page 1 is titled HOW TO PLAY and explains joystick control, returning to and holding in the gray center circle, and moving to the target. Page 2 is generated from the enabled optional features. It explains potential points and straight/accurate movement when rewards are enabled, explains green/red predictions when predictive cues are enabled without animation, and explains optional current-trial mapping purchase when information seeking is enabled. If none of those systems is enabled, it simply instructs the participant to complete each trial by moving to the target.
Page 1 ends with Press the joystick button to continue.; page 2 ends with Press the joystick button to practice.. Separate rising button presses are required, so holding the button cannot advance through both pages.
Predictive Animated Introduction
When EnablePredictiveCues=1 and EnableIntroductionAnimation=1, two animated pages replace the legacy text pages. One page demonstrates the green cue and the other the red cue. Each identifies the mapping predicted by that color, animates cursor movement and—when configured—a joystick illustration, and requires a rising joystick-button press to advance. The examples alternate between diagonal and rightward targets when looping. After the two cue pages, a Time to practice screen advances automatically after IntroductionPracticeScreenDurationMs.
During either introduction form:
Introduction=1TutorialPhase=1TaskPhase=0- The progress bar is hidden.
The legacy text pages hide the cursor, center, warning, target, and cross. The animated pages instead draw the demonstration cursor, center cue, target, cross, and optional joystick illustration.
A rising press of JoystickButtons1 advances each eligible introduction page. The experimenter may instead select SKIP INTRODUCTION (with confirmation), which enters the experiment directly and bypasses the sandbox. There is no state that identifies the individual introduction page.
The participant is not told about:
- The actual current-trial mapping. Predictive instruction pages do teach the cue-to-mapping meanings when enabled, and purchased information may reveal the actual mapping later.
- Mapping switches.
- Changes in visual sensory reliability.
- Experimental blocks.
- Prior conditions.
Sandbox
After the introduction, the participant enters either a free-movement sandbox or guided predictive-cue practice.
Legacy Free-Movement Sandbox
The participant sees:
- A black cursor.
- A gray center marker.
- A black center cross.
- No peripheral target.
- No warning cue.
- No progress bar.
The participant is shown:
Practice moving the cursor with the joystick. When you are ready to begin, return the cursor to the center and press the joystick button.
During the sandbox:
Introduction=1TutorialPhase=2TaskPhase=0TaskBlock=0TaskTrial=0TaskCondition=0- Normal direct mapping is used.
- There is no gain manipulation; the sandbox uses direct Normal mapping without visual noise.
- No targets are generated.
- No experimental timing phases occur.
The sandbox ends when both of the following conditions are satisfied:
- The cursor is inside the center tolerance region.
- A new joystick-button press occurs.
Because continuation uses rising-edge detection, the participant must release the button after leaving the introduction screen before pressing it again to leave the sandbox. The researcher can also select SKIP SANDBOX to enter the experiment.
Guided Predictive-Cue Sandbox
When EnablePredictiveCues=1 and EnableGuidedSandbox=1, the sandbox instead runs GuidedSandboxTrials practice trials (default 3) to a fixed rightward black target. Practice mappings alternate Normal, Reversed, Normal, and so forth. Each trial uses the normal center-hold, yellow warning, pre-target delay, target-visible, and feedback phases. During center hold, the center color predicts the practice mapping and on-screen text repeats the color meaning. Reversed practice uses the same anchored inversion and return-to-anchor behavior as the experiment.
Guided practice is not an experimental block: Introduction=1, TutorialPhase=2, TaskBlock=0, TaskTrial=0, and cue states remain 0. TaskPhase does reflect phases 1 through 6 during guided practice. After all practice targets are acquired, the participant must return to center and press the joystick button to begin the experiment. SKIP SANDBOX bypasses the remaining practice.
When the sandbox finishes:
Introductionbecomes 0.TutorialPhasebecomes 0.TaskPhasebecomes 1.- Experimental block and trial states become active.
Experimental Blocks
The task contains two alternative six-block designs selected by EnablePredictiveCues. It is 0 by default, which preserves the legacy design and its random-number-generator behavior.
Legacy Six-Block Design
There is no ExperimentMode parameter.
A block may be omitted by setting its trial-count parameter to 0.
TaskBlock retains the original block-role number, so block numbers may skip values when one or more blocks are disabled.
| Block | Trial-count parameter | PriorCondition
|
Mapping composition |
|---|---|---|---|
| 1 | BaselineTrials
|
0, Fixed | 100% Normal |
| 2 | InitialInvertedTrials
|
0, Fixed | 100% Inverted |
| 3 | ReturnNormalTrials
|
0, Fixed | 100% Normal |
| 4 | MixedTrials
|
1, HiddenMixed | Approximately 50% Normal and 50% Inverted |
| 5 | StrongPriorTrials
|
2, StrongNormal | Approximately 90% Normal and 10% Inverted |
| 6 | BalancedPriorTrials
|
3, Balanced | Approximately 50% Normal and 50% Inverted |
Blocks 4 and 6
For blocks 4 and 6:
floor(N/2)trials are assigned the Inverted mapping.- All remaining trials are assigned the Normal mapping.
- If the number of trials is odd, the additional trial is Normal.
Block 5
Block 5 contains a strongly Normal-dominant mapping distribution.
Approximately 10% of trials are assigned the Inverted mapping, using a rounded fixed trial count.
The remaining trials are Normal.
This is not implemented as an independent 10% switch probability on each trial.
Pseudorandomization
For blocks 4 through 6, mapping order is pseudorandomized.
The task attempts up to 64 candidate shuffles.
A candidate is preferred when:
- It does not strictly alternate throughout sequences of at least four trials.
- It does not contain excessively long runs of one mapping.
The preferred maximum run length is:
max(3, unavoidableRun + 1)
where:
unavoidableRun = (majority + minority) / (minority + 1)
using integer division.
If no candidate satisfies the constraints after 64 attempts, the final generated sequence is used.
After the mapping sequence is generated, sensory-reliability conditions are assigned separately using a dedicated random generator. Rather than an independent shuffle, the assignment algorithm attempts to counterbalance reliability categories across Normal/Inverted mappings and mapping-switch/non-switch trials while preserving the configured counts. Reliability assignment does not alter the mapping order. See Sensory Reliability.
Predictive-Cue Six-Block Design
When EnablePredictiveCues=1, the six legacy trial-count parameters above are inactive and the following design is used:
| Block | Trial-count parameter | Default trials | Default Normal probability | Cue |
|---|---|---|---|---|
| 1 | PredictiveBlock1Trials
|
20 | 100% | None |
| 2 | PredictiveBlock2Trials
|
10 | 0% (100% Reversed) | None |
| 3 | CuedBlock3Trials
|
40 | CuedBlock3NormalProbabilityPercent (50%)
|
Predictive |
| 4 | CuedBlock4Trials
|
40 | CuedBlock4NormalProbabilityPercent (75%)
|
Predictive |
| 5 | CuedBlock5Trials
|
40 | CuedBlock5NormalProbabilityPercent (25%)
|
Predictive |
| 6 | CuedBlock6Trials
|
40 | CuedBlock6NormalProbabilityPercent (50%)
|
Predictive |
The Normal count in each cued block is round(trials * NormalProbabilityPercent / 100); remaining trials are Reversed. For each actual mapping separately, the valid-cue count is round(mappingCount * CueAccuracyPercent / 100). A valid cue predicts the actual mapping and an invalid cue predicts the opposite mapping. Rounding means small blocks may not realize the percentages exactly.
The sequence generator uses a dedicated std::mt19937 seeded by CueRandomSeed. It evaluates up to 512 shuffled candidates, penalizing long mapping runs, long predicted-cue runs, strict mapping alternation, and strict cue alternation. It stops early when both maximum run lengths are at most 3 and neither sequence strictly alternates; otherwise it uses the best scored candidate. This algorithm is separate from the legacy 64-attempt pseudorandomization.
When CounterbalanceBiasedBlockOrder=1, the complete configured block-4 and block-5 definitions—their trial counts and Normal probabilities—are swapped before assignment to physical block roles 4 and 5. Blocks 3 and 6 are not swapped. Disabled predictive blocks retain no trials, and TaskBlock may therefore skip role numbers.
Predictive-Cue Display and Timing
Blocks 1 and 2 have no predictive cue. In blocks 3 through 6, entering HoldingCenter changes the center marker to the cue color. The cue disappears when the task leaves center hold; the later yellow warning does not retain the cue color. A persistent upper-left key shows the configured green and red mapping meanings throughout the experimental stage, including uncued blocks 1 and 2.
CueOnsetTimeMs is measured from trial start to the first entry into center hold. If center hold is broken and restarted, the onset time is not replaced. Manual trial reset clears it, while pause compensation shifts its internal timestamp. Cue display does not alter the center-hold duration or mapping.
Prior Conditions
PriorCondition represents the mapping-frequency context associated with the current block.
It does not represent the immediately preceding trial's mapping.
| Value | Name | Legacy-design meaning |
|---|---|---|
| 0 | Fixed | Fixed-mapping context used in blocks 1 through 3. |
| 1 | HiddenMixed | Approximately balanced hidden mapping context used in block 4. |
| 2 | StrongNormal | Strongly Normal-dominant mapping context used in block 5. |
| 3 | Balanced | Approximately balanced mapping context used in block 6. |
The mapping used on the preceding trial may be determined offline from the previous trial's TaskCondition.
In predictive-cue operation, fixed blocks 1 and 2 use PriorCondition=0. Cued blocks are classified from their configured Normal percentage: exactly 50% gives Balanced (3), greater than 50% gives StrongNormal (2), and less than 50% gives HiddenMixed (1). Thus the legacy names are retained even for an Inverted-biased predictive block; use BlockNormalProbability for the explicit percentage.
Joystick Input
Joystick input is provided through BCI2000's input logging system.
The application reads:
JoystickXposJoystickYposJoystickButtons1
JoystickButtons1 advances the introduction and exits the completed sandbox. Information purchasing uses the one-based state selected by InformationPurchaseButton, forming a name such as JoystickButtons2. It may be the same as JoystickButtons1. The selected state must exist during preflight.
Joystick X and Y values normally range from 0 through 32767.
Each axis is converted into the task's 0-through-1023 coordinate system:
taskJoystick = round(BCIJoystick * 1023 / 32767)
The converted value is normalized internally:
rawPosition = taskJoystick / 1023
The FEP application does not itself enable joystick logging.
Joystick logging should therefore be enabled using BCI2000's LogJoystick option.
See LogJoystick.
Joystick-to-Cursor Mapping
Before target onset, cursor position normally follows direct absolute joystick position:
cursorX = rawX cursorY = rawY
The mapping transformation used for target-directed movement is activated at target onset. The code defines no HighCursorGain parameter, no CursorGainCondition state, and no high-gain movement condition in this version.
Anchor Capture
When the target appears, the application stores:
- Current joystick X position.
- Current joystick Y position.
- Current cursor X position.
- Current cursor Y position.
- Current mapping direction (
+1for Normal or-1for Inverted).
These values form the anchor for transformed movement. Because joystick displacement relative to the anchor is initially zero, activating the transformed mapping does not cause an immediate cursor jump.
Normal Mapping
With Normal mapping, the cursor follows the joystick directly:
cursorX = joystickX / 1023 cursorY = joystickY / 1023
Inverted Mapping
After target onset on an Inverted trial:
cursorX = anchorCursorX - (joystickX - anchorJoystickX) / 1023 cursorY = anchorCursorY - (joystickY - anchorJoystickY) / 1023
Both axes are inverted. Cursor coordinates are constrained to the normalized range [0, 1]. While returning from a preceding anchored Inverted trial, that preceding transformation may remain active until the joystick returns to its stored anchor.
The cursor position resulting from mapping and clipping, but before sensory noise, is called the true cursor. Sensory noise perturbs only the displayed cursor.
Sensory Reliability
The current implementation manipulates visual sensory reliability using trial-wise Gaussian spatial noise added to the displayed cursor. This replaces the cursor-gain manipulation described in earlier versions. Sensory reliability is disabled by default (EnableSensoryReliability=0).
Reliability Conditions
SensoryReliabilityCondition
|
Condition | Visual-noise standard deviation | Description |
|---|---|---|---|
| 0 | High | 0 pixels | Noise-free visual cursor |
| 1 | Medium | MediumReliabilityNoiseStd (default 5 pixels)
|
Gaussian cursor-position noise |
| 2 | Low | LowReliabilityNoiseStd (default 15 pixels)
|
Larger Gaussian cursor-position noise |
The noise standard deviations are specified in reference-display pixels, normalized using the task's nominal 1000 by 750 coordinate system. Noise affects only the cursor during the TargetVisible phase; the target, center marker, warning marker, cross, and joystick input are not perturbed.
Enabling Reliability by Block
When EnableSensoryReliability=0, all trials use High reliability and no visual noise is applied, regardless of the requested proportions or block list. Therefore, SensoryReliabilityCondition=0 does not by itself establish that reliability manipulation was enabled.
When enabled, reliability conditions are assigned only within the numbered blocks listed in SensoryReliabilityBlocks, which defaults to blocks 4, 5, and 6. Blocks not listed always use High reliability. The block list may instead select any subset of the six block roles. A block disabled by setting its trial count to zero has no trials to assign.
Reliability Assignment and Counterbalancing
For each enabled block, counts for High, Medium, and Low trials are calculated from the configured proportions by taking their floors and distributing remaining trials according to the largest fractional remainders. The result matches the block's total trial count.
The application then uses a dedicated std::mt19937 generator to assign those conditions in a randomized trial order. The selection score favors counterbalancing reliability across (1) Normal versus Inverted mapping and (2) mapping-switch versus non-switch trials, subject to the remaining required condition counts. Thus reliability assignment is not a wholly independent shuffle of the mapping sequence. Exact balance in small blocks or uneven sequences is not guaranteed.
Reliability is assigned after the Normal/Inverted mapping sequence has been built and does not change that sequence. Only mapping changes, not reliability changes, generate MappingSwitch events. The dedicated noise/assignment seed is distinct from BCI2000's mapping/target random-number generator.
The configured proportions default to 0.34 High, 0.33 Medium, and 0.33 Low, and their sum must equal 1 within 1e-6. Low-reliability noise SD must be at least Medium-reliability noise SD.
X and Y noise are generated from independent Gaussian innovations and evolved over processing updates as:
a = exp(-elapsedSeconds / correlationTimeSeconds) noiseX = a * previousNoiseX + SD * sqrt(1 - a*a) * N_X(0,1) noiseY = a * previousNoiseY + SD * sqrt(1 - a*a) * N_Y(0,1)
The temporal correlation time is set by SensoryNoiseCorrelationTimeMs (default 100 ms); a value of zero produces independent innovations on each update. Each trial's noise generator is initialized from the effective seed and trial/block identity. Noise begins at zero at target onset, so the process builds up rather than beginning with stationary variance. Noise is cleared when the task leaves the target-visible phase and on trial reset or skip.
The displayed cursor is calculated as:
displayedX = clamp(trueX + noiseX / 1000, 0, 1) displayedY = clamp(trueY + noiseY / 750, 0, 1)
The true cursor is used for center detection and target-hit detection. Movement onset is detected from joystick movement. Therefore a displayed cursor that appears to touch the target is not necessarily counted as a hit, and a true cursor that reaches the target can register a hit despite noise displacing the displayed cursor away from it.
Noise Seeds and State Encoding
SensoryNoiseSeed defaults to 1. Setting it to 0 selects an automatically generated effective seed, recorded in SensoryNoiseSeedEffective and reported in the BCI2000 operator log.
Noise values are stored as positive integer states with an offset to represent negative noise; the configured SD is stored in hundredths of a pixel:
noiseX_pixels = (SensoryNoiseX - 1073741824) / 100 noiseY_pixels = (SensoryNoiseY - 1073741824) / 100 noiseSD_pixels = SensoryNoiseStd / 100
The recorded TrueCursorX/Y and CursorX/Y coordinates are quantized to the task's 0–1023 range. The noise states represent the generated visual perturbation before final boundary clipping; consequently, the difference between displayed and true coordinates may not equal the encoded noise exactly near display edges.
Important: TrueCursorX/Y is post-mapping, pre-noise position, not a pre-mapping/raw joystick trajectory. The raw joystick trajectory is available from logged joystick input states.
Information Seeking
Information seeking is disabled by default (EnableInformationSeeking=0) and is independent of predictive cues, sensory reliability, and the points system.
Availability and Trigger
A purchase is accepted only while all of the following are true:
- The task is in the experimental stage and
TaskPhase=2(HoldingCenter). - The true/task-logic cursor remains inside the center tolerance.
- A rising edge occurs on the
JoystickButtonsNstate selected byInformationPurchaseButton. - The configured purchase window has not expired.
- No information has already been purchased for the trial.
InformationPurchaseWindowMs=0 permits purchasing throughout an uninterrupted center hold. A nonzero value is measured from entry into HoldingCenter. Leaving and re-entering center starts a new hold and purchase-window timer unless a purchase already occurred. A purchase does not reset, pause, or extend center hold. Presses during other phases, tutorial/sandbox operation, or pause are not purchases. A held button cannot create repeated purchases.
Revealed Information
Only InformationType=0 is implemented. It reveals the actual mapping already assigned to the current trial as NORMAL or REVERSED; it is not inferred from the previous trial and remains correct even when a predictive cue is invalid. The text appears in the top display area until target onset. A nonzero InformationDisplayDurationMs may hide it sooner.
Published values 1 (future trials) and 2 (block mapping) are reserved but rejected by preflight. InformationHorizonTrials is also reserved and has no runtime effect. ShowInformationPurchaseHint is a deprecated compatibility parameter with no runtime effect; no center-hold purchase prompt is drawn.
InformationPurchaseTimeMs is relative to experimental trial start, not center-hold onset. It can therefore include waiting-for-center time. Compensated pause duration is excluded.
Interaction with Reset, Skip, and Points
A manual reset repeats the same trial and preserves an existing purchase, revealed mapping, purchase time, and point cost; it does not charge twice. A skipped trial or block awards no points and clears trial-specific information accounting when the next trial becomes active. When information seeking is enabled without points, purchases and their states still work and TrialInformationCost is recorded, but no trial or cumulative points are calculated.
Points System
The points system is disabled by default (EnableRewardSystem=0). When enabled, each successfully acquired, non-skipped trial begins with BaseTrialReward potential points and is scored as:
TrialReward = max(
0,
BaseTrialReward
- applied initial-direction penalty
- applied trajectory penalty
- purchased-information cost)
The default base value is 10 points; initial-direction and trajectory penalties default to 3 points each, and information cost defaults to 2 points. Parameter values may be fractional. State encodings use hundredths of a point.
Initial-Direction Penalty
Initial direction is measured from participant-visible displayed-cursor displacement. Measurement starts at the target-onset cursor anchor and ends after InitialDirectionWindowMs from detected movement onset, or at the latest available displayed position if the target is acquired sooner. Error is the unsigned 0–180 degree angle between that displacement and the anchor-to-target vector. Zero displacement is treated as 180 degrees. The penalty applies only when error is strictly greater than InitialDirectionThresholdDeg (default 45 degrees).
Trajectory Penalty
After movement onset, each displayed-cursor sample contributes its perpendicular distance from the ideal normalized center-to-target line, divided by center-to-target distance. TrajectoryDeviation is the arithmetic sample mean. The penalty applies only when this mean is strictly greater than TrajectoryDeviationThreshold (default 0.20). Because both performance metrics use the displayed cursor, sensory noise can affect point penalties even though target-hit logic uses the true cursor. The trajectory metric is a processing-sample mean, not a path-length-weighted integral.
Feedback and Cumulative Points
At target acquisition, point values are finalized and immediately added to CumulativeReward. During Feedback, the top text area displays + N points, with unnecessary trailing zeros removed. When rewards are enabled, Feedback lasts the greater of FeedbackSeconds and RewardFeedbackDurationMs / 1000; with defaults this is 1 second. No additional task phase is introduced.
When ShowCumulativeReward=1, the participant display also shows Total: N points. The cumulative state is maintained even when that display is disabled, persists across ordinary trials, and resets at run start. Skipped and unfinished trials do not award points.
Return-to-Anchor Behavior
After an Inverted trial, the previous transformed mapping may temporarily remain active while the participant returns the joystick toward its previous anchor.
The stored transformation is released once both joystick axes are within 8 task-coordinate units of the previous joystick anchor.
Normal direct mapping is then restored for ordinary centering.
This behavior reduces abrupt cursor jumps between transformed target movement and subsequent centering. It is also engaged when an in-progress Inverted trial is skipped or when an Inverted trial is reset during target-visible movement. Skipping an entire block does not explicitly engage this return path, so direct mapping may be restored immediately in that case.
Mapping Switches
A mapping switch occurs when:
next trial TaskCondition != completed trial TaskCondition
Mapping switches occur only at trial boundaries. Changes in sensory reliability alone do not produce mapping-switch events.
They do not occur:
- During target-directed movement.
- During the Feedback phase before the feedback interval ends.
The new mapping is selected when the task advances into the next trial.
MappingSwitch
MappingSwitch is an event-like state.
It is:
- 1 on the processing block that advances into a new trial whose mapping differs from the completed trial.
- 0 on the following processing block.
- 0 when no mapping change occurred.
It should therefore be interpreted as a one-processing-block pulse.
TrialsSinceMappingSwitch
TrialsSinceMappingSwitch records how many consecutive no-switch trial transitions have occurred since the most recent mapping change.
Behavior is:
- First experimental trial: 0.
- First trial following a mapping switch: 0.
- Next same-mapping trial: 1.
- Next same-mapping trial: 2.
- And so forth.
Because the first experimental trial also begins at 0, TrialsSinceMappingSwitch==0 by itself does not identify a switch.
Use MappingSwitch or a transition in TaskCondition to identify mapping changes. When skip controls are used, event states can be stale or missing for a processing block; compare adjacent trials and consult the skip-state guidance below.
Example
Consider the following mapping sequence:
Normal -> Normal -> Inverted -> Inverted
Within block 4, the corresponding states would behave approximately as follows:
| Trial | TaskCondition
|
MappingSwitch
|
TrialsSinceMappingSwitch
|
PriorCondition
|
|---|---|---|---|---|
| Normal | 0 | 0 | Depends on previous trial history | 1 |
| Normal | 0 | 0 | Previous value + 1 | 1 |
| Inverted | 1 | 1 on the transition processing block | 0 | 1 |
| Inverted | 1 | 0 | 1 | 1 |
Target Generation
A new target angle is generated for each new experimental trial.
TargetAngle ranges from:
0 through 3599
The value represents tenths of a degree:
angle in degrees = TargetAngle / 10
Targets therefore span:
0.0 through 359.9 degrees
Target coordinates are generated according to:
TargetX = 0.5 + 0.3 * cos(angle) TargetY = 0.5 + 0.4 * sin(angle)
The unequal normalized X and Y radii correspond to an approximately circular 300-pixel radius in the nominal 1000 by 750 design.
Targets:
- Are black.
- Are visually identical across all mapping conditions.
- Are visually identical across reliability conditions.
- Are not determined by mapping condition.
- Are not determined by reliability condition.
- Are not determined by mapping-switch status.
- May repeat.
- Are not explicitly angularly balanced.
- Do not appear during the introduction.
- Do not appear during the sandbox.
A new target is generated:
- For the first experimental trial.
- After each completed non-final trial.
Resetting a trial does not generate a new target. Advancing after a skipped trial generates a new target; skipping the remaining trials of a block may consume multiple target generations and change the subsequent target sequence.
Trial Phases
The current experimental phase is stored in TaskPhase.
| Value | Phase | Description | Participant display |
|---|---|---|---|
| 0 | Introduction / Sandbox | No active experimental trial | Introduction text or sandbox |
| 1 | WaitingForCenter | Waiting for cursor to enter the center region | Cursor, gray center, cross |
| 2 | HoldingCenter | Required uninterrupted center hold | Cursor, center, cross; the center is the predictive cue color on cued trials. Purchased mapping text may appear. No purchase prompt is shown. |
| 3 | Warning | Warning interval | Cursor, yellow warning marker, cross; unexpired purchased mapping text may remain |
| 4 | PreTargetDelay | Delay immediately before target appearance | Cursor, gray center, cross; unexpired purchased mapping text may remain |
| 5 | TargetVisible | Target-directed movement | Cursor, black target, cross |
| 6 | Feedback | Post-acquisition interval | Cursor and cross; + N points when rewards are enabled
|
| 7 | Finished | Experiment complete | End message |
An experimental target onset may be identified by a transition into:
TaskPhase == 5
Movement onset may be identified by a rising transition of:
MovementStarted
Target acquisition is identified by:
TargetHit == 1
Center and target-hit testing use the true, pre-noise cursor, not the displayed noisy cursor. During a skip operation, TaskPhase and related trial states may remain stale because the normal state-update path is bypassed. In particular, a skip directly to completion may not record TaskPhase=7.
Participant Display
The participant-facing window contains:
- A light background.
- A black cursor (diameter configurable with
CursorDiameterPixels). - A black central cross.
- A gray center marker.
- A larger yellow warning marker.
- A black peripheral target (diameter configurable with
TargetDiameterPixels). - An experimental progress indicator.
- Introduction and sandbox instructions in dark text on the light participant-window background.
- Predictive cue instruction animations and an optional joystick illustration.
- A persistent green/red cue key during predictive-cue experiments.
- Optional purchased-mapping text, trial point feedback, and cumulative points.
- An experiment-completion message.
The participant receives no mapping-switch event, validity label, reliability label, PriorCondition, block/trial number, block transition, or numerical mapping probability. Predictive cues provide probabilistic mapping information when enabled, and purchased information provides the actual mapping when requested. Noise under Medium and Low reliability may be perceptible as cursor jitter during target-visible movement.
The target remains black across all mapping and reliability conditions. There is no explicit success-color cue; the target disappears after successful acquisition. The completion text is the literal string " ended " shown in white.
The target diameter affects both its drawing and the radius used for target-hit testing. The cursor diameter affects its appearance only; it does not change the center tolerance or the target-hit radius.
Diagnostic Window
A separate Qt diagnostic window titled:
FEP Visuomotor Joystick Diagnostics
is displayed to the experimenter.
Displayed Information
During experimental trials, the visible metrics panel displays:
- Current task stage.
- Original block role number (
Block: N / 6), even if some blocks were disabled. - Trial number within the current block and block trial count.
- Overall trial number and total configured active trials.
- Current Normal or Inverted mapping.
- Current High, Medium, or Low reliability condition.
- Configured visual-noise standard deviation for that trial, in pixels.
- Current task phase.
- Real-time reaction time, movement time, and total time.
- Cumulative overall, Normal-mapping, and Reversed-mapping averages of reaction time, movement time, and total time.
- When predictive cues are enabled: predicted mapping, cue validity, block Normal probability, and configured cue accuracy.
The visible panel does not show target angle or coordinates, joystick coordinates, cursor coordinates, mapping-switch flag, trials-since-switch counter, movement-started status, PriorCondition, information-purchase status, point totals, direction/trajectory metrics, penalty flags, or a separate reset/status message. Run averages are divided by mapping, not by reliability, cue validity, or purchase status. A separate diagnostic text label exists internally but is hidden and not populated.
Diagnostic Controls
| Control | Availability | Effect | Confirmation |
|---|---|---|---|
RESET CURRENT TRIAL
|
Experiment phases 1–5; shown as RESET UNAVAILABLE otherwise
|
Restarts the same trial and emits TrialReset
|
No |
SKIP TRIAL
|
Experiment phases 1–5, not paused | Abandons the current trial and advances; emits TrialSkipped
|
No |
SKIP CURRENT BLOCK
|
Experiment phases 1–5, not paused | Advances past the remaining trials of the block; emits ConditionSkipped
|
Yes |
SKIP INTRODUCTION
|
Introduction stage, not paused | Enters the experiment directly, bypassing sandbox; emits IntroductionSkipped
|
Yes |
SKIP SANDBOX
|
Sandbox stage, not paused | Enters the experiment; emits SandboxSkipped
|
No |
PAUSE / RESUME
|
All stages/phases except Finished | Freezes task-phase progression and resumes with adjusted internal timestamps; uses TaskPaused
|
No |
There is no separate diagnostic Continue button for the introduction or sandbox. Those stages normally advance using a rising joystick-button press, or may be bypassed using the skip controls.
Trial Reset
A trial may be manually reset during:
- Waiting for center.
- Holding center.
- Warning.
- Pre-target delay.
- Target-visible movement.
Reset is unavailable during:
- Feedback.
- Finished.
- Introduction.
- Sandbox.
Resetting a trial:
- Returns the task to
WaitingForCenter. - Restarts the phase timer.
- Clears movement-onset timing.
- Clears target-onset timing.
- Clears
MovementStarted. - Clears
TargetHit. - Produces a
TrialResetpulse. - Clears timing states.
- Resets baseline accumulation.
- Clears visual-noise state.
- Clears predictive-cue onset/visibility timing but keeps the same preassigned cue and validity.
- Clears initial-direction, trajectory, penalty, and unfinalized trial-point measurements.
- Preserves any information already purchased for that same trial, including revealed mapping, cost, and timestamp.
- Keeps the same target.
- Keeps the same mapping.
- Keeps the same sensory-reliability condition.
- Keeps the same block number.
- Keeps the same trial number.
- Keeps
PriorCondition. - Keeps
TrialsSinceMappingSwitch. - Does not rebuild or reshuffle the experimental sequence.
TrialReset lasts for one processing block. Resetting an Inverted trial during target-visible movement also enables the return-to-anchor behavior. A reset request is not processed while paused; requests pending at the time of a pause are deferred until processing resumes. A preserved purchase is not charged a second time.
Skipping Trials, Blocks, and Tutorial Stages
Skip Trial
SKIP TRIAL is available during experimental phases before Feedback. It emits a one-processing-block TrialSkipped pulse, clears current movement, cue-onset, information, and point accounting, does not count or award points for the abandoned trial, and advances to the next trial or finishes the run. A new target is generated on each non-final advance. Skipping an Inverted trial engages the return-to-anchor behavior.
Skip Current Block
SKIP CURRENT BLOCK requires confirmation and is available during experimental phases before Feedback. It emits ConditionSkipped, advances through all remaining trials in the current block, and starts the next enabled block or finishes the run. It does not register those abandoned trials as completed measurements or award points. The operation calls the normal advancement routine repeatedly, consuming target-generation random-number draws. Unlike single-trial skip, it does not explicitly engage return-to-anchor for the interrupted Inverted trial.
Skip Introduction and Sandbox
SKIP INTRODUCTION, after confirmation, emits IntroductionSkipped and enters the experimental phase directly, also bypassing the sandbox. SKIP SANDBOX emits SandboxSkipped and enters the experimental phase from the sandbox. Both are available only in their corresponding stage when not paused.
Pause and Resume
PAUSE is available during introduction, sandbox, and experimental phases, including Feedback, but not Finished. While paused, TaskPaused is held at 1, phase progression and cursor rendering updates stop, and joystick states continue to be sampled. On resumption, internal phase, target-onset, movement-onset, center-hold, information-display/purchase, predictive-cue-onset, sensory-noise, and introduction-animation timestamps are shifted by the pause duration. Skip controls are disabled while paused; a button press made while paused is not a purchase, and holding it through resume creates no new rising edge.
State-Logging Caveats During Skips
The skip-handling branches return early from Process() before the usual end-of-block state publication. Consequently, TaskTrial, TaskBlock, TaskCondition, TaskPhase, TrialsSinceMappingSwitch, and other trial states may show the preceding values on the skip processing block. They normally update on a later ordinary processing block. MappingSwitch can be stale or fail to pulse on the skip block. If a skip ends the run, the usual TaskPhase=7 update may never be recorded. Do not rely on a single isolated processing block to reconstruct skip transitions; inspect adjacent samples, skip event states, and trial/block identifiers. These behaviors are analysis considerations of the current implementation, not intended additional task conditions.
Timing Measurements
Timing uses std::chrono::steady_clock.
Events are detected during BCI2000 Process() calls, so effective timing resolution is limited by the signal-processing block interval.
Movement Onset
The joystick baseline is initialized when the center-hold phase begins and updated during center holding.
Movement onset is detected when either joystick axis differs from the center-hold baseline by more than 8 task-coordinate units.
abs(currentX - baselineX) > 8
or:
abs(currentY - baselineY) > 8
Reaction Time
Reaction time is measured from:
target onset -> movement onset
and stored in:
ReactionTimeMs
Movement Time
Movement time is measured from:
movement onset -> target acquisition
and stored in:
MovementTimeMs
Total Time
Total time is measured from:
target onset -> target acquisition
and stored in:
TotalTimeMs
Timing values are expressed in rounded milliseconds.
Timing states remain populated through the Feedback phase. When a target is reached without a detected movement onset, reaction and movement times are recorded as 0 and excluded from the corresponding run averages, while total time is still recorded. Paused durations are excluded through adjustment of internal timestamps when resuming.
Parameters
Experiment Structure
| Parameter | Type | Default | Range | Description |
|---|---|---|---|---|
BaselineTrials
|
Integer | 20 | 0-10000 | Number of Normal trials in block 1 |
InitialInvertedTrials
|
Integer | 5 | 0-10000 | Number of Inverted trials in block 2 |
ReturnNormalTrials
|
Integer | 5 | 0-10000 | Number of Normal trials in block 3 |
MixedTrials
|
Integer | 20 | 0-10000 | Number of approximately balanced trials in block 4 |
StrongPriorTrials
|
Integer | 20 | 0-10000 | Number of Normal-dominant trials in block 5 |
BalancedPriorTrials
|
Integer | 20 | 0-10000 | Number of approximately balanced trials in block 6 |
At least one trial must be configured across the six block parameters. A count of zero disables that block without renumbering the remaining block roles.
The preceding six parameters are used only when EnablePredictiveCues=0. When predictive cues are enabled, at least one trial must instead be configured across the predictive trial-count parameters.
Predictive-Cue Design
| Parameter | Type | Default | Range | Description |
|---|---|---|---|---|
EnablePredictiveCues
|
Integer | 0 | 0-1 | Select predictive-cue design; 0 preserves legacy design |
CueAccuracyPercent
|
Integer | 80 | 0-100 | Valid-cue percentage calculated separately within each actual mapping |
CueColorAssignment
|
Integer | 0 | 0-1 | 0: green=Normal, red=Reversed; 1: green=Reversed, red=Normal |
CueRandomSeed
|
Integer | 1 | 0-2147483647 | Dedicated predictive-sequence seed; 0 chooses and records an automatic seed |
CounterbalanceBiasedBlockOrder
|
Integer | 0 | 0-1 | Swap complete configured block-4 and block-5 definitions |
PredictiveBlock1Trials
|
Integer | 20 | 0-10000 | Uncued 100% Normal familiarization trials |
PredictiveBlock2Trials
|
Integer | 10 | 0-10000 | Uncued 100% Reversed familiarization trials |
CuedBlock3Trials, CuedBlock4Trials, CuedBlock5Trials, CuedBlock6Trials
|
Integer | 40 each | 0-10000 | Trial counts for predictive blocks 3 through 6 |
CuedBlock3NormalProbabilityPercent
|
Integer | 50 | 0-100 | Configured Normal percentage for block 3 |
CuedBlock4NormalProbabilityPercent
|
Integer | 75 | 0-100 | Configured Normal percentage for block 4 |
CuedBlock5NormalProbabilityPercent
|
Integer | 25 | 0-100 | Configured Normal percentage for block 5 |
CuedBlock6NormalProbabilityPercent
|
Integer | 50 | 0-100 | Configured Normal percentage for block 6 |
EnableIntroductionAnimation
|
Integer | 1 | 0-1 | Use animated predictive-cue instruction pages |
IntroductionAnimationDurationMs
|
Integer | 2500 | 1-60000 | Cursor/joystick movement duration per animated example |
IntroductionCueDisplayDurationMs
|
Integer | 800 | 0-60000 | Cue-only interval before animated movement |
IntroductionAnimationPauseMs
|
Integer | 750 | 0-60000 | Pause between animated examples |
IntroductionAnimationLoop
|
Integer | 1 | 0-1 | Continuously loop examples |
IntroductionShowJoystickIllustration
|
Integer | 1 | 0-1 | Show animated joystick graphic |
IntroductionPracticeScreenDurationMs
|
Integer | 2000 | 0-60000 | Automatic Time to practice screen duration
|
EnableGuidedSandbox
|
Integer | 1 | 0-1 | Use guided predictive-cue practice |
GuidedSandboxTrials
|
Integer | 3 | 1-20 | Number of guided practice trials |
Task Timing and Display
| Parameter | Type | Default | Range | Description |
|---|---|---|---|---|
CenterHoldSeconds
|
Float | 3.0 | 0.0-60.0 | Required uninterrupted center-hold duration in seconds |
WarningSeconds
|
Float | 0.5 | 0.0-60.0 | Yellow warning interval in seconds |
PreTargetDelaySeconds
|
Float | 0.5 | 0.0-60.0 | Delay between warning and target onset in seconds |
FeedbackSeconds
|
Float | 0.5 | 0.0-60.0 | Feedback interval following target acquisition, in seconds |
CursorDiameterPixels
|
Float | 16.0 | 1.0-1000.0 | Cursor drawing diameter in nominal reference pixels |
TargetDiameterPixels
|
Float | 36.0 | 1.0-1000.0 | Target drawing and hit-test diameter in nominal reference pixels |
StimulusDisplay
|
Integer | 0 | 0 through number of detected displays | Physical monitor for participant stimuli; 0 uses default BCI2000 placement |
On Windows, the application enumerates available monitors for StimulusDisplay. CursorDiameterPixels affects cursor appearance only; TargetDiameterPixels also changes the hit-test radius.
Sensory Reliability Configuration
| Parameter | Type | Default | Range | Description |
|---|---|---|---|---|
EnableSensoryReliability
|
Integer | 0 | 0-1 | Enable trial-wise visual-reliability noise; 0 disables it |
MediumReliabilityNoiseStd
|
Float | 5.0 | 0.0-1000.0 | Gaussian noise SD in pixels for Medium reliability |
LowReliabilityNoiseStd
|
Float | 15.0 | 0.0-1000.0 | Gaussian noise SD in pixels for Low reliability |
HighReliabilityProportion
|
Float | 0.34 | 0.0-1.0 | Target High-reliability trial proportion in enabled blocks |
MediumReliabilityProportion
|
Float | 0.33 | 0.0-1.0 | Target Medium-reliability trial proportion in enabled blocks |
LowReliabilityProportion
|
Float | 0.33 | 0.0-1.0 | Target Low-reliability trial proportion in enabled blocks |
SensoryNoiseCorrelationTimeMs
|
Float | 100.0 | 0.0-60000.0 | Temporal correlation time constant of noise, in milliseconds; zero gives independent innovations |
SensoryNoiseSeed
|
Integer | 1 | 0-2147483647 | Dedicated condition-assignment and noise seed; zero automatically selects a seed |
SensoryReliabilityBlocks
|
List | 4 5 6 (BCI2000 definition: 3 4 5 6, where 3 is the list length)
|
Entries 1-6; no duplicates | Block role numbers in which reliability conditions may be assigned; an empty list means all trials are High reliability |
Points and Information Seeking
| Parameter | Type | Default | Range | Description |
|---|---|---|---|---|
EnableRewardSystem
|
Integer | 0 | 0-1 | Enable point calculation and feedback |
BaseTrialReward
|
Float | 10.0 | 0.0-100000.0 | Potential points per completed trial |
InitialDirectionPenalty
|
Float | 3.0 | 0.0-100000.0 | Points deducted when direction error exceeds threshold |
TrajectoryPenalty
|
Float | 3.0 | 0.0-100000.0 | Points deducted when mean trajectory deviation exceeds threshold |
InitialDirectionThresholdDeg
|
Float | 45.0 | 0.0-180.0 | Maximum initial angular error without penalty |
InitialDirectionWindowMs
|
Integer | 150 | 0-60000 | Displayed-cursor measurement window after movement onset |
TrajectoryDeviationThreshold
|
Float | 0.20 | 0.0-100.0 | Maximum mean deviation as a fraction of center-to-target distance |
RewardFeedbackDurationMs
|
Integer | 1000 | 0-60000 | Requested point-feedback duration |
ShowCumulativeReward
|
Integer | 0 | 0-1 | Show cumulative points when rewards are enabled |
EnableInformationSeeking
|
Integer | 0 | 0-1 | Enable optional current-trial mapping purchase |
InformationCost
|
Float | 2.0 | 0.0-100000.0 | Recorded point cost; deducted when rewards are also enabled |
InformationType
|
Integer | 0 | Published 0-2; only 0 accepted | 0 reveals current-trial mapping; 1 and 2 are reserved |
InformationHorizonTrials
|
Integer | 5 | 1-10000 | Reserved for unimplemented type 1; no runtime effect |
InformationDisplayDurationMs
|
Integer | 0 | 0-60000 | Mapping-text duration; 0 means until target onset |
InformationPurchaseButton
|
Integer | 1 | 1-32 | One-based JoystickButtonsN state used to purchase
|
InformationPurchaseWindowMs
|
Integer | 0 | 0-60000 | Purchase window after entering center hold; 0 means entire hold |
ShowInformationPurchaseHint
|
Integer | 0 | 0-1 | Deprecated compatibility parameter; no runtime effect |
Parameter Validation
Preflight requires at least one configured trial in the active legacy or predictive design; cue accuracy and predictive block probabilities in 0-100; positive animation duration and guided-practice count; finite, nonnegative reward/cost/threshold/duration values; initial-direction threshold no greater than 180; InformationType=0; positive information horizon; a valid existing selected JoystickButtonsN purchase state; and a maximum possible cumulative point value that fits the 32-bit fixed-point state. It also requires finite and nonnegative reliability values, Low-reliability SD not less than Medium, reliability proportions summing to 1 within 1e-6, valid unduplicated reliability-block numbers, positive cursor and target diameters, nonnegative task durations, and a valid selected display.
HighCursorGain is no longer a parameter in this version. There is no ExperimentMode or ResultsFile parameter.
States
The following states are declared by the FEP task. Widths and initial values refer to their published definitions; runtime values may change immediately on StartRun() or during Process().
| State | Width | Initial Value | Meaning |
|---|---|---|---|
CursorX
|
10 bit | 512 | Displayed horizontal cursor position, after mapping, sensory noise, and clipping (0-1023) |
CursorY
|
10 bit | 512 | Displayed vertical cursor position, after mapping, sensory noise, and clipping (0-1023) |
TaskPhase
|
3 bit | 0 | Current task phase (0-7) |
TaskCondition
|
1 bit | 0 | 0 Normal, 1 Inverted mapping |
TargetAngle
|
12 bit | 0 | Target angle in tenths of a degree |
TargetX
|
10 bit | 512 | Horizontal target coordinate (0-1023) |
TargetY
|
10 bit | 512 | Vertical target coordinate (0-1023) |
TaskBlock
|
8 bit | 0 | Current original experimental block role (1-6; 0 before experiment) |
TaskTrial
|
16 bit | 0 | Overall 1-based experimental trial number (0 before experiment) |
MovementStarted
|
1 bit | 0 | Level flag indicating detected movement onset during the trial |
TargetHit
|
1 bit | 0 | One-processing-block target-acquisition pulse |
TrialReset
|
1 bit | 0 | One-processing-block manual-reset pulse |
TrialSkipped
|
1 bit | 0 | One-processing-block trial-skip pulse |
ConditionSkipped
|
1 bit | 0 | One-processing-block current-block-skip pulse |
IntroductionSkipped
|
1 bit | 0 | One-processing-block introduction-skip pulse |
SandboxSkipped
|
1 bit | 0 | One-processing-block sandbox-skip pulse |
TaskPaused
|
1 bit | 0 | Level flag: 1 while paused; 0 otherwise |
MappingSwitch
|
1 bit | 0 | One-processing-block mapping-change event during normal progression; see skip caveats |
TrialsSinceMappingSwitch
|
16 bit | 0 | Consecutive non-switch trial transitions since the most recent mapping change |
PriorCondition
|
2 bit | 0 | Current block-level prior-frequency context (0-3) |
Introduction
|
1 bit | 0 | 1 during introduction or sandbox; 0 during experiment |
TutorialPhase
|
4 bit | 0 | 0 experiment, 1 introduction, 2 sandbox |
ReactionTimeMs
|
32 bit | 0 | Reaction time in rounded milliseconds |
MovementTimeMs
|
32 bit | 0 | Movement time in rounded milliseconds |
TotalTimeMs
|
32 bit | 0 | Target-onset to acquisition time in rounded milliseconds |
SensoryReliabilityCondition
|
2 bit | 0 | 0 High, 1 Medium, 2 Low reliability |
TrueCursorX
|
10 bit | 512 | Post-mapping, pre-noise horizontal task-logic cursor position (0-1023) |
TrueCursorY
|
10 bit | 512 | Post-mapping, pre-noise vertical task-logic cursor position (0-1023) |
SensoryNoiseX
|
31 bit | 1073741824 | X noise encoded as 1073741824 + round(100 * noise pixels) |
SensoryNoiseY
|
31 bit | 1073741824 | Y noise encoded as 1073741824 + round(100 * noise pixels) |
SensoryNoiseStd
|
18 bit | 0 | Configured noise SD encoded as round(100 * pixels) |
SensoryNoiseSeedEffective
|
32 bit | 1 | Effective noise and reliability-assignment seed |
InformationPurchased
|
1 bit | 0 | Level value: 1 after a successful purchase on the current trial |
InformationPurchaseTimeMs
|
32 bit | 0 | Purchase time in milliseconds relative to trial start |
InformationRevealedMapping
|
2 bit | 0 | 0 none, 1 Normal, 2 Inverted/Reversed |
TrialInformationCost
|
32 bit | 0 | Information cost in hundredths of a point |
InitialDirectionErrorDeg
|
15 bit | 0 | Initial angular error in hundredths of a degree |
InitialDirectionPenaltyApplied
|
1 bit | 0 | 1 when direction error strictly exceeds threshold |
TrajectoryDeviation
|
32 bit | 0 | Mean normalized deviation in millionths of center-to-target distance |
TrajectoryPenaltyApplied
|
1 bit | 0 | 1 when mean trajectory deviation strictly exceeds threshold |
TrialReward
|
32 bit | 0 | Final trial points in hundredths of a point |
CumulativeReward
|
32 bit | 0 | Run-total points in hundredths of a point |
CueMapping
|
2 bit | 0 | Predicted mapping: 0 none, 1 Normal, 2 Inverted/Reversed |
CueValidity
|
2 bit | 0 | 0 not applicable, 1 invalid, 2 valid |
CueReliability
|
7 bit | 0 | Configured cue accuracy percentage for the current block (0-100) |
CueVisible
|
1 bit | 0 | 1 while a predictive cue is displayed during center hold |
CueOnsetTimeMs
|
32 bit | 0 | First cue-onset time in milliseconds relative to trial start |
BlockNormalProbability
|
7 bit | 0 | Configured block-level Normal percentage (0-100); realized counts may differ by rounding |
CueRandomSeedEffective
|
32 bit | 1 | Effective predictive-sequence seed |
External Joystick States
| State | Description |
|---|---|
JoystickXpos
|
Raw horizontal joystick position supplied through BCI2000 input logging |
JoystickYpos
|
Raw vertical joystick position supplied through BCI2000 input logging |
JoystickButtons1
|
Joystick button used to advance introduction pages and exit the sandbox |
JoystickButtonsN selected by InformationPurchaseButton
|
Configured rising-edge input for information purchase during center hold |
The application also accesses BCI2000's standard Running state when ending the experiment. Joystick logging must be configured separately using LogJoystick.
States Not Present in the Current Implementation
The task does not define DisplayedCursorX, DisplayedCursorY, an exact state named SensoryReliability, PracticeTrial, TaskBlockType, or CursorGainCondition. Instead, displayed coordinates use CursorX/Y, pre-noise coordinates use TrueCursorX/Y, and visual reliability is recorded through SensoryReliabilityCondition and the sensory-noise states.
State Lifecycle and Encoding Notes
TargetX/Y have published initial values of 512 but are explicitly set to 0 during introduction/sandbox. TaskTrial is 1-based once experimental trials begin. Pulse states normally clear on the following processing block, whereas TaskPaused is held at 1 throughout a pause and MovementStarted remains high from movement detection until trial advancement.
Trial-specific information, performance, point, and cue-onset states reset when advancing to a new trial. CumulativeReward resets only at run start. Purchase states update on the accepted button-edge block. Performance and point states finalize with TargetHit and remain through Feedback. Manual reset preserves purchase states but clears performance and unfinalized points. Point-performance states remain zero when rewards are disabled, although TrialInformationCost may still be nonzero after a purchase. Cue mapping, validity, reliability, visibility, and onset states are zero during introduction/sandbox and in legacy operation; BlockNormalProbability and CueRandomSeedEffective are still published during legacy experiments.
Noise states use fixed-point encoding described in Noise Seeds and State Encoding. State publication immediately after skip operations has known limitations described in State-Logging Caveats During Skips.
Cursor Coordinates
CursorX and CursorY represent the final displayed cursor position including mapping inversion, return-to-anchor transformation, any applied Gaussian visual noise, and display-boundary clipping.
TrueCursorX and TrueCursorY record the separate post-mapping, pre-noise cursor trajectory. This is the trajectory used for center detection and target-hit detection. It does not represent untransformed joystick input.
The participant-visible drawing is positioned using the displayed cursor. Both true and displayed coordinates are recorded as 10-bit states over the range 0-1023. Encoded noise samples are recorded separately. The diagnostic window does not currently show either cursor coordinate pair.
The application does not record an independent pre-mapping cursor state. When enabled, JoystickXpos/Ypos provide the underlying joystick samples needed to reconstruct a raw joystick-equivalent trajectory offline.
Data Recording
The task records its behavioral variables as synchronized BCI2000 states in the standard .dat file, subject to the configured BCI2000 recording and joystick-logging settings.
Recorded information includes:
- Displayed and true cursor trajectories (
CursorX/YandTrueCursorX/Y). - Joystick trajectory when external joystick logging is enabled.
- Task phase, Normal/Inverted mapping, prior context, and mapping-switch history.
- Sensory-reliability condition, actual generated noise, configured noise SD, and effective seed.
- Predictive cue mapping, validity, configured cue accuracy, visibility/onset, block Normal probability, and effective cue seed.
- Information purchase, purchase time, revealed mapping, and point cost.
- Initial-direction error, trajectory deviation, penalty flags, trial points, and cumulative points.
- Target angle and coordinates, experimental block, and trial number.
- Movement onset, target acquisition, and reaction/movement/total timing.
- Trial reset, trial skip, block skip, introduction skip, sandbox skip, and pause status.
- Introduction/sandbox status and experiment completion as represented by task states.
The application passes signal channels through unchanged:
Output = Input;
Operator Logging
The application writes bciout messages for task startup and shutdown, effective sensory-noise and predictive-cue seeds, predictive-block realized mapping/validity counts, per-block High/Medium/Low reliability distributions split by Normal/Inverted mapping and switch status, and trial-completion results including trial, block, mapping, reliability, reaction time, and movement time. These are diagnostic/operator messages rather than a separate structured task-results file.
Secondary Output
The current implementation does not write an application-specific CSV file, JSON file, text results file, or database. There is no ResultsFile parameter.
Offline Analysis Notes
The table below gives common event and measurement identifications. When reset, skip, or pause controls are used, inspect adjacent processing blocks and the recorded configuration instead of relying solely on one state sample.
| Measurement or Event | Recommended Identification |
|---|---|
| Experimental samples | Introduction == 0
|
| Introduction | Introduction == 1 and TutorialPhase == 1
|
| Sandbox | Introduction == 1 and TutorialPhase == 2
|
| Active experimental trial | Introduction == 0, TaskTrial > 0, and TaskPhase from 1 through 6
|
| Target onset | Transition into TaskPhase == 5
|
| Movement onset | Rising transition of MovementStarted
|
| Target acquisition | TargetHit == 1
|
| Normal mapping | TaskCondition == 0
|
| Inverted mapping | TaskCondition == 1
|
| Predicted mapping | CueMapping: 0 none, 1 Normal, 2 Inverted/Reversed
|
| Valid/invalid predictive cue | CueValidity: 1 invalid, 2 valid; 0 not applicable
|
| Cue visible | CueVisible == 1; onset relative to trial start is CueOnsetTimeMs
|
| Configured cue accuracy | CueReliability percent
|
| Block Normal probability | BlockNormalProbability percent
|
| High reliability | SensoryReliabilityCondition == 0
|
| Medium reliability | SensoryReliabilityCondition == 1
|
| Low reliability | SensoryReliabilityCondition == 2
|
| Reliability globally disabled | Verify EnableSensoryReliability == 0 in recorded parameters; all trials then use condition 0
|
| Configured visual-noise SD | SensoryNoiseStd / 100 pixels
|
| Actual X visual noise | (SensoryNoiseX - 1073741824) / 100 pixels
|
| Actual Y visual noise | (SensoryNoiseY - 1073741824) / 100 pixels
|
| Pre-noise task-logic cursor trajectory | TrueCursorX and TrueCursorY
|
| Displayed cursor trajectory | CursorX and CursorY
|
| Mapping switch | MappingSwitch == 1 (subject to skip-operation caveats)
|
| Trials since switch | TrialsSinceMappingSwitch (subject to skip-operation caveats)
|
| Previous mapping | Previous trial's TaskCondition
|
| Prior context | PriorCondition
|
| Experimental block | TaskBlock
|
| Overall trial | TaskTrial
|
| Target angle | TargetAngle / 10 degrees
|
| Target position | TargetX and TargetY
|
| Joystick trajectory | JoystickXpos and JoystickYpos
|
| Reaction time | ReactionTimeMs
|
| Movement time | MovementTimeMs
|
| Total time | TotalTimeMs
|
| Information purchased | InformationPurchased == 1; onset is its rising transition and exact relative time is InformationPurchaseTimeMs
|
| Revealed mapping | InformationRevealedMapping: 0 none, 1 Normal, 2 Inverted/Reversed
|
| Information point cost | TrialInformationCost / 100
|
| Initial direction error | InitialDirectionErrorDeg / 100 degrees
|
| Initial-direction penalty | InitialDirectionPenaltyApplied == 1
|
| Mean normalized trajectory deviation | TrajectoryDeviation / 1000000
|
| Trajectory penalty | TrajectoryPenaltyApplied == 1
|
| Trial points | TrialReward / 100
|
| Cumulative points | CumulativeReward / 100
|
| Manual reset | TrialReset == 1
|
| Trial skipped | TrialSkipped == 1
|
| Current block skipped | ConditionSkipped == 1
|
| Introduction skipped | IntroductionSkipped == 1
|
| Sandbox skipped | SandboxSkipped == 1
|
| Task paused | TaskPaused == 1
|
| Experiment completion | TaskPhase == 7 in ordinary progression; may be absent for skip-to-finish
|
Event-Like States
The following are designed to be one-processing-block event flags: MappingSwitch, TargetHit, TrialReset, TrialSkipped, ConditionSkipped, IntroductionSkipped, and SandboxSkipped. MovementStarted instead remains high from movement onset through the rest of the trial and Feedback. TaskPaused is a level state held at 1 throughout a pause.
Analysis Considerations
- Use
CursorX/Yfor what the participant saw andTrueCursorX/Yfor the cursor that determined hits and centering. Visual noise and display clipping can make the two disagree. - Divide cursor-state coordinates by 1023 to recover normalized coordinates. Use the provided noise-state offset and scale to recover noise in pixels.
- Use the recorded parameter
EnableSensoryReliabilityto distinguish a disabled manipulation from genuine High-reliability trials. - Confirm
EnablePredictiveCues,EnableRewardSystem, andEnableInformationSeekingbefore interpreting zero-valued cue, point, or purchase states. - Predictive
CueValiditydescribes whether the prediction matches the current actual mapping; it is not the same as sensory reliability. - Purchase time is relative to trial start and may include waiting-for-center time. A purchase preserved across manual reset belongs to one experimental trial and should not be counted twice.
- Direction and trajectory metrics use the displayed cursor and may include sensory noise; hit logic uses
TrueCursorX/Y. - Reconstruct prior mapping by inspecting previous trials;
PriorConditionis a block context rather than a previous-trial label or inferred belief. - Check skip pulses and neighboring trial/block values when deriving event onsets. Mapping-switch pulses, trial identifiers, and
TaskPhasemay be stale or missing on early-return skip processing blocks. - Paused intervals should be identified from
TaskPaused, and internal timing measurements exclude pause duration on resume. - If target acquisition occurs without a detected movement onset, reaction and movement timing states are zero but total time is recorded; such zero values should not automatically be interpreted as physiologically instantaneous responses.
- Raw joystick reconstruction requires external input logging; the application itself does not activate
LogJoystick.
Differences from USBHIDJoystickTask
Retained
- BCI2000
ApplicationBasestructure. - USB joystick input.
- Center-out reaching.
- Center hold.
- Warning interval.
- Pre-target delay.
- Target-directed movement.
- Feedback interval.
- Continuous target-angle generation.
- Reaction-time measurement.
- Movement-time measurement.
- Total-time measurement.
- Manual trial reset.
- Progress bar.
- BCI2000 state logging.
- Direct and inverted joystick-control mappings.
Removed
The FEP task removes the earlier task's:
ExperimentMode.- Automatic-only and Controlled-only modes.
- Ordered-start condition.
TaskBlockType.- Green versus red condition-specific targets and legacy automatic/controlled condition instructions. Predictive mode teaches probabilistic cue meanings instead, while targets remain black.
- Condition-specific practice trials.
PracticeTrial.- Optional tutorial setting.
- Diagnostic Continue button.
- Secondary CSV results file.
- Participant-facing block announcements.
Added
The FEP task adds:
- Six predefined experimental block roles.
- Hidden Normal and Inverted mappings in the legacy design, with optional probabilistic or purchased mapping information.
- Unannounced mapping switches.
MappingSwitch.TrialsSinceMappingSwitch.PriorCondition.SensoryReliabilityConditionand configurable High/Medium/Low visual sensory reliability.- Configurable Gaussian cursor noise and correlation time.
- Separate
TrueCursorX/Yand displayedCursorX/Ylogging. SensoryNoiseX/Y,SensoryNoiseStd, andSensoryNoiseSeedEffective.- Researcher controls for skipping trial, block, introduction, and sandbox, and pausing/resuming.
TrialSkipped,ConditionSkipped,IntroductionSkipped,SandboxSkipped, andTaskPausedstates.- Configurable
CursorDiameterPixelsandTargetDiameterPixelsparameters. - Diagnostic real-time timing values and run averages.
- A legacy Normal-mapping sandbox and optional predictive guided practice.
- Black targets across all mapping conditions.
- Normal-dominant and approximately balanced mapping contexts.
- Optional probabilistic green/red mapping cues with valid/invalid trial logging.
- Dedicated predictive sequence generation, mapping probabilities, cue seed, cue key, and counterbalancing.
- Animated predictive-cue instruction pages and guided alternating Normal/Reversed practice.
- Optional point-based performance feedback and cumulative point display.
- Voluntary current-trial mapping information during center hold.
- Information-purchase, direction/trajectory, penalty, and point states.
Known Limitations and Analysis Considerations
- The current module does not implement an explicit computational Free Energy Principle model.
PriorConditionrepresents experimental block context rather than an inferred participant belief.- Participant surprise or expectation is not measured directly by the application.
- In the legacy design, blocks 4 and 6 use similar approximately balanced mapping-generation rules but occur after different preceding mapping histories.
- Legacy mapping pseudorandomization constraints are attempted but are not guaranteed if all 64 candidates fail. Predictive design evaluates up to 512 candidates and uses the best scored candidate if none meets its early-stop criteria.
- Reliability manipulation is disabled by default;
SensoryReliabilityCondition=0by itself does not show that reliability was enabled. - Reliability is assigned with a counterbalancing heuristic across mapping and switch status, not by a wholly independent shuffle.
- Gaussian noise affects the displayed cursor only during target-visible movement; it does not change the cursor position used for center and target-hit detection.
- The display may visually disagree with the target-hit decision because logic uses the true pre-noise cursor.
- The correlated noise process begins at zero at target onset rather than stationary variance.
- The true cursor is separately recorded, but no independent pre-mapping/untransformed cursor trajectory is recorded.
- The diagnostic window does not show target, joystick, cursor, switch, trials-since-switch, point, purchase, or free-form status fields; run averages are divided by Normal/Reversed mapping, not by reliability or cue validity.
TargetDiameterPixelschanges target-hit radius;CursorDiameterPixelschanges only cursor appearance.- Skip operations can result in stale or missing per-block values for
MappingSwitch,TaskPhase, and trial/block identifiers. Skip-to-finish may not publishTaskPhase=7. - A block skip during Inverted target-visible movement does not explicitly preserve the anchored return mapping.
- Pausing is allowed during introduction, sandbox, and feedback, and the timing system compensates for pause duration on resume.
- Physical display geometry depends on the configured participant monitor and BCI2000 window dimensions.
- No application-specific CSV, JSON, text results file, or database is generated.
- Predictive mapping and cue-validity percentages are rounded to integer trial counts, so small blocks may not realize exact percentages.
PriorConditionretains legacy category names in predictive mode; an Inverted-biased block is labeledHiddenMixed. UseBlockNormalProbabilityfor the explicit percentage.- Cue visibility is limited to
HoldingCenter; the cue is gone during Warning and PreTargetDelay, although the persistent color key remains. - Only current-trial purchased information (
InformationType=0) is implemented. Values 1 and 2 are rejected,InformationHorizonTrialsis reserved, andShowInformationPurchaseHinthas no effect. - Information purchasing is available only during center hold, not Warning or PreTargetDelay.
- Point metrics use displayed cursor samples and processing-block timing; trajectory deviation is a sample mean rather than a path-length-weighted integral.
- No unsuccessful-trial timeout exists, and points are awarded only at target acquisition.
- Point feedback may lengthen Feedback beyond
FeedbackSeconds. - No state distinguishes individual introduction pages.
References
Friston, K. The free-energy principle: a unified brain theory?. Nat Rev Neurosci 11, 127–138 (2010). https://doi.org/10.1038/nrn2787
See also
- Visuomotor Joystick Task
- Logging Input
- LogJoystick
- Module Command Line Options
- ApplicationWindow Class
- BCI2000 File Format
- ApplicationBase Class