Jump to content

VisuomotorJoystickTask

From BCI2000 Wiki

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:

Load video
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://www.bci2000.org/svn/trunk/src/private/Application/VisuomotorJoystickTask

The main application implementation is contained in:

USBHIDJoystickTask.cpp

with the corresponding header and build configuration in:

  • USBHIDJoystickTask.h
  • CMakeLists.txt

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 src/custom 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 for the original study.

Experiment Structure

Four experiment modes are available:

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

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

When the tutorial is enabled, its content depends on ExperimentMode:

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

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

Tutorial and Practice Sequence

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

The tutorial consists of the following stages:

TutorialPhase Stage Description
0 None Tutorial inactive; normal experiment operation
1 Introduction General explanation of the task and upcoming conditions
2 Normal free movement Participant explores normal direct joystick-to-cursor movement
3 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 EnableIntroduction=0, 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:

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

Practice trials differ from experimental trials in several ways:

  • Center hold is determined by PracticeCenterHoldTime rather than CenterHoldSeconds.
  • Practice targets follow a deterministic sequence.
  • TaskBlock and TaskTrial remain 0.
  • PracticeTrial 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 PracticeCenterHoldTime 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, Introduction returns to 0, the originally generated first experimental target is restored, and the experiment begins with the normal 1.5-second block announcement.

Experimental Trial Sequence

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

A trial then proceeds as follows:

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

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

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

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: 

cursor position = anchor cursor position - joystick displacement

The cursor is constrained to the participant display.

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

Controlled targets are displayed in red.

Joystick Input

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

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

The application reads:

  • JoystickXpos
  • JoystickYpos
  • JoystickButtons1

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

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

Experimental Target Generation

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

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

angle in degrees = TargetAngle / 10

This produces target angles from 0.0 through 359.9 degrees.

Targets are positioned at a 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:

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

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

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

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

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

These targets are positioned in the lower half of the participant display to reduce overlap with tutorial text.

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

Trial Phases

The current trial phase is recorded in TaskPhase.

Value Phase Description
0 Block announcement / no active practice trial During the experiment, the upcoming block type is being displayed. During non-trial tutorial screens, TaskPhase is also 0.
1 Waiting for center The task is waiting for the cursor to enter the center region.
2 Holding center The participant is completing the required center hold.
3 Warning The yellow warning cue is visible.
4 Pre-target delay The warning has ended and the task is waiting for target onset.
5 Target visible The peripheral target is visible and movement may occur.
6 Feedback The target has been acquired and the task is waiting before advancing.
7 Finished 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 TaskPhase=0, analysts should use Introduction to distinguish tutorial screens from experimental block announcements.

An experimental target onset is identified by: 

Introduction == 0
and TaskPhase transitions from 4 to 5

A practice target onset is identified by: 

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

Condition and Block Encodings

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

During the tutorial, TaskCondition reflects the tutorial condition rather than the first experimental condition. 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, TaskBlockType is forced to 0 and should not be interpreted as an experimental ordered-automatic block.

Participant Display

The participant-facing 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 StimulusDisplay 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.
  • Introduction 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 TrialReset 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 TrialReset event.
  • Keeps the same PracticeTrial 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 Process(). The effective temporal resolution is therefore limited by the BCI2000 processing-block interval.

Practice timing values are recorded in the BCI2000 states but are excluded from experimental timing summaries 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 .dat recording.

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

Tutorial and practice samples are part of the same BCI2000 run as the experiment. The Introduction state should therefore be used when separating tutorial/practice data from experimental data during offline analysis.

Practice trials record:

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

Practice trials are intentionally excluded from:

  • Experimental TaskTrial numbering.
  • Experimental TaskBlock numbering.
  • 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: 

trial,block,block_type,condition,reaction_time_ms,movement_time_ms,total_time_ms,success

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

Range: 0-1

Values:

  • 0: Skip the tutorial and begin the experiment normally.
  • 1: 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: 3

Range: 0-20

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

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

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

ControlledPracticeTrials

Number of controlled practice trials presented during the tutorial.

Type: integer

Default: 3

Range: 0-20

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

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

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: 1s

Range: 0s-60s

This parameter replaces CenterHoldSeconds during practice trials only.

Experimental trials continue to use CenterHoldSeconds.

ExperimentMode

Selects the overall experimental structure.

Type: integer enumeration

Default: 1

Range: 1-4

Values:

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

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

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

AutomaticTrials

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

Type: integer

Default: 5

Declared range: 0-10000

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

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

ControlledTrials

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

Type: integer

Default: 5

Declared range: 0-10000

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

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

OrderedStartCondition

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

Type: integer enumeration

Default: 0

Values:

  • 0: Automatic first
  • 1: Controlled first

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

It also does not affect tutorial order. 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: 5

Declared range: 0-10000

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

OrderedControlledTrials

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

Type: integer

Default: 5

Declared range: 0-10000

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

RandomAutomaticTrials

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

Type: integer

Default: 5

Declared range: 0-10000

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

RandomControlledTrials

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

Type: integer

Default: 5

Declared range: 0-10000

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

StimulusDisplay

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

Type: integer enumeration

Default: 0

Values:

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

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

The application verifies during preflight that the selected display exists.

CenterHoldSeconds

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

Type: floating point

Default: 3.0 seconds

Range: 0.0-60.0 seconds

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

This parameter does not control practice center-hold duration. Practice trials use PracticeCenterHoldTime.

WarningSeconds

Duration of the yellow warning cue.

Type: floating point

Default: 0.5 seconds

Range: 0.0-60.0 seconds

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

This parameter applies to both practice and experimental trials.

PreTargetDelaySeconds

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

Type: floating point

Default: 0.5 seconds

