BCI2000 Wiki - User contributions [en]

VisuomotorJoystickTask

2026-09-08T14:56:13Z

Aes2376: /* Video Overview */

==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, joystick and cursor movements are congruent. In the '''controlled''' condition, joystick-to-cursor movement is inverted after the target appears.

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

==Location==

The source code for the Visuomotor Joystick Task is located in the BCI2000 private application directory:

http://{{SERVERNAME}}/svn/trunk/src/private/Application/VisuomotorJoystickTask

The main application implementation is contained in:

<code>USBHIDJoystickTask.cpp</code>

with the corresponding header and build configuration in:

* <code>USBHIDJoystickTask.h</code>
* <code>CMakeLists.txt</code>

==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 tutorial and practice sequence.
* Automatic and controlled practice trials.
* Free-movement demonstrations of normal and reversed cursor control.
* Joystick-button and experimenter-controlled tutorial progression.
* 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, and trial events.
* A separate diagnostic window with trial information, tutorial controls, and manual trial reset.
* Trial-level reaction time, movement time, and total time measurements.
* Separation of tutorial/practice data from experimental trial numbering, experimental CSV output, and run-summary metrics.

The files inspected in the current development checkout are located under <code>src/custom</code> and are not associated with SVN history in that checkout. Revision-specific history should therefore be updated once the contribution is placed in its final version-controlled location.

===Source Code Revisions===

* Initial development: '''8/26/26'''
* Tested under: 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
* Current source revision: '''9/1/26'''
* Broken since: No known breaking revision

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

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|References]] for the original study.

===Experiment Structure===

Four experiment modes are available:

