Jump to content

VisuomotorJoystickTask: Difference between revisions

From BCI2000 Wiki
Aes2376 (talk | contribs)
m Documenting new Jitter changes
Aes2376 (talk | contribs)
No edit summary
 
Line 5: Line 5:
During each experimental trial, the participant moves a cursor to the center of the display, holds it there, waits through a warning period, and then moves to a peripheral target. In the '''automatic''' condition (labeled '''Normal''' to the participant), joystick and cursor movements are congruent. In the '''controlled''' condition (labeled '''Reversed''' to the participant), joystick-to-cursor movement is inverted after the target appears. The numerical <code>TaskCondition</code> encodings remain 0 and 1, respectively.
During each experimental trial, the participant moves a cursor to the center of the display, holds it there, waits through a warning period, and then moves to a peripheral target. In the '''automatic''' condition (labeled '''Normal''' to the participant), joystick and cursor movements are congruent. In the '''controlled''' condition (labeled '''Reversed''' to the participant), joystick-to-cursor movement is inverted after the target appears. The numerical <code>TaskCondition</code> encodings remain 0 and 1, respectively.


The task also includes an optional participant introduction and practice sequence. Before the experiment begins, participants may receive task instructions, explore both normal and reversed cursor mappings, and complete automatic and controlled practice trials. Tutorial and practice periods are recorded in the BCI2000 data stream but remain separate from experimental trial numbering and experimental performance summaries.
The task also includes an optional participant introduction and practice sequence, available in two forms. The default '''Easy''' introduction uses animated demonstrations, guided "your turn" screens, and short practice blocks to introduce the normal and reversed mappings. The '''Standard''' introduction is the earlier, text-driven sequence that combines instructions, free-movement exploration, and practice trials. The introduction may also be disabled entirely. Tutorial and practice periods are recorded in the BCI2000 data stream but remain separate from experimental trial numbering and experimental performance summaries.


The task is based on the visuomotor paradigm described by Neumann et al. (2018), which was developed to compare automatic and controlled movements and investigate their relationship to basal ganglia function and subthalamic deep brain stimulation in Parkinson's disease. The BCI2000 implementation adapts the original paradigm for USB joystick control and synchronized BCI2000 state recording.
The task is based on the visuomotor paradigm described by Neumann et al. (2018), which was developed to compare automatic and controlled movements and investigate their relationship to basal ganglia function and subthalamic deep brain stimulation in Parkinson's disease. The BCI2000 implementation adapts the original paradigm for USB joystick control and synchronized BCI2000 state recording.
Line 13: Line 13:
The following video demonstrates the Visuomotor Joystick Task running in BCI2000, including the participant display and joystick-controlled task behavior: <youtube alignment="center">https://www.youtube.com/watch?v=LSZW3nxg3Vg</youtube>
The following video demonstrates the Visuomotor Joystick Task running in BCI2000, including the participant display and joystick-controlled task behavior: <youtube alignment="center">https://www.youtube.com/watch?v=LSZW3nxg3Vg</youtube>


This video displays version 1 of the task, and as such does not include the pre-experiment participant tutorial and practice sequence.
This video displays version 1 of the task, and as such does not include the pre-experiment participant tutorial and practice sequence. It also predates the Easy introduction, the configurable target distance, and the runtime geometry controls described below.


==Location==
==Location==
Line 59: Line 59:
* Ordered and pseudorandom experimental blocks.
* Ordered and pseudorandom experimental blocks.
* Configurable trial counts and trial timing.
* Configurable trial counts and trial timing.
* An optional participant tutorial and practice sequence.
* An optional participant introduction and practice sequence, with '''Standard''' and '''Easy''' tutorial modes.
* Automatic and controlled practice trials.
* Automatic and controlled practice trials.
* Free-movement demonstrations of normal and reversed cursor control.
* Free-movement demonstrations of normal and reversed cursor control (Standard mode).
* Animated cursor, target, and joystick demonstrations with guided "your turn" screens (Easy mode).
* Joystick-button and experimenter-controlled tutorial progression.
* Joystick-button and experimenter-controlled tutorial progression.
* Automatic, timer-based Easy-introduction progression, including an optional surgery-friendly mode.
* USB joystick input through BCI2000's input logging system.
* USB joystick input through BCI2000's input logging system.
* Selection of the participant display on multi-monitor Windows systems.
* Selection of the participant display on multi-monitor Windows systems.
* BCI2000 state logging of task timing, cursor position, target position, condition, block structure, tutorial status, practice trials, and trial events.
* BCI2000 state logging of task timing, cursor position, target position, condition, block structure, tutorial status, practice trials, trial events, and runtime display geometry.
* A separate diagnostic window with visible performance metrics, tutorial controls, manual trial reset, researcher skip controls, and pause/resume.
* A separate diagnostic window with visible performance metrics, tutorial controls, manual trial reset, researcher skip controls, Easy-phase previous/restart controls, runtime cursor-diameter and target-distance controls, and pause/resume.
* Trial-level reaction time, movement time, and total time measurements.
* Trial-level reaction time, movement time, and total time measurements.
* Configurable cursor and target diameters, with target size affecting acquisition tolerance.
* Configurable cursor diameter, target diameter, and center-to-target distance, with target size affecting acquisition tolerance.
* Dedicated one-processing-block states for researcher skip events and a persistent pause state.
* Dedicated one-processing-block states for researcher skip, Easy-phase navigation, and geometry-change events, plus a persistent pause state.
* Participant-facing Normal/Reversed terminology and condition cues, without changing automatic/controlled state encodings.
* Participant-facing Normal/Reversed terminology and condition cues, without changing automatic/controlled state encodings.
* Separation of tutorial/practice data from experimental trial numbering and run-summary metrics.
* Separation of tutorial/practice data from experimental trial numbering and run-summary metrics.
* Behavioral recording through synchronized BCI2000 states; this version does not create a separate results CSV.
* Behavioral recording through synchronized BCI2000 states; this version does not create a separate results CSV.


The inspected development checkout contains the task under <code>src/custom/usb_hid_joystick_task</code> and has Git history through 2026-10-12 (commit <code>83404dd</code>).
The inspected development checkout contains the task under <code>src/custom/usb_hid_joystick_task</code> and has Git history through 2026-11-11 (commits <code>a169ed7</code> and <code>7d6d0ea</code>, plus uncommitted working-tree changes that add the <code>EasyIntroPrevious</code> and <code>EasyIntroRestarted</code> states and keep the center and warning cues at fixed size).


===Source Code Revisions===
===Source Code Revisions===
Line 82: Line 84:
* Known to compile under: Visual Studio 2022 / MSVC 19.35 for a prior version of the current source
* Known to compile under: Visual Studio 2022 / MSVC 19.35 for a prior version of the current source
* Earlier documented source revision: '''9/1/26'''
* Earlier documented source revision: '''9/1/26'''
* '''New version, 10/12/26:''' Latest inspected task commit <code>83404dd</code>. Added researcher pause/resume and skip controls with corresponding states, configurable cursor/target diameters, participant-facing Normal/Reversed labels and condition cues, and updated diagnostic metrics display; removed secondary CSV output and <code>ResultsFile</code>. Source moved to the inspected custom-module location and CMake target described above.
* Earlier version, 10/12/26: Task commit <code>83404dd</code> (the previously documented revision). Added researcher pause/resume and skip controls with corresponding states, configurable cursor/target diameters, participant-facing Normal/Reversed labels and condition cues, and updated diagnostic metrics display; removed secondary CSV output and <code>ResultsFile</code>. Source moved to the inspected custom-module location and CMake target described above.
* Current inspected source revision: '''10/12/26''' (Git commit <code>83404dd</code>)
* '''New version, 11/11/26:''' Latest inspected task revision (Git commits <code>a169ed7</code> and <code>7d6d0ea</code>, plus uncommitted working-tree changes). Added the '''Easy''' introduction tutorial mode and made it the default; replaced the boolean <code>EnableIntroduction</code> parameter with the enumerated <code>IntroductionMode</code> parameter; added <code>TargetDistancePixels</code>; added runtime cursor-diameter and target-distance controls to the diagnostic window together with <code>CursorDiameterPx10</code>, <code>TargetDistancePx10</code>, and <code>DisplayGeometryChanged</code>; added researcher '''PREVIOUS EASY PHASE''' and '''RESTART EASY PHASE''' controls with <code>EasyIntroPrevious</code> and <code>EasyIntroRestarted</code> events; added the <code>EasyIntroPhase</code> state and the <code>Application:EasyIntroduction</code> parameter group. The center and warning markers no longer scale with the cursor diameter.
* Observed in the inspected parameter files: the current application build was produced with BCI2000 framework 3.6.9567.1 (release, AMD64, MSVC 19.35) on 2026-11-10. This is build metadata from a saved parameter file, not a verified runtime test of every 11/11/26 change.
* Current inspected source revision: '''11/11/26''' (Git commits <code>a169ed7</code> and <code>7d6d0ea</code>, plus uncommitted working-tree changes)
* Broken since: No known breaking revision
* Broken since: No known breaking revision


The earlier framework and compiler information above does not establish a successful build or runtime test of the 10/12/26 source revision; the present update is based on source comparison.
The earlier framework and compiler information above does not establish a successful build or runtime test of the 11/11/26 source revision; the present update is based on source comparison. The 11/11/26 change record is summarized here and in the Version History section.


==Functional Description==
==Functional Description==
Line 132: Line 136:
In the mixed block, the application shuffles the configured numbers of automatic and controlled trials. The randomization attempts to avoid both strict alternation and excessively long runs of a single condition.
In the mixed block, the application shuffles the configured numbers of automatic and controlled trials. The randomization attempts to avoid both strict alternation and excessively long runs of a single condition.


When the tutorial is enabled, its content depends on <code>ExperimentMode</code>:
When the introduction is enabled, its content depends on <code>IntroductionMode</code>.
 
In '''Standard''' mode (<code>IntroductionMode=1</code>), tutorial content depends on <code>ExperimentMode</code>:


{| class="wikitable"
{| class="wikitable"
Line 151: Line 157:
|}
|}


When both conditions are present, the tutorial always presents automatic training before controlled training. <code>OrderedStartCondition</code> affects the experimental block order but does not change the tutorial order. The participant sees Normal/Reversed wording for these conditions, while the experiment parameters and state names continue to use Automatic/Controlled identifiers.
When both conditions are present, the Standard tutorial always presents automatic training before controlled training. <code>OrderedStartCondition</code> affects the experimental block order but does not change the tutorial order.
 
In '''Easy''' mode (<code>IntroductionMode=2</code>, the default), every experiment mode uses the same guided sequence: basic demonstration, normal demonstration, normal "your turn", normal practice when configured, reversed transition, reversed demonstration, reversed "your turn", reversed practice when configured, and a ready screen. The Easy tutorial always presents the normal mapping before the reversed mapping and, unlike the Standard tutorial, always includes a reversed section even in Automatic Only and Controlled Only modes.
 
In both tutorial modes, the participant sees Normal/Reversed wording, while the experiment parameters and state names continue to use Automatic/Controlled identifiers.


===Tutorial and Practice Sequence===
===Tutorial and Practice Sequence===


When <code>EnableIntroduction=1</code>, the tutorial begins at the start of each run before the first experimental block.
When <code>IntroductionMode</code> is 1 (Standard) or 2 (Easy), the tutorial begins at the start of each run before the first experimental block. When it is 0 (Disabled), the tutorial is skipped and the task begins with the experimental block-announcement sequence.


The tutorial consists of the following stages:
'''Standard introduction.''' The Standard introduction (<code>IntroductionMode=1</code>) consists of the following stages:


{| class="wikitable"
{| class="wikitable"
Line 201: Line 211:
|}
|}


When <code>EnableIntroduction=0</code>, the tutorial is skipped and the task begins with the original experimental block-announcement sequence.
'''Easy introduction.''' The Easy introduction (<code>IntroductionMode=2</code>, the default) uses a guided sequence of animated demonstrations, static "your turn" and transition screens, and short practice blocks. Its stages are recorded in the <code>EasyIntroPhase</code> state:


===Tutorial Continuation===
{| class="wikitable"
 
! EasyIntroPhase
Tutorial screens that require participant acknowledgement may be advanced using either:
! Stage
 
! Description
* Joystick button 1, or
|-
* The experimenter's '''CONTINUE''' button in the diagnostic window.
| 0
 
| None
Joystick continuation uses rising-edge detection. Pressing the button advances one eligible tutorial screen, while holding the button does not repeatedly advance the tutorial. The button must be released and pressed again to produce another continuation event.
| Easy introduction inactive
 
|-
Button presses are ignored during active practice trials and during tutorial transitions that require the participant to return the joystick or cursor to center.
| 1
 
| Basic demonstration
During the experimental portion of the run, joystick button presses do not control trial progression. The researcher '''CONTINUE''' control displays '''CONTINUE UNAVAILABLE''' when continuation is not permitted. The researcher can also use context-specific skip controls to bypass eligible tutorial stages; these actions are documented under [[#Researcher Skip Controls|Researcher Skip Controls]]. The task can be paused during tutorial stages.
| Animated cursor moves from the center to a target without a joystick illustration
|-
| 2
| Normal demonstration
| Animated cursor and joystick move together toward green targets
|-
| 3
| Normal: now your turn
| Static screen inviting the participant to try the normal mapping
|-
| 4
| Normal practice
| Normal-mapping practice trials using deterministic targets
|-
| 5
| Reversed introduction
| Static screen explaining that the cursor will move opposite the joystick
|-
| 6
| Reversed demonstration
| Animated cursor moves opposite the joystick toward red targets
|-
| 7
| Reversed: now your turn
| Static screen inviting the participant to try the reversed mapping
|-
| 8
| Reversed practice
| Reversed-mapping practice trials using deterministic targets
|-
| 9
| Ready
| Final summary screen before the experiment begins
|}


===Normal Free Movement===
The Easy sequence always runs in this order: basic demonstration, normal demonstration, normal "your turn", normal practice (when <code>EasyIntroNormalPracticeTrials &gt; 0</code>), reversed introduction, reversed demonstration, reversed "your turn", reversed practice (when <code>EasyIntroReversedPracticeTrials &gt; 0</code>), and ready. It is independent of <code>ExperimentMode</code>, so the reversed stages are presented even when only automatic experimental trials are configured.


During the normal free-movement stage, the participant may freely move the cursor using the direct absolute joystick mapping.
Easy-stage behavior:


There is no timer or trial progression during this stage. It continues until the participant presses the joystick button or the experimenter selects '''CONTINUE'''.
* Demonstration animations use <code>EasyIntroAnimationDurationMs</code> for each movement and <code>EasyIntroAnimationPauseMs</code> for the pause at the target. <code>EasyIntroAnimationLoop</code> repeats the demonstration until the stage advances, and <code>EasyIntroAnimationEnabled=0</code> replaces the animated movement with a near-static cursor position.
* <code>EasyIntroNormalDemoDirections</code> and <code>EasyIntroReversedDemoDirections</code> set how many example movements are shown (1-4; default 2). The first example moves to the lower right and the second directly right; additional examples fan upward.
* <code>EasyIntroRequireButtonPress=0</code> (the default) advances eligible stages automatically: animations after all configured examples have played, the "your turn" and reversed-introduction screens after <code>EasyIntroInterimScreenDurationMs</code>, and the ready screen after <code>EasyIntroReadyScreenDurationMs</code>. Joystick button 1 (unless surgery mode is enabled) or researcher '''CONTINUE''' can advance a static screen before its automatic timer expires. Demonstration screens do not become eligible for manual continuation until all configured examples have played.
* When <code>EasyIntroRequireButtonPress=1</code> and <code>EasyIntroSurgeryMode=0</code>, eligible stages wait for joystick button 1 or the researcher '''CONTINUE''' control. Static screens are immediately eligible; demonstration screens become eligible after all configured examples have played.
* When <code>EasyIntroSurgeryMode=1</code>, the non-practice Easy screens advance automatically and participant joystick-button continuation is disabled. Researcher '''CONTINUE''' remains available on eligible screens. Practice trials still require the participant to acquire the targets and return to center.
* When <code>EasyIntroRequireJoystickNeutral=1</code>, an automatic advance or participant joystick-button continuation from the normal or reversed demonstration waits until the joystick is neutral. When instruction text is enabled, the display then shows "Let go of the joystick to continue." Researcher '''CONTINUE''' bypasses this neutral-joystick gate.
* Easy practice uses <code>EasyIntroNormalPracticeTrials</code> and <code>EasyIntroReversedPracticeTrials</code> rather than the Standard practice-trial counts, and uses <code>EasyIntroPracticeCenterHoldMs</code> for its center hold. Success feedback lasts <code>EasyIntroFeedbackDurationMs</code>, or is omitted when <code>EasyIntroPracticeFeedback=0</code>.
* <code>EasyIntroShowInstructionText</code> and <code>EasyIntroShowJoystickIllustration</code> hide the instruction text and the animated joystick graphic, respectively.
* <code>EasyIntroAllowResearcherSkip=0</code> disables the researcher skip controls for the Easy introduction ('''SKIP INTRODUCTION''', '''SKIP PRACTICE''', and '''SKIP CURRENT EASY PHASE'''). The previous-phase and restart-phase controls remain available.


===Automatic Practice===
After the final Easy practice trial, the participant must return the cursor to the center before the sequence advances.


Automatic practice uses the same direct mapping and the same basic trial phases as experimental automatic trials:
===Tutorial Continuation===


# Waiting for center
Tutorial screens that require participant acknowledgement may be advanced using either:
# Holding center
# Warning
# Pre-target delay
# Target visible
# Feedback


Practice trials differ from experimental trials in several ways:
* Joystick button 1, or
* The experimenter's '''CONTINUE''' button in the diagnostic window.


* Center hold is determined by <code>PracticeCenterHoldTime</code> rather than <code>CenterHoldSeconds</code>.
Joystick continuation uses rising-edge detection. Pressing the button advances one eligible tutorial screen, while holding the button does not repeatedly advance the tutorial. The button must be released and pressed again to produce another continuation event.
* Practice targets follow a deterministic sequence.
* <code>TaskBlock</code> and <code>TaskTrial</code> remain 0.
* <code>PracticeTrial</code> identifies the active practice trial.
* Practice activity is recorded in BCI2000 states; this application writes no separate trial-level CSV file.
* Practice results are excluded from experimental completion counts and timing summaries.
* Practice reset attempts do not increment experimental reset metrics.


After the final automatic practice trial, the participant must return the cursor to the center before the tutorial advances.
In the '''Standard''' introduction, this applies to the introduction, normal free-movement, instruction, controlled free-movement, and completion screens. In the '''Easy''' introduction, researcher '''CONTINUE''' can advance any eligible non-practice stage. Joystick button 1 can do the same only when <code>EasyIntroSurgeryMode=0</code>. When <code>EasyIntroRequireButtonPress=1</code> and surgery mode is off, a participant joystick press or researcher '''CONTINUE''' is required; otherwise, stages also advance automatically after their animation or timer. Static Easy screens are immediately eligible, and demonstration screens become eligible after all configured examples have played. During the normal and reversed demonstrations, <code>EasyIntroRequireJoystickNeutral=1</code> delays automatic or participant-button advancement until the joystick is neutral; researcher '''CONTINUE''' bypasses that requirement.


===Controlled Free Movement===
Button presses are ignored during active practice trials and during tutorial transitions that require the participant to return the joystick or cursor to center.


The controlled free-movement stage allows the participant to explore reversed cursor control without a target.
During the experimental portion of the run, joystick button presses do not control trial progression. The researcher '''CONTINUE''' control displays '''CONTINUE UNAVAILABLE''' when continuation is not permitted. The researcher can also use context-specific skip, previous-phase, and restart-phase controls; these actions are documented under [[#Researcher Skip Controls|Researcher Skip Controls]]. The task can be paused during tutorial stages.


The participant is first asked to return the cursor to center. Once centered, the application records the current joystick and cursor positions as anchors and enables the same relative inverted mapping used during target-directed controlled movement.
===Normal Free Movement===


When the participant requests continuation, the task requires the joystick to return to the anchored position before advancing. This prevents an abrupt cursor jump when the mapping changes.
During the Standard introduction's normal free-movement stage, the participant may freely move the cursor using the direct absolute joystick mapping.


===Controlled Practice===
There is no timer or trial progression during this stage. It continues until the participant presses the joystick button or the experimenter selects '''CONTINUE'''.


Controlled practice uses the same basic controlled-trial behavior as the experiment:
The Easy introduction does not include a free-movement sandbox. Its normal demonstration, normal "your turn", and normal practice stages serve the same introductory purpose.


* Direct absolute mapping is used during centering.
===Automatic Practice===
* Joystick and cursor anchors are recorded when the target appears.
* Target-directed cursor movement uses the relative inverted mapping.
* The participant returns the joystick toward its anchor after target acquisition.


Controlled practice uses <code>PracticeCenterHoldTime</code> and deterministic practice targets and remains separate from experimental numbering and performance summaries. Its states are recorded in the BCI2000 data stream; no secondary CSV is written.
Automatic practice uses the same direct mapping and the same basic trial phases as experimental automatic trials:


After the final controlled practice trial, the participant must complete the return-to-center and return-to-anchor transition before the completion screen appears.
# Waiting for center
# Holding center
# Warning
# Pre-target delay
# Target visible
# Feedback


===Tutorial Completion===
Practice trials differ from experimental trials in several ways:


The completion screen summarizes the condition mappings:
* Center hold is determined by <code>PracticeCenterHoldTime</code> rather than <code>CenterHoldSeconds</code> in the Standard introduction, and by <code>EasyIntroPracticeCenterHoldMs</code> in the Easy introduction.
* Practice targets follow a deterministic sequence.
* <code>TaskBlock</code> and <code>TaskTrial</code> remain 0.
* <code>PracticeTrial</code> identifies the active practice trial.
* Practice activity is recorded in BCI2000 states; this application writes no separate trial-level CSV file.
* Practice results are excluded from experimental completion counts and timing summaries.
* Practice reset attempts do not increment experimental reset metrics.


* Normal (automatic): cursor movement follows joystick movement.
In the Easy introduction, normal practice is part of EasyIntroPhase 4, uses <code>EasyIntroNormalPracticeTrials</code> for its trial count, and uses <code>EasyIntroFeedbackDurationMs</code> for success feedback (or no feedback when <code>EasyIntroPracticeFeedback=0</code>). The same trial phases apply.
* Reversed (controlled): cursor movement is opposite joystick movement.
* Green targets identify automatic trials.
* Red targets identify controlled trials.


After continuation, the tutorial ends, <code>Introduction</code> returns to 0, the originally generated first experimental target is restored, and the experiment begins with the normal 1.5-second block announcement.
After the final automatic practice trial, the participant must return the cursor to the center before the tutorial advances.


===Experimental Trial Sequence===
===Controlled Free Movement===


Each experimental block begins with a 1.5-second announcement indicating whether the upcoming block is '''Normal''', '''Reversed''', or '''Mixed'''. These visible labels correspond to the existing automatic, controlled, and mixed block types; their numerical encodings are unchanged.
The controlled free-movement stage belongs to the Standard introduction. It allows the participant to explore reversed cursor control without a target.


A trial then proceeds as follows:
The participant is first asked to return the cursor to center. Once centered, the application records the current joystick and cursor positions as anchors and enables the same relative inverted mapping used during target-directed controlled movement.


# The participant moves the cursor into the center region.
When the participant requests continuation, the task requires the joystick to return to the anchored position before advancing. This prevents an abrupt cursor jump when the mapping changes.
# Once centered, the participant must remain there for <code>CenterHoldSeconds</code>.
# A yellow warning marker appears for <code>WarningSeconds</code>.
# A pre-target interval lasting <code>PreTargetDelaySeconds</code> follows.
# The target appears.
# The participant moves the cursor into the target.
# Target acquisition records the trial timing measurements and begins the feedback interval.
# After <code>FeedbackSeconds</code>, the task advances to the next trial or block.


If the participant leaves the center during the center-hold, warning, or pre-target interval, the task returns to the waiting-for-center phase and the preparation sequence begins again.
The Easy introduction has no controlled free-movement sandbox; its reversed demonstration and reversed "your turn" stages replace it.


A new target is generated when advancing to a new experimental trial. Manually resetting a trial does not generate a new target. Skipping an experimental trial instead advances to the next trial and generates a new target (unless the experiment has finished). A skip-block action advances past the remaining trials in the block.
===Controlled Practice===


===Automatic Condition (Normal)===
Controlled practice uses the same basic controlled-trial behavior as the experiment:


During an automatic trial, cursor position follows the joystick using a direct mapping. Moving the joystick in one direction moves the cursor in the corresponding direction.
* Direct absolute mapping is used during centering.
* Joystick and cursor anchors are recorded when the target appears.
* Target-directed cursor movement uses the relative inverted mapping.
* The participant returns the joystick toward its anchor after target acquisition.


Automatic targets are displayed in green.
Standard controlled practice uses <code>PracticeCenterHoldTime</code> and deterministic practice targets and remains separate from experimental numbering and performance summaries. Its states are recorded in the BCI2000 data stream; no secondary CSV is written.


===Controlled Condition (Reversed)===
In the Easy introduction, reversed practice is part of EasyIntroPhase 8, uses <code>EasyIntroReversedPracticeTrials</code> for its trial count, and uses <code>EasyIntroPracticeCenterHoldMs</code> plus <code>EasyIntroFeedbackDurationMs</code> (when <code>EasyIntroPracticeFeedback=1</code>).


During a controlled trial, the normal direct mapping is initially used while the participant returns to and holds the center.
After the final controlled practice trial, the participant must complete the return-to-center and return-to-anchor transition before the completion screen appears.


When the target appears, the current joystick position and cursor position are recorded as anchors. Cursor movement then becomes relative to those anchors and inverted. Moving the joystick away from its target-onset position causes the cursor to move in the opposite direction.
===Tutorial Completion===


Conceptually:
The Standard completion screen summarizes the condition mappings:


<pre>
* Normal (automatic): cursor movement follows joystick movement.
cursor position = anchor cursor position - joystick displacement
* Reversed (controlled): cursor movement is opposite joystick movement.
</pre>
* Green targets identify automatic trials.
* Red targets identify controlled trials.


The cursor is constrained to the participant display.
In the Easy introduction, the corresponding screen is EasyIntroPhase 9 (Ready). It states that green targets mean "move toward the target" and red targets mean "move in the opposite direction". Depending on the Easy-introduction parameters, it waits for participant joystick-button or researcher '''CONTINUE''' input, or advances automatically after <code>EasyIntroReadyScreenDurationMs</code>.


After completion of a controlled trial, the inverted mapping remains active until the joystick has returned close to the joystick position recorded at target onset. This prevents an abrupt cursor jump when returning from the controlled mapping to the normal mapping.
In both modes, the tutorial then ends, <code>Introduction</code> returns to 0, the originally generated first experimental target is restored, and the experiment begins with the normal 1.5-second block announcement.


Controlled targets are displayed in red.
===Experimental Trial Sequence===


===Joystick Input===
Each experimental block begins with a 1.5-second announcement indicating whether the upcoming block is '''Normal''', '''Reversed''', or '''Mixed'''. These visible labels correspond to the existing automatic, controlled, and mixed block types; their numerical encodings are unchanged.


Joystick input is provided through BCI2000's [[User Reference:Logging Input|input logging]] system.
A trial then proceeds as follows:


Joystick position states are expected to range from 0 through 32767. The application converts these values into internal task coordinates ranging from 0 through 1023.
# The participant moves the cursor into the center region.
# Once centered, the participant must remain there for <code>CenterHoldSeconds</code>.
# A yellow warning marker appears for <code>WarningSeconds</code>.
# A pre-target interval lasting <code>PreTargetDelaySeconds</code> follows.
# The target appears at <code>TargetDistancePixels</code> from the center.
# The participant moves the cursor into the target.
# Target acquisition records the trial timing measurements and begins the feedback interval.
# After <code>FeedbackSeconds</code>, the task advances to the next trial or block.


The application reads:
If the participant leaves the center during the center-hold, warning, or pre-target interval, the task returns to the waiting-for-center phase and the preparation sequence begins again.


* <code>JoystickXpos</code>
A new target is generated when advancing to a new experimental trial. Manually resetting a trial does not generate a new target. Skipping an experimental trial instead advances to the next trial and generates a new target (unless the experiment has finished). A skip-block action advances past the remaining trials in the block.
* <code>JoystickYpos</code>
* <code>JoystickButtons1</code>


<code>JoystickButtons1</code> is used during the tutorial as a participant continuation button. A rising button press may advance eligible tutorial screens. It does not advance active practice trials and has no effect on experimental trial progression.
===Automatic Condition (Normal)===
 
During an automatic trial, cursor position follows the joystick using a direct mapping. Moving the joystick in one direction moves the cursor in the corresponding direction.
 
Automatic targets are displayed in green.


Joystick recording is normally enabled using the <code>LogJoystick</code> option. See [[User Reference:Logging Input#LogJoystick|LogJoystick]] for configuration details.
===Controlled Condition (Reversed)===


===Experimental Target Generation===
During a controlled trial, the normal direct mapping is initially used while the participant returns to and holds the center.


A new target angle is generated for each new experimental trial.
When the target appears, the current joystick position and cursor position are recorded as anchors. Cursor movement then becomes relative to those anchors and inverted. Moving the joystick away from its target-onset position causes the cursor to move in the opposite direction.


The random target generator produces an integer between 0 and 3599. <code>TargetAngle</code> therefore represents tenths of a degree:
Conceptually:


<pre>
<pre>
angle in degrees = TargetAngle / 10
cursor position = anchor cursor position - joystick displacement
</pre>
</pre>


This produces target angles from 0.0 through 359.9 degrees.
The cursor is constrained to the participant display.


Targets are positioned at a fixed distance from the center using the generated angle.
After completion of a controlled trial, the inverted mapping remains active until the joystick has returned close to the joystick position recorded at target onset. This prevents an abrupt cursor jump when returning from the controlled mapping to the normal mapping.


Unlike the original Neumann et al. experiment, which used eight circularly arranged target locations, the BCI2000 implementation allows experimental targets to appear over a continuous range of angles.
Controlled targets are displayed in red.


===Practice Target Generation===
===Joystick Input===


Practice trials use a deterministic six-angle sequence rather than the experimental random target generator:
Joystick input is provided through BCI2000's [[User Reference:Logging Input|input logging]] system.


{| class="wikitable"
Joystick position states are expected to range from 0 through 32767. The application converts these values into internal task coordinates ranging from 0 through 1023.
! Sequence value
! Target angle
|-
| 150
| 15 degrees
|-
| 450
| 45 degrees
|-
| 750
| 75 degrees
|-
| 1050
| 105 degrees
|-
| 1350
| 135 degrees
|-
| 1650
| 165 degrees
|}


Automatic practice begins with the 15-degree target and follows the sequence in order.
The application reads:


Controlled practice begins with an offset of two positions, producing:
* <code>JoystickXpos</code>
* <code>JoystickYpos</code>
* <code>JoystickButtons1</code>
 
<code>JoystickButtons1</code> is used during the tutorial as a participant continuation button. A rising button press may advance eligible tutorial screens. It does not advance active practice trials and has no effect on experimental trial progression.
 
Joystick recording is normally enabled using the <code>LogJoystick</code> option. See [[User Reference:Logging Input#LogJoystick|LogJoystick]] for configuration details.
 
===Experimental Target Generation===
 
A new target angle is generated for each new experimental trial.
 
The random target generator produces an integer between 0 and 3599. <code>TargetAngle</code> therefore represents tenths of a degree:


<pre>
<pre>
75°, 105°, 135°, 165°, 15°, 45°
angle in degrees = TargetAngle / 10
</pre>
</pre>


If more than six practice trials are configured, the sequence repeats.
This produces target angles from 0.0 through 359.9 degrees.


These targets are positioned in the lower half of the participant display to reduce overlap with tutorial text.
Targets are positioned at a distance of <code>TargetDistancePixels</code> from the center (default 300 reference-display pixels) using the generated angle.


The random target generated for the first experimental trial is saved before the tutorial begins and restored after practice finishes.
Unlike the original Neumann et al. experiment, which used eight circularly arranged target locations, the BCI2000 implementation allows experimental targets to appear over a continuous range of angles.
 
If the target distance is changed at runtime through the diagnostic window, the current and saved experimental target positions are recalculated at the new distance. The current distance is recorded in <code>TargetDistancePx10</code>.


===Trial Phases===
===Practice Target Generation===


The current trial phase is recorded in <code>TaskPhase</code>.
Practice trials use a deterministic six-angle sequence rather than the experimental random target generator:


{| class="wikitable"
{| class="wikitable"
! Value
! Sequence value
! Phase
! Target angle
! Description
|-
|-
| 0
| 150
| Block announcement / no active practice trial
| 15 degrees
| During the experiment, the upcoming block type is being displayed. During non-trial tutorial screens, <code>TaskPhase</code> is also 0.
|-
|-
| 1
| 450
| Waiting for center
| 45 degrees
| The task is waiting for the cursor to enter the center region.
|-
|-
| 2
| 750
| Holding center
| 75 degrees
| The participant is completing the required center hold.
|-
|-
| 3
| 1050
| Warning
| 105 degrees
| The yellow warning cue is visible.
|-
|-
| 4
| 1350
| Pre-target delay
| 135 degrees
| The warning has ended and the task is waiting for target onset.
|-
|-
| 5
| 1650
| Target visible
| 165 degrees
| The peripheral target is visible and movement may occur.
|-
| 6
| Feedback
| The target has been acquired and the task is waiting before advancing.
|-
| 7
| Finished
| All configured experimental trials have been completed.
|}
|}


During active automatic or controlled practice trials, values 1 through 6 retain the same meanings as they do during experimental trials.
Automatic practice begins with the 15-degree target and follows the sequence in order.


Because non-trial tutorial screens use <code>TaskPhase=0</code>, analysts should use <code>Introduction</code> to distinguish tutorial screens from experimental block announcements.
Controlled practice begins with an offset of two positions, producing:
 
An experimental target onset is identified by:


<pre>
<pre>
Introduction == 0
75°, 105°, 135°, 165°, 15°, 45°
and TaskPhase transitions from 4 to 5
</pre>
</pre>


A practice target onset is identified by:
If more than six practice trials are configured, the sequence repeats.


<pre>
These targets are positioned in the lower half of the participant display to reduce overlap with tutorial text, at the current <code>TargetDistancePixels</code> distance. The same deterministic sequence is used for both Standard and Easy practice trials.
Introduction == 1
and PracticeTrial > 0
and TaskPhase transitions from 4 to 5
</pre>


===Condition and Block Encodings===
The random target generated for the first experimental trial is saved before the tutorial begins and restored after practice finishes.
 
===Trial Phases===
 
The current trial phase is recorded in <code>TaskPhase</code>.


{| class="wikitable"
{| class="wikitable"
! State/Parameter
! Value
! Value
! Meaning
! Phase
! Description
|-
|-
| <code>TaskCondition</code>
| 0
| 0
| Automatic
| Block announcement / no active practice trial
| During the experiment, the upcoming block type is being displayed. During non-trial tutorial screens, including Easy-introduction animation and text screens, <code>TaskPhase</code> is also 0.
|-
|-
| <code>TaskCondition</code>
| 1
| 1
| Controlled
| Waiting for center
| The task is waiting for the cursor to enter the center region.
|-
|-
| <code>TaskBlockType</code>
| 2
| 0
| Holding center
| Ordered automatic block
| The participant is completing the required center hold.
|-
|-
| <code>TaskBlockType</code>
| 3
| 1
| Warning
| Ordered controlled block
| The yellow warning cue is visible.
|-
| 4
| Pre-target delay
| The warning has ended and the task is waiting for target onset.
|-
|-
| <code>TaskBlockType</code>
| 5
| 2
| Target visible
| Pseudorandom mixed block
| The peripheral target is visible and movement may occur.
|-
|-
| <code>OrderedStartCondition</code>
| 6
| 0
| Feedback
| Automatic first
| The target has been acquired and the task is waiting before advancing.
|-
|-
| <code>OrderedStartCondition</code>
| 7
| 1
| Finished
| Controlled first
| The run has reached its end after the final trial, or after a researcher action skips the remaining trial(s).
|}
|}


During the tutorial, <code>TaskCondition</code> reflects the tutorial condition rather than the first experimental condition. It begins at 0 during the general introduction and normal free-movement stages, including in Controlled Only mode, and changes to 1 once the controlled portion of the tutorial begins.
During active automatic or controlled practice trials, including Easy-introduction practice, values 1 through 6 retain the same meanings as they do during experimental trials.


During the tutorial, <code>TaskBlockType</code> is forced to 0 and should not be interpreted as an experimental ordered-automatic block. The participant sees Normal for <code>TaskCondition=0</code> and Reversed for <code>TaskCondition=1</code>; these labels do not change the state values.
Because non-trial tutorial screens use <code>TaskPhase=0</code>, analysts should use <code>Introduction</code> to distinguish tutorial screens from experimental block announcements. Within the tutorial, <code>TutorialPhase</code> identifies Standard stages and <code>EasyIntroPhase</code> identifies Easy stages.


===Participant Display===
An experimental target onset is identified by:


The participant-facing [[Programming Reference:ApplicationWindow Class|ApplicationWindow]] contains:
<pre>
Introduction == 0
and TaskPhase transitions from 4 to 5
</pre>


* A light gray background (<code>0xEBEBEB</code>).
A practice target onset is identified by:
* A black cursor whose diameter is configured by <code>CursorDiameterPixels</code> (default 16 pixels in the reference display).
* A black central fixation cross.
* A gray center marker.
* A larger yellow warning marker.
* A green target during automatic (Normal) trials.
* A red target during controlled (Reversed) trials.
* A target diameter controlled by <code>TargetDiameterPixels</code> (default 36 pixels). This value also affects the elliptical target-hit tolerance, not just appearance.
* A visible '''NORMAL''' or '''REVERSED''' condition cue near the top of the participant display during relevant tutorial stages and block announcements.
* A progress bar near the top of the display during the experiment.
* Tutorial and practice instructions when the introduction is enabled, including white text in a dark gray message box.
* Block announcements using the terms Normal, Reversed, or Mixed.
* An "ended" message when all experimental trials are complete.


The experimental progress bar is hidden throughout the tutorial and practice sequence. Practice trials do not contribute to experimental progress. When a researcher skips the remainder of an experimental block, the bar can advance to reflect the skipped trial positions even though those trials are not counted as successfully completed.
<pre>
Introduction == 1
and PracticeTrial > 0
and TaskPhase transitions from 4 to 5
</pre>


The <code>StimulusDisplay</code> parameter may be used to select the physical monitor on which the participant window appears.
===Condition and Block Encodings===


''The Normal/Reversed cue is intentional in this USB HID task. The underlying state encoding remains <code>TaskCondition=0</code> for automatic/Normal and <code>TaskCondition=1</code> for controlled/Reversed.''
{| class="wikitable"
 
! State/Parameter
===Diagnostic Window===
! Value
 
! Meaning
A separate diagnostic window is shown to the experimenter. In the currently inspected version, the visible panel is the '''performance metrics panel'''. During the tutorial it presents the introduction/practice context, mapping condition and applicable practice-trial information; live timing is shown as placeholders where appropriate, and run averages are not yet available. During experimental trials it presents:
|-
 
| <code>TaskCondition</code>
* Normal or Reversed condition and trial numbering within the block and overall experiment.
| 0
* Real-time reaction time, movement time, and total time.
| Automatic
* Overall and condition-specific (automatic and controlled) mean timing measurements.
|-
 
| <code>TaskCondition</code>
The application still assembles a more detailed diagnostic text label containing tutorial phase, task phase, target position, joystick and cursor coordinates, movement status, block type, completion/reset counts, and other status information. However, that text widget is explicitly hidden in the inspected build (<code>mpDiagnosticText-&gt;hide()</code>). These detailed values are '''not visible''' in the current diagnostic window and should not be mistaken for on-screen readouts. Relevant values can still be obtained from the recorded states.
| 1
 
| Controlled
===Researcher Controls===
|-
 
| <code>TaskBlockType</code>
The diagnostic window contains a blue '''CONTINUE''' button on eligible tutorial screens. When continuation is unavailable, it displays '''CONTINUE UNAVAILABLE'''.
| 0
 
| Ordered automatic block
Its context-sensitive reset button displays:
|-
 
| <code>TaskBlockType</code>
* '''RESET PRACTICE TRIAL''' during eligible practice trials.
| 1
* '''RESET CURRENT TRIAL''' during eligible experimental trials.
| Ordered controlled block
* '''RESET UNAVAILABLE''' when reset is not permitted.
|-
| <code>TaskBlockType</code>
| 2
| Pseudorandom mixed block
|-
| <code>OrderedStartCondition</code>
| 0
| Automatic first
|-
| <code>OrderedStartCondition</code>
| 1
| Controlled first
|}


The current window also includes '''SKIP TRIAL''', '''SKIP CURRENT BLOCK''', '''SKIP INTRODUCTION''', '''SKIP PRACTICE''', '''SKIP SANDBOX''', and '''PAUSE'''/'''RESUME'''. Controls are enabled only in the appropriate task context. Skipping the current block and skipping the introduction prompt for confirmation; the other skip controls act without a confirmation dialog.
During the tutorial, <code>TaskCondition</code> reflects the tutorial condition rather than the first experimental condition. In the Standard introduction it begins at 0 during the general introduction and normal free-movement stages, including in Controlled Only mode, and changes to 1 once the controlled portion of the tutorial begins. In the Easy introduction it is 0 during the basic demonstration and all normal stages, changes to 1 when the reversed introduction begins, and remains 1 through the ready screen.


===Researcher Skip Controls===
During the tutorial, <code>TaskBlockType</code> is forced to 0 and should not be interpreted as an experimental ordered-automatic block. The participant sees Normal for <code>TaskCondition=0</code> and Reversed for <code>TaskCondition=1</code>; these labels do not change the state values.


{| class="wikitable"
===Participant Display===
! Control
! When available
! Behavior
! Recorded event
|-
| '''SKIP TRIAL'''
| During an experimental trial before feedback, while not paused
| Immediately advances to the next trial (or finishes the run if it was the last trial). A new target is generated for the next trial. A skipped trial does not increment completed-trial or reset metrics. In a controlled trial the return-to-anchor behavior is retained as needed.
| <code>TrialSkipped</code>
|-
| '''SKIP CURRENT BLOCK'''
| During an experimental trial before feedback, while not paused; confirmation required
| Skips the remaining trials in the current block, advances to the next block or ends the run, and increments the overall trial-position counter by the number skipped. It does not count these trials as completed.
| <code>ConditionSkipped</code>
|-
| '''SKIP INTRODUCTION'''
| During the tutorial, while not paused; confirmation required
| Exits the entire tutorial, restores the saved first experimental target, and enters the experimental block-announcement sequence.
| <code>IntroductionSkipped</code>
|-
| '''SKIP PRACTICE'''
| During an active practice trial, while not paused
| Ends the remaining practice trials for that practice condition. After Normal practice, proceeds to Reversed instructions if configured, otherwise tutorial completion; after Reversed practice, proceeds to completion.
| <code>PracticeSkipped</code>
|-
| '''SKIP SANDBOX'''
| During Normal or Reversed free movement, while not paused
| Ends the free-movement stage and proceeds to the appropriate next instructions, practice stage, or completion screen.
| <code>SandboxSkipped</code>
|}


Each skip event is written as a one-processing-block state pulse and is cleared at the beginning of the next processing block. Skip actions can bypass the regular end-of-<code>Process()</code> state synchronization. Therefore, the event pulse may precede the updated <code>TaskPhase</code>, <code>TaskTrial</code>, <code>TaskBlock</code>, target, or cursor states by one processing block. If a skip ends the entire run, the last recorded phase/trial values may retain their pre-skip values rather than representing the usual Finished-phase state. Offline analyses should therefore use the event states, not rely solely on a simultaneous change in other states.
The participant-facing [[Programming Reference:ApplicationWindow Class|ApplicationWindow]] contains:


===Pause and Resume===
* A light gray background (<code>0xEBEBEB</code>).
* A black cursor whose diameter is configured by <code>CursorDiameterPixels</code> (default 16 pixels in the reference display). The cursor diameter can also be changed at runtime from the diagnostic window; the center and warning markers retain their fixed sizes when it changes.
* A black central fixation cross.
* A gray center marker.
* A larger yellow warning marker.
* A green target during automatic (Normal) trials.
* A red target during controlled (Reversed) trials.
* A target diameter controlled by <code>TargetDiameterPixels</code> (default 36 pixels). This value also affects the elliptical target-hit tolerance, not just appearance.
* A center-to-target distance controlled by <code>TargetDistancePixels</code> (default 300 pixels).
* A visible '''NORMAL''' or '''REVERSED''' condition cue near the top of the participant display during relevant Standard tutorial stages and block announcements. The cue is not shown during the Easy introduction.
* A progress bar near the top of the display during the experiment.
* Tutorial and practice instructions when the introduction is enabled. The Standard introduction uses white text in a dark gray message box. The Easy introduction uses black text directly on the light background, and its text-only stages hide the cursor and fixation cross and occupy most of the display.
* Animated cursor and target demonstrations during the Easy introduction, optionally accompanied by an animated joystick illustration.
* Block announcements using the terms Normal, Reversed, or Mixed.
* An "ended" message when the run reaches its end, including when a skip action bypasses the remaining trial(s).
 
The experimental progress bar is hidden throughout the tutorial and practice sequence. Practice trials do not contribute to experimental progress. When a researcher skips the remainder of an experimental block, the bar can advance to reflect the skipped trial positions even though those trials are not counted as successfully completed.


The '''PAUSE'''/'''RESUME''' control is available during both tutorial and experimental portions of the run, but not after the task finishes.
Changing the cursor diameter or target distance in the diagnostic window updates the participant display on the next processing block, recalculates the current and saved experimental target positions, and pulses <code>DisplayGeometryChanged</code>. The applied values are recorded in <code>CursorDiameterPx10</code> and <code>TargetDistancePx10</code>. The target diameter can be changed only through the <code>TargetDiameterPixels</code> parameter before the run.


* Pausing sets <code>TaskPaused=1</code>. Task trial and cursor progression stop, but the BCI2000 stream continues to record samples with the pause state high.
The <code>StimulusDisplay</code> parameter may be used to select the physical monitor on which the participant window appears.
* Resuming sets <code>TaskPaused=0</code>. The program shifts the applicable phase, tutorial, target-onset, and movement-onset clocks forward by the paused duration.
* Paused time is excluded from the application's reaction time, movement time, total time, and active phase durations.
* Researcher skip actions are unavailable while paused.


A paused BCI2000 recording is not the same as a stopped BCI2000 run. Analysts should explicitly account for samples with <code>TaskPaused=1</code>.
''The Normal/Reversed cue is intentional in this USB HID task. The underlying state encoding remains <code>TaskCondition=0</code> for automatic/Normal and <code>TaskCondition=1</code> for controlled/Reversed. In the Easy introduction, condition is conveyed by target color and instruction text instead of the on-screen cue.''


===Trial Reset===
===Diagnostic Window===


Experimental trials may be manually reset before they reach the feedback phase.
A separate diagnostic window is shown to the experimenter. In the currently inspected version, the visible panel is the '''performance metrics panel'''. During the tutorial it presents the introduction/practice context, mapping condition, cursor diameter, target distance, and applicable practice-trial information; live timing is shown as placeholders where appropriate, and run averages are not yet available. During experimental trials it presents:


Resetting an experimental trial:
* Normal or Reversed condition and trial numbering within the block and overall experiment.
* Current cursor diameter and target distance.
* The current <code>ReactionTimeMs</code>, <code>MovementTimeMs</code>, and <code>TotalTimeMs</code> state values under a panel heading labeled '''REAL-TIME METRICS'''. These are not continuously running timers: they remain 0 until a target is acquired, then show the completed trial's values during feedback (and at run end for the final successful trial).
* Overall and condition-specific (automatic and controlled) mean timing measurements.


* Returns the task to the waiting-for-center phase.
Below the metrics panel are two spin boxes labeled '''Cursor diameter''' and '''Target distance'''. They adjust the displayed cursor size and center-to-target distance during a run. A change is applied on the next processing block, updates the current and saved target positions, pulses <code>DisplayGeometryChanged</code>, and updates <code>CursorDiameterPx10</code> and <code>TargetDistancePx10</code>.
* Clears the current movement and timing states.
* Generates a <code>TrialReset</code> event.
* Increments the experimental diagnostic reset count.
* Keeps the same trial number.
* Keeps the same target.
* Does not generate a successful-trial event or count as a completed experimental trial.


Practice trials may also be reset before feedback.
The application still assembles a more detailed diagnostic text label containing tutorial phase, task phase, target position, joystick and cursor coordinates, movement status, block type, completion/reset counts, and other status information. However, that text widget is explicitly hidden in the inspected build (<code>mpDiagnosticText-&gt;hide()</code>). These detailed values are '''not visible''' in the current diagnostic window and should not be mistaken for on-screen readouts. Relevant values can still be obtained from the recorded states.


Resetting a practice trial:
===Researcher Controls===


* Returns the practice trial to the waiting-for-center phase.
The diagnostic window contains a blue '''CONTINUE''' button on eligible tutorial screens. When continuation is unavailable, it displays '''CONTINUE UNAVAILABLE'''. In the Easy introduction, researcher '''CONTINUE''' remains available even when <code>EasyIntroSurgeryMode=1</code>; surgery mode disables participant joystick-button continuation, not this researcher control. When <code>EasyIntroRequireButtonPress=1</code> and surgery mode is off, either participant joystick input or researcher '''CONTINUE''' is required; otherwise, screens also advance automatically. Static Easy screens are immediately eligible, and demonstration screens become eligible after all configured examples have played. Researcher '''CONTINUE''' also bypasses the <code>EasyIntroRequireJoystickNeutral</code> gate.
* Clears movement and timing states.
* Generates a <code>TrialReset</code> event.
* Keeps the same <code>PracticeTrial</code> value.
* Keeps the same deterministic target.
* Does not increment experimental reset metrics.
* Does not increment experimental completed-trial metrics.


Reset is unavailable during tutorial instruction/free-movement screens and after a trial has entered feedback. Resetting a controlled trial after its target is visible also enables return-to-anchor handling so that resuming normal cursor control does not produce an abrupt jump. Reset preserves the current trial and its target, whereas '''SKIP TRIAL''' advances to a new one.
Its context-sensitive reset button displays:


===Timing Measurements===
* '''RESET PRACTICE TRIAL''' during eligible practice trials.
* '''RESET CURRENT TRIAL''' during eligible experimental trials.
* '''RESET UNAVAILABLE''' when reset is not permitted.


The task calculates reaction time, movement time, and total time for successfully completed practice and experimental trials.
The current window also includes '''SKIP TRIAL''', '''SKIP CURRENT BLOCK''', '''SKIP INTRODUCTION''', '''SKIP PRACTICE''', '''SKIP SANDBOX''', '''PREVIOUS EASY PHASE''', '''RESTART EASY PHASE''', and '''PAUSE'''/'''RESUME'''. Controls are enabled only in the appropriate task context. Skipping the current block and skipping the introduction prompt for confirmation; the other skip controls act without a confirmation dialog.


'''Reaction time''' is the interval between target appearance and detected movement onset.
During the Easy introduction, the '''SKIP SANDBOX''' button is relabeled '''SKIP CURRENT EASY PHASE'''. '''PREVIOUS EASY PHASE''' returns to the preceding Easy stage (it is unavailable on the basic-demonstration stage), and '''RESTART EASY PHASE''' restarts the current Easy stage, including restarting an active practice block at its first trial. Setting <code>EasyIntroAllowResearcherSkip=0</code> disables the Easy skip controls; the previous-phase and restart-phase controls remain available.


'''Movement time''' is the interval between detected movement onset and target acquisition.
===Researcher Skip Controls===


'''Total time''' is the interval between target appearance and target acquisition.
{| class="wikitable"
! Control
! When available
! Behavior
! Recorded event
|-
| '''SKIP TRIAL'''
| During an experimental trial before feedback, while not paused
| Immediately advances to the next trial (or finishes the run if it was the last trial). A new target is generated for the next trial. A skipped trial does not increment completed-trial or reset metrics. In a controlled trial the return-to-anchor behavior is retained as needed.
| <code>TrialSkipped</code>
|-
| '''SKIP CURRENT BLOCK'''
| During an experimental trial before feedback, while not paused; confirmation required
| Skips the remaining trials in the current block, advances to the next block or ends the run, and increments the overall trial-position counter by the number skipped. It does not count these trials as completed.
| <code>ConditionSkipped</code>
|-
| '''SKIP INTRODUCTION'''
| During the tutorial, while not paused; confirmation required
| Exits the entire tutorial, restores the saved first experimental target, and enters the experimental block-announcement sequence. In the Easy introduction this control is available only when <code>EasyIntroAllowResearcherSkip=1</code>.
| <code>IntroductionSkipped</code>
|-
| '''SKIP PRACTICE'''
| During an active Standard or Easy practice trial, while not paused
| Ends the remaining practice trials for that practice condition. In the Standard introduction, after Normal practice it proceeds to Reversed instructions if configured, otherwise tutorial completion; after Reversed practice it proceeds to completion. In the Easy introduction it advances to the next Easy stage. Available in Easy mode only when <code>EasyIntroAllowResearcherSkip=1</code>.
| <code>PracticeSkipped</code>
|-
| '''SKIP SANDBOX''' / '''SKIP CURRENT EASY PHASE'''
| During Standard Normal or Reversed free movement, or during any non-practice Easy stage, while not paused
| In Standard mode, ends the free-movement stage and proceeds to the appropriate next instructions, practice stage, or completion screen. In Easy mode, the button is relabeled '''SKIP CURRENT EASY PHASE''' and advances to the next Easy stage; from the ready stage it begins the experiment. Available in Easy mode only when <code>EasyIntroAllowResearcherSkip=1</code>.
| <code>SandboxSkipped</code>
|-
| '''PREVIOUS EASY PHASE'''
| During the Easy introduction, while not paused, and not on the basic-demonstration stage
| Returns to the preceding Easy stage. Moving back from the reversed-transition or ready stage re-enters the preceding practice block at its first trial.
| <code>EasyIntroPrevious</code>
|-
| '''RESTART EASY PHASE'''
| During the Easy introduction, while not paused
| Restarts the current Easy stage. If a practice stage is active, the practice block restarts at its first trial.
| <code>EasyIntroRestarted</code>
|}


Movement onset is detected when either joystick axis differs from the center-hold baseline by more than the task's joystick deadzone.
Each skip event is written as a one-processing-block state pulse and is cleared at the beginning of the next processing block. The Easy-phase navigation events <code>EasyIntroPrevious</code> and <code>EasyIntroRestarted</code> follow the same one-block pulse pattern. Skip and navigation actions can bypass the regular end-of-<code>Process()</code> state synchronization. Therefore, the event pulse may precede the updated <code>TaskPhase</code>, <code>TaskTrial</code>, <code>TaskBlock</code>, target, or cursor states by one processing block. If an action ends the entire run, the last recorded phase/trial values may retain their pre-action values rather than representing the usual Finished-phase state. Offline analyses should therefore use the event states, not rely solely on a simultaneous change in other states.


Timing is measured using a steady clock, but movement onset and target acquisition are detected during calls to <code>Process()</code>. The effective temporal resolution is therefore limited by the BCI2000 processing-block interval.
===Pause and Resume===


Practice timing values are recorded in the BCI2000 states but are excluded from experimental timing summaries. The task writes no application-specific CSV. When the researcher pauses the task, clock offsets are adjusted on resume so that the reported RT, MT, and total time exclude the paused interval, even though the paused samples remain in the BCI2000 data stream.
The '''PAUSE'''/'''RESUME''' control is available during both tutorial and experimental portions of the run, but not after the task finishes.


===Data Recording===
* Pausing sets <code>TaskPaused=1</code>. Task trial and cursor progression stop, but the BCI2000 stream continues to record samples with the pause state high.
* Resuming sets <code>TaskPaused=0</code>. The program shifts the applicable phase, tutorial, target-onset, and movement-onset clocks forward by the paused duration.
* Paused time is excluded from the application's reaction time, movement time, total time, and active phase durations.
* Researcher skip, previous-phase, and restart-phase actions are unavailable while paused.
* Display-geometry changes made in the diagnostic window are still applied during a pause, without advancing the task.


The task records its behavioral and tutorial variables as BCI2000 states, allowing them to be synchronized with the normal BCI2000 <code>.dat</code> recording.
A paused BCI2000 recording is not the same as a stopped BCI2000 run. Analysts should explicitly account for samples with <code>TaskPaused=1</code>.


Joystick coordinates are also recorded when [[User Reference:Logging Input#LogJoystick|joystick input logging]] is enabled.
===Trial Reset===


Tutorial and practice samples are part of the same BCI2000 run as the experiment. The <code>Introduction</code> state should therefore be used when separating tutorial/practice data from experimental data during offline analysis.
Experimental trials may be manually reset before they reach the feedback phase.


Practice trials record:
Resetting an experimental trial:


* Cursor trajectory.
* Returns the task to the waiting-for-center phase.
* Target coordinates and angle.
* Clears the current movement and timing states.
* Trial phase.
* Generates a <code>TrialReset</code> event.
* Practice condition.
* Increments the experimental diagnostic reset count.
* Movement onset.
* Keeps the same trial number.
* Target acquisition.
* Keeps the same target.
* Reaction time.
* Does not generate a successful-trial event or count as a completed experimental trial.
* Movement time.
* Total time.
* Practice reset events.
* Practice trial number.


Practice trials are intentionally excluded from:
Practice trials may also be reset before feedback, in both the Standard and Easy introductions.


* Experimental <code>TaskTrial</code> numbering.
Resetting a practice trial:
* Experimental <code>TaskBlock</code> numbering.
* Automatic and controlled completion counts.
* Automatic and controlled reset counts.
* Mean reaction-time summaries.
* Mean movement-time summaries.
* Mean total-time summaries.


'''No secondary results file is created by this application in the current version.''' The <code>ResultsFile</code> parameter and trial-level CSV writer were removed. All per-trial behavioral information must be reconstructed from the recorded BCI2000 <code>.dat</code> states; joystick state recording additionally depends on the normal <code>LogJoystick</code> configuration.
* Returns the practice trial to the waiting-for-center phase.
* Clears movement and timing states.
* Generates a <code>TrialReset</code> event.
* Keeps the same <code>PracticeTrial</code> value.
* Keeps the same deterministic target.
* Does not increment experimental reset metrics.
* Does not increment experimental completed-trial metrics.


Researcher skip events (<code>TrialSkipped</code>, <code>ConditionSkipped</code>, <code>IntroductionSkipped</code>, <code>PracticeSkipped</code>, <code>SandboxSkipped</code>) and the persistent <code>TaskPaused</code> state are also recorded. They identify deviations from ordinary trial/tutorial progression and samples recorded during pause.
Reset is unavailable during tutorial instruction, demonstration, and free-movement screens and after a trial has entered feedback. Resetting a controlled trial after its target is visible also enables return-to-anchor handling so that resuming normal cursor control does not produce an abrupt jump. Reset preserves the current trial and its target, whereas '''SKIP TRIAL''' advances to a new one.


The application writes BCI2000 console messages when the task starts and stops and when practice or experimental trials succeed. Messages include the applicable trial/condition and reaction/movement times; these console messages are not an additional trial-level results file and should not be treated as synchronized state data.
===Timing Measurements===


==Parameters==
The task calculates reaction time, movement time, and total time for successfully completed practice and experimental trials.


Parameters for experimental structure, timing, and display are grouped under <code>Application:USBHIDJoystick</code> in the BCI2000 parameter tree. <code>EnableIntroduction</code>, <code>AutomaticPracticeTrials</code>, <code>ControlledPracticeTrials</code>, and <code>PracticeCenterHoldTime</code> are grouped under <code>Application:Introduction</code>. Existing parameter files should use the current group definitions.
'''Reaction time''' is the interval between target appearance and detected movement onset.


===EnableIntroduction===
'''Movement time''' is the interval between detected movement onset and target acquisition.


Enables or disables the participant tutorial and practice sequence.
'''Total time''' is the interval between target appearance and target acquisition.


Type: integer boolean
Movement onset is detected when either joystick axis differs from the center-hold baseline by more than the task's joystick deadzone.


Default: <code>1</code>
Timing is measured using a steady clock, but movement onset and target acquisition are detected during calls to <code>Process()</code>. The effective temporal resolution is therefore limited by the BCI2000 processing-block interval.


Range: <code>0-1</code>
Practice timing values are recorded in the BCI2000 states but are excluded from experimental timing summaries. The task writes no application-specific CSV. When the researcher pauses the task, clock offsets are adjusted on resume so that the reported RT, MT, and total time exclude the paused interval, even though the paused samples remain in the BCI2000 data stream.


Values:
In the Easy introduction, the interval after a successful practice trial is set by <code>EasyIntroFeedbackDurationMs</code>, or is omitted when <code>EasyIntroPracticeFeedback=0</code>. This feedback interval follows target acquisition and does not change the recorded reaction, movement, or total times.


* <code>0</code>: Skip the tutorial and begin the experiment normally.
===Data Recording===
* <code>1</code>: Run the tutorial and practice sequence before the experiment.


This parameter applies to all experiment modes.
The task records its behavioral and tutorial variables as BCI2000 states, allowing them to be synchronized with the normal BCI2000 <code>.dat</code> recording.


===AutomaticPracticeTrials===
Joystick coordinates are also recorded when [[User Reference:Logging Input#LogJoystick|joystick input logging]] is enabled.


Number of automatic practice trials presented during the tutorial.
Tutorial and practice samples are part of the same BCI2000 run as the experiment. The <code>Introduction</code> state should therefore be used when separating tutorial/practice data from experimental data during offline analysis. Within the tutorial, <code>TutorialPhase</code> identifies Standard stages and <code>EasyIntroPhase</code> identifies Easy stages.


Type: integer
Practice trials record:


Default: <code>3</code>
* Cursor trajectory.
 
* Target coordinates and angle.
Range: <code>0-20</code>
* Trial phase.
 
* Practice condition.
The parameter is used only when the selected experiment mode contains automatic trials.
* Movement onset.
* Target acquisition.
* Reaction time.
* Movement time.
* Total time.
* Practice reset events.
* Practice trial number.


A value of 0 skips automatic practice trials while retaining the automatic instruction page.
Practice trials are intentionally excluded from:


Practice trials do not count toward the experimental trial-count parameters.
* Experimental <code>TaskTrial</code> numbering.
* Experimental <code>TaskBlock</code> numbering.
* Automatic and controlled completion counts.
* Automatic and controlled reset counts.
* Mean reaction-time summaries.
* Mean movement-time summaries.
* Mean total-time summaries.


===ControlledPracticeTrials===
'''No secondary results file is created by this application in the current version.''' The <code>ResultsFile</code> parameter and trial-level CSV writer were removed. All per-trial behavioral information must be reconstructed from the recorded BCI2000 <code>.dat</code> states; joystick state recording additionally depends on the normal <code>LogJoystick</code> configuration.


Number of controlled practice trials presented during the tutorial.
Researcher skip events (<code>TrialSkipped</code>, <code>ConditionSkipped</code>, <code>IntroductionSkipped</code>, <code>PracticeSkipped</code>, <code>SandboxSkipped</code>), Easy-phase navigation events (<code>EasyIntroPrevious</code>, <code>EasyIntroRestarted</code>), and the persistent <code>TaskPaused</code> state are also recorded. They identify deviations from ordinary trial/tutorial progression and samples recorded during pause.


Type: integer
Display geometry is recorded through <code>CursorDiameterPx10</code> and <code>TargetDistancePx10</code>, both expressed in tenths of a pixel, and each runtime change produces a one-block <code>DisplayGeometryChanged</code> pulse. Because a target-distance change moves the current and saved targets, <code>TargetX</code>/<code>TargetY</code> and <code>TargetAngle</code> should be interpreted together with the distance state for the samples in question.


Default: <code>3</code>
The application writes BCI2000 console messages when the task starts and stops and when practice or experimental trials succeed. Messages include the applicable trial/condition and reaction/movement times; these console messages are not an additional trial-level results file and should not be treated as synchronized state data.


Range: <code>0-20</code>
==Parameters==


The parameter is used only when the selected experiment mode contains controlled trials.
Parameters for experimental structure, timing, display, and display geometry are grouped under <code>Application:USBHIDJoystick</code> in the BCI2000 parameter tree. <code>AutomaticPracticeTrials</code>, <code>ControlledPracticeTrials</code>, and <code>PracticeCenterHoldTime</code> are grouped under <code>Application:Introduction</code>. <code>IntroductionMode</code> and the <code>EasyIntro*</code> parameters are grouped under <code>Application:EasyIntroduction</code>. Existing parameter files that use the removed <code>EnableIntroduction</code> parameter must be updated.


A value of 0 skips controlled practice trials. The controlled instruction page and controlled free-movement demonstration are still presented.
===IntroductionMode===


Practice trials do not count toward the experimental trial-count parameters.
Selects the participant introduction and practice sequence.


===PracticeCenterHoldTime===
Type: integer enumeration


Center-hold duration used during automatic and controlled practice trials.
Default: <code>2</code>


Type: floating-point time
Range: <code>0-2</code>


Default: <code>1s</code>
Values:


Range: <code>0s-60s</code>
* <code>0</code>: Disabled. Skip the introduction and begin the experiment normally.
* <code>1</code>: Standard. Text-driven introduction with free movement and practice trials.
* <code>2</code>: Easy. Guided demonstrations, "your turn" screens, and short practice blocks (default).


This parameter replaces <code>CenterHoldSeconds</code> during practice trials only.
This parameter applies to all experiment modes. It replaces the earlier boolean <code>EnableIntroduction</code> parameter: <code>EnableIntroduction=1</code> corresponds approximately to <code>IntroductionMode=1</code> (Standard), and <code>EnableIntroduction=0</code> corresponds to <code>IntroductionMode=0</code> (Disabled).


Experimental trials continue to use <code>CenterHoldSeconds</code>.
===AutomaticPracticeTrials===


===ExperimentMode===
Number of automatic practice trials presented during the Standard introduction (<code>IntroductionMode=1</code>).


Selects the overall experimental structure.
Type: integer


Type: integer enumeration
Default: <code>3</code>


Default: <code>1</code>
Range: <code>0-20</code>


Range: <code>1-4</code>
The parameter is used only when the selected experiment mode contains automatic trials.


Values:
A value of 0 skips automatic practice trials while retaining the automatic instruction page.


* <code>1</code>: Automatic only
The Easy introduction uses <code>EasyIntroNormalPracticeTrials</code> instead.
* <code>2</code>: Controlled only
* <code>3</code>: Ordered automatic and controlled
* <code>4</code>: Ordered automatic, ordered controlled, and pseudorandom mixed


The application verifies during preflight that the trial-count parameters required by the selected mode are at least 1.
Practice trials do not count toward the experimental trial-count parameters.


The selected mode also determines which condition-specific tutorial sections are presented when <code>EnableIntroduction=1</code>.
===ControlledPracticeTrials===


===AutomaticTrials===
Number of controlled practice trials presented during the Standard introduction (<code>IntroductionMode=1</code>).
 
Number of automatic experimental trials used by experiment modes 1 and 3.


Type: integer
Type: integer


Default: <code>5</code>
Default: <code>3</code>


Declared range: <code>0-10000</code>
Range: <code>0-20</code>


When used by the selected experiment mode, the value must be at least 1.
The parameter is used only when the selected experiment mode contains controlled trials.


Practice trials are additional and do not reduce or increment this count.
A value of 0 skips controlled practice trials. The controlled instruction page and controlled free-movement demonstration are still presented.


===ControlledTrials===
The Easy introduction uses <code>EasyIntroReversedPracticeTrials</code> instead.


Number of controlled experimental trials used by experiment modes 2 and 3.
Practice trials do not count toward the experimental trial-count parameters.


Type: integer
===PracticeCenterHoldTime===


Default: <code>5</code>
Center-hold duration used during Standard-introduction practice trials.


Declared range: <code>0-10000</code>
Type: floating-point time


When used by the selected experiment mode, the value must be at least 1.
Default: <code>1s</code>


Practice trials are additional and do not reduce or increment this count.
Range: <code>0s-60s</code>


===OrderedStartCondition===
This parameter replaces <code>CenterHoldSeconds</code> during Standard practice trials only.


Determines which experimental condition is presented first in experiment mode 3.
Easy-introduction practice trials use <code>EasyIntroPracticeCenterHoldMs</code>.


Type: integer enumeration
Experimental trials continue to use <code>CenterHoldSeconds</code>.


Default: <code>0</code>
The following parameters belong to the <code>Application:EasyIntroduction</code> group and affect only the Easy introduction.


Values:
===EasyIntroAnimationEnabled===


* <code>0</code>: Automatic first
Enables animated cursor demonstrations in the Easy introduction.
* <code>1</code>: Controlled first


This parameter does not affect experiment modes 1, 2, or 4.
Type: integer boolean


It also does not affect tutorial order. When both conditions are included, the tutorial always presents automatic training before controlled training.
Default: <code>1</code>


===OrderedAutomaticTrials===
Range: <code>0-1</code>


Number of experimental automatic trials in the ordered automatic block of experiment mode 4.
When set to 0, the cursor is displayed at a near-static position instead of animating between the center and target.


Type: integer
===EasyIntroAnimationDurationMs===


Default: <code>5</code>
Duration of each Easy-introduction demonstration movement.


Declared range: <code>0-10000</code>
Type: integer (milliseconds)


When mode 4 is selected, the value must be at least 1.
Default: <code>2500</code>


===OrderedControlledTrials===
Range: <code>1-60000</code>


Number of experimental controlled trials in the ordered controlled block of experiment mode 4.
===EasyIntroAnimationPauseMs===


Type: integer
Pause at the target before the next demonstration example or repetition.


Default: <code>5</code>
Type: integer (milliseconds)


Declared range: <code>0-10000</code>
Default: <code>750</code>


When mode 4 is selected, the value must be at least 1.
Range: <code>0-60000</code>


===RandomAutomaticTrials===
===EasyIntroAnimationLoop===


Number of experimental automatic trials included in the pseudorandom block of experiment mode 4.
Repeats the demonstration until the Easy stage advances.


Type: integer
Type: integer boolean


Default: <code>5</code>
Default: <code>1</code>


Declared range: <code>0-10000</code>
Range: <code>0-1</code>


When mode 4 is selected, the value must be at least 1.
When set to 0, the demonstration plays only the configured number of examples and then stops.


===RandomControlledTrials===
===EasyIntroNormalDemoDirections===


Number of experimental controlled trials included in the pseudorandom block of experiment mode 4.
Number of animated normal-mapping examples.


Type: integer
Type: integer


Default: <code>5</code>
Default: <code>2</code>


Declared range: <code>0-10000</code>
Range: <code>1-4</code>


When mode 4 is selected, the value must be at least 1.
Example 1 moves to the lower right and example 2 moves directly right; additional examples fan upward.


===StimulusDisplay===
===EasyIntroReversedDemoDirections===


Selects the physical display used for the participant-facing application window.
Number of animated reversed-mapping examples.


Type: integer enumeration
Type: integer


Default: <code>0</code>
Default: <code>2</code>


Values:
Range: <code>1-4</code>


* <code>0</code>: Automatic/default ApplicationWindow placement.
The visual target movements follow the same sequence as the normal examples, while the illustrated joystick moves in the opposite direction.
* <code>1</code> and above: Select one of the displays detected when the parameters are published.


On Windows, available monitors are enumerated with their dimensions and primary-display status.
===EasyIntroNormalPracticeTrials===


The application verifies during preflight that the selected display exists.
Number of normal-mapping practice trials in the Easy introduction.


===CenterHoldSeconds===
Type: integer


Duration for which the participant must keep the cursor within the center region during experimental trials.
Default: <code>3</code>


Type: floating point
Range: <code>0-20</code>


Default: <code>3.0</code> seconds
A value of 0 skips normal practice while retaining the normal demonstration and "your turn" stages.


Range: <code>0.0-60.0</code> seconds
===EasyIntroReversedPracticeTrials===


Leaving the center during this interval restarts the center-acquisition sequence.
Number of reversed-mapping practice trials in the Easy introduction.


This parameter does not control practice center-hold duration. Practice trials use <code>PracticeCenterHoldTime</code>.
Type: integer


===WarningSeconds===
Default: <code>3</code>


Duration of the yellow warning cue.
Range: <code>0-20</code>


Type: floating point
A value of 0 skips reversed practice while retaining the reversed demonstration and "your turn" stages.


Default: <code>0.5</code> seconds
===EasyIntroPracticeCenterHoldMs===


Range: <code>0.0-60.0</code> seconds
Center-hold duration for Easy-introduction practice trials.


Leaving the center during the warning interval restarts the center-acquisition sequence.
Type: integer (milliseconds)


This parameter applies to both practice and experimental trials.
Default: <code>3000</code>


===PreTargetDelaySeconds===
Range: <code>0-60000</code>


Delay between the end of the warning cue and target appearance.
This value replaces <code>PracticeCenterHoldTime</code> during Easy practice only.


Type: floating point
===EasyIntroPracticeFeedback===


Default: <code>0.5</code> seconds
Enables the brief success-feedback interval after an Easy practice target is acquired.


Range: <code>0.0-60.0</code> seconds
Type: integer boolean


The participant must remain centered during this interval.
Default: <code>1</code>


This parameter applies to both practice and experimental trials.
Range: <code>0-1</code>


===FeedbackSeconds===
===EasyIntroFeedbackDurationMs===


Interval between successful target acquisition and advancement to the next trial, tutorial transition, or experimental block.
Duration of the Easy practice success-feedback interval.


Type: floating point
Type: integer (milliseconds)


Default: <code>0.5</code> seconds
Default: <code>500</code>


Range: <code>0.0-60.0</code> seconds
Range: <code>0-60000</code>


This parameter applies to both practice and experimental trials.
This value is used only when <code>EasyIntroPracticeFeedback=1</code>.


===CursorDiameterPixels===
===EasyIntroRequireButtonPress===


Cursor diameter, expressed in reference-display pixels and converted to normalized rendering dimensions during initialization.
Controls whether eligible Easy-introduction screens wait for manual continuation rather than advancing on their timers.


Type: floating point
Type: integer boolean


Default: <code>16.0</code>
Default: <code>0</code>


Range: <code>1.0-1000.0</code>
Range: <code>0-1</code>


A positive value is required by preflight validation.
When set to 0, stages advance automatically after their animations and timers. Joystick button 1 (when surgery mode is off) and researcher '''CONTINUE''' can still advance an eligible static screen before its timer expires. When set to 1 and <code>EasyIntroSurgeryMode=0</code>, stages wait for joystick button 1 or '''CONTINUE'''. Static screens are immediately eligible; demonstration screens become eligible after all configured examples have played. When surgery mode is on, this parameter does not prevent automatic advancement.


===TargetDiameterPixels===
===EasyIntroSurgeryMode===


Target diameter, expressed in reference-display pixels and converted to normalized rendering dimensions during initialization.
Advances the non-practice Easy-introduction screens automatically without participant button presses.


Type: floating point
Type: integer boolean


Default: <code>36.0</code>
Default: <code>0</code>


Range: <code>1.0-1000.0</code>
Range: <code>0-1</code>


A positive value is required by preflight validation. In addition to determining visual size, this parameter affects the ellipse used to determine target acquisition. Consequently, changing it can change the effective movement tolerance and behavioral measurements.
This mode is intended for sessions in which the participant cannot operate the joystick button. Participant joystick-button continuation is disabled, and the configured animation, interim-screen, and ready-screen timers control progression. Researcher '''CONTINUE''' remains available on eligible non-practice screens. Practice trials still require the participant to acquire each target and return to center.


''The <code>ResultsFile</code> parameter was removed; see [[#Data Recording|Data Recording]].''
===EasyIntroInterimScreenDurationMs===


==States==
Time that transition and "your turn" screens remain visible when advancing automatically.


The following states are defined by <code>USBHIDJoystickTask</code> and are recorded with the normal BCI2000 data stream.
Type: integer (milliseconds)


===Introduction===
Default: <code>2000</code>


1-bit state indicating whether the participant tutorial/practice sequence is active.
Range: <code>0-60000</code>


Initial value: <code>0</code>
===EasyIntroReadyScreenDurationMs===


Values:
Time that the final Easy ready screen remains visible before the experiment starts automatically.


* <code>0</code>: Tutorial inactive or disabled; experimental data
Type: integer (milliseconds)
* <code>1</code>: Tutorial or practice sequence active


When <code>EnableIntroduction=1</code>, this state becomes 1 at the beginning of the run and returns to 0 when the tutorial completes and the experiment begins.
Default: <code>5000</code>


This is the primary state for separating tutorial/practice samples from experimental samples during offline analysis.
Range: <code>0-60000</code>


===TutorialPhase===
This value applies when the ready screen advances automatically.


4-bit state indicating the current stage of the tutorial.
===EasyIntroRequireJoystickNeutral===


Initial value: <code>0</code>
Requires the joystick to be neutral before an automatic or participant-button advance leaves the normal or reversed Easy demonstration stage.


Values:
Type: integer boolean


* <code>0</code>: Tutorial inactive
Default: <code>1</code>
* <code>1</code>: General introduction
* <code>2</code>: Normal free movement
* <code>3</code>: Automatic instructions
* <code>4</code>: Automatic practice
* <code>5</code>: Controlled instructions
* <code>6</code>: Controlled free movement
* <code>7</code>: Controlled practice
* <code>8</code>: Practice complete


After the final automatic or controlled practice feedback interval, <code>TutorialPhase</code> may remain 4 or 7 while <code>PracticeTrial</code> has returned to 0 and the task waits for the participant to return to center.
Range: <code>0-1</code>


Outside the tutorial, <code>TutorialPhase</code> is 0.
When an automatic advance or participant joystick-button request occurs while the joystick is not neutral, the stage waits for neutral. If <code>EasyIntroShowInstructionText=1</code>, the display asks the participant to let go. Researcher '''CONTINUE''' bypasses this requirement.


===PracticeTrial===
===EasyIntroShowJoystickIllustration===


8-bit state identifying the active practice trial.
Shows the animated joystick illustration during the normal and reversed Easy demonstrations. The basic demonstration never shows the joystick illustration.


Initial value: <code>0</code>
Type: integer boolean


Values:
Default: <code>1</code>


* <code>0</code>: No active practice trial
Range: <code>0-1</code>
* <code>1</code> and above: One-based practice trial number within the current practice condition


The state remains nonzero through the practice trial's feedback phase.
===EasyIntroShowInstructionText===


After the final practice feedback interval it returns to 0 while the tutorial may still wait for the participant to return to center.
Shows the Easy-introduction instruction text.


Resetting a practice trial does not increment <code>PracticeTrial</code>.
Type: integer boolean


===CursorX===
Default: <code>1</code>


10-bit state representing the current horizontal cursor coordinate.
Range: <code>0-1</code>


Initial value: <code>512</code>
===EasyIntroAllowResearcherSkip===


Produced range: <code>0-1023</code>
Enables the researcher skip controls during the Easy introduction.


The state is updated continuously while the task runs, including during free movement, practice, and experimental trials.
Type: integer boolean


===CursorY===
Default: <code>1</code>


10-bit state representing the current vertical cursor coordinate.
Range: <code>0-1</code>


Initial value: <code>512</code>
When set to 0, the Easy introduction cannot be exited or advanced with '''SKIP INTRODUCTION''', '''SKIP PRACTICE''', or '''SKIP CURRENT EASY PHASE'''. The '''PREVIOUS EASY PHASE''' and '''RESTART EASY PHASE''' controls remain available.


Produced range: <code>0-1023</code>
===ExperimentMode===


The state is updated continuously while the task runs, including during free movement, practice, and experimental trials.
Selects the overall experimental structure.


===TaskPhase===
Type: integer enumeration


3-bit state containing the current trial phase.
Default: <code>1</code>


Initial value: <code>0</code>
Range: <code>1-4</code>


Values:
Values:


* <code>0</code>: Experimental block announcement or non-trial tutorial screen
* <code>1</code>: Automatic only
* <code>1</code>: Waiting for center
* <code>2</code>: Controlled only
* <code>2</code>: Holding center
* <code>3</code>: Ordered automatic and controlled
* <code>3</code>: Warning
* <code>4</code>: Ordered automatic, ordered controlled, and pseudorandom mixed
* <code>4</code>: Pre-target delay
* <code>5</code>: Target visible
* <code>6</code>: Feedback
* <code>7</code>: Finished


During active practice trials, values 1 through 6 have the same meanings as during experimental trials.
The application verifies during preflight that the trial-count parameters required by the selected mode are at least 1.


During non-trial tutorial screens, <code>TaskPhase</code> is forced to 0. Therefore, <code>TaskPhase=0</code> alone no longer uniquely identifies an experimental block announcement.
The selected mode also determines which condition-specific tutorial sections are presented in the Standard introduction. The Easy introduction does not depend on <code>ExperimentMode</code>.


Use:
===AutomaticTrials===


<pre>
Number of automatic experimental trials used by experiment modes 1 and 3.
Introduction == 0 and TaskPhase == 0
</pre>


to identify an experimental block announcement.
Type: integer


===TaskCondition===
Default: <code>5</code>


1-bit state identifying the current movement condition.
Declared range: <code>0-10000</code>


Initial value: <code>0</code>
When used by the selected experiment mode, the value must be at least 1.


Values:
Practice trials are additional and do not reduce or increment this count.


* <code>0</code>: Automatic (participant-facing '''Normal''')
===ControlledTrials===
* <code>1</code>: Controlled (participant-facing '''Reversed''')


During active practice trials, this state identifies the practice condition.
Number of controlled experimental trials used by experiment modes 2 and 3.


During the general introduction and normal free-movement tutorial stages, it initially reports 0 even when the configured experiment is Controlled Only.
Type: integer


During the experiment it retains its original meaning.
Default: <code>5</code>


===TaskBlockType===
Declared range: <code>0-10000</code>


2-bit state identifying the type of the current experimental block.
When used by the selected experiment mode, the value must be at least 1.


Initial value: <code>0</code>
Practice trials are additional and do not reduce or increment this count.


Values:
===OrderedStartCondition===


* <code>0</code>: Ordered automatic
Determines which experimental condition is presented first in experiment mode 3.
* <code>1</code>: Ordered controlled
* <code>2</code>: Pseudorandom mixed


During the tutorial, this state is forced to 0. It should therefore only be interpreted as an experimental block type when <code>Introduction=0</code>.
Type: integer enumeration


===TargetAngle===
Default: <code>0</code>


12-bit state containing the target angle in tenths of a degree.
Values:


Initial value: <code>0</code>
* <code>0</code>: Automatic first
* <code>1</code>: Controlled first


During experimental trials, generated values range from <code>0-3599</code>.
This parameter does not affect experiment modes 1, 2, or 4.


To convert to degrees:
It also does not affect tutorial order. The Standard tutorial presents automatic training before controlled training when both are included, and the Easy tutorial always presents the normal stages before the reversed stages.


<pre>
===OrderedAutomaticTrials===
degrees = TargetAngle / 10
</pre>


During practice trials, the state contains the deterministic practice-target angle.
Number of experimental automatic trials in the ordered automatic block of experiment mode 4.


During non-trial tutorial screens, the state is set to 0.
Type: integer


After tutorial completion, the saved first experimental target is restored.
Default: <code>5</code>


===TargetX===
Declared range: <code>0-10000</code>


10-bit state containing the horizontal coordinate of the current target.
When mode 4 is selected, the value must be at least 1.


Initial value: <code>512</code>
===OrderedControlledTrials===


Coordinate units correspond to the task's 0-through-1023 coordinate system.
Number of experimental controlled trials in the ordered controlled block of experiment mode 4.


During practice trials, it describes the current deterministic practice target.
Type: integer


During non-trial tutorial screens, the target coordinate is written as <code>0</code> rather than retaining its initial value <code>512</code>; gate it by task phase and tutorial status during analysis.
Default: <code>5</code>


===TargetY===
Declared range: <code>0-10000</code>


10-bit state containing the vertical coordinate of the current target.
When mode 4 is selected, the value must be at least 1.


Initial value: <code>512</code>
===RandomAutomaticTrials===


Coordinate units correspond to the task's 0-through-1023 coordinate system.
Number of experimental automatic trials included in the pseudorandom block of experiment mode 4.


During practice trials, it describes the current deterministic practice target.
Type: integer


During non-trial tutorial screens, the target coordinate is written as <code>0</code> rather than retaining its initial value <code>512</code>; gate it by task phase and tutorial status during analysis.
Default: <code>5</code>


===TaskBlock===
Declared range: <code>0-10000</code>


8-bit state containing the current one-based experimental block number.
When mode 4 is selected, the value must be at least 1.


Initial value: <code>0</code>
===RandomControlledTrials===


While <code>Introduction=1</code>:
Number of experimental controlled trials included in the pseudorandom block of experiment mode 4.


<pre>
Type: integer
TaskBlock = 0
</pre>


When the tutorial completes, the first experimental block begins with:
Default: <code>5</code>


<pre>
Declared range: <code>0-10000</code>
TaskBlock = 1
</pre>


Practice trials do not consume experimental block numbers.
When mode 4 is selected, the value must be at least 1.


===TaskTrial===
===StimulusDisplay===


16-bit state containing the current one-based overall experimental trial number.
Selects the physical display used for the participant-facing application window.


Initial value: <code>0</code>
Type: integer enumeration


While <code>Introduction=1</code>:
Default: <code>0</code>


<pre>
Values:
TaskTrial = 0
</pre>


When the tutorial completes, the first experimental trial begins with:
* <code>0</code>: Automatic/default ApplicationWindow placement.
* <code>1</code> and above: Select one of the displays detected when the parameters are published.


<pre>
On Windows, available monitors are enumerated with their dimensions and primary-display status.
TaskTrial = 1
</pre>


Trial numbering continues across experimental block boundaries. Manually resetting an experimental trial does not increment <code>TaskTrial</code>.
The application verifies during preflight that the selected display exists.


Practice trials do not consume experimental trial numbers.
===CenterHoldSeconds===


===MovementStarted===
Duration for which the participant must keep the cursor within the center region during experimental trials.


1-bit state indicating whether movement onset has been detected during the current active practice or experimental trial.
Type: floating point


Initial value: <code>0</code>
Default: <code>3.0</code> seconds


The state changes to 1 when joystick displacement exceeds the movement deadzone after target onset. It remains high during the remainder of the movement and feedback period.
Range: <code>0.0-60.0</code> seconds


A rising transition from 0 to 1 identifies movement onset.
Leaving the center during this interval restarts the center-acquisition sequence.


During non-trial tutorial screens, the state is forced to 0.
This parameter does not control practice center-hold duration. Standard practice trials use <code>PracticeCenterHoldTime</code>, and Easy practice trials use <code>EasyIntroPracticeCenterHoldMs</code>.


Use <code>Introduction</code> to distinguish practice movement onset from experimental movement onset.
===WarningSeconds===


===TargetHit===
Duration of the yellow warning cue.


1-bit event-like state indicating successful target acquisition.
Type: floating point


Initial value: <code>0</code>
Default: <code>0.5</code> seconds


The state is set to 1 when the cursor reaches a practice or experimental target and is cleared at the beginning of the following processing block. It therefore acts as a one-processing-block pulse.
Range: <code>0.0-60.0</code> seconds


Experimental acquisition:
Leaving the center during the warning interval restarts the center-acquisition sequence.


<pre>
This parameter applies to both practice and experimental trials.
TargetHit == 1 and Introduction == 0
</pre>


Practice acquisition:
===PreTargetDelaySeconds===


<pre>
Delay between the end of the warning cue and target appearance.
TargetHit == 1 and Introduction == 1
</pre>


===TrialReset===
Type: floating point


1-bit event-like state indicating a manual trial reset.
Default: <code>0.5</code> seconds


Initial value: <code>0</code>
Range: <code>0.0-60.0</code> seconds


The state is set to 1 when the experimenter successfully resets a practice or experimental trial and is cleared at the beginning of the following processing block.
The participant must remain centered during this interval.


Experimental reset:
This parameter applies to both practice and experimental trials.


<pre>
===FeedbackSeconds===
TrialReset == 1 and Introduction == 0
</pre>


Practice reset:
Interval between successful target acquisition and advancement to the next trial, tutorial transition, or experimental block.


<pre>
Type: floating point
TrialReset == 1 and Introduction == 1
</pre>


===TrialSkipped===
Default: <code>0.5</code> seconds


1-bit event state for the researcher's '''SKIP TRIAL''' command during an eligible experimental trial.
Range: <code>0.0-60.0</code> seconds


Initial value: <code>0</code>
This parameter applies to experimental trials and Standard-introduction practice trials. Easy-introduction practice instead uses <code>EasyIntroFeedbackDurationMs</code> when <code>EasyIntroPracticeFeedback=1</code>, or no feedback interval when it is 0.


The state is set to 1 when an experimental trial is skipped and cleared on the following processing block. Skipping advances trial position without counting a successful target acquisition and without increasing completed/reset metrics. The next trial receives a newly generated target, unless the run ends.
===CursorDiameterPixels===


===ConditionSkipped===
Cursor diameter, expressed in reference-display pixels and converted to normalized rendering dimensions during initialization.


1-bit event state for the researcher's '''SKIP CURRENT BLOCK''' command.
Type: floating point


Initial value: <code>0</code>
Default: <code>16.0</code>


The state is set to 1 for one processing block when the remainder of the current experimental block is skipped. This command advances the overall trial-position counter over the skipped trials, which can change the progress indicator without changing completed-trial counts. The control requires experimenter confirmation.
Range: <code>1.0-1000.0</code>


===IntroductionSkipped===
A positive value is required by preflight validation.


1-bit event state for the researcher's '''SKIP INTRODUCTION''' command.
The cursor diameter can also be changed at runtime using the '''Cursor diameter''' control in the diagnostic window. Runtime changes are recorded in <code>CursorDiameterPx10</code>. The center and warning markers retain their fixed sizes when the cursor diameter changes. Because the cursor radius contributes to the target-hit ellipse, changing the cursor diameter also changes the effective target-acquisition tolerance.


Initial value: <code>0</code>
===TargetDiameterPixels===


The state is set to 1 for one processing block when the tutorial is exited before normal completion. The current run proceeds directly to the experimental block-announcement sequence and restores the saved first experimental target. This control requires confirmation.
Target diameter, expressed in reference-display pixels and converted to normalized rendering dimensions during initialization.


===PracticeSkipped===
Type: floating point


1-bit event state for the researcher's '''SKIP PRACTICE''' command.
Default: <code>36.0</code>


Initial value: <code>0</code>
Range: <code>1.0-1000.0</code>


The state is set to 1 for one processing block when the remaining trials in the current practice condition are bypassed. It identifies incomplete tutorial practice and is distinct from experimental <code>TrialSkipped</code>.
A positive value is required by preflight validation. In addition to determining visual size, this parameter affects the ellipse used to determine target acquisition. Consequently, changing it can change the effective movement tolerance and behavioral measurements.


===SandboxSkipped===
This parameter is not adjustable at runtime from the diagnostic window.


1-bit event state for the researcher's '''SKIP SANDBOX''' command.
===TargetDistancePixels===


Initial value: <code>0</code>
Center-to-target distance, expressed in reference-display pixels.


The state is set to 1 for one processing block when a Normal or Reversed free-movement sandbox is bypassed. The tutorial advances to the appropriate next stage.
Type: floating point


===TaskPaused===
Default: <code>300.0</code>


1-bit persistent (level) state showing whether the task is paused.
Range: <code>1.0-350.0</code>


Initial value: <code>0</code>
The value applies to experimental targets, practice targets, and Easy-introduction demonstration targets. It can also be changed at runtime using the '''Target distance''' control in the diagnostic window; the applied value is recorded in <code>TargetDistancePx10</code>. Changing the distance recalculates the current and saved experimental target positions, so <code>TargetX</code> and <code>TargetY</code> change without a new target angle being generated.


* <code>0</code>: Task running normally.
''The <code>ResultsFile</code> parameter was removed; see [[#Data Recording|Data Recording]].''
* <code>1</code>: Task paused; task progression is suspended, while the BCI2000 data stream continues.


Unlike the five skip states, <code>TaskPaused</code> remains high throughout a pause and returns to 0 on resume. Paused time is excluded from the task's reported timing intervals by shifting the relevant clock references on resume.
==States==


===ReactionTimeMs===
The following states are defined by <code>USBHIDJoystickTask</code> and are recorded with the normal BCI2000 data stream.
 
===Introduction===


32-bit state containing reaction time in milliseconds.
1-bit state indicating whether the participant tutorial/practice sequence is active.


Initial value: <code>0</code>
Initial value: <code>0</code>


Reaction time is measured from target appearance to detected movement onset.
Values:
 
* <code>0</code>: Tutorial inactive or disabled; experimental data
* <code>1</code>: Tutorial or practice sequence active


The state is populated during successful practice and experimental trials.
When <code>IntroductionMode</code> is 1 or 2, this state becomes 1 at the beginning of the run and returns to 0 when the tutorial completes and the experiment begins.


Practice timing values should be distinguished from experimental values using <code>Introduction</code>.
This is the primary state for separating tutorial/practice samples from experimental samples during offline analysis.


===MovementTimeMs===
===TutorialPhase===


32-bit state containing movement time in milliseconds.
4-bit state indicating the current stage of the tutorial.


Initial value: <code>0</code>
Initial value: <code>0</code>


Movement time is measured from detected movement onset to target acquisition.
Values:


The state is populated during successful practice and experimental trials.
* <code>0</code>: Tutorial inactive
* <code>1</code>: General introduction
* <code>2</code>: Normal free movement
* <code>3</code>: Automatic instructions
* <code>4</code>: Automatic practice
* <code>5</code>: Controlled instructions
* <code>6</code>: Controlled free movement
* <code>7</code>: Controlled practice
* <code>8</code>: Practice complete


Practice timing values should be distinguished from experimental values using <code>Introduction</code>.
After the final automatic or controlled practice feedback interval, <code>TutorialPhase</code> may remain 4 or 7 while <code>PracticeTrial</code> has returned to 0 and the task waits for the participant to return to center.
 
Outside the tutorial, <code>TutorialPhase</code> is 0.
 
The values above describe the Standard introduction. In the Easy introduction, <code>TutorialPhase</code> remains 0 throughout; use <code>EasyIntroPhase</code> to identify the stage.


===TotalTimeMs===
===EasyIntroPhase===


32-bit state containing total target-directed trial time in milliseconds.
4-bit state identifying the current stage of the Easy introduction.


Initial value: <code>0</code>
Initial value: <code>0</code>


Total time is measured from target appearance to target acquisition.
Values:
 
* <code>0</code>: Easy introduction inactive
* <code>1</code>: Basic demonstration
* <code>2</code>: Normal demonstration
* <code>3</code>: Normal: now your turn
* <code>4</code>: Normal practice
* <code>5</code>: Reversed introduction
* <code>6</code>: Reversed demonstration
* <code>7</code>: Reversed: now your turn
* <code>8</code>: Reversed practice
* <code>9</code>: Ready


The state is populated during successful practice and experimental trials.
The state is nonzero only while <code>IntroductionMode=2</code> and <code>Introduction=1</code>. Outside the Easy introduction it is 0. <code>TutorialPhase</code> is 0 during all Easy stages.


Practice timing values should be distinguished from experimental values using <code>Introduction</code>.
===PracticeTrial===


===External Joystick States===
8-bit state identifying the active practice trial.


The application also uses states provided by BCI2000's [[User Reference:Logging Input|input logging]] system. These states are not defined by <code>USBHIDJoystickTask</code> itself.
Initial value: <code>0</code>


{| class="wikitable"
Values:
! State
 
! Description
* <code>0</code>: No active practice trial
|-
* <code>1</code> and above: One-based practice trial number within the current practice condition
| <code>JoystickXpos</code>
 
| Horizontal joystick position. BCI2000 joystick input logging uses values from 0 through 32767.
The state remains nonzero through the practice trial's feedback phase.
|-
| <code>JoystickYpos</code>
| Vertical joystick position. BCI2000 joystick input logging uses values from 0 through 32767.
|-
| <code>JoystickButtons1</code>
| State of joystick button 1. During the tutorial, a rising press may advance eligible instruction or free-movement screens. It does not advance active practice trials and does not control experimental progression.
|-
| <code>Running</code>
| Standard BCI2000 system state. The application sets it to 0 when all configured experimental trials have been completed.
|}


For details about enabling joystick recording and the joystick states provided by BCI2000, see [[User Reference:Logging Input|Logging Input]].
After the final practice feedback interval it returns to 0 while the tutorial may still wait for the participant to return to center.


===Data Analysis Notes===
Resetting a practice trial does not increment <code>PracticeTrial</code>.


Because the tutorial and practice sequence are recorded within the same BCI2000 run as the experiment, analyses should use <code>Introduction</code> to distinguish experimental data from tutorial and practice data.
Both Standard and Easy practice trials use this state; use <code>TutorialPhase</code> or <code>EasyIntroPhase</code> to determine which practice mode is active.


{| class="wikitable"
===CursorX===
! Measurement/Event
 
! Recommended identification
10-bit state representing the current horizontal cursor coordinate.
|-
 
| Experimental samples
Initial value: <code>512</code>
| <code>Introduction == 0</code>
 
|-
Produced range: <code>0-1023</code>
| Tutorial/practice samples
 
| <code>Introduction == 1</code>
The state is updated continuously while the task runs, including during free movement, practice, and experimental trials.
|-
 
| Experimental trial
===CursorY===
| <code>Introduction == 0</code> and <code>TaskTrial > 0</code>; check skip events when reconstructing completed trials
 
|-
10-bit state representing the current vertical cursor coordinate.
| Practice trial
 
| <code>Introduction == 1</code> and <code>PracticeTrial > 0</code>
Initial value: <code>512</code>
|-
 
| Experimental block announcement
Produced range: <code>0-1023</code>
| <code>Introduction == 0</code> and <code>TaskPhase == 0</code>
 
|-
The state is updated continuously while the task runs, including during free movement, practice, and experimental trials.
| Non-trial tutorial screen
 
| <code>Introduction == 1</code>, typically with <code>TaskPhase == 0</code>
===CursorDiameterPx10===
|-
 
| Experimental target onset
16-bit state containing the runtime cursor diameter in tenths of a reference-display pixel.
| <code>Introduction == 0</code> and transition from <code>TaskPhase=4</code> to <code>TaskPhase=5</code>
 
|-
Initial value: <code>160</code>
| Practice target onset
 
| <code>Introduction == 1</code>, <code>PracticeTrial > 0</code>, and transition from <code>TaskPhase=4</code> to <code>TaskPhase=5</code>
At the start of a run, the value reflects <code>CursorDiameterPixels</code>. It is updated whenever the researcher changes the '''Cursor diameter''' control in the diagnostic window.
|-
 
| Experimental movement onset
To convert to pixels:
| Rising transition of <code>MovementStarted</code> with <code>Introduction == 0</code>
 
|-
<pre>
| Practice movement onset
cursor diameter (px) = CursorDiameterPx10 / 10
| Rising transition of <code>MovementStarted</code> with <code>Introduction == 1</code>
</pre>
|-
 
| Experimental target acquisition
===TargetDistancePx10===
| <code>TargetHit == 1</code> and <code>Introduction == 0</code>
 
|-
16-bit state containing the runtime center-to-target distance in tenths of a reference-display pixel.
| Practice target acquisition
 
| <code>TargetHit == 1</code> and <code>Introduction == 1</code>
Initial value: <code>3000</code>
|-
 
| Experimental reset
At the start of a run, the value reflects <code>TargetDistancePixels</code>. It is updated whenever the researcher changes the '''Target distance''' control in the diagnostic window.
| <code>TrialReset == 1</code> and <code>Introduction == 0</code>
 
|-
To convert to pixels:
| Practice reset
 
| <code>TrialReset == 1</code> and <code>Introduction == 1</code>
<pre>
|-
target distance (px) = TargetDistancePx10 / 10
| Experimental trial number
</pre>
| <code>TaskTrial</code>
 
|-
===DisplayGeometryChanged===
| Practice trial number
 
| <code>PracticeTrial</code>
1-bit event-like state indicating that a runtime display-geometry change was applied.
|-
 
| Experimental block number
Initial value: <code>0</code>
| <code>TaskBlock</code>
 
|-
The state is set to 1 for one processing block when a change to the cursor diameter or target distance is applied, and is cleared at the beginning of the following processing block. It does not indicate that target diameter changed, because that parameter is fixed for the run.
| Automatic vs. controlled
 
| <code>TaskCondition</code>, interpreted together with <code>Introduction</code>
===TaskPhase===
|-
 
| Ordered vs. mixed experimental block
3-bit state containing the current trial phase.
 
Initial value: <code>0</code>
 
Values:
 
* <code>0</code>: Experimental block announcement or non-trial tutorial screen
* <code>1</code>: Waiting for center
* <code>2</code>: Holding center
* <code>3</code>: Warning
* <code>4</code>: Pre-target delay
* <code>5</code>: Target visible
* <code>6</code>: Feedback
* <code>7</code>: Finished (the run reached its end normally or through a skip action)
 
During active practice trials, values 1 through 6 have the same meanings as during experimental trials, including Easy-introduction practice.
 
During non-trial tutorial screens, <code>TaskPhase</code> is forced to 0. This includes all non-practice Easy stages. Therefore, <code>TaskPhase=0</code> alone no longer uniquely identifies an experimental block announcement.
 
Use:
 
<pre>
Introduction == 0 and TaskPhase == 0
</pre>
 
to identify an experimental block announcement. Within the tutorial, <code>EasyIntroPhase</code> or <code>TutorialPhase</code> identifies the screen type.
 
===TaskCondition===
 
1-bit state identifying the current movement condition.
 
Initial value: <code>0</code>
 
Values:
 
* <code>0</code>: Automatic (participant-facing '''Normal''')
* <code>1</code>: Controlled (participant-facing '''Reversed''')
 
During active practice trials, this state identifies the practice condition.
 
During the general introduction and normal free-movement tutorial stages, it initially reports 0 even when the configured experiment is Controlled Only. In the Easy introduction it reports 0 through the basic demonstration and normal stages, then reports 1 from the reversed-introduction stage onward.
 
During the experiment it retains its original meaning.
 
===TaskBlockType===
 
2-bit state identifying the type of the current experimental block.
 
Initial value: <code>0</code>
 
Values:
 
* <code>0</code>: Ordered automatic
* <code>1</code>: Ordered controlled
* <code>2</code>: Pseudorandom mixed
 
During the tutorial, this state is forced to 0. It should therefore only be interpreted as an experimental block type when <code>Introduction=0</code>.
 
===TargetAngle===
 
12-bit state containing the target angle in tenths of a degree.
 
Initial value: <code>0</code>
 
During experimental trials, generated values range from <code>0-3599</code>.
 
To convert to degrees:
 
<pre>
degrees = TargetAngle / 10
</pre>
 
During practice trials, the state contains the deterministic practice-target angle.
 
During non-trial tutorial screens, including Easy demonstration and text screens, the state is set to 0.
 
After tutorial completion, the saved first experimental target is restored.
 
===TargetX===
 
10-bit state containing the horizontal coordinate of the current target.
 
Initial value: <code>512</code>
 
Coordinate units correspond to the task's 0-through-1023 coordinate system.
 
During practice trials, it describes the current deterministic practice target.
 
During non-trial tutorial screens, including Easy demonstration and text screens, the target coordinate is written as <code>0</code> rather than retaining its initial value <code>512</code>; gate it by task phase and tutorial status during analysis.
 
A runtime change of <code>TargetDistancePixels</code> moves the current target and updates this state without generating a new target angle.
 
===TargetY===
 
10-bit state containing the vertical coordinate of the current target.
 
Initial value: <code>512</code>
 
Coordinate units correspond to the task's 0-through-1023 coordinate system.
 
During practice trials, it describes the current deterministic practice target.
 
During non-trial tutorial screens, including Easy demonstration and text screens, the target coordinate is written as <code>0</code> rather than retaining its initial value <code>512</code>; gate it by task phase and tutorial status during analysis.
 
A runtime change of <code>TargetDistancePixels</code> moves the current target and updates this state without generating a new target angle.
 
===TaskBlock===
 
8-bit state containing the current one-based experimental block number.
 
Initial value: <code>0</code>
 
While <code>Introduction=1</code>:
 
<pre>
TaskBlock = 0
</pre>
 
When the tutorial completes, the first experimental block begins with:
 
<pre>
TaskBlock = 1
</pre>
 
Practice trials do not consume experimental block numbers.
 
===TaskTrial===
 
16-bit state containing the current one-based overall experimental trial number.
 
Initial value: <code>0</code>
 
While <code>Introduction=1</code>:
 
<pre>
TaskTrial = 0
</pre>
 
When the tutorial completes, the first experimental trial begins with:
 
<pre>
TaskTrial = 1
</pre>
 
Trial numbering continues across experimental block boundaries. Manually resetting an experimental trial does not increment <code>TaskTrial</code>.
 
Practice trials do not consume experimental trial numbers.
 
===MovementStarted===
 
1-bit state indicating whether movement onset has been detected during the current active practice or experimental trial.
 
Initial value: <code>0</code>
 
The state changes to 1 when joystick displacement exceeds the movement deadzone after target onset. It remains high during the remainder of the movement and feedback period.
 
A rising transition from 0 to 1 identifies movement onset.
 
During non-trial tutorial screens, the state is forced to 0.
 
Use <code>Introduction</code> to distinguish practice movement onset from experimental movement onset.
 
===TargetHit===
 
1-bit event-like state indicating successful target acquisition.
 
Initial value: <code>0</code>
 
The state is set to 1 when the cursor reaches a practice or experimental target and is cleared at the beginning of the following processing block. It therefore acts as a one-processing-block pulse.
 
Experimental acquisition:
 
<pre>
TargetHit == 1 and Introduction == 0
</pre>
 
Practice acquisition:
 
<pre>
TargetHit == 1 and Introduction == 1
</pre>
 
===TrialReset===
 
1-bit event-like state indicating a manual trial reset.
 
Initial value: <code>0</code>
 
The state is set to 1 when the experimenter successfully resets a practice or experimental trial and is cleared at the beginning of the following processing block.
 
Experimental reset:
 
<pre>
TrialReset == 1 and Introduction == 0
</pre>
 
Practice reset:
 
<pre>
TrialReset == 1 and Introduction == 1
</pre>
 
===TrialSkipped===
 
1-bit event state for the researcher's '''SKIP TRIAL''' command during an eligible experimental trial.
 
Initial value: <code>0</code>
 
The state is set to 1 when an experimental trial is skipped and cleared on the following processing block. Skipping advances trial position without counting a successful target acquisition and without increasing completed/reset metrics. The next trial receives a newly generated target, unless the run ends.
 
===ConditionSkipped===
 
1-bit event state for the researcher's '''SKIP CURRENT BLOCK''' command.
 
Initial value: <code>0</code>
 
The state is set to 1 for one processing block when the remainder of the current experimental block is skipped. This command advances the overall trial-position counter over the skipped trials, which can change the progress indicator without changing completed-trial counts. The control requires experimenter confirmation.
 
===IntroductionSkipped===
 
1-bit event state for the researcher's '''SKIP INTRODUCTION''' command.
 
Initial value: <code>0</code>
 
The state is set to 1 for one processing block when the tutorial is exited before normal completion. The current run proceeds directly to the experimental block-announcement sequence and restores the saved first experimental target. This control requires confirmation.
 
===PracticeSkipped===
 
1-bit event state for the researcher's '''SKIP PRACTICE''' command.
 
Initial value: <code>0</code>
 
The state is set to 1 for one processing block when the remaining trials in the current practice condition are bypassed. It identifies incomplete tutorial practice and is distinct from experimental <code>TrialSkipped</code>.
 
===SandboxSkipped===
 
1-bit event state for the researcher's '''SKIP SANDBOX''' command.
 
Initial value: <code>0</code>
 
The state is set to 1 for one processing block when a Normal or Reversed free-movement sandbox is bypassed in the Standard introduction, or when the researcher advances past a non-practice Easy stage using '''SKIP CURRENT EASY PHASE'''. The tutorial advances to the appropriate next stage.
 
===EasyIntroPrevious===
 
1-bit event state for the researcher's '''PREVIOUS EASY PHASE''' command.
 
Initial value: <code>0</code>
 
The state is set to 1 for one processing block when the researcher moves back to the preceding Easy-introduction stage, and is cleared at the beginning of the following processing block. It is recorded only during the Easy introduction.
 
===EasyIntroRestarted===
 
1-bit event state for the researcher's '''RESTART EASY PHASE''' command.
 
Initial value: <code>0</code>
 
The state is set to 1 for one processing block when the researcher restarts the current Easy-introduction stage, and is cleared at the beginning of the following processing block. If the restarted stage is a practice block, the block begins again at its first trial.
 
===TaskPaused===
 
1-bit persistent (level) state showing whether the task is paused.
 
Initial value: <code>0</code>
 
* <code>0</code>: Task running normally.
* <code>1</code>: Task paused; task progression is suspended, while the BCI2000 data stream continues.
 
Unlike the skip and Easy-phase event states, <code>TaskPaused</code> remains high throughout a pause and returns to 0 on resume. Paused time is excluded from the task's reported timing intervals by shifting the relevant clock references on resume.
 
===ReactionTimeMs===
 
32-bit state containing reaction time in milliseconds.
 
Initial value: <code>0</code>
 
Reaction time is measured from target appearance to detected movement onset.
 
The state is populated during successful practice and experimental trials.
 
Practice timing values should be distinguished from experimental values using <code>Introduction</code>.
 
===MovementTimeMs===
 
32-bit state containing movement time in milliseconds.
 
Initial value: <code>0</code>
 
Movement time is measured from detected movement onset to target acquisition.
 
The state is populated during successful practice and experimental trials.
 
Practice timing values should be distinguished from experimental values using <code>Introduction</code>.
 
===TotalTimeMs===
 
32-bit state containing total target-directed trial time in milliseconds.
 
Initial value: <code>0</code>
 
Total time is measured from target appearance to target acquisition.
 
The state is populated during successful practice and experimental trials.
 
Practice timing values should be distinguished from experimental values using <code>Introduction</code>.
 
===External Joystick States===
 
The application also uses states provided by BCI2000's [[User Reference:Logging Input|input logging]] system. These states are not defined by <code>USBHIDJoystickTask</code> itself.
 
{| class="wikitable"
! State
! Description
|-
| <code>JoystickXpos</code>
| Horizontal joystick position. BCI2000 joystick input logging uses values from 0 through 32767.
|-
| <code>JoystickYpos</code>
| Vertical joystick position. BCI2000 joystick input logging uses values from 0 through 32767.
|-
| <code>JoystickButtons1</code>
| State of joystick button 1. During the tutorial, a rising press may advance eligible instruction or free-movement screens. In the Easy introduction it can advance an eligible screen when <code>EasyIntroSurgeryMode=0</code>. When <code>EasyIntroRequireButtonPress=1</code> and surgery mode is off, either this participant input or researcher '''CONTINUE''' is required; when it is 0, stages also advance automatically. It does not advance active practice trials and does not control experimental progression.
|-
| <code>Running</code>
| Standard BCI2000 system state. The application sets it to 0 when the run reaches its end, including when a researcher skips the final trial or the remainder of the final block.
|}
 
For details about enabling joystick recording and the joystick states provided by BCI2000, see [[User Reference:Logging Input|Logging Input]].
 
===Data Analysis Notes===
 
Because the tutorial and practice sequence are recorded within the same BCI2000 run as the experiment, analyses should use <code>Introduction</code> to distinguish experimental data from tutorial and practice data.
 
{| class="wikitable"
! Measurement/Event
! Recommended identification
|-
| Experimental samples
| <code>Introduction == 0</code>
|-
| Tutorial/practice samples
| <code>Introduction == 1</code>
|-
| Experimental trial
| <code>Introduction == 0</code> and <code>TaskTrial > 0</code>; check skip events when reconstructing completed trials
|-
| Practice trial
| <code>Introduction == 1</code> and <code>PracticeTrial > 0</code>; use <code>TutorialPhase</code> or <code>EasyIntroPhase</code> to distinguish Standard from Easy practice
|-
| Experimental block announcement
| <code>Introduction == 0</code> and <code>TaskPhase == 0</code>
|-
| Non-trial tutorial screen
| <code>Introduction == 1</code>, typically with <code>TaskPhase == 0</code>
|-
| Standard-introduction stage
| <code>Introduction == 1</code> and <code>TutorialPhase > 0</code>
|-
| Easy-introduction stage
| <code>Introduction == 1</code> and <code>EasyIntroPhase > 0</code>
|-
| Experimental target onset
| <code>Introduction == 0</code> and transition from <code>TaskPhase=4</code> to <code>TaskPhase=5</code>
|-
| Practice target onset
| <code>Introduction == 1</code>, <code>PracticeTrial > 0</code>, and transition from <code>TaskPhase=4</code> to <code>TaskPhase=5</code>
|-
| Experimental movement onset
| Rising transition of <code>MovementStarted</code> with <code>Introduction == 0</code>
|-
| Practice movement onset
| Rising transition of <code>MovementStarted</code> with <code>Introduction == 1</code>
|-
| Experimental target acquisition
| <code>TargetHit == 1</code> and <code>Introduction == 0</code>
|-
| Practice target acquisition
| <code>TargetHit == 1</code> and <code>Introduction == 1</code>
|-
| Experimental reset
| <code>TrialReset == 1</code> and <code>Introduction == 0</code>
|-
| Practice reset
| <code>TrialReset == 1</code> and <code>Introduction == 1</code>
|-
| Experimental trial number
| <code>TaskTrial</code>
|-
| Practice trial number
| <code>PracticeTrial</code>
|-
| Experimental block number
| <code>TaskBlock</code>
|-
| Automatic vs. controlled
| <code>TaskCondition</code>, interpreted together with <code>Introduction</code>
|-
| Ordered vs. mixed experimental block
| <code>TaskBlockType</code> when <code>Introduction == 0</code>
| <code>TaskBlockType</code> when <code>Introduction == 0</code>
|-
|-
| Reaction time
| Reaction time
| <code>ReactionTimeMs</code>, gated by <code>Introduction</code> and the relevant trial event
| <code>ReactionTimeMs</code>, gated by <code>Introduction</code> and the relevant trial event
|-
|-
| Movement time
| Movement time
| <code>MovementTimeMs</code>, gated by <code>Introduction</code> and the relevant trial event
| <code>MovementTimeMs</code>, gated by <code>Introduction</code> and the relevant trial event
|-
|-
| Total time
| Total time
| <code>TotalTimeMs</code>, gated by <code>Introduction</code> and the relevant trial event
| <code>TotalTimeMs</code>, gated by <code>Introduction</code> and the relevant trial event
|-
|-
| Cursor trajectory
| Cursor trajectory
| <code>CursorX</code> and <code>CursorY</code>
| <code>CursorX</code> and <code>CursorY</code>
|-
|-
| Target coordinates
| Target coordinates
| <code>TargetX</code> and <code>TargetY</code> on actual trials; non-trial tutorial screens set these to <code>0</code>
| <code>TargetX</code> and <code>TargetY</code> on actual trials; non-trial tutorial screens set these to <code>0</code>. Interpret together with <code>TargetDistancePx10</code> when the distance may have been changed at runtime.
|-
|-
| Target angle
| Target angle
| <code>TargetAngle</code>
| <code>TargetAngle</code>
|-
| Skipped experimental trial
| <code>TrialSkipped == 1</code>
|-
| Skipped experimental block remainder
| <code>ConditionSkipped == 1</code>
|-
| Introduction bypassed
| <code>IntroductionSkipped == 1</code>
|-
| Practice bypassed
| <code>PracticeSkipped == 1</code>
|-
| Free-movement sandbox bypassed
| <code>SandboxSkipped == 1</code>; in the Easy introduction this event also records '''SKIP CURRENT EASY PHASE'''
|-
| Easy phase moved backward
| <code>EasyIntroPrevious == 1</code>
|-
|-
| Skipped experimental trial
| Easy phase restarted
| <code>TrialSkipped == 1</code>
| <code>EasyIntroRestarted == 1</code>
|-
|-
| Skipped experimental block remainder
| Runtime cursor diameter
| <code>ConditionSkipped == 1</code>
| <code>CursorDiameterPx10</code> (tenths of a pixel)
|-
|-
| Introduction bypassed
| Runtime target distance
| <code>IntroductionSkipped == 1</code>
| <code>TargetDistancePx10</code> (tenths of a pixel)
|-
| Practice bypassed
| <code>PracticeSkipped == 1</code>
|-
|-
| Free-movement sandbox bypassed
| Display-geometry change applied
| <code>SandboxSkipped == 1</code>
| <code>DisplayGeometryChanged == 1</code>
|-
|-
| Samples recorded while the task is paused
| Samples recorded while the task is paused
Line 1,437: Line 1,890:
|}
|}


<code>TargetHit</code>, <code>TrialReset</code>, <code>TrialSkipped</code>, <code>ConditionSkipped</code>, <code>IntroductionSkipped</code>, <code>PracticeSkipped</code>, and <code>SandboxSkipped</code> are single-processing-block pulses. <code>MovementStarted</code> remains high after movement onset until the trial advances or is reset. <code>TaskPaused</code> is a level state that remains high throughout a pause.
<code>TargetHit</code>, <code>TrialReset</code>, <code>TrialSkipped</code>, <code>ConditionSkipped</code>, <code>IntroductionSkipped</code>, <code>PracticeSkipped</code>, <code>SandboxSkipped</code>, <code>EasyIntroPrevious</code>, <code>EasyIntroRestarted</code>, and <code>DisplayGeometryChanged</code> are single-processing-block pulses. <code>MovementStarted</code> remains high after movement onset until the trial advances or is reset. <code>TaskPaused</code> is a level state that remains high throughout a pause.


Analyses written for earlier versions of the task should be updated before use with tutorial-enabled data. In particular:
Analyses written for earlier versions of the task should be updated before use with tutorial-enabled data. In particular:
Line 1,451: Line 1,904:
* Samples recorded during <code>TaskPaused=1</code> remain in the <code>.dat</code> stream. Exclude or flag them as appropriate; RT/MT/total-time values already exclude the pause duration.
* Samples recorded during <code>TaskPaused=1</code> remain in the <code>.dat</code> stream. Exclude or flag them as appropriate; RT/MT/total-time values already exclude the pause duration.
* <code>TargetX</code> and <code>TargetY</code> are 0 during non-trial tutorial screens, not their initial 512 values.
* <code>TargetX</code> and <code>TargetY</code> are 0 during non-trial tutorial screens, not their initial 512 values.
* In the Easy introduction, <code>TutorialPhase</code> remains 0; use <code>EasyIntroPhase</code> to identify the active stage. A practice stage can therefore be identified from <code>PracticeTrial > 0</code> together with <code>EasyIntroPhase</code> 4 or 8.
* <code>PracticeTrial</code> numbering restarts for each practice block and does not indicate whether the block belongs to the Standard or Easy introduction.
* Runtime changes to the cursor diameter or target distance appear in <code>CursorDiameterPx10</code> and <code>TargetDistancePx10</code>, with a one-block <code>DisplayGeometryChanged</code> pulse. A target-distance change moves the current target without changing <code>TargetAngle</code>, so target coordinates from before and after the change are not directly comparable in normalized distance terms. A cursor-diameter change also alters the effective target-acquisition tolerance because the cursor radius contributes to the hit ellipse.
* <code>EasyIntroPrevious</code> and <code>EasyIntroRestarted</code> record researcher navigation within the Easy introduction; they are not participant events and do not indicate skipped trials.
* Condition names printed on screen and in console messages are Normal/Reversed, but the numeric <code>TaskCondition</code> codes remain Automatic=0 and Controlled=1.
* Condition names printed on screen and in console messages are Normal/Reversed, but the numeric <code>TaskCondition</code> codes remain Automatic=0 and Controlled=1.
* No application-specific CSV is created in the current version; reconstruct trial-level results from synchronized BCI2000 state recordings.
* No application-specific CSV is created in the current version; reconstruct trial-level results from synchronized BCI2000 state recordings.

Latest revision as of 19:58, 11 November 2026

Synopsis

USBHIDJoystickTask is a BCI2000 application module that implements a center-out visuomotor reaching task controlled with a USB HID joystick. The task is designed to compare movements made under a normal joystick-to-cursor mapping with movements made under an inverted mapping.

During each experimental trial, the participant moves a cursor to the center of the display, holds it there, waits through a warning period, and then moves to a peripheral target. In the automatic condition (labeled Normal to the participant), joystick and cursor movements are congruent. In the controlled condition (labeled Reversed to the participant), joystick-to-cursor movement is inverted after the target appears. The numerical TaskCondition encodings remain 0 and 1, respectively.

The task also includes an optional participant introduction and practice sequence, available in two forms. The default Easy introduction uses animated demonstrations, guided "your turn" screens, and short practice blocks to introduce the normal and reversed mappings. The Standard introduction is the earlier, text-driven sequence that combines instructions, free-movement exploration, and practice trials. The introduction may also be disabled entirely. Tutorial and practice periods are recorded in the BCI2000 data stream but remain separate from experimental trial numbering and experimental performance summaries.

The task is based on the visuomotor paradigm described by Neumann et al. (2018), which was developed to compare automatic and controlled movements and investigate their relationship to basal ganglia function and subthalamic deep brain stimulation in Parkinson's disease. The BCI2000 implementation adapts the original paradigm for USB joystick control and synchronized BCI2000 state recording.

Video Overview

The following video demonstrates the Visuomotor Joystick Task running in BCI2000, including the participant display and joystick-controlled task behavior:

This video displays version 1 of the task, and as such does not include the pre-experiment participant tutorial and practice sequence. It also predates the Easy introduction, the configurable target distance, and the runtime geometry controls described below.

Location

In the inspected development checkout, the USB HID Visuomotor Joystick Task is located at:

src/custom/usb_hid_joystick_task/

The main application implementation is contained in:

USBHIDJoystickTask.cpp

with the corresponding header and build configuration in:

  • USBHIDJoystickTask.h
  • CMakeLists.txt

The CMake target is usb_hid_joystick_task_custom (configured with NOBUNDLE), and the target explicitly requires C++17. This checkout is tracked in Git; the former src/private/Application/VisuomotorJoystickTask SVN location does not describe the inspected source tree.

The paths and target above describe the checkout inspected for this documentation update; another deployed BCI2000 tree may arrange custom modules differently.

Versioning

Author

Alexander Speer

Friedman Lab, Department of Neurosurgery

Washington University in St. Louis

Developed in the Friedman Lab.

Contact: speer@wustl.edu

Version History

The task was developed as a USB HID joystick implementation of the automatic/controlled visuomotor reaching paradigm described by Neumann et al. (2018).

The current implementation includes:

  • Automatic and controlled visuomotor conditions.
  • Ordered and pseudorandom experimental blocks.
  • Configurable trial counts and trial timing.
  • An optional participant introduction and practice sequence, with Standard and Easy tutorial modes.
  • Automatic and controlled practice trials.
  • Free-movement demonstrations of normal and reversed cursor control (Standard mode).
  • Animated cursor, target, and joystick demonstrations with guided "your turn" screens (Easy mode).
  • Joystick-button and experimenter-controlled tutorial progression.
  • Automatic, timer-based Easy-introduction progression, including an optional surgery-friendly mode.
  • USB joystick input through BCI2000's input logging system.
  • Selection of the participant display on multi-monitor Windows systems.
  • BCI2000 state logging of task timing, cursor position, target position, condition, block structure, tutorial status, practice trials, trial events, and runtime display geometry.
  • A separate diagnostic window with visible performance metrics, tutorial controls, manual trial reset, researcher skip controls, Easy-phase previous/restart controls, runtime cursor-diameter and target-distance controls, and pause/resume.
  • Trial-level reaction time, movement time, and total time measurements.
  • Configurable cursor diameter, target diameter, and center-to-target distance, with target size affecting acquisition tolerance.
  • Dedicated one-processing-block states for researcher skip, Easy-phase navigation, and geometry-change events, plus a persistent pause state.
  • Participant-facing Normal/Reversed terminology and condition cues, without changing automatic/controlled state encodings.
  • Separation of tutorial/practice data from experimental trial numbering and run-summary metrics.
  • Behavioral recording through synchronized BCI2000 states; this version does not create a separate results CSV.

The inspected development checkout contains the task under src/custom/usb_hid_joystick_task and has Git history through 2026-11-11 (commits a169ed7 and 7d6d0ea, plus uncommitted working-tree changes that add the EasyIntroPrevious and EasyIntroRestarted states and keep the center and warning cues at fixed size).

Source Code Revisions

  • Initial development: 8/26/26
  • Tested under (earlier revision): BCI2000 framework 3.6.9528.4, Release x64, MSVC 19.35
  • Known to compile under: Visual Studio 2022 / MSVC 19.35 for a prior version of the current source
  • Earlier documented source revision: 9/1/26
  • Earlier version, 10/12/26: Task commit 83404dd (the previously documented revision). Added researcher pause/resume and skip controls with corresponding states, configurable cursor/target diameters, participant-facing Normal/Reversed labels and condition cues, and updated diagnostic metrics display; removed secondary CSV output and ResultsFile. Source moved to the inspected custom-module location and CMake target described above.
  • New version, 11/11/26: Latest inspected task revision (Git commits a169ed7 and 7d6d0ea, plus uncommitted working-tree changes). Added the Easy introduction tutorial mode and made it the default; replaced the boolean EnableIntroduction parameter with the enumerated IntroductionMode parameter; added TargetDistancePixels; added runtime cursor-diameter and target-distance controls to the diagnostic window together with CursorDiameterPx10, TargetDistancePx10, and DisplayGeometryChanged; added researcher PREVIOUS EASY PHASE and RESTART EASY PHASE controls with EasyIntroPrevious and EasyIntroRestarted events; added the EasyIntroPhase state and the Application:EasyIntroduction parameter group. The center and warning markers no longer scale with the cursor diameter.
  • Observed in the inspected parameter files: the current application build was produced with BCI2000 framework 3.6.9567.1 (release, AMD64, MSVC 19.35) on 2026-11-10. This is build metadata from a saved parameter file, not a verified runtime test of every 11/11/26 change.
  • Current inspected source revision: 11/11/26 (Git commits a169ed7 and 7d6d0ea, plus uncommitted working-tree changes)
  • Broken since: No known breaking revision

The earlier framework and compiler information above does not establish a successful build or runtime test of the 11/11/26 source revision; the present update is based on source comparison. The 11/11/26 change record is summarized here and in the Version History section.

Functional Description

Scientific Basis

This task is a BCI2000 adaptation of the visuomotor task described by Neumann et al. (2018).

In the original experiment, participants controlled a cursor using a pen and digitizing tablet. Targets appeared around a central fixation point. In the automatic condition, movement of the pen and cursor was congruent. In the controlled condition, the pen-to-cursor mapping was inverted. Automatic targets were shown in green and controlled targets in red.

Trials in the original experiment began at a central fixation cross. Participants remained at the center for 3 seconds, after which a yellow warning cue appeared for 500 ms. The target appeared 500 ms after the warning cue. The original experiment used eight possible target positions arranged around the center and included both ordered condition blocks and a pseudorandom block.

The present BCI2000 implementation preserves the central features of this paradigm, including the automatic and inverted controlled mappings, green and red targets, 3-second default experimental center hold, 500-ms warning period, 500-ms pre-target delay, and ordered and mixed experimental structures. The current participant-facing descriptions call these mappings Normal and Reversed, respectively; the legacy condition identifiers are retained in code and parameters.

There are several implementation differences. The BCI2000 version uses a USB HID joystick (Any joystick should work, provided that Windows recognizes it as a game controller.) rather than a digitizing tablet, allows the timing and number of trials to be configured, and generates experimental targets over a continuous range of angles rather than restricting targets to eight positions. It also provides an optional tutorial and practice sequence and records task variables directly as synchronized BCI2000 states.

See References for the original study.

Experiment Structure

Four experiment modes are available:

Value Mode Description
1 Automatic Only Runs one block containing only automatic trials.
2 Controlled Only Runs one block containing only controlled trials.
3 Ordered Runs one automatic block and one controlled block. OrderedStartCondition determines which condition occurs first.
4 Ordered + Pseudorandom Runs an ordered automatic block, an ordered controlled block, and then a mixed pseudorandom block containing both conditions.

In the mixed block, the application shuffles the configured numbers of automatic and controlled trials. The randomization attempts to avoid both strict alternation and excessively long runs of a single condition.

When the introduction is enabled, its content depends on IntroductionMode.

In Standard mode (IntroductionMode=1), tutorial content depends on ExperimentMode:

Experiment mode Tutorial content
Automatic Only General introduction, normal free movement, automatic instructions, automatic practice, completion
Controlled Only General introduction, normal free movement, controlled instructions, controlled free movement, controlled practice, completion
Ordered Automatic tutorial and practice followed by controlled tutorial and practice
Ordered + Pseudorandom Automatic tutorial and practice followed by controlled tutorial and practice

When both conditions are present, the Standard tutorial always presents automatic training before controlled training. OrderedStartCondition affects the experimental block order but does not change the tutorial order.

In Easy mode (IntroductionMode=2, the default), every experiment mode uses the same guided sequence: basic demonstration, normal demonstration, normal "your turn", normal practice when configured, reversed transition, reversed demonstration, reversed "your turn", reversed practice when configured, and a ready screen. The Easy tutorial always presents the normal mapping before the reversed mapping and, unlike the Standard tutorial, always includes a reversed section even in Automatic Only and Controlled Only modes.

In both tutorial modes, the participant sees Normal/Reversed wording, while the experiment parameters and state names continue to use Automatic/Controlled identifiers.

Tutorial and Practice Sequence

When IntroductionMode is 1 (Standard) or 2 (Easy), the tutorial begins at the start of each run before the first experimental block. When it is 0 (Disabled), the tutorial is skipped and the task begins with the experimental block-announcement sequence.

Standard introduction. The Standard introduction (IntroductionMode=1) consists of the following stages:

TutorialPhase Stage Description
0 None Tutorial inactive; normal experiment operation
1 Introduction General explanation of the task and upcoming conditions
2 Normal free movement Participant explores normal direct joystick-to-cursor movement
3 Normal instructions Explanation of the automatic (Normal) condition and green targets
4 Normal practice Automatic practice trials using the normal mapping
5 Reversed instructions Explanation of the controlled (Reversed) condition and red targets
6 Reversed free movement Participant explores continuous reversed joystick-to-cursor control
7 Reversed practice Controlled practice trials using the inverted mapping
8 Complete Practice-complete summary before the experiment begins

Easy introduction. The Easy introduction (IntroductionMode=2, the default) uses a guided sequence of animated demonstrations, static "your turn" and transition screens, and short practice blocks. Its stages are recorded in the EasyIntroPhase state:

EasyIntroPhase Stage Description
0 None Easy introduction inactive
1 Basic demonstration Animated cursor moves from the center to a target without a joystick illustration
2 Normal demonstration Animated cursor and joystick move together toward green targets
3 Normal: now your turn Static screen inviting the participant to try the normal mapping
4 Normal practice Normal-mapping practice trials using deterministic targets
5 Reversed introduction Static screen explaining that the cursor will move opposite the joystick
6 Reversed demonstration Animated cursor moves opposite the joystick toward red targets
7 Reversed: now your turn Static screen inviting the participant to try the reversed mapping
8 Reversed practice Reversed-mapping practice trials using deterministic targets
9 Ready Final summary screen before the experiment begins

The Easy sequence always runs in this order: basic demonstration, normal demonstration, normal "your turn", normal practice (when EasyIntroNormalPracticeTrials > 0), reversed introduction, reversed demonstration, reversed "your turn", reversed practice (when EasyIntroReversedPracticeTrials > 0), and ready. It is independent of ExperimentMode, so the reversed stages are presented even when only automatic experimental trials are configured.

Easy-stage behavior:

  • Demonstration animations use EasyIntroAnimationDurationMs for each movement and EasyIntroAnimationPauseMs for the pause at the target. EasyIntroAnimationLoop repeats the demonstration until the stage advances, and EasyIntroAnimationEnabled=0 replaces the animated movement with a near-static cursor position.
  • EasyIntroNormalDemoDirections and EasyIntroReversedDemoDirections set how many example movements are shown (1-4; default 2). The first example moves to the lower right and the second directly right; additional examples fan upward.
  • EasyIntroRequireButtonPress=0 (the default) advances eligible stages automatically: animations after all configured examples have played, the "your turn" and reversed-introduction screens after EasyIntroInterimScreenDurationMs, and the ready screen after EasyIntroReadyScreenDurationMs. Joystick button 1 (unless surgery mode is enabled) or researcher CONTINUE can advance a static screen before its automatic timer expires. Demonstration screens do not become eligible for manual continuation until all configured examples have played.
  • When EasyIntroRequireButtonPress=1 and EasyIntroSurgeryMode=0, eligible stages wait for joystick button 1 or the researcher CONTINUE control. Static screens are immediately eligible; demonstration screens become eligible after all configured examples have played.
  • When EasyIntroSurgeryMode=1, the non-practice Easy screens advance automatically and participant joystick-button continuation is disabled. Researcher CONTINUE remains available on eligible screens. Practice trials still require the participant to acquire the targets and return to center.
  • When EasyIntroRequireJoystickNeutral=1, an automatic advance or participant joystick-button continuation from the normal or reversed demonstration waits until the joystick is neutral. When instruction text is enabled, the display then shows "Let go of the joystick to continue." Researcher CONTINUE bypasses this neutral-joystick gate.
  • Easy practice uses EasyIntroNormalPracticeTrials and EasyIntroReversedPracticeTrials rather than the Standard practice-trial counts, and uses EasyIntroPracticeCenterHoldMs for its center hold. Success feedback lasts EasyIntroFeedbackDurationMs, or is omitted when EasyIntroPracticeFeedback=0.
  • EasyIntroShowInstructionText and EasyIntroShowJoystickIllustration hide the instruction text and the animated joystick graphic, respectively.
  • EasyIntroAllowResearcherSkip=0 disables the researcher skip controls for the Easy introduction (SKIP INTRODUCTION, SKIP PRACTICE, and SKIP CURRENT EASY PHASE). The previous-phase and restart-phase controls remain available.

After the final Easy practice trial, the participant must return the cursor to the center before the sequence advances.

Tutorial Continuation

Tutorial screens that require participant acknowledgement may be advanced using either:

  • Joystick button 1, or
  • The experimenter's CONTINUE button in the diagnostic window.

Joystick continuation uses rising-edge detection. Pressing the button advances one eligible tutorial screen, while holding the button does not repeatedly advance the tutorial. The button must be released and pressed again to produce another continuation event.

In the Standard introduction, this applies to the introduction, normal free-movement, instruction, controlled free-movement, and completion screens. In the Easy introduction, researcher CONTINUE can advance any eligible non-practice stage. Joystick button 1 can do the same only when EasyIntroSurgeryMode=0. When EasyIntroRequireButtonPress=1 and surgery mode is off, a participant joystick press or researcher CONTINUE is required; otherwise, stages also advance automatically after their animation or timer. Static Easy screens are immediately eligible, and demonstration screens become eligible after all configured examples have played. During the normal and reversed demonstrations, EasyIntroRequireJoystickNeutral=1 delays automatic or participant-button advancement until the joystick is neutral; researcher CONTINUE bypasses that requirement.

Button presses are ignored during active practice trials and during tutorial transitions that require the participant to return the joystick or cursor to center.

During the experimental portion of the run, joystick button presses do not control trial progression. The researcher CONTINUE control displays CONTINUE UNAVAILABLE when continuation is not permitted. The researcher can also use context-specific skip, previous-phase, and restart-phase controls; these actions are documented under Researcher Skip Controls. The task can be paused during tutorial stages.

Normal Free Movement

During the Standard introduction's normal free-movement stage, the participant may freely move the cursor using the direct absolute joystick mapping.

There is no timer or trial progression during this stage. It continues until the participant presses the joystick button or the experimenter selects CONTINUE.

The Easy introduction does not include a free-movement sandbox. Its normal demonstration, normal "your turn", and normal practice stages serve the same introductory purpose.

Automatic Practice

Automatic practice uses the same direct mapping and the same basic trial phases as experimental automatic trials:

  1. Waiting for center
  2. Holding center
  3. Warning
  4. Pre-target delay
  5. Target visible
  6. Feedback

Practice trials differ from experimental trials in several ways:

  • Center hold is determined by PracticeCenterHoldTime rather than CenterHoldSeconds in the Standard introduction, and by EasyIntroPracticeCenterHoldMs in the Easy introduction.
  • Practice targets follow a deterministic sequence.
  • TaskBlock and TaskTrial remain 0.
  • PracticeTrial identifies the active practice trial.
  • Practice activity is recorded in BCI2000 states; this application writes no separate trial-level CSV file.
  • Practice results are excluded from experimental completion counts and timing summaries.
  • Practice reset attempts do not increment experimental reset metrics.

In the Easy introduction, normal practice is part of EasyIntroPhase 4, uses EasyIntroNormalPracticeTrials for its trial count, and uses EasyIntroFeedbackDurationMs for success feedback (or no feedback when EasyIntroPracticeFeedback=0). The same trial phases apply.

After the final automatic practice trial, the participant must return the cursor to the center before the tutorial advances.

Controlled Free Movement

The controlled free-movement stage belongs to the Standard introduction. It allows the participant to explore reversed cursor control without a target.

The participant is first asked to return the cursor to center. Once centered, the application records the current joystick and cursor positions as anchors and enables the same relative inverted mapping used during target-directed controlled movement.

When the participant requests continuation, the task requires the joystick to return to the anchored position before advancing. This prevents an abrupt cursor jump when the mapping changes.

The Easy introduction has no controlled free-movement sandbox; its reversed demonstration and reversed "your turn" stages replace it.

Controlled Practice

Controlled practice uses the same basic controlled-trial behavior as the experiment:

  • Direct absolute mapping is used during centering.
  • Joystick and cursor anchors are recorded when the target appears.
  • Target-directed cursor movement uses the relative inverted mapping.
  • The participant returns the joystick toward its anchor after target acquisition.

Standard controlled practice uses PracticeCenterHoldTime and deterministic practice targets and remains separate from experimental numbering and performance summaries. Its states are recorded in the BCI2000 data stream; no secondary CSV is written.

In the Easy introduction, reversed practice is part of EasyIntroPhase 8, uses EasyIntroReversedPracticeTrials for its trial count, and uses EasyIntroPracticeCenterHoldMs plus EasyIntroFeedbackDurationMs (when EasyIntroPracticeFeedback=1).

After the final controlled practice trial, the participant must complete the return-to-center and return-to-anchor transition before the completion screen appears.

Tutorial Completion

The Standard completion screen summarizes the condition mappings:

  • Normal (automatic): cursor movement follows joystick movement.
  • Reversed (controlled): cursor movement is opposite joystick movement.
  • Green targets identify automatic trials.
  • Red targets identify controlled trials.

In the Easy introduction, the corresponding screen is EasyIntroPhase 9 (Ready). It states that green targets mean "move toward the target" and red targets mean "move in the opposite direction". Depending on the Easy-introduction parameters, it waits for participant joystick-button or researcher CONTINUE input, or advances automatically after EasyIntroReadyScreenDurationMs.

In both modes, the tutorial then ends, Introduction returns to 0, the originally generated first experimental target is restored, and the experiment begins with the normal 1.5-second block announcement.

Experimental Trial Sequence

Each experimental block begins with a 1.5-second announcement indicating whether the upcoming block is Normal, Reversed, or Mixed. These visible labels correspond to the existing automatic, controlled, and mixed block types; their numerical encodings are unchanged.

A trial then proceeds as follows:

  1. The participant moves the cursor into the center region.
  2. Once centered, the participant must remain there for CenterHoldSeconds.
  3. A yellow warning marker appears for WarningSeconds.
  4. A pre-target interval lasting PreTargetDelaySeconds follows.
  5. The target appears at TargetDistancePixels from the center.
  6. The participant moves the cursor into the target.
  7. Target acquisition records the trial timing measurements and begins the feedback interval.
  8. After FeedbackSeconds, the task advances to the next trial or block.

If the participant leaves the center during the center-hold, warning, or pre-target interval, the task returns to the waiting-for-center phase and the preparation sequence begins again.

A new target is generated when advancing to a new experimental trial. Manually resetting a trial does not generate a new target. Skipping an experimental trial instead advances to the next trial and generates a new target (unless the experiment has finished). A skip-block action advances past the remaining trials in the block.

Automatic Condition (Normal)

During an automatic trial, cursor position follows the joystick using a direct mapping. Moving the joystick in one direction moves the cursor in the corresponding direction.

Automatic targets are displayed in green.

Controlled Condition (Reversed)

During a controlled trial, the normal direct mapping is initially used while the participant returns to and holds the center.

When the target appears, the current joystick position and cursor position are recorded as anchors. Cursor movement then becomes relative to those anchors and inverted. Moving the joystick away from its target-onset position causes the cursor to move in the opposite direction.

Conceptually:

cursor position = anchor cursor position - joystick displacement

The cursor is constrained to the participant display.

After completion of a controlled trial, the inverted mapping remains active until the joystick has returned close to the joystick position recorded at target onset. This prevents an abrupt cursor jump when returning from the controlled mapping to the normal mapping.

Controlled targets are displayed in red.

Joystick Input

Joystick input is provided through BCI2000's input logging system.

Joystick position states are expected to range from 0 through 32767. The application converts these values into internal task coordinates ranging from 0 through 1023.

The application reads:

  • JoystickXpos
  • JoystickYpos
  • JoystickButtons1

JoystickButtons1 is used during the tutorial as a participant continuation button. A rising button press may advance eligible tutorial screens. It does not advance active practice trials and has no effect on experimental trial progression.

Joystick recording is normally enabled using the LogJoystick option. See LogJoystick for configuration details.

Experimental Target Generation

A new target angle is generated for each new experimental trial.

The random target generator produces an integer between 0 and 3599. TargetAngle therefore represents tenths of a degree:

angle in degrees = TargetAngle / 10

This produces target angles from 0.0 through 359.9 degrees.

Targets are positioned at a distance of TargetDistancePixels from the center (default 300 reference-display pixels) using the generated angle.

Unlike the original Neumann et al. experiment, which used eight circularly arranged target locations, the BCI2000 implementation allows experimental targets to appear over a continuous range of angles.

If the target distance is changed at runtime through the diagnostic window, the current and saved experimental target positions are recalculated at the new distance. The current distance is recorded in TargetDistancePx10.

Practice Target Generation

Practice trials use a deterministic six-angle sequence rather than the experimental random target generator:

Sequence value Target angle
150 15 degrees
450 45 degrees
750 75 degrees
1050 105 degrees
1350 135 degrees
1650 165 degrees

Automatic practice begins with the 15-degree target and follows the sequence in order.

Controlled practice begins with an offset of two positions, producing:

75°, 105°, 135°, 165°, 15°, 45°

If more than six practice trials are configured, the sequence repeats.

These targets are positioned in the lower half of the participant display to reduce overlap with tutorial text, at the current TargetDistancePixels distance. The same deterministic sequence is used for both Standard and Easy practice trials.

The random target generated for the first experimental trial is saved before the tutorial begins and restored after practice finishes.

Trial Phases

The current trial phase is recorded in TaskPhase.

Value Phase Description
0 Block announcement / no active practice trial During the experiment, the upcoming block type is being displayed. During non-trial tutorial screens, including Easy-introduction animation and text screens, TaskPhase is also 0.
1 Waiting for center The task is waiting for the cursor to enter the center region.
2 Holding center The participant is completing the required center hold.
3 Warning The yellow warning cue is visible.
4 Pre-target delay The warning has ended and the task is waiting for target onset.
5 Target visible The peripheral target is visible and movement may occur.
6 Feedback The target has been acquired and the task is waiting before advancing.
7 Finished The run has reached its end after the final trial, or after a researcher action skips the remaining trial(s).

During active automatic or controlled practice trials, including Easy-introduction practice, values 1 through 6 retain the same meanings as they do during experimental trials.

Because non-trial tutorial screens use TaskPhase=0, analysts should use Introduction to distinguish tutorial screens from experimental block announcements. Within the tutorial, TutorialPhase identifies Standard stages and EasyIntroPhase identifies Easy stages.

An experimental target onset is identified by:

Introduction == 0
and TaskPhase transitions from 4 to 5

A practice target onset is identified by:

Introduction == 1
and PracticeTrial > 0
and TaskPhase transitions from 4 to 5

Condition and Block Encodings

State/Parameter Value Meaning
TaskCondition 0 Automatic
TaskCondition 1 Controlled
TaskBlockType 0 Ordered automatic block
TaskBlockType 1 Ordered controlled block
TaskBlockType 2 Pseudorandom mixed block
OrderedStartCondition 0 Automatic first
OrderedStartCondition 1 Controlled first

During the tutorial, TaskCondition reflects the tutorial condition rather than the first experimental condition. In the Standard introduction it begins at 0 during the general introduction and normal free-movement stages, including in Controlled Only mode, and changes to 1 once the controlled portion of the tutorial begins. In the Easy introduction it is 0 during the basic demonstration and all normal stages, changes to 1 when the reversed introduction begins, and remains 1 through the ready screen.

During the tutorial, TaskBlockType is forced to 0 and should not be interpreted as an experimental ordered-automatic block. The participant sees Normal for TaskCondition=0 and Reversed for TaskCondition=1; these labels do not change the state values.

Participant Display

The participant-facing ApplicationWindow contains:

  • A light gray background (0xEBEBEB).
  • A black cursor whose diameter is configured by CursorDiameterPixels (default 16 pixels in the reference display). The cursor diameter can also be changed at runtime from the diagnostic window; the center and warning markers retain their fixed sizes when it changes.
  • A black central fixation cross.
  • A gray center marker.
  • A larger yellow warning marker.
  • A green target during automatic (Normal) trials.
  • A red target during controlled (Reversed) trials.
  • A target diameter controlled by TargetDiameterPixels (default 36 pixels). This value also affects the elliptical target-hit tolerance, not just appearance.
  • A center-to-target distance controlled by TargetDistancePixels (default 300 pixels).
  • A visible NORMAL or REVERSED condition cue near the top of the participant display during relevant Standard tutorial stages and block announcements. The cue is not shown during the Easy introduction.
  • A progress bar near the top of the display during the experiment.
  • Tutorial and practice instructions when the introduction is enabled. The Standard introduction uses white text in a dark gray message box. The Easy introduction uses black text directly on the light background, and its text-only stages hide the cursor and fixation cross and occupy most of the display.
  • Animated cursor and target demonstrations during the Easy introduction, optionally accompanied by an animated joystick illustration.
  • Block announcements using the terms Normal, Reversed, or Mixed.
  • An "ended" message when the run reaches its end, including when a skip action bypasses the remaining trial(s).

The experimental progress bar is hidden throughout the tutorial and practice sequence. Practice trials do not contribute to experimental progress. When a researcher skips the remainder of an experimental block, the bar can advance to reflect the skipped trial positions even though those trials are not counted as successfully completed.

Changing the cursor diameter or target distance in the diagnostic window updates the participant display on the next processing block, recalculates the current and saved experimental target positions, and pulses DisplayGeometryChanged. The applied values are recorded in CursorDiameterPx10 and TargetDistancePx10. The target diameter can be changed only through the TargetDiameterPixels parameter before the run.

The StimulusDisplay parameter may be used to select the physical monitor on which the participant window appears.

The Normal/Reversed cue is intentional in this USB HID task. The underlying state encoding remains TaskCondition=0 for automatic/Normal and TaskCondition=1 for controlled/Reversed. In the Easy introduction, condition is conveyed by target color and instruction text instead of the on-screen cue.

Diagnostic Window

A separate diagnostic window is shown to the experimenter. In the currently inspected version, the visible panel is the performance metrics panel. During the tutorial it presents the introduction/practice context, mapping condition, cursor diameter, target distance, and applicable practice-trial information; live timing is shown as placeholders where appropriate, and run averages are not yet available. During experimental trials it presents:

  • Normal or Reversed condition and trial numbering within the block and overall experiment.
  • Current cursor diameter and target distance.
  • The current ReactionTimeMs, MovementTimeMs, and TotalTimeMs state values under a panel heading labeled REAL-TIME METRICS. These are not continuously running timers: they remain 0 until a target is acquired, then show the completed trial's values during feedback (and at run end for the final successful trial).
  • Overall and condition-specific (automatic and controlled) mean timing measurements.

Below the metrics panel are two spin boxes labeled Cursor diameter and Target distance. They adjust the displayed cursor size and center-to-target distance during a run. A change is applied on the next processing block, updates the current and saved target positions, pulses DisplayGeometryChanged, and updates CursorDiameterPx10 and TargetDistancePx10.

The application still assembles a more detailed diagnostic text label containing tutorial phase, task phase, target position, joystick and cursor coordinates, movement status, block type, completion/reset counts, and other status information. However, that text widget is explicitly hidden in the inspected build (mpDiagnosticText->hide()). These detailed values are not visible in the current diagnostic window and should not be mistaken for on-screen readouts. Relevant values can still be obtained from the recorded states.

Researcher Controls

The diagnostic window contains a blue CONTINUE button on eligible tutorial screens. When continuation is unavailable, it displays CONTINUE UNAVAILABLE. In the Easy introduction, researcher CONTINUE remains available even when EasyIntroSurgeryMode=1; surgery mode disables participant joystick-button continuation, not this researcher control. When EasyIntroRequireButtonPress=1 and surgery mode is off, either participant joystick input or researcher CONTINUE is required; otherwise, screens also advance automatically. Static Easy screens are immediately eligible, and demonstration screens become eligible after all configured examples have played. Researcher CONTINUE also bypasses the EasyIntroRequireJoystickNeutral gate.

Its context-sensitive reset button displays:

  • RESET PRACTICE TRIAL during eligible practice trials.
  • RESET CURRENT TRIAL during eligible experimental trials.
  • RESET UNAVAILABLE when reset is not permitted.

The current window also includes SKIP TRIAL, SKIP CURRENT BLOCK, SKIP INTRODUCTION, SKIP PRACTICE, SKIP SANDBOX, PREVIOUS EASY PHASE, RESTART EASY PHASE, and PAUSE/RESUME. Controls are enabled only in the appropriate task context. Skipping the current block and skipping the introduction prompt for confirmation; the other skip controls act without a confirmation dialog.

During the Easy introduction, the SKIP SANDBOX button is relabeled SKIP CURRENT EASY PHASE. PREVIOUS EASY PHASE returns to the preceding Easy stage (it is unavailable on the basic-demonstration stage), and RESTART EASY PHASE restarts the current Easy stage, including restarting an active practice block at its first trial. Setting EasyIntroAllowResearcherSkip=0 disables the Easy skip controls; the previous-phase and restart-phase controls remain available.

Researcher Skip Controls

Control When available Behavior Recorded event
SKIP TRIAL During an experimental trial before feedback, while not paused Immediately advances to the next trial (or finishes the run if it was the last trial). A new target is generated for the next trial. A skipped trial does not increment completed-trial or reset metrics. In a controlled trial the return-to-anchor behavior is retained as needed. TrialSkipped
SKIP CURRENT BLOCK During an experimental trial before feedback, while not paused; confirmation required Skips the remaining trials in the current block, advances to the next block or ends the run, and increments the overall trial-position counter by the number skipped. It does not count these trials as completed. ConditionSkipped
SKIP INTRODUCTION During the tutorial, while not paused; confirmation required Exits the entire tutorial, restores the saved first experimental target, and enters the experimental block-announcement sequence. In the Easy introduction this control is available only when EasyIntroAllowResearcherSkip=1. IntroductionSkipped
SKIP PRACTICE During an active Standard or Easy practice trial, while not paused Ends the remaining practice trials for that practice condition. In the Standard introduction, after Normal practice it proceeds to Reversed instructions if configured, otherwise tutorial completion; after Reversed practice it proceeds to completion. In the Easy introduction it advances to the next Easy stage. Available in Easy mode only when EasyIntroAllowResearcherSkip=1. PracticeSkipped
SKIP SANDBOX / SKIP CURRENT EASY PHASE During Standard Normal or Reversed free movement, or during any non-practice Easy stage, while not paused In Standard mode, ends the free-movement stage and proceeds to the appropriate next instructions, practice stage, or completion screen. In Easy mode, the button is relabeled SKIP CURRENT EASY PHASE and advances to the next Easy stage; from the ready stage it begins the experiment. Available in Easy mode only when EasyIntroAllowResearcherSkip=1. SandboxSkipped
PREVIOUS EASY PHASE During the Easy introduction, while not paused, and not on the basic-demonstration stage Returns to the preceding Easy stage. Moving back from the reversed-transition or ready stage re-enters the preceding practice block at its first trial. EasyIntroPrevious
RESTART EASY PHASE During the Easy introduction, while not paused Restarts the current Easy stage. If a practice stage is active, the practice block restarts at its first trial. EasyIntroRestarted

Each skip event is written as a one-processing-block state pulse and is cleared at the beginning of the next processing block. The Easy-phase navigation events EasyIntroPrevious and EasyIntroRestarted follow the same one-block pulse pattern. Skip and navigation actions can bypass the regular end-of-Process() state synchronization. Therefore, the event pulse may precede the updated TaskPhase, TaskTrial, TaskBlock, target, or cursor states by one processing block. If an action ends the entire run, the last recorded phase/trial values may retain their pre-action values rather than representing the usual Finished-phase state. Offline analyses should therefore use the event states, not rely solely on a simultaneous change in other states.

Pause and Resume

The PAUSE/RESUME control is available during both tutorial and experimental portions of the run, but not after the task finishes.

  • Pausing sets TaskPaused=1. Task trial and cursor progression stop, but the BCI2000 stream continues to record samples with the pause state high.
  • Resuming sets TaskPaused=0. The program shifts the applicable phase, tutorial, target-onset, and movement-onset clocks forward by the paused duration.
  • Paused time is excluded from the application's reaction time, movement time, total time, and active phase durations.
  • Researcher skip, previous-phase, and restart-phase actions are unavailable while paused.
  • Display-geometry changes made in the diagnostic window are still applied during a pause, without advancing the task.

A paused BCI2000 recording is not the same as a stopped BCI2000 run. Analysts should explicitly account for samples with TaskPaused=1.

Trial Reset

Experimental trials may be manually reset before they reach the feedback phase.

Resetting an experimental trial:

  • Returns the task to the waiting-for-center phase.
  • Clears the current movement and timing states.
  • Generates a TrialReset event.
  • Increments the experimental diagnostic reset count.
  • Keeps the same trial number.
  • Keeps the same target.
  • Does not generate a successful-trial event or count as a completed experimental trial.

Practice trials may also be reset before feedback, in both the Standard and Easy introductions.

Resetting a practice trial:

  • Returns the practice trial to the waiting-for-center phase.
  • Clears movement and timing states.
  • Generates a TrialReset event.
  • Keeps the same PracticeTrial value.
  • Keeps the same deterministic target.
  • Does not increment experimental reset metrics.
  • Does not increment experimental completed-trial metrics.

Reset is unavailable during tutorial instruction, demonstration, and free-movement screens and after a trial has entered feedback. Resetting a controlled trial after its target is visible also enables return-to-anchor handling so that resuming normal cursor control does not produce an abrupt jump. Reset preserves the current trial and its target, whereas SKIP TRIAL advances to a new one.

Timing Measurements

The task calculates reaction time, movement time, and total time for successfully completed practice and experimental trials.

Reaction time is the interval between target appearance and detected movement onset.

Movement time is the interval between detected movement onset and target acquisition.

Total time is the interval between target appearance and target acquisition.

Movement onset is detected when either joystick axis differs from the center-hold baseline by more than the task's joystick deadzone.

Timing is measured using a steady clock, but movement onset and target acquisition are detected during calls to Process(). The effective temporal resolution is therefore limited by the BCI2000 processing-block interval.

Practice timing values are recorded in the BCI2000 states but are excluded from experimental timing summaries. The task writes no application-specific CSV. When the researcher pauses the task, clock offsets are adjusted on resume so that the reported RT, MT, and total time exclude the paused interval, even though the paused samples remain in the BCI2000 data stream.

In the Easy introduction, the interval after a successful practice trial is set by EasyIntroFeedbackDurationMs, or is omitted when EasyIntroPracticeFeedback=0. This feedback interval follows target acquisition and does not change the recorded reaction, movement, or total times.

Data Recording

The task records its behavioral and tutorial variables as BCI2000 states, allowing them to be synchronized with the normal BCI2000 .dat recording.

Joystick coordinates are also recorded when joystick input logging is enabled.

Tutorial and practice samples are part of the same BCI2000 run as the experiment. The Introduction state should therefore be used when separating tutorial/practice data from experimental data during offline analysis. Within the tutorial, TutorialPhase identifies Standard stages and EasyIntroPhase identifies Easy stages.

Practice trials record:

  • Cursor trajectory.
  • Target coordinates and angle.
  • Trial phase.
  • Practice condition.
  • Movement onset.
  • Target acquisition.
  • Reaction time.
  • Movement time.
  • Total time.
  • Practice reset events.
  • Practice trial number.

Practice trials are intentionally excluded from:

  • Experimental TaskTrial numbering.
  • Experimental TaskBlock numbering.
  • Automatic and controlled completion counts.
  • Automatic and controlled reset counts.
  • Mean reaction-time summaries.
  • Mean movement-time summaries.
  • Mean total-time summaries.

No secondary results file is created by this application in the current version. The ResultsFile parameter and trial-level CSV writer were removed. All per-trial behavioral information must be reconstructed from the recorded BCI2000 .dat states; joystick state recording additionally depends on the normal LogJoystick configuration.

Researcher skip events (TrialSkipped, ConditionSkipped, IntroductionSkipped, PracticeSkipped, SandboxSkipped), Easy-phase navigation events (EasyIntroPrevious, EasyIntroRestarted), and the persistent TaskPaused state are also recorded. They identify deviations from ordinary trial/tutorial progression and samples recorded during pause.

Display geometry is recorded through CursorDiameterPx10 and TargetDistancePx10, both expressed in tenths of a pixel, and each runtime change produces a one-block DisplayGeometryChanged pulse. Because a target-distance change moves the current and saved targets, TargetX/TargetY and TargetAngle should be interpreted together with the distance state for the samples in question.

The application writes BCI2000 console messages when the task starts and stops and when practice or experimental trials succeed. Messages include the applicable trial/condition and reaction/movement times; these console messages are not an additional trial-level results file and should not be treated as synchronized state data.

Parameters

Parameters for experimental structure, timing, display, and display geometry are grouped under Application:USBHIDJoystick in the BCI2000 parameter tree. AutomaticPracticeTrials, ControlledPracticeTrials, and PracticeCenterHoldTime are grouped under Application:Introduction. IntroductionMode and the EasyIntro* parameters are grouped under Application:EasyIntroduction. Existing parameter files that use the removed EnableIntroduction parameter must be updated.

IntroductionMode

Selects the participant introduction and practice sequence.

Type: integer enumeration

Default: 2

Range: 0-2

Values:

  • 0: Disabled. Skip the introduction and begin the experiment normally.
  • 1: Standard. Text-driven introduction with free movement and practice trials.
  • 2: Easy. Guided demonstrations, "your turn" screens, and short practice blocks (default).

This parameter applies to all experiment modes. It replaces the earlier boolean EnableIntroduction parameter: EnableIntroduction=1 corresponds approximately to IntroductionMode=1 (Standard), and EnableIntroduction=0 corresponds to IntroductionMode=0 (Disabled).

AutomaticPracticeTrials

Number of automatic practice trials presented during the Standard introduction (IntroductionMode=1).

Type: integer

Default: 3

Range: 0-20

The parameter is used only when the selected experiment mode contains automatic trials.

A value of 0 skips automatic practice trials while retaining the automatic instruction page.

The Easy introduction uses EasyIntroNormalPracticeTrials instead.

Practice trials do not count toward the experimental trial-count parameters.

ControlledPracticeTrials

Number of controlled practice trials presented during the Standard introduction (IntroductionMode=1).

Type: integer

Default: 3

Range: 0-20

The parameter is used only when the selected experiment mode contains controlled trials.

A value of 0 skips controlled practice trials. The controlled instruction page and controlled free-movement demonstration are still presented.

The Easy introduction uses EasyIntroReversedPracticeTrials instead.

Practice trials do not count toward the experimental trial-count parameters.

PracticeCenterHoldTime

Center-hold duration used during Standard-introduction practice trials.

Type: floating-point time

Default: 1s

Range: 0s-60s

This parameter replaces CenterHoldSeconds during Standard practice trials only.

Easy-introduction practice trials use EasyIntroPracticeCenterHoldMs.

Experimental trials continue to use CenterHoldSeconds.

The following parameters belong to the Application:EasyIntroduction group and affect only the Easy introduction.

EasyIntroAnimationEnabled

Enables animated cursor demonstrations in the Easy introduction.

Type: integer boolean

Default: 1

Range: 0-1

When set to 0, the cursor is displayed at a near-static position instead of animating between the center and target.

EasyIntroAnimationDurationMs

Duration of each Easy-introduction demonstration movement.

Type: integer (milliseconds)

Default: 2500

Range: 1-60000

EasyIntroAnimationPauseMs

Pause at the target before the next demonstration example or repetition.

Type: integer (milliseconds)

Default: 750

Range: 0-60000

EasyIntroAnimationLoop

Repeats the demonstration until the Easy stage advances.

Type: integer boolean

Default: 1

Range: 0-1

When set to 0, the demonstration plays only the configured number of examples and then stops.

EasyIntroNormalDemoDirections

Number of animated normal-mapping examples.

Type: integer

Default: 2

Range: 1-4

Example 1 moves to the lower right and example 2 moves directly right; additional examples fan upward.

EasyIntroReversedDemoDirections

Number of animated reversed-mapping examples.

Type: integer

Default: 2

Range: 1-4

The visual target movements follow the same sequence as the normal examples, while the illustrated joystick moves in the opposite direction.

EasyIntroNormalPracticeTrials

Number of normal-mapping practice trials in the Easy introduction.

Type: integer

Default: 3

Range: 0-20

A value of 0 skips normal practice while retaining the normal demonstration and "your turn" stages.

EasyIntroReversedPracticeTrials

Number of reversed-mapping practice trials in the Easy introduction.

Type: integer

Default: 3

Range: 0-20

A value of 0 skips reversed practice while retaining the reversed demonstration and "your turn" stages.

EasyIntroPracticeCenterHoldMs

Center-hold duration for Easy-introduction practice trials.

Type: integer (milliseconds)

Default: 3000

Range: 0-60000

This value replaces PracticeCenterHoldTime during Easy practice only.

EasyIntroPracticeFeedback

Enables the brief success-feedback interval after an Easy practice target is acquired.

Type: integer boolean

Default: 1

Range: 0-1

EasyIntroFeedbackDurationMs

Duration of the Easy practice success-feedback interval.

Type: integer (milliseconds)

Default: 500

Range: 0-60000

This value is used only when EasyIntroPracticeFeedback=1.

EasyIntroRequireButtonPress

Controls whether eligible Easy-introduction screens wait for manual continuation rather than advancing on their timers.

Type: integer boolean

Default: 0

Range: 0-1

When set to 0, stages advance automatically after their animations and timers. Joystick button 1 (when surgery mode is off) and researcher CONTINUE can still advance an eligible static screen before its timer expires. When set to 1 and EasyIntroSurgeryMode=0, stages wait for joystick button 1 or CONTINUE. Static screens are immediately eligible; demonstration screens become eligible after all configured examples have played. When surgery mode is on, this parameter does not prevent automatic advancement.

EasyIntroSurgeryMode

Advances the non-practice Easy-introduction screens automatically without participant button presses.

Type: integer boolean

Default: 0

Range: 0-1

This mode is intended for sessions in which the participant cannot operate the joystick button. Participant joystick-button continuation is disabled, and the configured animation, interim-screen, and ready-screen timers control progression. Researcher CONTINUE remains available on eligible non-practice screens. Practice trials still require the participant to acquire each target and return to center.

EasyIntroInterimScreenDurationMs

Time that transition and "your turn" screens remain visible when advancing automatically.

Type: integer (milliseconds)

Default: 2000

Range: 0-60000

EasyIntroReadyScreenDurationMs

Time that the final Easy ready screen remains visible before the experiment starts automatically.

Type: integer (milliseconds)

Default: 5000

Range: 0-60000

This value applies when the ready screen advances automatically.

EasyIntroRequireJoystickNeutral

Requires the joystick to be neutral before an automatic or participant-button advance leaves the normal or reversed Easy demonstration stage.

Type: integer boolean

Default: 1

Range: 0-1

When an automatic advance or participant joystick-button request occurs while the joystick is not neutral, the stage waits for neutral. If EasyIntroShowInstructionText=1, the display asks the participant to let go. Researcher CONTINUE bypasses this requirement.

EasyIntroShowJoystickIllustration

Shows the animated joystick illustration during the normal and reversed Easy demonstrations. The basic demonstration never shows the joystick illustration.

Type: integer boolean

Default: 1

Range: 0-1

EasyIntroShowInstructionText

Shows the Easy-introduction instruction text.

Type: integer boolean

Default: 1

Range: 0-1

EasyIntroAllowResearcherSkip

Enables the researcher skip controls during the Easy introduction.

Type: integer boolean

Default: 1

Range: 0-1

When set to 0, the Easy introduction cannot be exited or advanced with SKIP INTRODUCTION, SKIP PRACTICE, or SKIP CURRENT EASY PHASE. The PREVIOUS EASY PHASE and RESTART EASY PHASE controls remain available.

ExperimentMode

Selects the overall experimental structure.

Type: integer enumeration

Default: 1

Range: 1-4

Values:

  • 1: Automatic only
  • 2: Controlled only
  • 3: Ordered automatic and controlled
  • 4: Ordered automatic, ordered controlled, and pseudorandom mixed

The application verifies during preflight that the trial-count parameters required by the selected mode are at least 1.

The selected mode also determines which condition-specific tutorial sections are presented in the Standard introduction. The Easy introduction does not depend on ExperimentMode.

AutomaticTrials

Number of automatic experimental trials used by experiment modes 1 and 3.

Type: integer

Default: 5

Declared range: 0-10000

When used by the selected experiment mode, the value must be at least 1.

Practice trials are additional and do not reduce or increment this count.

ControlledTrials

Number of controlled experimental trials used by experiment modes 2 and 3.

Type: integer

Default: 5

Declared range: 0-10000

When used by the selected experiment mode, the value must be at least 1.

Practice trials are additional and do not reduce or increment this count.

OrderedStartCondition

Determines which experimental condition is presented first in experiment mode 3.

Type: integer enumeration

Default: 0

Values:

  • 0: Automatic first
  • 1: Controlled first

This parameter does not affect experiment modes 1, 2, or 4.

It also does not affect tutorial order. The Standard tutorial presents automatic training before controlled training when both are included, and the Easy tutorial always presents the normal stages before the reversed stages.

OrderedAutomaticTrials

Number of experimental automatic trials in the ordered automatic block of experiment mode 4.

Type: integer

Default: 5

Declared range: 0-10000

When mode 4 is selected, the value must be at least 1.

OrderedControlledTrials

Number of experimental controlled trials in the ordered controlled block of experiment mode 4.

Type: integer

Default: 5

Declared range: 0-10000

When mode 4 is selected, the value must be at least 1.

RandomAutomaticTrials

Number of experimental automatic trials included in the pseudorandom block of experiment mode 4.

Type: integer

Default: 5

Declared range: 0-10000

When mode 4 is selected, the value must be at least 1.

RandomControlledTrials

Number of experimental controlled trials included in the pseudorandom block of experiment mode 4.

Type: integer

Default: 5

Declared range: 0-10000

When mode 4 is selected, the value must be at least 1.

StimulusDisplay

Selects the physical display used for the participant-facing application window.

Type: integer enumeration

Default: 0

Values:

  • 0: Automatic/default ApplicationWindow placement.
  • 1 and above: Select one of the displays detected when the parameters are published.

On Windows, available monitors are enumerated with their dimensions and primary-display status.

The application verifies during preflight that the selected display exists.

CenterHoldSeconds

Duration for which the participant must keep the cursor within the center region during experimental trials.

Type: floating point

Default: 3.0 seconds

Range: 0.0-60.0 seconds

Leaving the center during this interval restarts the center-acquisition sequence.

This parameter does not control practice center-hold duration. Standard practice trials use PracticeCenterHoldTime, and Easy practice trials use EasyIntroPracticeCenterHoldMs.

WarningSeconds

Duration of the yellow warning cue.

Type: floating point

Default: 0.5 seconds

Range: 0.0-60.0 seconds

Leaving the center during the warning interval restarts the center-acquisition sequence.

This parameter applies to both practice and experimental trials.

PreTargetDelaySeconds

Delay between the end of the warning cue and target appearance.

Type: floating point

Default: 0.5 seconds

Range: 0.0-60.0 seconds

The participant must remain centered during this interval.

This parameter applies to both practice and experimental trials.

FeedbackSeconds

Interval between successful target acquisition and advancement to the next trial, tutorial transition, or experimental block.

Type: floating point

Default: 0.5 seconds

Range: 0.0-60.0 seconds

This parameter applies to experimental trials and Standard-introduction practice trials. Easy-introduction practice instead uses EasyIntroFeedbackDurationMs when EasyIntroPracticeFeedback=1, or no feedback interval when it is 0.

CursorDiameterPixels

Cursor diameter, expressed in reference-display pixels and converted to normalized rendering dimensions during initialization.

Type: floating point

Default: 16.0

Range: 1.0-1000.0

A positive value is required by preflight validation.

The cursor diameter can also be changed at runtime using the Cursor diameter control in the diagnostic window. Runtime changes are recorded in CursorDiameterPx10. The center and warning markers retain their fixed sizes when the cursor diameter changes. Because the cursor radius contributes to the target-hit ellipse, changing the cursor diameter also changes the effective target-acquisition tolerance.

TargetDiameterPixels

Target diameter, expressed in reference-display pixels and converted to normalized rendering dimensions during initialization.

Type: floating point

Default: 36.0

Range: 1.0-1000.0

A positive value is required by preflight validation. In addition to determining visual size, this parameter affects the ellipse used to determine target acquisition. Consequently, changing it can change the effective movement tolerance and behavioral measurements.

This parameter is not adjustable at runtime from the diagnostic window.

TargetDistancePixels

Center-to-target distance, expressed in reference-display pixels.

Type: floating point

Default: 300.0

Range: 1.0-350.0

The value applies to experimental targets, practice targets, and Easy-introduction demonstration targets. It can also be changed at runtime using the Target distance control in the diagnostic window; the applied value is recorded in TargetDistancePx10. Changing the distance recalculates the current and saved experimental target positions, so TargetX and TargetY change without a new target angle being generated.

The ResultsFile parameter was removed; see Data Recording.

States

The following states are defined by USBHIDJoystickTask and are recorded with the normal BCI2000 data stream.

Introduction

1-bit state indicating whether the participant tutorial/practice sequence is active.

Initial value: 0

Values:

  • 0: Tutorial inactive or disabled; experimental data
  • 1: Tutorial or practice sequence active

When IntroductionMode is 1 or 2, this state becomes 1 at the beginning of the run and returns to 0 when the tutorial completes and the experiment begins.

This is the primary state for separating tutorial/practice samples from experimental samples during offline analysis.

TutorialPhase

4-bit state indicating the current stage of the tutorial.

Initial value: 0

Values:

  • 0: Tutorial inactive
  • 1: General introduction
  • 2: Normal free movement
  • 3: Automatic instructions
  • 4: Automatic practice
  • 5: Controlled instructions
  • 6: Controlled free movement
  • 7: Controlled practice
  • 8: Practice complete

After the final automatic or controlled practice feedback interval, TutorialPhase may remain 4 or 7 while PracticeTrial has returned to 0 and the task waits for the participant to return to center.

Outside the tutorial, TutorialPhase is 0.

The values above describe the Standard introduction. In the Easy introduction, TutorialPhase remains 0 throughout; use EasyIntroPhase to identify the stage.

EasyIntroPhase

4-bit state identifying the current stage of the Easy introduction.

Initial value: 0

Values:

  • 0: Easy introduction inactive
  • 1: Basic demonstration
  • 2: Normal demonstration
  • 3: Normal: now your turn
  • 4: Normal practice
  • 5: Reversed introduction
  • 6: Reversed demonstration
  • 7: Reversed: now your turn
  • 8: Reversed practice
  • 9: Ready

The state is nonzero only while IntroductionMode=2 and Introduction=1. Outside the Easy introduction it is 0. TutorialPhase is 0 during all Easy stages.

PracticeTrial

8-bit state identifying the active practice trial.

Initial value: 0

Values:

  • 0: No active practice trial
  • 1 and above: One-based practice trial number within the current practice condition

The state remains nonzero through the practice trial's feedback phase.

After the final practice feedback interval it returns to 0 while the tutorial may still wait for the participant to return to center.

Resetting a practice trial does not increment PracticeTrial.

Both Standard and Easy practice trials use this state; use TutorialPhase or EasyIntroPhase to determine which practice mode is active.

CursorX

10-bit state representing the current horizontal cursor coordinate.

Initial value: 512

Produced range: 0-1023

The state is updated continuously while the task runs, including during free movement, practice, and experimental trials.

CursorY

10-bit state representing the current vertical cursor coordinate.

Initial value: 512

Produced range: 0-1023

The state is updated continuously while the task runs, including during free movement, practice, and experimental trials.

CursorDiameterPx10

16-bit state containing the runtime cursor diameter in tenths of a reference-display pixel.

Initial value: 160

At the start of a run, the value reflects CursorDiameterPixels. It is updated whenever the researcher changes the Cursor diameter control in the diagnostic window.

To convert to pixels:

cursor diameter (px) = CursorDiameterPx10 / 10

TargetDistancePx10

16-bit state containing the runtime center-to-target distance in tenths of a reference-display pixel.

Initial value: 3000

At the start of a run, the value reflects TargetDistancePixels. It is updated whenever the researcher changes the Target distance control in the diagnostic window.

To convert to pixels:

target distance (px) = TargetDistancePx10 / 10

DisplayGeometryChanged

1-bit event-like state indicating that a runtime display-geometry change was applied.

Initial value: 0

The state is set to 1 for one processing block when a change to the cursor diameter or target distance is applied, and is cleared at the beginning of the following processing block. It does not indicate that target diameter changed, because that parameter is fixed for the run.

TaskPhase

3-bit state containing the current trial phase.

Initial value: 0

Values:

  • 0: Experimental block announcement or non-trial tutorial screen
  • 1: Waiting for center
  • 2: Holding center
  • 3: Warning
  • 4: Pre-target delay
  • 5: Target visible
  • 6: Feedback
  • 7: Finished (the run reached its end normally or through a skip action)

During active practice trials, values 1 through 6 have the same meanings as during experimental trials, including Easy-introduction practice.

During non-trial tutorial screens, TaskPhase is forced to 0. This includes all non-practice Easy stages. Therefore, TaskPhase=0 alone no longer uniquely identifies an experimental block announcement.

Use:

Introduction == 0 and TaskPhase == 0

to identify an experimental block announcement. Within the tutorial, EasyIntroPhase or TutorialPhase identifies the screen type.

TaskCondition

1-bit state identifying the current movement condition.

Initial value: 0

Values:

  • 0: Automatic (participant-facing Normal)
  • 1: Controlled (participant-facing Reversed)

During active practice trials, this state identifies the practice condition.

During the general introduction and normal free-movement tutorial stages, it initially reports 0 even when the configured experiment is Controlled Only. In the Easy introduction it reports 0 through the basic demonstration and normal stages, then reports 1 from the reversed-introduction stage onward.

During the experiment it retains its original meaning.

TaskBlockType

2-bit state identifying the type of the current experimental block.

Initial value: 0

Values:

  • 0: Ordered automatic
  • 1: Ordered controlled
  • 2: Pseudorandom mixed

During the tutorial, this state is forced to 0. It should therefore only be interpreted as an experimental block type when Introduction=0.

TargetAngle

12-bit state containing the target angle in tenths of a degree.

Initial value: 0

During experimental trials, generated values range from 0-3599.

To convert to degrees:

degrees = TargetAngle / 10

During practice trials, the state contains the deterministic practice-target angle.

During non-trial tutorial screens, including Easy demonstration and text screens, the state is set to 0.

After tutorial completion, the saved first experimental target is restored.

TargetX

10-bit state containing the horizontal coordinate of the current target.

Initial value: 512

Coordinate units correspond to the task's 0-through-1023 coordinate system.

During practice trials, it describes the current deterministic practice target.

During non-trial tutorial screens, including Easy demonstration and text screens, the target coordinate is written as 0 rather than retaining its initial value 512; gate it by task phase and tutorial status during analysis.

A runtime change of TargetDistancePixels moves the current target and updates this state without generating a new target angle.

TargetY

10-bit state containing the vertical coordinate of the current target.

Initial value: 512

Coordinate units correspond to the task's 0-through-1023 coordinate system.

During practice trials, it describes the current deterministic practice target.

During non-trial tutorial screens, including Easy demonstration and text screens, the target coordinate is written as 0 rather than retaining its initial value 512; gate it by task phase and tutorial status during analysis.

A runtime change of TargetDistancePixels moves the current target and updates this state without generating a new target angle.

TaskBlock

8-bit state containing the current one-based experimental block number.

Initial value: 0

While Introduction=1:

TaskBlock = 0

When the tutorial completes, the first experimental block begins with:

TaskBlock = 1

Practice trials do not consume experimental block numbers.

TaskTrial

16-bit state containing the current one-based overall experimental trial number.

Initial value: 0

While Introduction=1:

TaskTrial = 0

When the tutorial completes, the first experimental trial begins with:

TaskTrial = 1

Trial numbering continues across experimental block boundaries. Manually resetting an experimental trial does not increment TaskTrial.

Practice trials do not consume experimental trial numbers.

MovementStarted

1-bit state indicating whether movement onset has been detected during the current active practice or experimental trial.

Initial value: 0

The state changes to 1 when joystick displacement exceeds the movement deadzone after target onset. It remains high during the remainder of the movement and feedback period.

A rising transition from 0 to 1 identifies movement onset.

During non-trial tutorial screens, the state is forced to 0.

Use Introduction to distinguish practice movement onset from experimental movement onset.

TargetHit

1-bit event-like state indicating successful target acquisition.

Initial value: 0

The state is set to 1 when the cursor reaches a practice or experimental target and is cleared at the beginning of the following processing block. It therefore acts as a one-processing-block pulse.

Experimental acquisition:

TargetHit == 1 and Introduction == 0

Practice acquisition:

TargetHit == 1 and Introduction == 1

TrialReset

1-bit event-like state indicating a manual trial reset.

Initial value: 0

The state is set to 1 when the experimenter successfully resets a practice or experimental trial and is cleared at the beginning of the following processing block.

Experimental reset:

TrialReset == 1 and Introduction == 0

Practice reset:

TrialReset == 1 and Introduction == 1

TrialSkipped

1-bit event state for the researcher's SKIP TRIAL command during an eligible experimental trial.

Initial value: 0

The state is set to 1 when an experimental trial is skipped and cleared on the following processing block. Skipping advances trial position without counting a successful target acquisition and without increasing completed/reset metrics. The next trial receives a newly generated target, unless the run ends.

ConditionSkipped

1-bit event state for the researcher's SKIP CURRENT BLOCK command.

Initial value: 0

The state is set to 1 for one processing block when the remainder of the current experimental block is skipped. This command advances the overall trial-position counter over the skipped trials, which can change the progress indicator without changing completed-trial counts. The control requires experimenter confirmation.

IntroductionSkipped

1-bit event state for the researcher's SKIP INTRODUCTION command.

Initial value: 0

The state is set to 1 for one processing block when the tutorial is exited before normal completion. The current run proceeds directly to the experimental block-announcement sequence and restores the saved first experimental target. This control requires confirmation.

PracticeSkipped

1-bit event state for the researcher's SKIP PRACTICE command.

Initial value: 0

The state is set to 1 for one processing block when the remaining trials in the current practice condition are bypassed. It identifies incomplete tutorial practice and is distinct from experimental TrialSkipped.

SandboxSkipped

1-bit event state for the researcher's SKIP SANDBOX command.

Initial value: 0

The state is set to 1 for one processing block when a Normal or Reversed free-movement sandbox is bypassed in the Standard introduction, or when the researcher advances past a non-practice Easy stage using SKIP CURRENT EASY PHASE. The tutorial advances to the appropriate next stage.

EasyIntroPrevious

1-bit event state for the researcher's PREVIOUS EASY PHASE command.

Initial value: 0

The state is set to 1 for one processing block when the researcher moves back to the preceding Easy-introduction stage, and is cleared at the beginning of the following processing block. It is recorded only during the Easy introduction.

EasyIntroRestarted

1-bit event state for the researcher's RESTART EASY PHASE command.

Initial value: 0

The state is set to 1 for one processing block when the researcher restarts the current Easy-introduction stage, and is cleared at the beginning of the following processing block. If the restarted stage is a practice block, the block begins again at its first trial.

TaskPaused

1-bit persistent (level) state showing whether the task is paused.

Initial value: 0

  • 0: Task running normally.
  • 1: Task paused; task progression is suspended, while the BCI2000 data stream continues.

Unlike the skip and Easy-phase event states, TaskPaused remains high throughout a pause and returns to 0 on resume. Paused time is excluded from the task's reported timing intervals by shifting the relevant clock references on resume.

ReactionTimeMs

32-bit state containing reaction time in milliseconds.

Initial value: 0

Reaction time is measured from target appearance to detected movement onset.

The state is populated during successful practice and experimental trials.

Practice timing values should be distinguished from experimental values using Introduction.

MovementTimeMs

32-bit state containing movement time in milliseconds.

Initial value: 0

Movement time is measured from detected movement onset to target acquisition.

The state is populated during successful practice and experimental trials.

Practice timing values should be distinguished from experimental values using Introduction.

TotalTimeMs

32-bit state containing total target-directed trial time in milliseconds.

Initial value: 0

Total time is measured from target appearance to target acquisition.

The state is populated during successful practice and experimental trials.

Practice timing values should be distinguished from experimental values using Introduction.

External Joystick States

The application also uses states provided by BCI2000's input logging system. These states are not defined by USBHIDJoystickTask itself.

State Description
JoystickXpos Horizontal joystick position. BCI2000 joystick input logging uses values from 0 through 32767.
JoystickYpos Vertical joystick position. BCI2000 joystick input logging uses values from 0 through 32767.
JoystickButtons1 State of joystick button 1. During the tutorial, a rising press may advance eligible instruction or free-movement screens. In the Easy introduction it can advance an eligible screen when EasyIntroSurgeryMode=0. When EasyIntroRequireButtonPress=1 and surgery mode is off, either this participant input or researcher CONTINUE is required; when it is 0, stages also advance automatically. It does not advance active practice trials and does not control experimental progression.
Running Standard BCI2000 system state. The application sets it to 0 when the run reaches its end, including when a researcher skips the final trial or the remainder of the final block.

For details about enabling joystick recording and the joystick states provided by BCI2000, see Logging Input.

Data Analysis Notes

Because the tutorial and practice sequence are recorded within the same BCI2000 run as the experiment, analyses should use Introduction to distinguish experimental data from tutorial and practice data.

Measurement/Event Recommended identification
Experimental samples Introduction == 0
Tutorial/practice samples Introduction == 1
Experimental trial Introduction == 0 and TaskTrial > 0; check skip events when reconstructing completed trials
Practice trial Introduction == 1 and PracticeTrial > 0; use TutorialPhase or EasyIntroPhase to distinguish Standard from Easy practice
Experimental block announcement Introduction == 0 and TaskPhase == 0
Non-trial tutorial screen Introduction == 1, typically with TaskPhase == 0
Standard-introduction stage Introduction == 1 and TutorialPhase > 0
Easy-introduction stage Introduction == 1 and EasyIntroPhase > 0
Experimental target onset Introduction == 0 and transition from TaskPhase=4 to TaskPhase=5
Practice target onset Introduction == 1, PracticeTrial > 0, and transition from TaskPhase=4 to TaskPhase=5
Experimental movement onset Rising transition of MovementStarted with Introduction == 0
Practice movement onset Rising transition of MovementStarted with Introduction == 1
Experimental target acquisition TargetHit == 1 and Introduction == 0
Practice target acquisition TargetHit == 1 and Introduction == 1
Experimental reset TrialReset == 1 and Introduction == 0
Practice reset TrialReset == 1 and Introduction == 1
Experimental trial number TaskTrial
Practice trial number PracticeTrial
Experimental block number TaskBlock
Automatic vs. controlled TaskCondition, interpreted together with Introduction
Ordered vs. mixed experimental block TaskBlockType when Introduction == 0
Reaction time ReactionTimeMs, gated by Introduction and the relevant trial event
Movement time MovementTimeMs, gated by Introduction and the relevant trial event
Total time TotalTimeMs, gated by Introduction and the relevant trial event
Cursor trajectory CursorX and CursorY
Target coordinates TargetX and TargetY on actual trials; non-trial tutorial screens set these to 0. Interpret together with TargetDistancePx10 when the distance may have been changed at runtime.
Target angle TargetAngle
Skipped experimental trial TrialSkipped == 1
Skipped experimental block remainder ConditionSkipped == 1
Introduction bypassed IntroductionSkipped == 1
Practice bypassed PracticeSkipped == 1
Free-movement sandbox bypassed SandboxSkipped == 1; in the Easy introduction this event also records SKIP CURRENT EASY PHASE
Easy phase moved backward EasyIntroPrevious == 1
Easy phase restarted EasyIntroRestarted == 1
Runtime cursor diameter CursorDiameterPx10 (tenths of a pixel)
Runtime target distance TargetDistancePx10 (tenths of a pixel)
Display-geometry change applied DisplayGeometryChanged == 1
Samples recorded while the task is paused TaskPaused == 1

TargetHit, TrialReset, TrialSkipped, ConditionSkipped, IntroductionSkipped, PracticeSkipped, SandboxSkipped, EasyIntroPrevious, EasyIntroRestarted, and DisplayGeometryChanged are single-processing-block pulses. MovementStarted remains high after movement onset until the trial advances or is reset. TaskPaused is a level state that remains high throughout a pause.

Analyses written for earlier versions of the task should be updated before use with tutorial-enabled data. In particular:

  • TaskPhase=0 no longer always identifies an experimental block announcement.
  • TargetHit=1 may indicate a practice or experimental success.
  • TrialReset=1 may indicate a practice or experimental reset.
  • Nonzero timing states may belong to practice trials.
  • TaskCondition and TaskBlockType should not be interpreted as experimental condition/block variables while Introduction=1.
  • Skip events mark incomplete trials or tutorial stages; skipped experimental trials do not produce TargetHit or increase completed-trial metrics.
  • ConditionSkipped can cause the progress indicator and overall trial-position counter to jump across uncompleted trials.
  • On a skip processing block, non-event states such as TaskTrial, TaskBlock, TaskPhase, and target coordinates may not update until the following block because skip dispatch returns before the normal state synchronization. A skip that finishes the run can leave final values at their pre-skip settings.
  • Samples recorded during TaskPaused=1 remain in the .dat stream. Exclude or flag them as appropriate; RT/MT/total-time values already exclude the pause duration.
  • TargetX and TargetY are 0 during non-trial tutorial screens, not their initial 512 values.
  • In the Easy introduction, TutorialPhase remains 0; use EasyIntroPhase to identify the active stage. A practice stage can therefore be identified from PracticeTrial > 0 together with EasyIntroPhase 4 or 8.
  • PracticeTrial numbering restarts for each practice block and does not indicate whether the block belongs to the Standard or Easy introduction.
  • Runtime changes to the cursor diameter or target distance appear in CursorDiameterPx10 and TargetDistancePx10, with a one-block DisplayGeometryChanged pulse. A target-distance change moves the current target without changing TargetAngle, so target coordinates from before and after the change are not directly comparable in normalized distance terms. A cursor-diameter change also alters the effective target-acquisition tolerance because the cursor radius contributes to the hit ellipse.
  • EasyIntroPrevious and EasyIntroRestarted record researcher navigation within the Easy introduction; they are not participant events and do not indicate skipped trials.
  • Condition names printed on screen and in console messages are Normal/Reversed, but the numeric TaskCondition codes remain Automatic=0 and Controlled=1.
  • No application-specific CSV is created in the current version; reconstruct trial-level results from synchronized BCI2000 state recordings.

References

Neumann WJ, Schroll H, de Almeida Marcelino AL, Horn A, Ewert S, Irmen F, Krause P, Schneider GH, Hamker F, Kühn AA. Functional segregation of basal ganglia pathways in Parkinson's disease. Brain. 2018;141(9):2655-2669. doi:10.1093/brain/awy206.

See also