Range: 0.0-60.0 seconds

The participant must remain centered during this interval.

This parameter applies to both practice and experimental trials.

FeedbackSeconds

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

Type: floating point

Default: 0.5 seconds

Range: 0.0-60.0 seconds

This parameter applies to both practice and experimental trials.

ResultsFile

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

Type: string

Default:

block_visuomotor_results_usb_hid.csv

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 USBHIDJoystickTask and are recorded with the normal BCI2000 data stream.

Introduction

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

Initial value: 0

Values:

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

When EnableIntroduction=1, this state becomes 1 at the beginning of the run and returns to 0 when the tutorial completes and the experiment begins.

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

TutorialPhase

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

Initial value: 0

Values:

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

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

Outside the tutorial, TutorialPhase is 0.

PracticeTrial

8-bit state identifying the active practice trial.

Initial value: 0

Values:

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

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

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

Resetting a practice trial does not increment PracticeTrial.

CursorX

10-bit state representing the current horizontal cursor coordinate.

Initial value: 512

Produced range: 0-1023

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

CursorY

10-bit state representing the current vertical cursor coordinate.

Initial value: 512

Produced range: 0-1023

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

TaskPhase

3-bit state containing the current trial phase.

Initial value: 0

Values:

  • 0: Experimental block announcement or non-trial tutorial screen
  • 1: Waiting for center
  • 2: Holding center
  • 3: Warning
  • 4: Pre-target delay
  • 5: Target visible
  • 6: Feedback
  • 7: Finished

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

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

Use: 

Introduction == 0 and TaskPhase == 0

to identify an experimental block announcement.

TaskCondition

1-bit state identifying the current movement condition.

Initial value: 0

Values:

  • 0: Automatic
  • 1: 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: 0

Values:

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

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

TargetAngle

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

Initial value: 0

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

To convert to degrees: 

degrees = TargetAngle / 10

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

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

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

TargetX

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

Initial value: 512

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

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

During non-trial tutorial screens, target states are suppressed.

TargetY

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

Initial value: 512

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

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

During non-trial tutorial screens, target states are suppressed.

TaskBlock

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

Initial value: 0

While Introduction=1: 

TaskBlock = 0

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

TaskBlock = 1

Practice trials do not consume experimental block numbers.

TaskTrial

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

Initial value: 0

While Introduction=1: 

TaskTrial = 0

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

TaskTrial = 1

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

Practice trials do not consume experimental trial numbers.

MovementStarted

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

Initial value: 0

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

A rising transition from 0 to 1 identifies movement onset.

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

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

TargetHit

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

Initial value: 0

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

Experimental acquisition: 

TargetHit == 1 and Introduction == 0

Practice acquisition: 

TargetHit == 1 and Introduction == 1

TrialReset

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

Initial value: 0

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

Experimental reset: 

TrialReset == 1 and Introduction == 0

Practice reset: 

TrialReset == 1 and Introduction == 1

ReactionTimeMs

32-bit state containing reaction time in milliseconds.

Initial value: 0

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

The state is populated during successful practice and experimental trials.

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

MovementTimeMs

32-bit state containing movement time in milliseconds.

Initial value: 0

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

The state is populated during successful practice and experimental trials.

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

TotalTimeMs

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

Initial value: 0

Total time is measured from target appearance to target acquisition.

The state is populated during successful practice and experimental trials.

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

External Joystick States

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

State Description
JoystickXpos Horizontal joystick position. BCI2000 joystick input logging uses values from 0 through 32767.
JoystickYpos Vertical joystick position. BCI2000 joystick input logging uses values from 0 through 32767.
JoystickButtons1 State of joystick button 1. During the tutorial, a rising press may advance eligible instruction or free-movement screens. It does not advance active practice trials and does not control experimental progression.
Running Standard BCI2000 system state. The application sets it to 0 when all configured experimental trials have been completed.

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

Data Analysis Notes

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

Measurement/Event Recommended identification
Experimental samples Introduction == 0
Tutorial/practice samples Introduction == 1
Experimental trial Introduction == 0 and TaskTrial > 0
Practice trial Introduction == 1 and PracticeTrial > 0
Experimental block announcement Introduction == 0 and TaskPhase == 0
Non-trial tutorial screen Introduction == 1, typically with TaskPhase == 0
Experimental target onset Introduction == 0 and transition from TaskPhase=4 to TaskPhase=5
Practice target onset Introduction == 1, PracticeTrial > 0, and transition from TaskPhase=4 to TaskPhase=5
Experimental movement onset Rising transition of MovementStarted with Introduction == 0
Practice movement onset Rising transition of MovementStarted with Introduction == 1
Experimental target acquisition TargetHit == 1 and Introduction == 0
Practice target acquisition TargetHit == 1 and Introduction == 1
Experimental reset TrialReset == 1 and Introduction == 0
Practice reset TrialReset == 1 and Introduction == 1
Experimental trial number TaskTrial
Practice trial number PracticeTrial
Experimental block number TaskBlock
Automatic vs. controlled TaskCondition, interpreted together with Introduction
Ordered vs. mixed experimental block TaskBlockType when Introduction == 0
Reaction time ReactionTimeMs, gated by Introduction and the relevant trial event
Movement time MovementTimeMs, gated by Introduction and the relevant trial event
Total time TotalTimeMs, gated by Introduction and the relevant trial event
Cursor trajectory CursorX and CursorY
Target coordinates TargetX and TargetY
Target angle TargetAngle

TargetHit and TrialReset are single-processing-block pulses. MovementStarted, 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:

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

References

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

See also

Retrieved from "http://www.bci2000.org/mediawiki/index.php?title=VisuomotorJoystickTask&oldid=12581"