{| class="wikitable"
! 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. <code>OrderedStartCondition</code> 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 tutorial is enabled, its content depends on <code>ExperimentMode</code>:

{| class="wikitable"
! 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 tutorial always presents automatic training before controlled training. <code>OrderedStartCondition</code> affects the experimental block order but does not change the tutorial order.

===Tutorial and Practice Sequence===

When <code>EnableIntroduction=1</code>, the tutorial begins at the start of each run before the first experimental block.

The tutorial consists of the following stages:

{| class="wikitable"
! 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
| Automatic instructions
| Explanation of the automatic condition and green targets
|-
| 4
| Automatic practice
| Automatic practice trials using the normal mapping
|-
| 5
| Controlled instructions
| Explanation of the controlled condition and red targets
|-
| 6
| Controlled free movement
| Participant explores continuous reversed joystick-to-cursor control
|-
| 7
| Controlled practice
| Controlled practice trials using the inverted mapping
|-
| 8
| Complete
| Practice-complete summary before the experiment begins
|}

When <code>EnableIntroduction=0</code>, the tutorial is skipped and the task begins with the original experimental block-announcement sequence.

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

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.

===Normal Free Movement===

During the 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'''.

===Automatic Practice===

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

# Waiting for center
# Holding center
# Warning
# Pre-target delay
# Target visible
# Feedback

Practice trials differ from experimental trials in several ways:

* Center hold is determined by <code>PracticeCenterHoldTime</code> rather than <code>CenterHoldSeconds</code>.
* Practice targets follow a deterministic sequence.
* <code>TaskBlock</code> and <code>TaskTrial</code> remain 0.
* <code>PracticeTrial</code> identifies the active practice trial.
* No trial row is written to the secondary 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.

===Controlled Free Movement===

The controlled free-movement stage 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.

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

Controlled practice uses <code>PracticeCenterHoldTime</code> and deterministic practice targets and remains separate from experimental numbering, CSV output, and performance summaries.

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 completion screen summarizes the condition mappings:

* Automatic: cursor movement follows joystick movement.
* 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.

===Experimental Trial Sequence===

Each experimental block begins with a 1.5-second announcement indicating whether the upcoming block is '''Automatic''', '''Controlled''', or '''Mixed'''.

A trial then proceeds as follows:

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

A new target is generated when advancing to a new experimental trial. Manually resetting a trial does not generate a new target.

===Automatic Condition===

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

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:

<pre>
cursor position = anchor cursor position - joystick displacement
</pre>

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 [[User Reference:Logging Input|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:

* <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>
angle in degrees = TargetAngle / 10
</pre>

This produces target angles from 0.0 through 359.9 degrees.

Targets are positioned at a fixed distance from the center 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.

===Practice Target Generation===

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

{| class="wikitable"
! 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:

<pre>
75°, 105°, 135°, 165°, 15°, 45°
</pre>

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.

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"
! 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, <code>TaskPhase</code> 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
| 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.

Because non-trial tutorial screens use <code>TaskPhase=0</code>, analysts should use <code>Introduction</code> to distinguish tutorial screens from experimental block announcements.

An experimental target onset is identified by:

<pre>
Introduction == 0
and TaskPhase transitions from 4 to 5
</pre>

A practice target onset is identified by:

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

===Condition and Block Encodings===

{| class="wikitable"
! State/Parameter
! Value
! Meaning
|-
| <code>TaskCondition</code>
| 0
| Automatic
|-
| <code>TaskCondition</code>
| 1
| Controlled
|-
| <code>TaskBlockType</code>
| 0
| Ordered automatic block
|-
| <code>TaskBlockType</code>
| 1
| Ordered controlled block
|-
| <code>TaskBlockType</code>
| 2
| Pseudorandom mixed block
|-
| <code>OrderedStartCondition</code>
| 0
| Automatic first
|-
| <code>OrderedStartCondition</code>
| 1
| Controlled first
|}

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 the tutorial, <code>TaskBlockType</code> is forced to 0 and should not be interpreted as an experimental ordered-automatic block.

===Participant Display===

The participant-facing [[Programming Reference:ApplicationWindow Class|ApplicationWindow]] contains:

* A light gray background.
* A black cursor.
* A black central fixation cross.
* A gray center marker.
* A larger yellow warning marker.
* A green target during automatic trials.
* A red target during controlled trials.
* A progress bar near the top of the display during the experiment.
* Tutorial and practice instructions when the introduction is enabled.
* Block announcements.
* 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.

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

===Diagnostic Window===

A separate diagnostic window is shown to the experimenter.

During the tutorial, it displays information including:

* Tutorial mode.
* Numeric and textual tutorial phase.
* Tutorial condition.
* Practice trial number.
* Experimental trial as not yet started.
* Joystick coordinates.
* Cursor coordinates.
* Target angle.
* Movement status.
* <code>Introduction</code> state.
* Tutorial status.

During the experiment, it displays information including:

* Current condition and task phase.
* Current block and block type.
* Overall and condition-specific trial numbers.
* Target angle and coordinates.
* Raw joystick states and converted task coordinates.
* Cursor coordinates.
* Movement status.
* Reaction time, movement time, and total time.
* Completed-trial and reset counts.
* Mean timing measurements for automatic, controlled, and overall performance.

The diagnostic window contains a blue '''CONTINUE''' button for tutorial screens that require continuation.

It also contains a reset button whose function changes according to task context:

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

===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 <code>TrialReset</code> event.
* Increments the experimental diagnostic reset count.
* Keeps the same trial number.
* Keeps the same target.
* Does not write a completed-trial row to the secondary CSV file.

Practice trials may also be reset before feedback.

Resetting a practice trial:

* 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 write a CSV row.

Reset is unavailable during tutorial instruction/free-movement screens and after a trial has entered feedback.

===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 <code>Process()</code>. 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 and the secondary CSV output.

===Data Recording===

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

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

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.

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 <code>TaskTrial</code> numbering.
* Experimental <code>TaskBlock</code> numbering.
* Secondary CSV rows.
* Automatic and controlled completion counts.
* Automatic and controlled reset counts.
* Mean reaction-time summaries.
* Mean movement-time summaries.
* Mean total-time summaries.

The current implementation additionally writes a secondary CSV file containing one row for each successfully completed experimental trial:

<pre>
trial,block,block_type,condition,reaction_time_ms,movement_time_ms,total_time_ms,success
</pre>

Reset trials and practice trials do not generate CSV rows.

==Parameters==

===EnableIntroduction===

Enables or disables the participant tutorial and practice sequence.

Type: integer boolean

Default: <code>1</code>

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

Values:

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

This parameter applies to all experiment modes.

===AutomaticPracticeTrials===

Number of automatic practice trials presented during the tutorial.

Type: integer

Default: <code>3</code>

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

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.

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

===ControlledPracticeTrials===

Number of controlled practice trials presented during the tutorial.

Type: integer

Default: <code>3</code>

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

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.

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

===PracticeCenterHoldTime===

Center-hold duration used during automatic and controlled practice trials.

Type: floating-point time

Default: <code>1s</code>

Range: <code>0s-60s</code>

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

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

===ExperimentMode===

Selects the overall experimental structure.

Type: integer enumeration

Default: <code>1</code>

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

Values:

* <code>1</code>: Automatic only
* <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.

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

===AutomaticTrials===

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

Type: integer

Default: <code>5</code>

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

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: <code>5</code>

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

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: <code>0</code>

Values:

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

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

It also does not affect tutorial order. When both conditions are included, the tutorial always presents automatic training before controlled training.

===OrderedAutomaticTrials===

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

Type: integer

Default: <code>5</code>

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

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: <code>5</code>

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

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: <code>5</code>

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

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: <code>5</code>

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

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: <code>0</code>

Values:

* <code>0</code>: Use the normal/default ApplicationWindow placement.
* <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.

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: <code>3.0</code> seconds

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

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

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

===WarningSeconds===

Duration of the yellow warning cue.

Type: floating point

Default: <code>0.5</code> seconds

Range: <code>0.0-60.0</code> 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: <code>0.5</code> seconds

Range: <code>0.0-60.0</code> 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: <code>0.5</code> seconds

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

This parameter applies to both practice and experimental trials.

===ResultsFile===

Specifies the file used for the secondary experimental trial-level CSV output.

Type: string

Default:

<code>block_visuomotor_results_usb_hid.csv</code>

The file is opened when the application initializes and is overwritten if a file with the same name already exists. Initialization fails if the file cannot be created.

Only successful experimental trials are written to this file. Practice trials are not written to the CSV.

==States==

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

===Introduction===

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

Initial value: <code>0</code>

Values:

* <code>0</code>: Tutorial inactive or disabled; experimental data
* <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.

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: <code>0</code>

Values:

* <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

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.

===PracticeTrial===

8-bit state identifying the active practice trial.

Initial value: <code>0</code>

Values:

* <code>0</code>: No active practice trial
* <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.

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 <code>PracticeTrial</code>.

===CursorX===

10-bit state representing the current horizontal cursor coordinate.

Initial value: <code>512</code>

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

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: <code>512</code>

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

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

===TaskPhase===

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

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

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.

Use:

<pre>
Introduction == 0 and TaskPhase == 0
</pre>

to identify an experimental block announcement.

===TaskCondition===

1-bit state identifying the current movement condition.

Initial value: <code>0</code>

Values:

* <code>0</code>: Automatic
* <code>1</code>: Controlled

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.

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, 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, target states are suppressed.

===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, target states are suppressed.

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

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

===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>
|-
| Practice trial
| <code>Introduction == 1</code> and <code>PracticeTrial > 0</code>
|-
| 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>
|-
| 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>
|-
| Reaction time
| <code>ReactionTimeMs</code>, gated by <code>Introduction</code> and the relevant trial event
|-
| Movement time
| <code>MovementTimeMs</code>, gated by <code>Introduction</code> and the relevant trial event
|-
| Total time
| <code>TotalTimeMs</code>, gated by <code>Introduction</code> and the relevant trial event
|-
| Cursor trajectory
| <code>CursorX</code> and <code>CursorY</code>
|-
| Target coordinates
| <code>TargetX</code> and <code>TargetY</code>
|-
| Target angle
| <code>TargetAngle</code>
|}

<code>TargetHit</code> and <code>TrialReset</code> are single-processing-block pulses. <code>MovementStarted</code>, in contrast, remains high after movement onset until the trial advances or is reset.

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

* <code>TaskPhase=0</code> no longer always identifies an experimental block announcement.
* <code>TargetHit=1</code> may indicate a practice or experimental success.
* <code>TrialReset=1</code> may indicate a practice or experimental reset.
* Nonzero timing states may belong to practice trials.
* <code>TaskCondition</code> and <code>TaskBlockType</code> should not be interpreted as experimental condition/block variables while <code>Introduction=1</code>.

==References==

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

==See also==

* [[User Reference:Logging Input|Logging Input]]
* [[User Reference:Logging Input#LogJoystick|LogJoystick]]
* [[User Reference:Module Command Line Options|Module Command Line Options]]
* [[Programming Reference:ApplicationWindow Class|ApplicationWindow Class]]
* [[Technical Reference:BCI2000 File Format|BCI2000 File Format]]
* [[Programming Reference:ApplicationBase Class|ApplicationBase Class]]

VisuomotorJoystickTask

2026-09-08T14:54:56Z

Aes2376:

==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, joystick and cursor movements are congruent. In the '''controlled''' condition, joystick-to-cursor movement is inverted after the target appears.

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 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: <youtube alignment="center">https://www.youtube.com/watch?v=LSZW3nxg3Vg</youtube>

==Location==

The source code for the Visuomotor Joystick Task is located in the BCI2000 private application directory:

http://{{SERVERNAME}}/svn/trunk/src/private/Application/VisuomotorJoystickTask

The main application implementation is contained in:

<code>USBHIDJoystickTask.cpp</code>

with the corresponding header and build configuration in:

* <code>USBHIDJoystickTask.h</code>
* <code>CMakeLists.txt</code>

==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 tutorial and practice sequence.
* Automatic and controlled practice trials.
* Free-movement demonstrations of normal and reversed cursor control.
* Joystick-button and experimenter-controlled tutorial progression.
* 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, and trial events.
* A separate diagnostic window with trial information, tutorial controls, and manual trial reset.
* Trial-level reaction time, movement time, and total time measurements.
* Separation of tutorial/practice data from experimental trial numbering, experimental CSV output, and run-summary metrics.

The files inspected in the current development checkout are located under <code>src/custom</code> and are not associated with SVN history in that checkout. Revision-specific history should therefore be updated once the contribution is placed in its final version-controlled location.

===Source Code Revisions===

* Initial development: '''8/26/26'''
* Tested under: 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
* Current source revision: '''9/1/26'''
* Broken since: No known breaking revision

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

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|References]] for the original study.

===Experiment Structure===

Four experiment modes are available:

{| class="wikitable"
! 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. <code>OrderedStartCondition</code> 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 tutorial is enabled, its content depends on <code>ExperimentMode</code>:

{| class="wikitable"
! 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 tutorial always presents automatic training before controlled training. <code>OrderedStartCondition</code> affects the experimental block order but does not change the tutorial order.

===Tutorial and Practice Sequence===

When <code>EnableIntroduction=1</code>, the tutorial begins at the start of each run before the first experimental block.

The tutorial consists of the following stages:

{| class="wikitable"
! 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
| Automatic instructions
| Explanation of the automatic condition and green targets
|-
| 4
| Automatic practice
| Automatic practice trials using the normal mapping
|-
| 5
| Controlled instructions
| Explanation of the controlled condition and red targets
|-
| 6
| Controlled free movement
| Participant explores continuous reversed joystick-to-cursor control
|-
| 7
| Controlled practice
| Controlled practice trials using the inverted mapping
|-
| 8
| Complete
| Practice-complete summary before the experiment begins
|}

When <code>EnableIntroduction=0</code>, the tutorial is skipped and the task begins with the original experimental block-announcement sequence.

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

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.

===Normal Free Movement===

During the 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'''.

===Automatic Practice===

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

# Waiting for center
# Holding center
# Warning
# Pre-target delay
# Target visible
# Feedback

Practice trials differ from experimental trials in several ways:

* Center hold is determined by <code>PracticeCenterHoldTime</code> rather than <code>CenterHoldSeconds</code>.
* Practice targets follow a deterministic sequence.
* <code>TaskBlock</code> and <code>TaskTrial</code> remain 0.
* <code>PracticeTrial</code> identifies the active practice trial.
* No trial row is written to the secondary 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.

===Controlled Free Movement===

The controlled free-movement stage 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.

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

Controlled practice uses <code>PracticeCenterHoldTime</code> and deterministic practice targets and remains separate from experimental numbering, CSV output, and performance summaries.

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 completion screen summarizes the condition mappings:

* Automatic: cursor movement follows joystick movement.
* 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.

===Experimental Trial Sequence===

Each experimental block begins with a 1.5-second announcement indicating whether the upcoming block is '''Automatic''', '''Controlled''', or '''Mixed'''.

A trial then proceeds as follows:

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

A new target is generated when advancing to a new experimental trial. Manually resetting a trial does not generate a new target.

===Automatic Condition===

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

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:

<pre>
cursor position = anchor cursor position - joystick displacement
</pre>

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 [[User Reference:Logging Input|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:

* <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>
angle in degrees = TargetAngle / 10
</pre>

This produces target angles from 0.0 through 359.9 degrees.

Targets are positioned at a fixed distance from the center 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.

===Practice Target Generation===

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

{| class="wikitable"
! 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:

<pre>
75°, 105°, 135°, 165°, 15°, 45°
</pre>

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.

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"
! 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, <code>TaskPhase</code> 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
| 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.

Because non-trial tutorial screens use <code>TaskPhase=0</code>, analysts should use <code>Introduction</code> to distinguish tutorial screens from experimental block announcements.

An experimental target onset is identified by:

<pre>
Introduction == 0
and TaskPhase transitions from 4 to 5
</pre>

A practice target onset is identified by:

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

===Condition and Block Encodings===

{| class="wikitable"
! State/Parameter
! Value
! Meaning
|-
| <code>TaskCondition</code>
| 0
| Automatic
|-
| <code>TaskCondition</code>
| 1
| Controlled
|-
| <code>TaskBlockType</code>
| 0
| Ordered automatic block
|-
| <code>TaskBlockType</code>
| 1
| Ordered controlled block
|-
| <code>TaskBlockType</code>
| 2
| Pseudorandom mixed block
|-
| <code>OrderedStartCondition</code>
| 0
| Automatic first
|-
| <code>OrderedStartCondition</code>
| 1
| Controlled first
|}

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 the tutorial, <code>TaskBlockType</code> is forced to 0 and should not be interpreted as an experimental ordered-automatic block.

===Participant Display===

The participant-facing [[Programming Reference:ApplicationWindow Class|ApplicationWindow]] contains:

* A light gray background.
* A black cursor.
* A black central fixation cross.
* A gray center marker.
* A larger yellow warning marker.
* A green target during automatic trials.
* A red target during controlled trials.
* A progress bar near the top of the display during the experiment.
* Tutorial and practice instructions when the introduction is enabled.
* Block announcements.
* 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.

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

===Diagnostic Window===

A separate diagnostic window is shown to the experimenter.

During the tutorial, it displays information including:

* Tutorial mode.
* Numeric and textual tutorial phase.
* Tutorial condition.
* Practice trial number.
* Experimental trial as not yet started.
* Joystick coordinates.
* Cursor coordinates.
* Target angle.
* Movement status.
* <code>Introduction</code> state.
* Tutorial status.

During the experiment, it displays information including:

* Current condition and task phase.
* Current block and block type.
* Overall and condition-specific trial numbers.
* Target angle and coordinates.
* Raw joystick states and converted task coordinates.
* Cursor coordinates.
* Movement status.
* Reaction time, movement time, and total time.
* Completed-trial and reset counts.
* Mean timing measurements for automatic, controlled, and overall performance.

The diagnostic window contains a blue '''CONTINUE''' button for tutorial screens that require continuation.

It also contains a reset button whose function changes according to task context:

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

===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 <code>TrialReset</code> event.
* Increments the experimental diagnostic reset count.
* Keeps the same trial number.
* Keeps the same target.
* Does not write a completed-trial row to the secondary CSV file.

Practice trials may also be reset before feedback.

Resetting a practice trial:

* 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 write a CSV row.

Reset is unavailable during tutorial instruction/free-movement screens and after a trial has entered feedback.

===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 <code>Process()</code>. 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 and the secondary CSV output.

===Data Recording===

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

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

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.

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 <code>TaskTrial</code> numbering.
* Experimental <code>TaskBlock</code> numbering.
* Secondary CSV rows.
* Automatic and controlled completion counts.
* Automatic and controlled reset counts.
* Mean reaction-time summaries.
* Mean movement-time summaries.
* Mean total-time summaries.

The current implementation additionally writes a secondary CSV file containing one row for each successfully completed experimental trial:

<pre>
trial,block,block_type,condition,reaction_time_ms,movement_time_ms,total_time_ms,success
</pre>

Reset trials and practice trials do not generate CSV rows.

==Parameters==

===EnableIntroduction===

Enables or disables the participant tutorial and practice sequence.

Type: integer boolean

Default: <code>1</code>

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

Values:

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

This parameter applies to all experiment modes.

===AutomaticPracticeTrials===

Number of automatic practice trials presented during the tutorial.

Type: integer

Default: <code>3</code>

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

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.

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

===ControlledPracticeTrials===

Number of controlled practice trials presented during the tutorial.

Type: integer

Default: <code>3</code>

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

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.

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

===PracticeCenterHoldTime===

Center-hold duration used during automatic and controlled practice trials.

Type: floating-point time

Default: <code>1s</code>

Range: <code>0s-60s</code>

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

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

===ExperimentMode===

Selects the overall experimental structure.

Type: integer enumeration

Default: <code>1</code>

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

Values:

* <code>1</code>: Automatic only
* <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.

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

===AutomaticTrials===

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

Type: integer

Default: <code>5</code>

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

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: <code>5</code>

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

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: <code>0</code>

Values:

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

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

It also does not affect tutorial order. When both conditions are included, the tutorial always presents automatic training before controlled training.

===OrderedAutomaticTrials===

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

Type: integer

Default: <code>5</code>

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

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: <code>5</code>

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

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: <code>5</code>

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

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: <code>5</code>

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

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: <code>0</code>

Values:

* <code>0</code>: Use the normal/default ApplicationWindow placement.
* <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.

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: <code>3.0</code> seconds

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

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

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

===WarningSeconds===

Duration of the yellow warning cue.

Type: floating point

Default: <code>0.5</code> seconds

Range: <code>0.0-60.0</code> 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: <code>0.5</code> seconds

Range: <code>0.0-60.0</code> 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: <code>0.5</code> seconds

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

This parameter applies to both practice and experimental trials.

===ResultsFile===

Specifies the file used for the secondary experimental trial-level CSV output.

Type: string

Default:

<code>block_visuomotor_results_usb_hid.csv</code>

The file is opened when the application initializes and is overwritten if a file with the same name already exists. Initialization fails if the file cannot be created.

Only successful experimental trials are written to this file. Practice trials are not written to the CSV.

==States==

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

===Introduction===

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

Initial value: <code>0</code>

Values:

* <code>0</code>: Tutorial inactive or disabled; experimental data
* <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.

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: <code>0</code>

Values:

* <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

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.

===PracticeTrial===

8-bit state identifying the active practice trial.

Initial value: <code>0</code>

Values:

* <code>0</code>: No active practice trial
* <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.

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 <code>PracticeTrial</code>.

===CursorX===

10-bit state representing the current horizontal cursor coordinate.

Initial value: <code>512</code>

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

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: <code>512</code>

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

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

===TaskPhase===

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

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

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.

Use:

<pre>
Introduction == 0 and TaskPhase == 0
</pre>

to identify an experimental block announcement.

===TaskCondition===

1-bit state identifying the current movement condition.

Initial value: <code>0</code>

Values:

* <code>0</code>: Automatic
* <code>1</code>: Controlled

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.

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, 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, target states are suppressed.

===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, target states are suppressed.

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

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

===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>
|-
| Practice trial
| <code>Introduction == 1</code> and <code>PracticeTrial > 0</code>
|-
| 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>
|-
| 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>
|-
| Reaction time
| <code>ReactionTimeMs</code>, gated by <code>Introduction</code> and the relevant trial event
|-
| Movement time
| <code>MovementTimeMs</code>, gated by <code>Introduction</code> and the relevant trial event
|-
| Total time
| <code>TotalTimeMs</code>, gated by <code>Introduction</code> and the relevant trial event
|-
| Cursor trajectory
| <code>CursorX</code> and <code>CursorY</code>
|-
| Target coordinates
| <code>TargetX</code> and <code>TargetY</code>
|-
| Target angle
| <code>TargetAngle</code>
|}

<code>TargetHit</code> and <code>TrialReset</code> are single-processing-block pulses. <code>MovementStarted</code>, in contrast, remains high after movement onset until the trial advances or is reset.

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

* <code>TaskPhase=0</code> no longer always identifies an experimental block announcement.
* <code>TargetHit=1</code> may indicate a practice or experimental success.
* <code>TrialReset=1</code> may indicate a practice or experimental reset.
* Nonzero timing states may belong to practice trials.
* <code>TaskCondition</code> and <code>TaskBlockType</code> should not be interpreted as experimental condition/block variables while <code>Introduction=1</code>.

==References==

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

==See also==

* [[User Reference:Logging Input|Logging Input]]
* [[User Reference:Logging Input#LogJoystick|LogJoystick]]
* [[User Reference:Module Command Line Options|Module Command Line Options]]
* [[Programming Reference:ApplicationWindow Class|ApplicationWindow Class]]
* [[Technical Reference:BCI2000 File Format|BCI2000 File Format]]
* [[Programming Reference:ApplicationBase Class|ApplicationBase Class]]

VisuomotorJoystickTask

2026-09-02T19:26:33Z

Aes2376:

VisuomotorJoystickTask

2026-09-01T22:50:55Z

Aes2376:

VisuomotorJoystickTask

2026-09-01T17:04:33Z

Aes2376: /* Scientific Basis */

VisuomotorJoystickTask

2026-09-01T17:01:53Z

Aes2376: /* Author */

VisuomotorJoystickTask

2026-09-01T17:01:36Z

Aes2376: /* Source Code Revisions */

VisuomotorJoystickTask

2026-09-01T17:00:40Z

Aes2376: /* Location */

VisuomotorJoystickTask

2026-09-01T16:59:01Z

Aes2376: /* Location */

VisuomotorJoystickTask

2026-09-01T16:51:28Z

Aes2376: /* Location */

VisuomotorJoystickTask

2026-09-01T16:50:33Z

Aes2376:

VisuomotorJoystickTask

2026-09-01T16:49:27Z

Aes2376: Init