BCI2000 Wiki - User contributions [en]

FEP VisuomotorJoystickTask

2026-10-19T15:38:22Z

Aes2376: Major task changes documenting reliability jitter changes

==Synopsis==

'''FEP_VisuomotorJoystickTask''' is a BCI2000 application module implementing a center-out visuomotor reaching task designed to investigate how participants adapt their behavior when the relationship between their actions and sensory consequences changes unexpectedly.

Participants control a cursor using a USB HID joystick and repeatedly move from a central starting location to peripheral targets. The joystick-to-cursor mapping is treated as a hidden environmental state: on a given trial, joystick movement may produce either a normal cursor movement or an inverted cursor movement. These mappings are not explicitly cued to the participant.

The task was developed in the context of the '''Free Energy Principle (FEP)''' and related theories of predictive processing and active inference. In this framework, an agent maintains an internal model of the causes of its sensory observations and uses incoming evidence to update that model. When observations conflict with the agent's expectations, the agent may need to revise its estimate of the current hidden state.

The present task operationalizes this problem using a simple visuomotor environment. The hidden state is the current joystick-to-cursor mapping. Participants first accumulate experience with particular mappings and mapping frequencies, creating different histories of prior exposure. The mapping can then change without warning, requiring the participant to infer from the resulting cursor behavior that the current sensorimotor relationship has changed.

The task therefore allows behavioral measurements to be related to three major features of inference:

* '''Prior experience''': Different experimental blocks expose participants to different frequencies of Normal and Inverted mappings.
* '''Unexpected state changes''': Mapping changes may occur between trials without an explicit visual cue.
* '''Behavioral updating''': Reaction time, movement time, total time, and cursor trajectory may be examined following mapping switches and across subsequent trials.

The experiment also includes a configurable visual sensory-reliability manipulation. On selected trials, Gaussian spatial noise perturbs the displayed cursor without changing the task-logic cursor position. High reliability has no visual noise; Medium and Low reliability use configurable noise amplitudes. This is a visual-feedback noise manipulation, not a cursor-gain manipulation.

Importantly, the software does not itself compute free energy, prediction error, posterior probability, Bayesian belief, or another formal FEP quantity. Instead, it creates a controlled hidden-state visuomotor task whose behavioral and neural data may be used to investigate questions motivated by those theories.

The current implementation includes:

* Normal and inverted joystick-to-cursor mappings.
* Unannounced mapping changes between trials.
* Six sequential experimental block roles with different mapping frequencies.
* High, Medium, and Low visual sensory-reliability conditions with configurable Gaussian cursor noise (disabled by default).
* Mapping-switch, prior-condition, and trials-since-switch state logging.
* A minimal participant introduction.
* A Normal-mapping joystick sandbox.
* Reaction-time, movement-time, total-time, displayed and true cursor, joystick (when logging is enabled), target, mapping, reliability, noise, and researcher-control states in the BCI2000 data stream.
* Experimenter controls for resetting, skipping, pausing, and resuming the task.

The participant is not explicitly informed about mapping changes, sensory-reliability conditions, mapping probabilities, or experimental block structure. Visual noise may nevertheless be perceptible.

==Location==

Upon completion of an SVN update or checkout of the relevant source tree, the current FEP Visuomotor Joystick Task is located in:

<pre>
src/custom/FEP_VisuomotorJoystickTask/
</pre>

The main implementation is contained in:

<pre>
FEP_VisuomotorJoystickTask.cpp
</pre>

with the corresponding header and build configuration in:

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

The application is included from:

<pre>
src/custom/CMakeLists.txt
</pre>

The current CMake target is:

<pre>
FEP_VisuomotorJoystickTask_custom
</pre>

The module uses <code>NOBUNDLE</code> in its <code>bci2000_add_application_module</code> declaration. Its Windows executable is typically named:

<pre>
FEP_VisuomotorJoystickTask_custom.exe
</pre>

A separate <code>src/custom/FEP_VisuomotorJoystickTask_pacing_test/</code> diagnostic module is also included in the custom build. That module is for investigating a rendering/pacing issue and is not the experimental task.

==Versioning==

===Author===

'''Alexander Speer'''

Friedman Lab, Department of Neurosurgery

Washington University in St. Louis

Developed in the Friedman Lab.

Contact: speer@wustl.edu

===Version History===

====New version: 19 October 2026====

This updated version replaces the earlier Normal/High cursor-gain manipulation with configurable High/Medium/Low visual sensory reliability; introduces temporally correlated Gaussian cursor noise and separate true-versus-displayed cursor states; adds researcher controls for skipping trials, blocks, introduction, and sandbox and for pausing/resuming; adds associated BCI2000 event and reliability states; provides configurable cursor and target diameters; and redesigns the diagnostic window to show real-time timings and run averages. The experimental mapping and six block roles remain in place. The current build uses the <code>FEP_VisuomotorJoystickTask_custom</code> target.

No independent numeric version identifier is declared in the inspected module; the date above identifies this documentation update and implementation revision, not an asserted source revision number.

The current FEP task is maintained under <code>src/custom</code>. In the inspected development checkout, the module does not currently have independent Git or SVN revision history.

An earlier inspected BCI2000 build was produced using:

* BCI2000 framework 3.6.9535
* BCI2000 source revision 9535
* Visual Studio 2022 / MSVC 19.35
* Release x64 configuration

These values refer to an inspected BCI2000 build containing the module, not to an independently verified revision number of the current FEP task.

==Scientific Motivation==

===Free Energy Principle===

The Free Energy Principle proposes that biological agents maintain internal models of the causes of their sensory inputs and continually update those models in order to reduce discrepancies between predicted and observed sensory states.

A useful way to interpret the present task is as a hidden-state inference problem.

The participant directly observes:

* Joystick movement.
* Cursor movement.
* Target position.
* The sensory consequences of each movement.

The participant is not directly told:

* Which joystick-to-cursor mapping is currently active.
* Whether the mapping has changed.
* The probability of a mapping occurring.
* The current experimental block.
* Whether visual sensory reliability has changed.

The current mapping therefore acts as a hidden environmental state that must be inferred from the relationship between action and observed cursor movement.

For example, after many Normal trials, a participant may expect the cursor to move in the same direction as the joystick. If the next trial unexpectedly uses the Inverted mapping, the observed cursor movement conflicts with that expectation. Subsequent behavior can then be examined to determine how rapidly the participant adjusts to the new mapping.

===Why the Task Was Developed===

The task was designed to create an experimentally controlled situation in which prior experience and new sensory evidence can come into conflict.

Several aspects of the experiment make this possible.

First, the frequency of Normal and Inverted mappings changes across blocks. This changes the participant's recent history of mapping exposure.

Second, mapping changes are not announced. Participants therefore cannot simply follow an explicit instruction telling them which mapping to use.

Third, the task records the exact trials on which the mapping changes and the number of trials that have occurred since the most recent switch.

This makes it possible to compare behavior:

* Before and after an unexpected mapping change.
* On switch versus non-switch trials.
* Across successive trials following a switch.
* Under different histories of Normal and Inverted mapping exposure.
* Under High, Medium, and Low visual sensory reliability (when enabled).

The task can therefore be used to investigate how prior experience influences behavioral adaptation to unexpected changes in sensorimotor contingencies.

===Implementation Versus Theory===

The current application implements the experimental manipulations required for this type of analysis, but it does not contain an explicit computational model of the participant.

In particular, the software does not calculate:

* Variational free energy.
* Prediction error.
* Posterior probability.
* Belief distributions.
* Bayesian surprise.
* Learning rate.
* Adaptation score.

These quantities, if used, must be estimated during offline behavioral or neural analysis.

==Functional Description==

===Mapping Conditions===

The FEP task uses two joystick-to-cursor mappings:

{| class="wikitable"
! <code>TaskCondition</code>
! Mapping
! Description
|-
| 0
| Normal
| Joystick displacement moves the cursor in the corresponding direction.
|-
| 1
| Inverted
| Joystick displacement moves the cursor in the opposite direction on both axes.
|}

The current mapping is not visually indicated to the participant.

Unlike the earlier USBHIDJoystickTask, the FEP task does not use the terms '''Automatic''' and '''Controlled''' in its implementation.

===Behavioral Measurements===

The task records information that may be used to examine:

* Reaction time.
* Movement time.
* Total target-acquisition time.
* Cursor trajectory.
* Initial movement direction.
* Trajectory curvature.
* Performance immediately following a mapping switch.
* Performance as a function of trials since the previous switch.
* Effects of different mapping-frequency contexts.
* Effects of High, Medium, and Low visual sensory reliability when the manipulation is enabled.
* Differences between true and displayed cursor trajectories under visual noise.

==Experiment Structure==

Each run proceeds in the following order:

# Introduction (unless skipped by the researcher).
# Joystick sandbox (unless bypassed or skipped).
# Experimental block 1, if enabled.
# Experimental block 2, if enabled.
# Experimental block 3, if enabled.
# Experimental block 4, if enabled.
# Experimental block 5, if enabled.
# Experimental block 6, if enabled.
# Experiment completion.

Experimental block transitions are not announced to the participant. Skipping the introduction using the researcher window enters the experiment directly and also bypasses the sandbox. Trial and block skipping can change which trials are actually performed.

Each experimental trial proceeds as follows:

# The participant returns the cursor to the center.
# The participant holds the cursor within the center region.
# A yellow warning cue appears.
# A pre-target delay occurs.
# A peripheral target appears.
# The participant moves the cursor toward the target.
# The target is acquired.
# A short feedback interval occurs.
# The task advances to the next trial.

==Introduction==

The introduction provides only the minimum information needed to operate the task.

The participant is shown:

<pre>
Use the joystick to control the cursor.

At the beginning of each trial, return the cursor to the center and hold it there.

The center will turn yellow before the target appears.

Once the target appears, move the cursor to the target.

Press the joystick button to continue.
</pre>

During the introduction:

* <code>Introduction=1</code>
* <code>TutorialPhase=1</code>
* <code>TaskPhase=0</code>
* The cursor is hidden.
* The center marker is hidden.
* The warning cue is hidden.
* The target is hidden.
* The central cross is hidden.
* The progress bar is hidden.

A rising press of <code>JoystickButtons1</code> advances to the sandbox. The experimenter may instead select <code>SKIP INTRODUCTION</code> (with confirmation), which enters the experiment directly and bypasses the sandbox.

The participant is not told about:

* Normal versus Inverted mappings.
* Mapping switches.
* Changes in visual sensory reliability.
* Mapping probabilities.
* Experimental blocks.
* Prior conditions.

==Sandbox==

After the introduction, the participant enters a free-movement sandbox.

The participant sees:

* A black cursor.
* A gray center marker.
* A black center cross.
* No peripheral target.
* No warning cue.
* No progress bar.

The participant is shown:

<pre>
Practice moving the cursor with the joystick.

When you are ready to begin, return the cursor to the center and press the joystick button.
</pre>

During the sandbox:

* <code>Introduction=1</code>
* <code>TutorialPhase=2</code>
* <code>TaskPhase=0</code>
* <code>TaskBlock=0</code>
* <code>TaskTrial=0</code>
* <code>TaskCondition=0</code>
* Normal direct mapping is used.
* There is no gain manipulation; the sandbox uses direct Normal mapping without visual noise.
* No targets are generated.
* No experimental timing phases occur.

The sandbox ends when both of the following conditions are satisfied:

# The cursor is inside the center tolerance region.
# A new joystick-button press occurs.

Because continuation uses rising-edge detection, the participant must release the button after leaving the introduction screen before pressing it again to leave the sandbox. The researcher can also select <code>SKIP SANDBOX</code> to enter the experiment.

When the sandbox finishes:

* <code>Introduction</code> becomes 0.
* <code>TutorialPhase</code> becomes 0.
* <code>TaskPhase</code> becomes 1.
* Experimental block and trial states become active.

==Experimental Blocks==

The task contains six predefined block roles.

There is no <code>ExperimentMode</code> parameter.

A block may be omitted by setting its trial-count parameter to 0.

<code>TaskBlock</code> retains the original block-role number, so block numbers may skip values when one or more blocks are disabled.

{| class="wikitable"
! Block
! Trial-count parameter
! <code>PriorCondition</code>
! Mapping composition
|-
| 1
| <code>BaselineTrials</code>
| 0, Fixed
| 100% Normal
|-
| 2
| <code>InitialInvertedTrials</code>
| 0, Fixed
| 100% Inverted
|-
| 3
| <code>ReturnNormalTrials</code>
| 0, Fixed
| 100% Normal
|-
| 4
| <code>MixedTrials</code>
| 1, HiddenMixed
| Approximately 50% Normal and 50% Inverted
|-
| 5
| <code>StrongPriorTrials</code>
| 2, StrongNormal
| Approximately 90% Normal and 10% Inverted
|-
| 6
| <code>BalancedPriorTrials</code>
| 3, Balanced
| Approximately 50% Normal and 50% Inverted
|}

===Blocks 4 and 6===

For blocks 4 and 6:

* <code>floor(N/2)</code> trials are assigned the Inverted mapping.
* All remaining trials are assigned the Normal mapping.
* If the number of trials is odd, the additional trial is Normal.

===Block 5===

Block 5 contains a strongly Normal-dominant mapping distribution.

Approximately 10% of trials are assigned the Inverted mapping, using a rounded fixed trial count.

The remaining trials are Normal.

This is not implemented as an independent 10% switch probability on each trial.

===Pseudorandomization===

For blocks 4 through 6, mapping order is pseudorandomized.

The task attempts up to 64 candidate shuffles.

A candidate is preferred when:

* It does not strictly alternate throughout sequences of at least four trials.
* It does not contain excessively long runs of one mapping.

The preferred maximum run length is:

<pre>
max(3, unavoidableRun + 1)
</pre>

where:

<pre>
unavoidableRun = (majority + minority) / (minority + 1)
</pre>

using integer division.

If no candidate satisfies the constraints after 64 attempts, the final generated sequence is used.

After the mapping sequence is generated, sensory-reliability conditions are assigned separately using a dedicated random generator. Rather than an independent shuffle, the assignment algorithm attempts to counterbalance reliability categories across Normal/Inverted mappings and mapping-switch/non-switch trials while preserving the configured counts. Reliability assignment does not alter the mapping order. See [[#Sensory Reliability|Sensory Reliability]].

==Prior Conditions==

<code>PriorCondition</code> represents the mapping-frequency context associated with the current block.

It does not represent the immediately preceding trial's mapping.

{| class="wikitable"
! Value
! Name
! Meaning
|-
| 0
| Fixed
| Fixed-mapping context used in blocks 1 through 3.
|-
| 1
| HiddenMixed
| Approximately balanced hidden mapping context used in block 4.
|-
| 2
| StrongNormal
| Strongly Normal-dominant mapping context used in block 5.
|-
| 3
| Balanced
| Approximately balanced mapping context used in block 6.
|}

The mapping used on the preceding trial may be determined offline from the previous trial's <code>TaskCondition</code>.

==Joystick Input==

Joystick input is provided through BCI2000's [[User Reference:Logging Input|input logging]] system.

The application reads:

* <code>JoystickXpos</code>
* <code>JoystickYpos</code>
* <code>JoystickButtons1</code>

Joystick X and Y values normally range from 0 through 32767.

Each axis is converted into the task's 0-through-1023 coordinate system:

<pre>
taskJoystick = round(BCIJoystick * 1023 / 32767)
</pre>

The converted value is normalized internally:

<pre>
rawPosition = taskJoystick / 1023
</pre>

The FEP application does not itself enable joystick logging.

Joystick logging should therefore be enabled using BCI2000's <code>LogJoystick</code> option.

See [[User Reference:Logging Input#LogJoystick|LogJoystick]].

==Joystick-to-Cursor Mapping==

Before target onset, cursor position normally follows direct absolute joystick position:

<pre>
cursorX = rawX
cursorY = rawY
</pre>

The mapping transformation used for target-directed movement is activated at target onset. The code defines no <code>HighCursorGain</code> parameter, no <code>CursorGainCondition</code> state, and no high-gain movement condition in this version.

===Anchor Capture===

When the target appears, the application stores:

* Current joystick X position.
* Current joystick Y position.
* Current cursor X position.
* Current cursor Y position.
* Current mapping direction (<code>+1</code> for Normal or <code>-1</code> for Inverted).

These values form the anchor for transformed movement. Because joystick displacement relative to the anchor is initially zero, activating the transformed mapping does not cause an immediate cursor jump.

===Normal Mapping===

With Normal mapping, the cursor follows the joystick directly:

<pre>
cursorX = joystickX / 1023
cursorY = joystickY / 1023
</pre>

===Inverted Mapping===

After target onset on an Inverted trial:

<pre>
cursorX = anchorCursorX - (joystickX - anchorJoystickX) / 1023
cursorY = anchorCursorY - (joystickY - anchorJoystickY) / 1023
</pre>

Both axes are inverted. Cursor coordinates are constrained to the normalized range <code>[0, 1]</code>. While returning from a preceding anchored Inverted trial, that preceding transformation may remain active until the joystick returns to its stored anchor.

The cursor position resulting from mapping and clipping, but before sensory noise, is called the true cursor. Sensory noise perturbs only the displayed cursor.

==Sensory Reliability==

The current implementation manipulates visual sensory reliability using trial-wise Gaussian spatial noise added to the displayed cursor. This replaces the cursor-gain manipulation described in earlier versions. Sensory reliability is disabled by default (<code>EnableSensoryReliability=0</code>).

===Reliability Conditions===

{| class="wikitable"
! <code>SensoryReliabilityCondition</code>
! Condition
! Visual-noise standard deviation
! Description
|-
| 0
| High
| 0 pixels
| Noise-free visual cursor
|-
| 1
| Medium
| <code>MediumReliabilityNoiseStd</code> (default 5 pixels)
| Gaussian cursor-position noise
|-
| 2
| Low
| <code>LowReliabilityNoiseStd</code> (default 15 pixels)
| Larger Gaussian cursor-position noise
|}

The noise standard deviations are specified in reference-display pixels, normalized using the task's nominal 1000 by 750 coordinate system. Noise affects only the cursor during the <code>TargetVisible</code> phase; the target, center marker, warning marker, cross, and joystick input are not perturbed.

===Enabling Reliability by Block===

When <code>EnableSensoryReliability=0</code>, all trials use High reliability and no visual noise is applied, regardless of the requested proportions or block list. Therefore, <code>SensoryReliabilityCondition=0</code> does not by itself establish that reliability manipulation was enabled.

When enabled, reliability conditions are assigned only within the numbered blocks listed in <code>SensoryReliabilityBlocks</code>, which defaults to blocks 4, 5, and 6. Blocks not listed always use High reliability. The block list may instead select any subset of the six block roles. A block disabled by setting its trial count to zero has no trials to assign.

===Reliability Assignment and Counterbalancing===

For each enabled block, counts for High, Medium, and Low trials are calculated from the configured proportions by taking their floors and distributing remaining trials according to the largest fractional remainders. The result matches the block's total trial count.

The application then uses a dedicated <code>std::mt19937</code> generator to assign those conditions in a randomized trial order. The selection score favors counterbalancing reliability across (1) Normal versus Inverted mapping and (2) mapping-switch versus non-switch trials, subject to the remaining required condition counts. Thus reliability assignment is not a wholly independent shuffle of the mapping sequence. Exact balance in small blocks or uneven sequences is not guaranteed.

Reliability is assigned after the Normal/Inverted mapping sequence has been built and does not change that sequence. Only mapping changes, not reliability changes, generate <code>MappingSwitch</code> events. The dedicated noise/assignment seed is distinct from BCI2000's mapping/target random-number generator.

The configured proportions default to 0.34 High, 0.33 Medium, and 0.33 Low, and their sum must equal 1 within <code>1e-6</code>. Low-reliability noise SD must be at least Medium-reliability noise SD.

===Temporally Correlated Visual Noise===

X and Y noise are generated from independent Gaussian innovations and evolved over processing updates as:

<pre>
a = exp(-elapsedSeconds / correlationTimeSeconds)
noiseX = a * previousNoiseX + SD * sqrt(1 - a*a) * N_X(0,1)
noiseY = a * previousNoiseY + SD * sqrt(1 - a*a) * N_Y(0,1)
</pre>

The temporal correlation time is set by <code>SensoryNoiseCorrelationTimeMs</code> (default 100 ms); a value of zero produces independent innovations on each update. Each trial's noise generator is initialized from the effective seed and trial/block identity. Noise begins at zero at target onset, so the process builds up rather than beginning with stationary variance. Noise is cleared when the task leaves the target-visible phase and on trial reset or skip.

The displayed cursor is calculated as:

<pre>
displayedX = clamp(trueX + noiseX / 1000, 0, 1)
displayedY = clamp(trueY + noiseY / 750, 0, 1)
</pre>

The true cursor is used for center detection and target-hit detection. Movement onset is detected from joystick movement. Therefore a displayed cursor that appears to touch the target is not necessarily counted as a hit, and a true cursor that reaches the target can register a hit despite noise displacing the displayed cursor away from it.

===Noise Seeds and State Encoding===

<code>SensoryNoiseSeed</code> defaults to 1. Setting it to 0 selects an automatically generated effective seed, recorded in <code>SensoryNoiseSeedEffective</code> and reported in the BCI2000 operator log.

Noise values are stored as positive integer states with an offset to represent negative noise; the configured SD is stored in hundredths of a pixel:

<pre>
noiseX_pixels = (SensoryNoiseX - 1073741824) / 100
noiseY_pixels = (SensoryNoiseY - 1073741824) / 100
noiseSD_pixels = SensoryNoiseStd / 100
</pre>

The recorded <code>TrueCursorX/Y</code> and <code>CursorX/Y</code> coordinates are quantized to the task's 0–1023 range. The noise states represent the generated visual perturbation before final boundary clipping; consequently, the difference between displayed and true coordinates may not equal the encoded noise exactly near display edges.

Important: <code>TrueCursorX/Y</code> is post-mapping, pre-noise position, not a pre-mapping/raw joystick trajectory. The raw joystick trajectory is available from logged joystick input states.

==Return-to-Anchor Behavior==

After an Inverted trial, the previous transformed mapping may temporarily remain active while the participant returns the joystick toward its previous anchor.

The stored transformation is released once both joystick axes are within 8 task-coordinate units of the previous joystick anchor.

Normal direct mapping is then restored for ordinary centering.

This behavior reduces abrupt cursor jumps between transformed target movement and subsequent centering. It is also engaged when an in-progress Inverted trial is skipped or when an Inverted trial is reset during target-visible movement. Skipping an entire block does not explicitly engage this return path, so direct mapping may be restored immediately in that case.

==Mapping Switches==

A mapping switch occurs when:

<pre>
next trial TaskCondition != completed trial TaskCondition
</pre>

Mapping switches occur only at trial boundaries. Changes in sensory reliability alone do not produce mapping-switch events.

They do not occur:

* During target-directed movement.
* During the Feedback phase before the feedback interval ends.

The new mapping is selected when the task advances into the next trial.

===MappingSwitch===

<code>MappingSwitch</code> is an event-like state.

It is:

* 1 on the processing block that advances into a new trial whose mapping differs from the completed trial.
* 0 on the following processing block.
* 0 when no mapping change occurred.

It should therefore be interpreted as a one-processing-block pulse.

===TrialsSinceMappingSwitch===

<code>TrialsSinceMappingSwitch</code> records how many consecutive no-switch trial transitions have occurred since the most recent mapping change.

Behavior is:

* First experimental trial: 0.
* First trial following a mapping switch: 0.
* Next same-mapping trial: 1.
* Next same-mapping trial: 2.
* And so forth.

Because the first experimental trial also begins at 0, <code>TrialsSinceMappingSwitch==0</code> by itself does not identify a switch.

Use <code>MappingSwitch</code> or a transition in <code>TaskCondition</code> to identify mapping changes. When skip controls are used, event states can be stale or missing for a processing block; compare adjacent trials and consult the skip-state guidance below.

===Example===

Consider the following mapping sequence:

<pre>
Normal -> Normal -> Inverted -> Inverted
</pre>

Within block 4, the corresponding states would behave approximately as follows:

{| class="wikitable"
! Trial
! <code>TaskCondition</code>
! <code>MappingSwitch</code>
! <code>TrialsSinceMappingSwitch</code>
! <code>PriorCondition</code>
|-
| Normal
| 0
| 0
| Depends on previous trial history
| 1
|-
| Normal
| 0
| 0
| Previous value + 1
| 1
|-
| Inverted
| 1
| 1 on the transition processing block
| 0
| 1
|-
| Inverted
| 1
| 0
| 1
| 1
|}

==Target Generation==

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

<code>TargetAngle</code> ranges from:

<pre>
0 through 3599
</pre>

The value represents tenths of a degree:

<pre>
angle in degrees = TargetAngle / 10
</pre>

Targets therefore span:

<pre>
0.0 through 359.9 degrees
</pre>

Target coordinates are generated according to:

<pre>
TargetX = 0.5 + 0.3 * cos(angle)
TargetY = 0.5 + 0.4 * sin(angle)
</pre>

The unequal normalized X and Y radii correspond to an approximately circular 300-pixel radius in the nominal 1000 by 750 design.

Targets:

* Are black.
* Are visually identical across all mapping conditions.
* Are visually identical across reliability conditions.
* Are not determined by mapping condition.
* Are not determined by reliability condition.
* Are not determined by mapping-switch status.
* May repeat.
* Are not explicitly angularly balanced.
* Do not appear during the introduction.
* Do not appear during the sandbox.

A new target is generated:

* For the first experimental trial.
* After each completed non-final trial.

Resetting a trial does not generate a new target. Advancing after a skipped trial generates a new target; skipping the remaining trials of a block may consume multiple target generations and change the subsequent target sequence.

==Trial Phases==

The current experimental phase is stored in <code>TaskPhase</code>.

{| class="wikitable"
! Value
! Phase
! Description
! Participant display
|-
| 0
| Introduction / Sandbox
| No active experimental trial
| Introduction text or sandbox
|-
| 1
| WaitingForCenter
| Waiting for cursor to enter the center region
| Cursor, gray center, cross
|-
| 2
| HoldingCenter
| Required uninterrupted center hold
| Cursor, gray center, cross
|-
| 3
| Warning
| Warning interval
| Cursor, yellow warning marker, cross
|-
| 4
| PreTargetDelay
| Delay immediately before target appearance
| Cursor, gray center, cross
|-
| 5
| TargetVisible
| Target-directed movement
| Cursor, black target, cross
|-
| 6
| Feedback
| Post-acquisition interval
| Cursor and cross
|-
| 7
| Finished
| Experiment complete
| End message
|}

An experimental target onset may be identified by a transition into:

<pre>
TaskPhase == 5
</pre>

Movement onset may be identified by a rising transition of:

<pre>
MovementStarted
</pre>

Target acquisition is identified by:

<pre>
TargetHit == 1
</pre>

Center and target-hit testing use the true, pre-noise cursor, not the displayed noisy cursor. During a skip operation, <code>TaskPhase</code> and related trial states may remain stale because the normal state-update path is bypassed. In particular, a skip directly to completion may not record <code>TaskPhase=7</code>.

==Participant Display==

The participant-facing window contains:

* A light background.
* A black cursor (diameter configurable with <code>CursorDiameterPixels</code>).
* A black central cross.
* A gray center marker.
* A larger yellow warning marker.
* A black peripheral target (diameter configurable with <code>TargetDiameterPixels</code>).
* An experimental progress indicator.
* Introduction and sandbox instructions in white text on a dark-gray background.
* An experiment-completion message.

The participant receives no explicit visual indication of the current mapping, current reliability condition, mapping switches, <code>PriorCondition</code>, block or trial numbers, block transitions, or mapping probabilities. However, noise under Medium and Low reliability may be perceptible as cursor jitter during target-visible movement.

The target remains black across all mapping and reliability conditions. There is no explicit success-color cue; the target disappears after successful acquisition. The completion text is the literal string <code>" ended "</code> shown in white.

The target diameter affects both its drawing and the radius used for target-hit testing. The cursor diameter affects its appearance only; it does not change the center tolerance or the target-hit radius.

==Diagnostic Window==

A separate Qt diagnostic window titled:

<pre>
FEP Visuomotor Joystick Diagnostics
</pre>

is displayed to the experimenter.

===Displayed Information===

During experimental trials, the visible metrics panel displays:

* Current task stage.
* Original block role number (<code>Block: N / 6</code>), even if some blocks were disabled.
* Trial number within the current block and block trial count.
* Overall trial number and total configured active trials.
* Current Normal or Inverted mapping.
* Current High, Medium, or Low reliability condition.
* Configured visual-noise standard deviation for that trial, in pixels.
* Current task phase.
* Real-time reaction time, movement time, and total time.
* Cumulative overall, Normal-mapping, and Reversed-mapping averages of reaction time, movement time, and total time.

The visible panel does not show target angle or coordinates, joystick coordinates, cursor coordinates, mapping-switch flag, trials-since-switch counter, movement-started status, <code>PriorCondition</code>, or a separate reset/status message. Run averages are divided by mapping, not by sensory reliability. A separate diagnostic text label exists internally but is hidden and not populated.

===Diagnostic Controls===

{| class="wikitable"
! Control
! Availability
! Effect
! Confirmation
|-
| <code>RESET CURRENT TRIAL</code>
| Experiment phases 1–5; shown as <code>RESET UNAVAILABLE</code> otherwise
| Restarts the same trial and emits <code>TrialReset</code>
| No
|-
| <code>SKIP TRIAL</code>
| Experiment phases 1–5, not paused
| Abandons the current trial and advances; emits <code>TrialSkipped</code>
| No
|-
| <code>SKIP CURRENT BLOCK</code>
| Experiment phases 1–5, not paused
| Advances past the remaining trials of the block; emits <code>ConditionSkipped</code>
| Yes
|-
| <code>SKIP INTRODUCTION</code>
| Introduction stage, not paused
| Enters the experiment directly, bypassing sandbox; emits <code>IntroductionSkipped</code>
| Yes
|-
| <code>SKIP SANDBOX</code>
| Sandbox stage, not paused
| Enters the experiment; emits <code>SandboxSkipped</code>
| No
|-
| <code>PAUSE</code> / <code>RESUME</code>
| All stages/phases except Finished
| Freezes task-phase progression and resumes with adjusted internal timestamps; uses <code>TaskPaused</code>
| No
|}

There is no separate diagnostic Continue button for the introduction or sandbox. Those stages normally advance using a rising joystick-button press, or may be bypassed using the skip controls.

==Trial Reset==

A trial may be manually reset during:

* Waiting for center.
* Holding center.
* Warning.
* Pre-target delay.
* Target-visible movement.

Reset is unavailable during:

* Feedback.
* Finished.
* Introduction.
* Sandbox.

Resetting a trial:

* Returns the task to <code>WaitingForCenter</code>.
* Restarts the phase timer.
* Clears movement-onset timing.
* Clears target-onset timing.
* Clears <code>MovementStarted</code>.
* Clears <code>TargetHit</code>.
* Produces a <code>TrialReset</code> pulse.
* Clears timing states.
* Resets baseline accumulation.
* Clears visual-noise state.
* Keeps the same target.
* Keeps the same mapping.
* Keeps the same sensory-reliability condition.
* Keeps the same block number.
* Keeps the same trial number.
* Keeps <code>PriorCondition</code>.
* Keeps <code>TrialsSinceMappingSwitch</code>.
* Does not rebuild or reshuffle the experimental sequence.

<code>TrialReset</code> lasts for one processing block. Resetting an Inverted trial during target-visible movement also enables the return-to-anchor behavior. A reset request is not processed while paused; requests pending at the time of a pause are deferred until processing resumes.

==Skipping Trials, Blocks, and Tutorial Stages==

===Skip Trial===

<code>SKIP TRIAL</code> is available during experimental phases before Feedback. It emits a one-processing-block <code>TrialSkipped</code> pulse, clears the current movement/timing values, does not count the abandoned trial in completed-trial performance averages, and advances to the next trial or finishes the run. A new target is generated on each non-final advance. Skipping an Inverted trial engages the return-to-anchor behavior.

===Skip Current Block===

<code>SKIP CURRENT BLOCK</code> requires confirmation and is available during experimental phases before Feedback. It emits <code>ConditionSkipped</code>, advances through all remaining trials in the current block, and starts the next enabled block or finishes the run. It does not register those abandoned trials as completed performance measurements. The operation calls the normal advancement routine repeatedly, consuming target-generation random-number draws. Unlike single-trial skip, it does not explicitly engage return-to-anchor for the interrupted Inverted trial.

===Skip Introduction and Sandbox===

<code>SKIP INTRODUCTION</code>, after confirmation, emits <code>IntroductionSkipped</code> and enters the experimental phase directly, also bypassing the sandbox. <code>SKIP SANDBOX</code> emits <code>SandboxSkipped</code> and enters the experimental phase from the sandbox. Both are available only in their corresponding stage when not paused.

===Pause and Resume===

<code>PAUSE</code> is available during introduction, sandbox, and experimental phases, including Feedback, but not Finished. While paused, <code>TaskPaused</code> is held at 1, phase progression and cursor rendering updates stop, and joystick states continue to be sampled. On resumption, internal phase, target-onset, movement-onset, and noise-update timestamps are shifted by the pause duration so that measured task intervals exclude paused time. Skip controls are disabled while paused; pending requests are not executed until processing resumes.

===State-Logging Caveats During Skips===

The skip-handling branches return early from <code>Process()</code> before the usual end-of-block state publication. Consequently, <code>TaskTrial</code>, <code>TaskBlock</code>, <code>TaskCondition</code>, <code>TaskPhase</code>, <code>TrialsSinceMappingSwitch</code>, and other trial states may show the preceding values on the skip processing block. They normally update on a later ordinary processing block. <code>MappingSwitch</code> can be stale or fail to pulse on the skip block. If a skip ends the run, the usual <code>TaskPhase=7</code> update may never be recorded. Do not rely on a single isolated processing block to reconstruct skip transitions; inspect adjacent samples, skip event states, and trial/block identifiers. These behaviors are analysis considerations of the current implementation, not intended additional task conditions.

==Timing Measurements==

Timing uses <code>std::chrono::steady_clock</code>.

Events are detected during BCI2000 <code>Process()</code> calls, so effective timing resolution is limited by the signal-processing block interval.

===Movement Onset===

The joystick baseline is initialized when the center-hold phase begins and updated during center holding.

Movement onset is detected when either joystick axis differs from the center-hold baseline by more than 8 task-coordinate units.

<pre>
abs(currentX - baselineX) > 8
</pre>

or:

<pre>
abs(currentY - baselineY) > 8
</pre>

===Reaction Time===

Reaction time is measured from:

<pre>
target onset -> movement onset
</pre>

and stored in:

<code>ReactionTimeMs</code>

===Movement Time===

Movement time is measured from:

<pre>
movement onset -> target acquisition
</pre>

and stored in:

<code>MovementTimeMs</code>

===Total Time===

Total time is measured from:

<pre>
target onset -> target acquisition
</pre>

and stored in:

<code>TotalTimeMs</code>

Timing values are expressed in rounded milliseconds.

Timing states remain populated through the Feedback phase. When a target is reached without a detected movement onset, reaction and movement times are recorded as 0 and excluded from the corresponding run averages, while total time is still recorded. Paused durations are excluded through adjustment of internal timestamps when resuming.

==Parameters==

===Experiment Structure===

{| class="wikitable"
! Parameter
! Type
! Default
! Range
! Description
|-
| <code>BaselineTrials</code>
| Integer
| 20
| 0-10000
| Number of Normal trials in block 1
|-
| <code>InitialInvertedTrials</code>
| Integer
| 5
| 0-10000
| Number of Inverted trials in block 2
|-
| <code>ReturnNormalTrials</code>
| Integer
| 5
| 0-10000
| Number of Normal trials in block 3
|-
| <code>MixedTrials</code>
| Integer
| 20
| 0-10000
| Number of approximately balanced trials in block 4
|-
| <code>StrongPriorTrials</code>
| Integer
| 20
| 0-10000
| Number of Normal-dominant trials in block 5
|-
| <code>BalancedPriorTrials</code>
| Integer
| 20
| 0-10000
| Number of approximately balanced trials in block 6
|}

At least one trial must be configured across the six block parameters. A count of zero disables that block without renumbering the remaining block roles.

===Task Timing and Display===

{| class="wikitable"
! Parameter
! Type
! Default
! Range
! Description
|-
| <code>CenterHoldSeconds</code>
| Float
| 3.0
| 0.0-60.0
| Required uninterrupted center-hold duration in seconds
|-
| <code>WarningSeconds</code>
| Float
| 0.5
| 0.0-60.0
| Yellow warning interval in seconds
|-
| <code>PreTargetDelaySeconds</code>
| Float
| 0.5
| 0.0-60.0
| Delay between warning and target onset in seconds
|-
| <code>FeedbackSeconds</code>
| Float
| 0.5
| 0.0-60.0
| Feedback interval following target acquisition, in seconds
|-
| <code>CursorDiameterPixels</code>
| Float
| 16.0
| 1.0-1000.0
| Cursor drawing diameter in nominal reference pixels
|-
| <code>TargetDiameterPixels</code>
| Float
| 36.0
| 1.0-1000.0
| Target drawing and hit-test diameter in nominal reference pixels
|-
| <code>StimulusDisplay</code>
| Integer
| 0
| 0 through number of detected displays
| Physical monitor for participant stimuli; 0 uses default BCI2000 placement
|}

On Windows, the application enumerates available monitors for <code>StimulusDisplay</code>. <code>CursorDiameterPixels</code> affects cursor appearance only; <code>TargetDiameterPixels</code> also changes the hit-test radius.

===Sensory Reliability Configuration===

{| class="wikitable"
! Parameter
! Type
! Default
! Range
! Description
|-
| <code>EnableSensoryReliability</code>
| Integer
| 0
| 0-1
| Enable trial-wise visual-reliability noise; 0 disables it
|-
| <code>MediumReliabilityNoiseStd</code>
| Float
| 5.0
| 0.0-1000.0
| Gaussian noise SD in pixels for Medium reliability
|-
| <code>LowReliabilityNoiseStd</code>
| Float
| 15.0
| 0.0-1000.0
| Gaussian noise SD in pixels for Low reliability
|-
| <code>HighReliabilityProportion</code>
| Float
| 0.34
| 0.0-1.0
| Target High-reliability trial proportion in enabled blocks
|-
| <code>MediumReliabilityProportion</code>
| Float
| 0.33
| 0.0-1.0
| Target Medium-reliability trial proportion in enabled blocks
|-
| <code>LowReliabilityProportion</code>
| Float
| 0.33
| 0.0-1.0
| Target Low-reliability trial proportion in enabled blocks
|-
| <code>SensoryNoiseCorrelationTimeMs</code>
| Float
| 100.0
| 0.0-60000.0
| Temporal correlation time constant of noise, in milliseconds; zero gives independent innovations
|-
| <code>SensoryNoiseSeed</code>
| Integer
| 1
| 0-2147483647
| Dedicated condition-assignment and noise seed; zero automatically selects a seed
|-
| <code>SensoryReliabilityBlocks</code>
| List
| 4 5 6 (BCI2000 definition: <code>3 4 5 6</code>, where 3 is the list length)
| Entries 1-6; no duplicates
| Block role numbers in which reliability conditions may be assigned; an empty list means all trials are High reliability
|}

===Parameter Validation===

Preflight requires at least one configured experimental trial, finite and nonnegative reliability values, noise SD for Low reliability not less than that for Medium, reliability proportions summing to 1 within <code>1e-6</code>, valid unduplicated reliability-block numbers, positive cursor and target diameters, nonnegative task durations, and a valid selected display. The published parameter definitions also specify the listed bounds.

<code>HighCursorGain</code> is no longer a parameter in this version. There is no <code>ExperimentMode</code> or <code>ResultsFile</code> parameter.

==States==

The following states are declared by the FEP task. Widths and initial values refer to their published definitions; runtime values may change immediately on <code>StartRun()</code> or during <code>Process()</code>.

{| class="wikitable"
! State
! Width
! Initial Value
! Meaning
|-
| <code>CursorX</code>
| 10 bit
| 512
| Displayed horizontal cursor position, after mapping, sensory noise, and clipping (0-1023)
|-
| <code>CursorY</code>
| 10 bit
| 512
| Displayed vertical cursor position, after mapping, sensory noise, and clipping (0-1023)
|-
| <code>TaskPhase</code>
| 3 bit
| 0
| Current task phase (0-7)
|-
| <code>TaskCondition</code>
| 1 bit
| 0
| 0 Normal, 1 Inverted mapping
|-
| <code>TargetAngle</code>
| 12 bit
| 0
| Target angle in tenths of a degree
|-
| <code>TargetX</code>
| 10 bit
| 512
| Horizontal target coordinate (0-1023)
|-
| <code>TargetY</code>
| 10 bit
| 512
| Vertical target coordinate (0-1023)
|-
| <code>TaskBlock</code>
| 8 bit
| 0
| Current original experimental block role (1-6; 0 before experiment)
|-
| <code>TaskTrial</code>
| 16 bit
| 0
| Overall 1-based experimental trial number (0 before experiment)
|-
| <code>MovementStarted</code>
| 1 bit
| 0
| Level flag indicating detected movement onset during the trial
|-
| <code>TargetHit</code>
| 1 bit
| 0
| One-processing-block target-acquisition pulse
|-
| <code>TrialReset</code>
| 1 bit
| 0
| One-processing-block manual-reset pulse
|-
| <code>TrialSkipped</code>
| 1 bit
| 0
| One-processing-block trial-skip pulse
|-
| <code>ConditionSkipped</code>
| 1 bit
| 0
| One-processing-block current-block-skip pulse
|-
| <code>IntroductionSkipped</code>
| 1 bit
| 0
| One-processing-block introduction-skip pulse
|-
| <code>SandboxSkipped</code>
| 1 bit
| 0
| One-processing-block sandbox-skip pulse
|-
| <code>TaskPaused</code>
| 1 bit
| 0
| Level flag: 1 while paused; 0 otherwise
|-
| <code>MappingSwitch</code>
| 1 bit
| 0
| One-processing-block mapping-change event during normal progression; see skip caveats
|-
| <code>TrialsSinceMappingSwitch</code>
| 16 bit
| 0
| Consecutive non-switch trial transitions since the most recent mapping change
|-
| <code>PriorCondition</code>
| 2 bit
| 0
| Current block-level prior-frequency context (0-3)
|-
| <code>Introduction</code>
| 1 bit
| 0
| 1 during introduction or sandbox; 0 during experiment
|-
| <code>TutorialPhase</code>
| 4 bit
| 0
| 0 experiment, 1 introduction, 2 sandbox
|-
| <code>ReactionTimeMs</code>
| 32 bit
| 0
| Reaction time in rounded milliseconds
|-
| <code>MovementTimeMs</code>
| 32 bit
| 0
| Movement time in rounded milliseconds
|-
| <code>TotalTimeMs</code>
| 32 bit
| 0
| Target-onset to acquisition time in rounded milliseconds
|-
| <code>SensoryReliabilityCondition</code>
| 2 bit
| 0
| 0 High, 1 Medium, 2 Low reliability
|-
| <code>TrueCursorX</code>
| 10 bit
| 512
| Post-mapping, pre-noise horizontal task-logic cursor position (0-1023)
|-
| <code>TrueCursorY</code>
| 10 bit
| 512
| Post-mapping, pre-noise vertical task-logic cursor position (0-1023)
|-
| <code>SensoryNoiseX</code>
| 31 bit
| 1073741824
| X noise encoded as 1073741824 + round(100 * noise pixels)
|-
| <code>SensoryNoiseY</code>
| 31 bit
| 1073741824
| Y noise encoded as 1073741824 + round(100 * noise pixels)
|-
| <code>SensoryNoiseStd</code>
| 18 bit
| 0
| Configured noise SD encoded as round(100 * pixels)
|-
| <code>SensoryNoiseSeedEffective</code>
| 32 bit
| 1
| Effective noise and reliability-assignment seed
|}

===External Joystick States===

{| class="wikitable"
! State
! Description
|-
| <code>JoystickXpos</code>
| Raw horizontal joystick position supplied through BCI2000 input logging
|-
| <code>JoystickYpos</code>
| Raw vertical joystick position supplied through BCI2000 input logging
|-
| <code>JoystickButtons1</code>
| Joystick button used to advance the introduction and sandbox
|}

The application also accesses BCI2000's standard <code>Running</code> state when ending the experiment. Joystick logging must be configured separately using <code>LogJoystick</code>.

===States Not Present in the Current Implementation===

The task does not define <code>DisplayedCursorX</code>, <code>DisplayedCursorY</code>, an exact state named <code>SensoryReliability</code>, <code>PracticeTrial</code>, <code>TaskBlockType</code>, or <code>CursorGainCondition</code>. Instead, displayed coordinates use <code>CursorX/Y</code>, pre-noise coordinates use <code>TrueCursorX/Y</code>, and visual reliability is recorded through <code>SensoryReliabilityCondition</code> and the sensory-noise states.

===State Lifecycle and Encoding Notes===

<code>TargetX/Y</code> have published initial values of 512 but are explicitly set to 0 during introduction/sandbox. <code>TaskTrial</code> is 1-based once experimental trials begin. Pulse states normally clear on the following processing block, whereas <code>TaskPaused</code> is held at 1 throughout a pause and <code>MovementStarted</code> remains high from movement detection until trial advancement. Noise states use fixed-point encoding described in [[#Noise Seeds and State Encoding|Noise Seeds and State Encoding]]. State publication immediately after skip operations has known limitations described in [[#State-Logging Caveats During Skips|State-Logging Caveats During Skips]].

==Cursor Coordinates==

<code>CursorX</code> and <code>CursorY</code> represent the final displayed cursor position including mapping inversion, return-to-anchor transformation, any applied Gaussian visual noise, and display-boundary clipping.

<code>TrueCursorX</code> and <code>TrueCursorY</code> record the separate post-mapping, pre-noise cursor trajectory. This is the trajectory used for center detection and target-hit detection. It does not represent untransformed joystick input.

The participant-visible drawing is positioned using the displayed cursor. Both true and displayed coordinates are recorded as 10-bit states over the range 0-1023. Encoded noise samples are recorded separately. The diagnostic window does not currently show either cursor coordinate pair.

The application does not record an independent pre-mapping cursor state. When enabled, <code>JoystickXpos/Ypos</code> provide the underlying joystick samples needed to reconstruct a raw joystick-equivalent trajectory offline.

==Data Recording==

The task records its behavioral variables as synchronized BCI2000 states in the standard <code>.dat</code> file, subject to the configured BCI2000 recording and joystick-logging settings.

Recorded information includes:

* Displayed and true cursor trajectories (<code>CursorX/Y</code> and <code>TrueCursorX/Y</code>).
* Joystick trajectory when external joystick logging is enabled.
* Task phase, Normal/Inverted mapping, prior context, and mapping-switch history.
* Sensory-reliability condition, actual generated noise, configured noise SD, and effective seed.
* Target angle and coordinates, experimental block, and trial number.
* Movement onset, target acquisition, and reaction/movement/total timing.
* Trial reset, trial skip, block skip, introduction skip, sandbox skip, and pause status.
* Introduction/sandbox status and experiment completion as represented by task states.

The application passes signal channels through unchanged:

<pre>
Output = Input;
</pre>

===Operator Logging===

The application writes <code>bciout</code> messages for task startup and shutdown, the effective sensory-noise seed, per-block High/Medium/Low reliability distributions split by Normal/Inverted mapping and switch status, and trial-completion results including trial, block, mapping, reliability, reaction time, and movement time. These are diagnostic/operator messages rather than a separate structured task-results file.

===Secondary Output===

The current implementation does not write an application-specific CSV file, JSON file, text results file, or database. There is no <code>ResultsFile</code> parameter.

==Offline Analysis Notes==

The table below gives common event and measurement identifications. When reset, skip, or pause controls are used, inspect adjacent processing blocks and the recorded configuration instead of relying solely on one state sample.

{| class="wikitable"
! Measurement or Event
! Recommended Identification
|-
| Experimental samples
| <code>Introduction == 0</code>
|-
| Introduction
| <code>Introduction == 1</code> and <code>TutorialPhase == 1</code>
|-
| Sandbox
| <code>Introduction == 1</code> and <code>TutorialPhase == 2</code>
|-
| Active experimental trial
| <code>Introduction == 0</code>, <code>TaskTrial > 0</code>, and <code>TaskPhase</code> from 1 through 6
|-
| Target onset
| Transition into <code>TaskPhase == 5</code>
|-
| Movement onset
| Rising transition of <code>MovementStarted</code>
|-
| Target acquisition
| <code>TargetHit == 1</code>
|-
| Normal mapping
| <code>TaskCondition == 0</code>
|-
| Inverted mapping
| <code>TaskCondition == 1</code>
|-
| High reliability
| <code>SensoryReliabilityCondition == 0</code>
|-
| Medium reliability
| <code>SensoryReliabilityCondition == 1</code>
|-
| Low reliability
| <code>SensoryReliabilityCondition == 2</code>
|-
| Reliability globally disabled
| Verify <code>EnableSensoryReliability == 0</code> in recorded parameters; all trials then use condition 0
|-
| Configured visual-noise SD
| <code>SensoryNoiseStd / 100</code> pixels
|-
| Actual X visual noise
| <code>(SensoryNoiseX - 1073741824) / 100</code> pixels
|-
| Actual Y visual noise
| <code>(SensoryNoiseY - 1073741824) / 100</code> pixels
|-
| Pre-noise task-logic cursor trajectory
| <code>TrueCursorX</code> and <code>TrueCursorY</code>
|-
| Displayed cursor trajectory
| <code>CursorX</code> and <code>CursorY</code>
|-
| Mapping switch
| <code>MappingSwitch == 1</code> (subject to skip-operation caveats)
|-
| Trials since switch
| <code>TrialsSinceMappingSwitch</code> (subject to skip-operation caveats)
|-
| Previous mapping
| Previous trial's <code>TaskCondition</code>
|-
| Prior context
| <code>PriorCondition</code>
|-
| Experimental block
| <code>TaskBlock</code>
|-
| Overall trial
| <code>TaskTrial</code>
|-
| Target angle
| <code>TargetAngle / 10</code> degrees
|-
| Target position
| <code>TargetX</code> and <code>TargetY</code>
|-
| Joystick trajectory
| <code>JoystickXpos</code> and <code>JoystickYpos</code>
|-
| Reaction time
| <code>ReactionTimeMs</code>
|-
| Movement time
| <code>MovementTimeMs</code>
|-
| Total time
| <code>TotalTimeMs</code>
|-
| Manual reset
| <code>TrialReset == 1</code>
|-
| Trial skipped
| <code>TrialSkipped == 1</code>
|-
| Current block skipped
| <code>ConditionSkipped == 1</code>
|-
| Introduction skipped
| <code>IntroductionSkipped == 1</code>
|-
| Sandbox skipped
| <code>SandboxSkipped == 1</code>
|-
| Task paused
| <code>TaskPaused == 1</code>
|-
| Experiment completion
| <code>TaskPhase == 7</code> in ordinary progression; may be absent for skip-to-finish
|}

===Event-Like States===

The following are designed to be one-processing-block event flags: <code>MappingSwitch</code>, <code>TargetHit</code>, <code>TrialReset</code>, <code>TrialSkipped</code>, <code>ConditionSkipped</code>, <code>IntroductionSkipped</code>, and <code>SandboxSkipped</code>. <code>MovementStarted</code> instead remains high from movement onset through the rest of the trial and Feedback. <code>TaskPaused</code> is a level state held at 1 throughout a pause.

===Analysis Considerations===

* Use <code>CursorX/Y</code> for what the participant saw and <code>TrueCursorX/Y</code> for the cursor that determined hits and centering. Visual noise and display clipping can make the two disagree.
* Divide cursor-state coordinates by 1023 to recover normalized coordinates. Use the provided noise-state offset and scale to recover noise in pixels.
* Use the recorded parameter <code>EnableSensoryReliability</code> to distinguish a disabled manipulation from genuine High-reliability trials.
* Reconstruct prior mapping by inspecting previous trials; <code>PriorCondition</code> is a block context rather than a previous-trial label or inferred belief.
* Check skip pulses and neighboring trial/block values when deriving event onsets. Mapping-switch pulses, trial identifiers, and <code>TaskPhase</code> may be stale or missing on early-return skip processing blocks.
* Paused intervals should be identified from <code>TaskPaused</code>, and internal timing measurements exclude pause duration on resume.
* If target acquisition occurs without a detected movement onset, reaction and movement timing states are zero but total time is recorded; such zero values should not automatically be interpreted as physiologically instantaneous responses.
* Raw joystick reconstruction requires external input logging; the application itself does not activate <code>LogJoystick</code>.

==Differences from USBHIDJoystickTask==

===Retained===

* BCI2000 <code>ApplicationBase</code> structure.
* USB joystick input.
* Center-out reaching.
* Center hold.
* Warning interval.
* Pre-target delay.
* Target-directed movement.
* Feedback interval.
* Continuous target-angle generation.
* Reaction-time measurement.
* Movement-time measurement.
* Total-time measurement.
* Manual trial reset.
* Progress bar.
* BCI2000 state logging.
* Direct and inverted joystick-control mappings.

===Removed===

The FEP task removes the earlier task's:

* <code>ExperimentMode</code>.
* Automatic-only and Controlled-only modes.
* Ordered-start condition.
* <code>TaskBlockType</code>.
* Green versus red condition-specific targets.
* Explicit condition instructions.
* Explicit teaching of the inverted mapping.
* Condition-specific practice trials.
* <code>PracticeTrial</code>.
* Optional tutorial setting.
* Diagnostic Continue button.
* Secondary CSV results file.
* Participant-facing block announcements.

===Added===

The FEP task adds:

* Six predefined experimental block roles.
* Hidden Normal and Inverted mappings.
* Unannounced mapping switches.
* <code>MappingSwitch</code>.
* <code>TrialsSinceMappingSwitch</code>.
* <code>PriorCondition</code>.
* <code>SensoryReliabilityCondition</code> and configurable High/Medium/Low visual sensory reliability.
* Configurable Gaussian cursor noise and correlation time.
* Separate <code>TrueCursorX/Y</code> and displayed <code>CursorX/Y</code> logging.
* <code>SensoryNoiseX/Y</code>, <code>SensoryNoiseStd</code>, and <code>SensoryNoiseSeedEffective</code>.
* Researcher controls for skipping trial, block, introduction, and sandbox, and pausing/resuming.
* <code>TrialSkipped</code>, <code>ConditionSkipped</code>, <code>IntroductionSkipped</code>, <code>SandboxSkipped</code>, and <code>TaskPaused</code> states.
* Configurable <code>CursorDiameterPixels</code> and <code>TargetDiameterPixels</code> parameters.
* Diagnostic real-time timing values and run averages.
* A minimal Normal-mapping sandbox.
* Black targets across all mapping conditions.
* Normal-dominant and approximately balanced mapping contexts.

==Known Limitations and Analysis Considerations==

* The current module does not implement an explicit computational Free Energy Principle model.
* <code>PriorCondition</code> represents experimental block context rather than an inferred participant belief.
* Participant surprise or expectation is not measured directly by the application.
* Blocks 4 and 6 use similar approximately balanced mapping-generation rules but occur after different preceding mapping histories.
* Mapping pseudorandomization constraints are attempted but are not guaranteed if all 64 candidate sequences fail.
* There is no unsuccessful-trial timeout.
* Reliability manipulation is disabled by default; <code>SensoryReliabilityCondition=0</code> by itself does not show that reliability was enabled.
* Reliability is assigned with a counterbalancing heuristic across mapping and switch status, not by a wholly independent shuffle.
* Gaussian noise affects the displayed cursor only during target-visible movement; it does not change the cursor position used for center and target-hit detection.
* The display may visually disagree with the target-hit decision because logic uses the true pre-noise cursor.
* The correlated noise process begins at zero at target onset rather than stationary variance.
* The true cursor is separately recorded, but no independent pre-mapping/untransformed cursor trajectory is recorded.
* The diagnostic window does not show target, joystick, cursor, switch, trials-since-switch, or free-form status fields; run averages are divided by Normal/Reversed mapping, not by reliability.
* <code>TargetDiameterPixels</code> changes target-hit radius; <code>CursorDiameterPixels</code> changes only cursor appearance.
* Skip operations can result in stale or missing per-block values for <code>MappingSwitch</code>, <code>TaskPhase</code>, and trial/block identifiers. Skip-to-finish may not publish <code>TaskPhase=7</code>.
* A block skip during Inverted target-visible movement does not explicitly preserve the anchored return mapping.
* Pausing is allowed during introduction, sandbox, and feedback, and the timing system compensates for pause duration on resume.
* Physical display geometry depends on the configured participant monitor and BCI2000 window dimensions.
* No application-specific CSV, JSON, text results file, or database is generated.

==References==

Friston, K. The free-energy principle: a unified brain theory?. Nat Rev Neurosci 11, 127–138 (2010). https://doi.org/10.1038/nrn2787

==See also==

* [[VisuomotorJoystickTask|Visuomotor Joystick Task]]
* [[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]]

* [[Category:User Application]]

VisuomotorJoystickTask

2026-10-19T15:36:59Z

Aes2376: Documenting new Jitter changes

==Synopsis==

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

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

The task also includes an optional participant introduction and practice sequence. Before the experiment begins, participants may receive task instructions, explore both normal and reversed cursor mappings, and complete automatic and controlled practice trials. Tutorial and practice periods are recorded in the BCI2000 data stream but remain separate from experimental trial numbering and experimental performance summaries.

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

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

<pre>
src/custom/usb_hid_joystick_task/
</pre>

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>

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

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

==Versioning==

===Author===

'''Alexander Speer'''

Friedman Lab, Department of Neurosurgery

Washington University in St. Louis

Developed in the Friedman Lab.

Contact: speer@wustl.edu

===Version History===

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

The current implementation includes:

* Automatic and controlled visuomotor conditions.
* Ordered and pseudorandom experimental blocks.
* Configurable trial counts and trial timing.
* An optional participant 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 visible performance metrics, tutorial controls, manual trial reset, researcher skip controls, and pause/resume.
* Trial-level reaction time, movement time, and total time measurements.
* Configurable cursor and target diameters, with target size affecting acquisition tolerance.
* Dedicated one-processing-block states for researcher skip events and a persistent pause state.
* Participant-facing Normal/Reversed terminology and condition cues, without changing automatic/controlled state encodings.
* Separation of tutorial/practice data from experimental trial numbering and run-summary metrics.
* Behavioral recording through synchronized BCI2000 states; this version does not create a separate results CSV.

The inspected development checkout contains the task under <code>src/custom/usb_hid_joystick_task</code> and has Git history through 2026-10-12 (commit <code>83404dd</code>).

===Source Code Revisions===

* Initial development: '''8/26/26'''
* Tested under (earlier revision): BCI2000 framework 3.6.9528.4, Release x64, MSVC 19.35
* Known to compile under: Visual Studio 2022 / MSVC 19.35 for a prior version of the current source
* Earlier documented source revision: '''9/1/26'''
* '''New version, 10/12/26:''' Latest inspected task commit <code>83404dd</code>. Added researcher pause/resume and skip controls with corresponding states, configurable cursor/target diameters, participant-facing Normal/Reversed labels and condition cues, and updated diagnostic metrics display; removed secondary CSV output and <code>ResultsFile</code>. Source moved to the inspected custom-module location and CMake target described above.
* Current inspected source revision: '''10/12/26''' (Git commit <code>83404dd</code>)
* Broken since: No known breaking revision

The earlier framework and compiler information above does not establish a successful build or runtime test of the 10/12/26 source revision; the present update is based on source comparison.

==Functional Description==

===Scientific Basis===

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

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

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

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

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

See [[#References|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. The participant sees Normal/Reversed wording for these conditions, while the experiment parameters and state names continue to use Automatic/Controlled identifiers.

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

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. The researcher '''CONTINUE''' control displays '''CONTINUE UNAVAILABLE''' when continuation is not permitted. The researcher can also use context-specific skip controls to bypass eligible tutorial stages; these actions are documented under [[#Researcher Skip Controls|Researcher Skip Controls]]. The task can be paused during tutorial stages.

===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.
* Practice activity is recorded in BCI2000 states; this application writes no separate trial-level CSV file.
* Practice results are excluded from experimental completion counts and timing summaries.
* Practice reset attempts do not increment experimental reset metrics.

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

===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 and performance summaries. Its states are recorded in the BCI2000 data stream; no secondary CSV is written.

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:

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

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 '''Normal''', '''Reversed''', or '''Mixed'''. These visible labels correspond to the existing automatic, controlled, and mixed block types; their numerical encodings are unchanged.

A trial then proceeds as follows:

# 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. Skipping an experimental trial instead advances to the next trial and generates a new target (unless the experiment has finished). A skip-block action advances past the remaining trials in the block.

===Automatic Condition (Normal)===

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

Automatic targets are displayed in green.

===Controlled Condition (Reversed)===

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

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

Conceptually:

<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. The participant sees Normal for <code>TaskCondition=0</code> and Reversed for <code>TaskCondition=1</code>; these labels do not change the state values.

===Participant Display===

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

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

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

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

''The Normal/Reversed cue is intentional in this USB HID task. The underlying state encoding remains <code>TaskCondition=0</code> for automatic/Normal and <code>TaskCondition=1</code> for controlled/Reversed.''

===Diagnostic Window===

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

* Normal or Reversed condition and trial numbering within the block and overall experiment.
* Real-time reaction time, movement time, and total time.
* Overall and condition-specific (automatic and controlled) mean timing measurements.

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

===Researcher Controls===

The diagnostic window contains a blue '''CONTINUE''' button on eligible tutorial screens. When continuation is unavailable, it displays '''CONTINUE UNAVAILABLE'''.

Its context-sensitive reset button displays:

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

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

===Researcher Skip Controls===

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

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

===Pause and Resume===

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

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

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

===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 generate a successful-trial event or count as a completed experimental trial.

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 increment experimental completed-trial metrics.

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

===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. The task writes no application-specific CSV. When the researcher pauses the task, clock offsets are adjusted on resume so that the reported RT, MT, and total time exclude the paused interval, even though the paused samples remain in the BCI2000 data stream.

===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.
* Automatic and controlled completion counts.
* Automatic and controlled reset counts.
* Mean reaction-time summaries.
* Mean movement-time summaries.
* Mean total-time summaries.

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

Researcher skip events (<code>TrialSkipped</code>, <code>ConditionSkipped</code>, <code>IntroductionSkipped</code>, <code>PracticeSkipped</code>, <code>SandboxSkipped</code>) and the persistent <code>TaskPaused</code> state are also recorded. They identify deviations from ordinary trial/tutorial progression and samples recorded during pause.

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

==Parameters==

Parameters for experimental structure, timing, and display are grouped under <code>Application:USBHIDJoystick</code> in the BCI2000 parameter tree. <code>EnableIntroduction</code>, <code>AutomaticPracticeTrials</code>, <code>ControlledPracticeTrials</code>, and <code>PracticeCenterHoldTime</code> are grouped under <code>Application:Introduction</code>. Existing parameter files should use the current group definitions.

===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>: Automatic/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.

===CursorDiameterPixels===

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

Type: floating point

Default: <code>16.0</code>

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

A positive value is required by preflight validation.

===TargetDiameterPixels===

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

Type: floating point

Default: <code>36.0</code>

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

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

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

==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 (participant-facing '''Normal''')
* <code>1</code>: Controlled (participant-facing '''Reversed''')

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

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

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, the target coordinate is written as <code>0</code> rather than retaining its initial value <code>512</code>; gate it by task phase and tutorial status during analysis.

===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, the target coordinate is written as <code>0</code> rather than retaining its initial value <code>512</code>; gate it by task phase and tutorial status during analysis.

===TaskBlock===

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

Initial value: <code>0</code>

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

<pre>
TaskBlock = 0
</pre>

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

<pre>
TaskBlock = 1
</pre>

Practice trials do not consume experimental block numbers.

===TaskTrial===

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

Initial value: <code>0</code>

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

<pre>
TaskTrial = 0
</pre>

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

<pre>
TaskTrial = 1
</pre>

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

Practice trials do not consume experimental trial numbers.

===MovementStarted===

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

Initial value: <code>0</code>

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

A rising transition from 0 to 1 identifies movement onset.

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

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

===TargetHit===

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

Initial value: <code>0</code>

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

Experimental acquisition:

<pre>
TargetHit == 1 and Introduction == 0
</pre>

Practice acquisition:

<pre>
TargetHit == 1 and Introduction == 1
</pre>

===TrialReset===

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

Initial value: <code>0</code>

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

Experimental reset:

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

Practice reset:

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

===TrialSkipped===

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

Initial value: <code>0</code>

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

===ConditionSkipped===

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

Initial value: <code>0</code>

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

===IntroductionSkipped===

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

Initial value: <code>0</code>

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

===PracticeSkipped===

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

Initial value: <code>0</code>

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

===SandboxSkipped===

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

Initial value: <code>0</code>

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

===TaskPaused===

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

Initial value: <code>0</code>

* <code>0</code>: Task running normally.
* <code>1</code>: Task paused; task progression is suspended, while the BCI2000 data stream continues.

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

===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>; check skip events when reconstructing completed trials
|-
| 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> on actual trials; non-trial tutorial screens set these to <code>0</code>
|-
| Target angle
| <code>TargetAngle</code>
|-
| Skipped experimental trial
| <code>TrialSkipped == 1</code>
|-
| Skipped experimental block remainder
| <code>ConditionSkipped == 1</code>
|-
| Introduction bypassed
| <code>IntroductionSkipped == 1</code>
|-
| Practice bypassed
| <code>PracticeSkipped == 1</code>
|-
| Free-movement sandbox bypassed
| <code>SandboxSkipped == 1</code>
|-
| Samples recorded while the task is paused
| <code>TaskPaused == 1</code>
|}

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

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>.
* Skip events mark incomplete trials or tutorial stages; skipped experimental trials do not produce <code>TargetHit</code> or increase completed-trial metrics.
* <code>ConditionSkipped</code> can cause the progress indicator and overall trial-position counter to jump across uncompleted trials.
* On a skip processing block, non-event states such as <code>TaskTrial</code>, <code>TaskBlock</code>, <code>TaskPhase</code>, and target coordinates may not update until the following block because skip dispatch returns before the normal state synchronization. A skip that finishes the run can leave final values at their pre-skip settings.
* Samples recorded during <code>TaskPaused=1</code> remain in the <code>.dat</code> stream. Exclude or flag them as appropriate; RT/MT/total-time values already exclude the pause duration.
* <code>TargetX</code> and <code>TargetY</code> are 0 during non-trial tutorial screens, not their initial 512 values.
* Condition names printed on screen and in console messages are Normal/Reversed, but the numeric <code>TaskCondition</code> codes remain Automatic=0 and Controlled=1.
* No application-specific CSV is created in the current version; reconstruct trial-level results from synchronized BCI2000 state recordings.

==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]]
* [[Category:User Application]]

BCI2000 to BIDS Converter

2026-09-29T00:03:34Z

Aes2376:

==Synopsis==

'''BCI2000 to BIDS Converter''' (<code>bci2000-bids</code>) is an open-source Python tool for converting BCI2000 <code>.dat</code> recordings into datasets organized according to the [https://bids.neuroimaging.io/ Brain Imaging Data Structure (BIDS)].

The converter reads signals, parameters, state definitions, and state values stored in a BCI2000 data file and maps them into BIDS-compatible electrophysiology, event, motion, and metadata files.

The converter supports:

* Behavioral/state-only BIDS datasets.
* EEG datasets.
* Intracranial EEG (iEEG) datasets, including ECoG, SEEG, and DBS recordings.
* Conversion of BCI2000 signal channels to EDF.
* Conversion of BCI2000 state transitions into <code>*_events.tsv</code>.
* Conversion of continuous BCI2000 states into BIDS motion files.
* Reusable JSON or YAML state-routing profiles.
* Automatic generation of review-required starter profiles.
* Conversion of multiple <code>.dat</code> files into sequential BIDS runs.
* Optional preservation of the original BCI2000 files in <code>sourcedata/</code>.
* SHA-256 checksums for preserved source recordings.
* Command-line and graphical interfaces.
* Optional validation using the [https://bids-standard.github.io/bids-validator/ BIDS Validator].

The converter is intended for offline organization and export of data that have already been recorded by BCI2000. It does not modify the original <code>.dat</code> recordings.

==Project Source==

The Python package and command-line program are named:

<pre>
bci2000-bids
</pre>

The Python import package is:

<pre>
bci2000_bids
</pre>

Source code:

[https://github.com/alexanderspeer/BCI2000-to-BIDS-Converter BCI2000 to BIDS Converter on GitHub]

The converter relies on BCI2000Tools for reading BCI2000 recordings. See [[BCI2000Tools.EventRelated|BCI2000Tools]] for information about BCI2000's Python tools.

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

Current software version: '''0.1.0'''

The initial implementation provides:

* Reading of BCI2000 <code>.dat</code> recordings using BCI2000Tools.
* Single-file and multi-file conversion.
* Deterministic BIDS run numbering.
* Behavioral, EEG, and iEEG output.
* EDF electrophysiology output.
* BIDS event generation from BCI2000 states.
* BIDS motion output from continuous BCI2000 states.
* JSON and YAML state-routing profiles.
* Automatic starter-profile generation.
* Source-file preservation and SHA-256 checksums.
* Staged conversion and protected publication of output datasets.
* Command-line interface.
* Tkinter graphical interface.
* Optional BIDS validation.

The software requires Python 3.10 or newer.

==Functional Description==

===BCI2000 Data Model===

A standard BCI2000 <code>.dat</code> file contains the recorded signal together with BCI2000 parameters and states. See [[Technical Reference:BCI2000 File Format|BCI2000 File Format]] for the complete native format specification.

The converter uses these components differently:

{| class="wikitable"
! BCI2000 information
! Use by the converter
|-
| Signal channels
| May be exported as BIDS EEG or iEEG electrophysiology data.
|-
| Sampling rate
| Used as the sampling frequency of the exported recording and motion data.
|-
| Channel names
| Used to name channels in the electrophysiology output.
|-
| Channel units
| Used when constructing the BIDS channel table and EDF output.
|-
| State definitions
| Used to identify states that may be mapped to events, event metadata, or continuous motion channels.
|-
| State samples
| Used to generate event timing and continuous motion data.
|-
| Parameters
| Used to obtain selected recording metadata such as sampling rate, channel names, channel units, application, signal source, and data format.
|}

Not every BCI2000 state or parameter is automatically exported. State routing is controlled by a conversion profile so that the scientific meaning of study-specific states remains under user control.

===Conversion Pipeline===

The overall conversion process is:

<pre>
BCI2000 .dat recording(s)
|
v
BCI2000Tools reader
|
+---- signal channels
|
+---- parameters
|
+---- state definitions and values
|
v
State-routing profile
|
+---- event states --------> *_events.tsv
|
+---- event metadata ------> additional event columns
|
+---- continuous states ---> motion/*.tsv
|
+---- ignored states
|
v
BIDS writers
|
+---- EEG/iEEG EDF
+---- channels.tsv
+---- JSON sidecars
+---- events.tsv
+---- motion files
+---- participants.tsv
+---- dataset_description.json
|
v
Optional BIDS validation
</pre>

For a normal conversion, the software:

# Loads the optional conversion configuration.
# Resolves subject, session, task, datatype, neural-export, preservation, and output settings.
# Normalizes BIDS labels.
# Discovers input <code>.dat</code> files.
# Sorts the files and assigns sequential BIDS run numbers.
# Loads the requested state-routing profile.
# If no profile is supplied, analyzes the first recording and generates a review-required starter profile.
# Creates a temporary staging dataset.
# Reads each BCI2000 recording.
# Extracts states referenced by the active profile.
# Generates BIDS events and/or motion data.
# Writes electrophysiology data if neural export is enabled.
# Optionally copies source data and calculates checksums.
# Optionally validates the staged BIDS dataset.
# Publishes the completed dataset.

The original <code>.dat</code> files are read-only during normal conversion.

==Supported Input==

===BCI2000 Files===

The converter accepts:

* A single BCI2000 <code>.dat</code> file.
* Multiple <code>.dat</code> files.
* A directory containing <code>.dat</code> files.
* A directory tree containing <code>.dat</code> files when recursive discovery is enabled.

For directory input, normal discovery searches the immediate directory.

Recursive discovery may be enabled with:

<pre>
--recursive
</pre>

Input recordings are sorted deterministically. Each discovered recording becomes a separate BIDS run beginning with <code>run-01</code>.

For example:

<pre>
recording1.dat -> run-01
recording2.dat -> run-02
recording3.dat -> run-03
</pre>

The converter does not currently infer recording groups from BCI2000 metadata. The supplied files are treated as recordings belonging to the subject/session/task selected for that conversion.

Duplicate source filenames are rejected even if the files originate from different directories.

===Reading BCI2000 Data===

BCI2000 files are opened using:

<pre>
BCI2000Tools.FileReader.bcistream
</pre>

The reader obtains:

* Parameters.
* State definitions.
* Sampling frequency.
* Number of samples.
* Number of channels.
* Channel names.
* Channel units.

Signal and state arrays are decoded when required by the requested conversion.

The sampling frequency is first obtained from the BCI2000 <code>SamplingRate</code> parameter. If that cannot be interpreted, the sampling frequency reported by the BCI2000Tools stream is used.

Channel names are normally obtained from:

<pre>
ChannelNames
</pre>

If valid channel names are unavailable, fallback names are generated:

<pre>
ch001
ch002
ch003
...
</pre>

Channel units are read from:

<pre>
SourceChUnits
</pre>

When units are unavailable for neural EDF output, the converter currently uses <code>uV</code> as the fallback unit.

The converter requests calibrated signal values from BCI2000Tools.

===Companion Files===

The current converter operates on information embedded in BCI2000 <code>.dat</code> files.

It does not automatically ingest companion files such as separate parameter files, video files, imaging files, or other study-specific files.

==BIDS Output==

===Supported BIDS Datatypes===

The converter currently supports:

{| class="wikitable"
! Datatype
! Purpose
! Neural export
|-
| <code>beh</code>
| Behavioral/state-only data
| No
|-
| <code>eeg</code>
| Scalp EEG recordings
| Yes
|-
| <code>ieeg</code>
| Intracranial electrophysiology
| Yes
|}

For iEEG conversion, the neural channel type may be specified as:

* <code>ECOG</code>
* <code>SEEG</code>
* <code>DBS</code>

Channels beginning with <code>ECG</code> or <code>EKG</code> are classified as ECG channels.

===Generated Dataset Structure===

A conversion containing iEEG, events, motion data, and preserved source data may produce a structure similar to:

<pre>
bids/
├── dataset_description.json
├── participants.tsv
├── participants.json
├── sub-001/
│ └── ses-01/
│ ├── ieeg/
│ │ ├── sub-001_ses-01_task-motor_run-01_ieeg.edf
│ │ ├── sub-001_ses-01_task-motor_run-01_ieeg.json
│ │ ├── sub-001_ses-01_task-motor_run-01_channels.tsv
│ │ ├── sub-001_ses-01_task-motor_run-01_events.tsv
│ │ └── sub-001_ses-01_task-motor_run-01_events.json
│ └── motion/
│ ├── sub-001_ses-01_task-motor_run-01_tracksys-unknown_motion.tsv
│ ├── sub-001_ses-01_task-motor_run-01_tracksys-unknown_motion.json
│ └── sub-001_ses-01_task-motor_run-01_tracksys-unknown_channels.tsv
├── sourcedata/
│ └── sub-001/
│ └── ses-01/
│ └── bci2000/
│ ├── recording.dat
│ └── checksums.tsv
└── code/
└── bci2000-bids/
└── auto-profile-motor.json
</pre>

The <code>code/bci2000-bids/auto-profile-*.json</code> file is generated only when automatic profile generation is used.

Behavioral-only conversion does not create a placeholder electrophysiology file.

===Dataset-Level Files===

The converter creates or maintains:

* <code>dataset_description.json</code>
* <code>participants.tsv</code>
* <code>participants.json</code>

The generated dataset description identifies the dataset as raw BIDS data and records <code>bci2000-bids</code> as conversion software.

The implementation writes BIDS version:

<pre>
1.10.1
</pre>

The participant table initially contains the BIDS participant identifier.

Study-specific clinical information is not automatically inferred from BCI2000 recordings.

==BCI2000 State Profiles==

===Purpose===

BCI2000 applications may define many study-specific states. Their names alone are not sufficient to determine their scientific meaning.

For this reason, the converter uses a '''state-routing profile''' to determine how states should be represented in BIDS.

Profiles may be written in:

* JSON.
* YAML.

A state may be assigned to:

* An event.
* An additional event column.
* A continuous motion channel.
* The ignore list.

A state should not be assigned to multiple routing categories.

===Example Profile===

A simple profile may look like:

<pre>
name: generic-motion

metadata:
tracking_system: unknown

events:
Marker:
strategy: rising_edge
trial_type: marker

motion:
PositionX:
column: position_x
type: POSITION
units: arbitrary

ignore:
- SourceTime
</pre>

In this example:

* <code>Marker</code> creates BIDS event rows.
* <code>PositionX</code> becomes a continuous BIDS motion channel.
* <code>SourceTime</code> is deliberately ignored.

===Profile Validation===

Profiles are checked before conversion.

Invalid profiles include cases such as:

* Invalid JSON or YAML.
* Unsupported event strategies.
* Duplicate state routing.
* Invalid event-column definitions.
* Duplicate event-column names.
* Reserved event-column names.
* Invalid motion definitions.
* Invalid metadata structures.

The standard BIDS event fields:

<pre>
onset
duration
trial_type
</pre>

are reserved and cannot be redefined as custom event columns.

==Automatic Profile Generation==

If a profile is not supplied, the converter may inspect the first recording and create a starter profile.

The automatic profile generator examines properties such as:

* State name.
* State bit width.
* Minimum value.
* Maximum value.
* Number of unique values.
* Number of transitions.
* Transition fraction.
* Number of nonzero samples.
* Percentage of nonzero samples.

States with names suggesting continuously varying signals such as joystick, cursor, gaze, position, or similar values may be proposed as motion channels.

Low-cardinality or event-like states may be proposed as events.

Internal-looking states such as:

* <code>SourceTime</code>
* <code>Running</code>
* <code>Recording</code>

may be proposed for exclusion.

Automatically generated profiles contain:

<pre>
"review_required": true
</pre>

and are saved inside the BIDS dataset under:

<pre>
code/bci2000-bids/
</pre>

'''Automatically generated profiles are suggestions and should be reviewed before scientific use.''' The converter cannot determine the experimental meaning of a state from its name or numeric behavior alone.

==Event Conversion==

BCI2000 states may be converted into BIDS <code>*_events.tsv</code> rows.

The base event table contains:

<pre>
onset duration trial_type
</pre>

Onsets and durations are expressed in seconds.

===Event Strategies===

The following event strategies are supported:

{| class="wikitable"
! Strategy
! Behavior
|-
| <code>rising_edge</code>
| Creates an event when the state changes from zero to nonzero.
|-
| <code>falling_edge</code>
| Creates an event when the state changes from nonzero to zero.
|-
| <code>change</code>
| Creates an event whenever the state value changes.
|-
| <code>value_change</code>
| Creates an event whenever the state value changes.
|-
| <code>nonzero_change</code>
| Creates an event when a transition results in a nonzero value.
|-
| <code>interval</code>
| Treats each continuous nonzero period as an event interval.
|}

Edge and value-change events have zero duration.

For <code>interval</code>, the duration corresponds to the length of the contiguous nonzero period.

===Additional Event Columns===

Other BCI2000 states may be mapped as additional columns associated with generated events.

For example, a task may use one state to trigger an event while states such as condition, target, block, response type, or trial number are sampled at that event and placed into additional TSV columns.

Additional nonstandard columns are described in the corresponding <code>*_events.json</code> sidecar.

An additional event-column mapping by itself does not create an event. An event rule must first define when event rows are generated.

==Motion and Continuous State Conversion==

Continuously varying BCI2000 states may be written to the BIDS <code>motion/</code> directory.

Examples may include states representing:

* Joystick position.
* Cursor position.
* Eye position.
* Gaze position.
* Limb position.
* Other continuous task or kinematic variables.

The converter does not determine these meanings automatically during normal conversion. The user specifies them through the state-routing profile.

A typical motion output consists of:

<pre>
sub-001_ses-01_task-motor_run-01_tracksys-unknown_motion.tsv
sub-001_ses-01_task-motor_run-01_tracksys-unknown_motion.json
sub-001_ses-01_task-motor_run-01_tracksys-unknown_channels.tsv
</pre>

The motion TSV is headerless.

Column information is stored in the motion channels TSV:

<pre>
name type units description
</pre>

A motion mapping may define:

* Column name.
* Motion type.
* Units.
* Description.

The associated JSON sidecar records information such as:

* Sampling frequency.
* Start time.
* Column order.
* Tracking-system name.

All motion states in one output file must contain the same number of samples.

==Neural Signal Conversion==

When neural export is enabled, BCI2000 signal channels are exported as EDF.

The converter currently supports:

* EEG EDF output.
* iEEG EDF output.

The BCI2000 signal matrix is read with calibration gains applied and converted into the orientation required by the output writer.

A corresponding BIDS channel table contains:

<pre>
name type units
</pre>

For EEG, channels normally use the BIDS channel type:

<pre>
EEG
</pre>

For iEEG, the channel type is selected from:

<pre>
ECOG
SEEG
DBS
</pre>

The electrophysiology JSON sidecar includes information such as:

* Task name.
* Sampling frequency.
* Recording duration.
* Reference.
* Source system.
* Conversion software.

The source system is identified as:

<pre>
BCI2000
</pre>

The conversion software is identified as:

<pre>
bci2000-bids
</pre>

==Installation==

===Requirements===

Python '''3.10 or newer''' is required.

The primary Python dependencies are:

* <code>numpy</code>
* <code>pyEDFlib</code>
* <code>PyYAML</code>
* <code>BCI2000Tools</code>

Tkinter is required for the graphical interface.

===Recommended Installation===

From a local checkout of the repository, create a Python virtual environment.

On macOS or Linux:

<pre>
python3 -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install -e .
</pre>

On Windows PowerShell:

<pre>
py -3.14 -m venv .venv
.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install -e .
</pre>

The package also defines installation extras for BCI2000 and YAML support:

<pre>
python -m pip install -e ".[yaml,bci2000]"
</pre>

For development:

<pre>
python -m pip install -e ".[yaml,bci2000,dev]"
</pre>

On Debian or Ubuntu systems, Tkinter may need to be installed separately:

<pre>
sudo apt install python3-tk
</pre>

The external BIDS Validator is not installed automatically with the Python package.

==Graphical Interface==

The graphical interface may be launched with:

<pre>
bci2000-bids-gui
</pre>

or:

<pre>
python -m bci2000_bids.gui
</pre>

It may also be launched from the main command:

<pre>
bci2000-bids gui
</pre>

The GUI supports:

* Selecting one or more <code>.dat</code> files.
* Selecting an input directory.
* Recursive input discovery.
* Selecting a BIDS output directory.
* Subject label entry.
* Session label entry.
* Task label entry.
* Behavioral, EEG, or iEEG datatype selection.
* ECoG, SEEG, or DBS iEEG channel-type selection.
* Enabling or disabling neural export.
* Loading an existing profile.
* Creating a profile using an interactive state-routing editor.
* Automatic starter-profile generation.
* Source preservation.
* SHA-256 checksum generation.
* Existing-output policy selection.
* Recording inspection.
* Dry runs.
* Conversion.
* Optional BIDS validation.
* Progress and status reporting.

The default GUI configuration uses:

* Session <code>01</code>.
* Datatype <code>beh</code>.
* Neural export disabled.
* BIDS validation enabled.
* Existing-output policy <code>error</code>.

==Command-Line Interface==

The command-line program is:

<pre>
bci2000-bids
</pre>

The equivalent module invocation is:

<pre>
python -m bci2000_bids
</pre>

The primary commands are:

<pre>
inspect
convert
profile
validate
gui
</pre>

===Inspect===

To inspect one BCI2000 recording without converting it:

<pre>
bci2000-bids inspect recording.dat
</pre>

Inspection reports information including:

* File name.
* Resolved path.
* Recording duration.
* Sampling frequency.
* Number of channels.
* Number of samples.
* Channel names.
* State names.
* State bit widths.
* Selected BCI2000 parameters.

Selected parameters include:

* <code>SamplingRate</code>
* <code>DataFormat</code>
* <code>Application</code>
* <code>SignalSource</code>
* <code>ChannelNames</code>
* <code>SourceChUnits</code>

===Generate a Profile===

A starter state-routing profile may be generated with:

<pre>
bci2000-bids profile recording.dat --output profile.json
</pre>

If <code>--output</code> is omitted, the generated JSON profile is printed to standard output.

The profile should be reviewed before conversion.

===Basic Conversion===

A basic iEEG conversion is:

<pre>
bci2000-bids convert recording.dat \
--output bids \
--subject 001 \
--session 01 \
--task motor \
--datatype ieeg \
--channel-type ECOG
</pre>

===Behavioral/State-Only Conversion===

To convert states without neural data:

<pre>
bci2000-bids convert recording.dat \
--output bids \
--subject 001 \
--session 01 \
--task motor \
--datatype beh \
--no-neural \
--profile profile.json
</pre>

===Directory Conversion===

To recursively discover BCI2000 files:

<pre>
bci2000-bids convert incoming/ \
--output bids/ \
--subject 001 \
--session 01 \
--task motor \
--datatype eeg \
--recursive
</pre>

===Source Preservation===

To retain the original BCI2000 recordings:

<pre>
bci2000-bids convert recording.dat \
--output bids \
--subject 001 \
--session 01 \
--task motor \
--datatype ieeg \
--channel-type ECOG \
--profile profile.json \
--preserve-source
</pre>

===Validation During Conversion===

To run BIDS validation before publishing the converted dataset:

<pre>
bci2000-bids convert recording.dat \
--output bids \
--subject 001 \
--session 01 \
--task motor \
--datatype ieeg \
--channel-type ECOG \
--validate
</pre>

===Dry Run===

A conversion may be checked without publishing the final dataset using:

<pre>
--dry-run
</pre>

A dry run performs discovery, profile/configuration resolution, run assignment, and destination checking without publishing the final converted dataset.

===Debug Logging===

The global debugging option is:

<pre>
bci2000-bids --debug ...
</pre>

<code>--debug</code> must appear before the subcommand.

==Typical Workflow==

A typical command-line workflow is:

===1. Inspect the recording===

<pre>
bci2000-bids inspect recording.dat
</pre>

===2. Generate a starter profile===

<pre>
bci2000-bids profile recording.dat --output profile.json
</pre>

===3. Review the profile===

Inspect the generated state mappings and confirm that each BCI2000 state has been assigned to the correct scientific role.

In particular, confirm which states represent:

* Experimental events.
* Event metadata.
* Continuous behavioral or motion signals.
* States that should be ignored.

===4. Perform a dry run===

<pre>
bci2000-bids convert recording.dat \
--output bids \
--subject 001 \
--session 01 \
--task motor \
--datatype ieeg \
--channel-type ECOG \
--profile profile.json \
--dry-run
</pre>

===5. Convert===

<pre>
bci2000-bids convert recording.dat \
--output bids \
--subject 001 \
--session 01 \
--task motor \
--datatype ieeg \
--channel-type ECOG \
--profile profile.json \
--preserve-source
</pre>

===6. Validate===

<pre>
bci2000-bids validate bids/
</pre>

==Configuration Files==

In addition to state-routing profiles, general conversion settings may be stored in JSON or YAML configuration files.

A configuration may contain fields such as:

* Subject.
* Session.
* Task.
* Datatype.
* Neural export.
* iEEG channel type.
* Source preservation.
* Existing-output behavior.
* Profile path.

For example:

<pre>
subject: "001"
session: "01"
task: "motor"
datatype: "beh"
preserve_source: true
profile: "generic-motion.yaml"
</pre>

A configuration may be supplied with:

<pre>
bci2000-bids convert recording.dat \
--output bids \
--config examples/configs/study.yaml
</pre>

Command-line configuration handling is still under development. Explicit <code>--subject</code> and <code>--task</code> arguments should currently be supplied for reliable noninteractive CLI use.

==Existing Output Handling==

The converter protects existing BIDS data by default.

The existing-output policy may be selected using:

<pre>
--on-existing
</pre>

Supported values are:

{| class="wikitable"
! Value
! Behavior
|-
| <code>error</code>
| Default. Stop if the target subject/session already exists.
|-
| <code>skip</code>
| Leave the existing subject/session unchanged and skip conversion.
|-
| <code>overwrite</code>
| Rebuild the requested subject/session while retaining other dataset content.
|}

The default policy is:

<pre>
error
</pre>

==Source Data Preservation==

When:

<pre>
--preserve-source
</pre>

is enabled, the original BCI2000 recording is copied to:

<pre>
sourcedata/sub-<subject>/ses-<session>/bci2000/
</pre>

For example:

<pre>
sourcedata/sub-001/ses-01/bci2000/recording.dat
</pre>

A SHA-256 checksum manifest is written as:

<pre>
sourcedata/sub-001/ses-01/bci2000/checksums.tsv
</pre>

with columns:

<pre>
filename sha256
</pre>

The preserved BCI2000 files are copies of the original recordings and are '''not anonymized by the converter'''.

Users should therefore review BCI2000 parameters and other source metadata before distributing <code>sourcedata/</code> outside the research environment.

==Data Safety==

Conversions are built in a temporary staging directory rather than directly modifying the published BIDS dataset.

When updating an existing dataset:

# The current dataset is copied into a staging location.
# New conversion output is created in staging.
# Validation may be performed against the staged dataset.
# The original dataset is retained until processing succeeds.
# The staged dataset is moved into place after successful conversion.

When replacement of an existing output root is necessary, the current output is temporarily renamed to a backup location before publication of the staged dataset.

If publication fails, the converter attempts to restore the previous dataset.

EDF files are also created through temporary output before final replacement.

Additional input checks include rejection of:

* Duplicate input basenames.
* Invalid subject labels.
* Invalid session labels.
* Invalid task labels.
* Invalid tracking-system names.
* Invalid iEEG channel types.
* Missing states required by a profile.
* Invalid signal dimensions.
* Duplicate or invalid EDF channel labels.
* Nonfinite neural samples.
* Certain EDF-incompatible signal conditions.

==BIDS Validation==

The converter includes an optional validation step.

To validate an existing converted dataset:

<pre>
bci2000-bids validate bids/
</pre>

The converter first performs basic internal checks, including confirming that:

<pre>
dataset_description.json
</pre>

exists and contains valid JSON.

When available, it then invokes the external BIDS Validator.

The [https://bids-standard.github.io/bids-validator/ official BIDS Validator] may also be used independently.

When validation is enabled during conversion, validation occurs against the staged dataset before it is published. A validation failure therefore prevents the invalid staged conversion from replacing the existing output dataset.

The external validator must currently be installed separately.

==Clinical and Participant Metadata==

The converter currently handles operational BIDS identifiers and recording metadata such as:

* Participant identifier.
* Session identifier.
* Task.
* Datatype.
* Run number.
* Sampling frequency.
* Recording duration.
* Channel names.
* Channel units.
* Neural channel type.
* Reference information.
* Motion tracking-system name.

The converter does '''not''' currently automatically extract or request study-specific clinical metadata such as:

* Diagnosis.
* Age.
* Sex.
* Handedness.
* Surgical procedure.
* Medication state.
* DBS stimulation state.
* Implant target.
* Recording location.
* Participant name.
* Medical record number.
* Date of birth.

Such metadata must be handled separately when required by a study.

==Limitations==

The current version is focused specifically on converting BCI2000 recordings and synchronized states into electrophysiology, behavioral, event, and motion components of BIDS.

The following are not currently supported:

* Imaging conversion.
* Video conversion.
* NeuroOmega file conversion.
* Automatic ingestion of BCI2000 companion files.
* Modalities other than <code>beh</code>, <code>eeg</code>, and <code>ieeg</code>.
* BrainVision output.
* FIF output.
* NIfTI output.
* Automatic grouping of recordings using BCI2000 recording metadata.
* Comprehensive export of every BCI2000 parameter into BIDS metadata.
* Automatic extraction of clinical or surgical metadata.
* Automatic anonymization of preserved BCI2000 source files.
* Automatic generation of <code>.bidsignore</code>.
* General provenance manifests beyond source checksums and generated conversion profiles.

Automatic state classification is heuristic and should not be treated as a substitute for knowledge of the experiment.

==Development and Testing==

The project contains unit and integration tests for core conversion functionality.

Current automated testing covers areas including:

* BIDS dataset initialization.
* Dataset descriptions.
* Participant-table creation.
* BIDS label normalization.
* BIDS run naming.
* Rising-edge event generation.
* Interval event generation.
* State-change event generation.
* Motion TSV output.
* Motion channel definitions.
* Duplicate state-routing rejection.
* BCI2000 parameter parsing utilities.
* Deterministic input discovery.
* Recursive input discovery.
* Synthetic state/event conversion.
* Synthetic iEEG EDF conversion.
* EDF read-back using pyEDFlib.
* Missing-unit fallback behavior.

The current integration tests use synthetic/mock BCI2000 recordings rather than decoding real clinical or experimental BCI2000 files.

Real BCI2000 files should therefore be tested and reviewed in the intended research environment before relying on a new conversion workflow for production datasets.

==BIDS Background==

[https://bids.neuroimaging.io/ BIDS] is a community-developed standard for organizing neural and associated experimental data in a consistent filesystem structure.

A typical BIDS hierarchy follows the general form:

<pre>
dataset/
└── sub-<subject>/
└── ses-<session>/
└── <datatype>/
</pre>

Within this structure, file names encode entities such as subject, session, task, and run.

The BCI2000 to BIDS Converter performs this transformation automatically for supported BCI2000 data while retaining synchronization between neural signals and selected BCI2000 states.

For the complete standard, see the [https://bids-specification.readthedocs.io/en/stable/ BIDS Specification].

==References==

# Gorgolewski KJ, Auer T, Calhoun VD, et al. [https://doi.org/10.1038/sdata.2016.44 The brain imaging data structure, a format for organizing and describing outputs of neuroimaging experiments]. ''Scientific Data''. 2016;3:160044. doi:10.1038/sdata.2016.44.
# [https://bids.neuroimaging.io/ Brain Imaging Data Structure (BIDS)].
# [https://bids-specification.readthedocs.io/en/stable/ BIDS Specification].
# [https://bids-standard.github.io/bids-validator/ BIDS Validator].
# frederik-lam. [https://github.com/Cybernetics-and-Motor-Physiology-Lab/BCI2000-BIDS_converter BCI2000-BIDS_converter]. Cybernetics-and-Motor-Physiology-Lab. MATLAB-based framework for converting BCI2000 <code>.dat</code> recordings into BIDS-compatible electrophysiology datasets.

==See also==

* [[Technical Reference:BCI2000 File Format|BCI2000 File Format]]
* [[User Reference:Data File Formats|BCI2000 Data File Formats]]
* [[User Reference:BCI2000Export|BCI2000Export]]
* [[User Reference:Command Line Processing|BCI2000 Command Line Processing]]
* [[BCI2000Tools.EventRelated|BCI2000Tools and Python Data Analysis]]
* [[User Tutorial:Data Analysis|BCI2000 Data Analysis Tutorials]]
* [https://bids.neuroimaging.io/ Brain Imaging Data Structure]
* [https://bids-specification.readthedocs.io/en/stable/ BIDS Specification]
* [https://bids-standard.github.io/bids-validator/ BIDS Validator]

[[Category:Data Analysis Tools]]

BCI2000 to BIDS Converter

2026-09-28T23:58:39Z

Aes2376: Created page with "==Synopsis== '''BCI2000 to BIDS Converter''' (<code>bci2000-bids</code>) is an open-source Python tool for converting BCI2000 <code>.dat</code> recordings into datasets organized according to the [https://bids.neuroimaging.io/ Brain Imaging Data Structure (BIDS)]. The converter reads signals, parameters, state definitions, and state values stored in a BCI2000 data file and maps them into BIDS-compatible electrophysiology, event, motion, and metadata files. The convert..."

==Synopsis==

'''BCI2000 to BIDS Converter''' (<code>bci2000-bids</code>) is an open-source Python tool for converting BCI2000 <code>.dat</code> recordings into datasets organized according to the [https://bids.neuroimaging.io/ Brain Imaging Data Structure (BIDS)].

The converter reads signals, parameters, state definitions, and state values stored in a BCI2000 data file and maps them into BIDS-compatible electrophysiology, event, motion, and metadata files.

The converter supports:

* Behavioral/state-only BIDS datasets.
* EEG datasets.
* Intracranial EEG (iEEG) datasets, including ECoG, SEEG, and DBS recordings.
* Conversion of BCI2000 signal channels to EDF.
* Conversion of BCI2000 state transitions into <code>*_events.tsv</code>.
* Conversion of continuous BCI2000 states into BIDS motion files.
* Reusable JSON or YAML state-routing profiles.
* Automatic generation of review-required starter profiles.
* Conversion of multiple <code>.dat</code> files into sequential BIDS runs.
* Optional preservation of the original BCI2000 files in <code>sourcedata/</code>.
* SHA-256 checksums for preserved source recordings.
* Command-line and graphical interfaces.
* Optional validation using the [https://bids-standard.github.io/bids-validator/ BIDS Validator].

The converter is intended for offline organization and export of data that have already been recorded by BCI2000. It does not modify the original <code>.dat</code> recordings.

==Project Source==

The Python package and command-line program are named:

<pre>
bci2000-bids
</pre>

The Python import package is:

<pre>
bci2000_bids
</pre>



The converter relies on BCI2000Tools for reading BCI2000 recordings. See [[BCI2000Tools.EventRelated|BCI2000Tools]] for information about BCI2000's Python tools.

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

Current software version: '''0.1.0'''

The initial implementation provides:

* Reading of BCI2000 <code>.dat</code> recordings using BCI2000Tools.
* Single-file and multi-file conversion.
* Deterministic BIDS run numbering.
* Behavioral, EEG, and iEEG output.
* EDF electrophysiology output.
* BIDS event generation from BCI2000 states.
* BIDS motion output from continuous BCI2000 states.
* JSON and YAML state-routing profiles.
* Automatic starter-profile generation.
* Source-file preservation and SHA-256 checksums.
* Staged conversion and protected publication of output datasets.
* Command-line interface.
* Tkinter graphical interface.
* Optional BIDS validation.

The software requires Python 3.10 or newer.

==Functional Description==

===BCI2000 Data Model===

A standard BCI2000 <code>.dat</code> file contains the recorded signal together with BCI2000 parameters and states. See [[Technical Reference:BCI2000 File Format|BCI2000 File Format]] for the complete native format specification.

The converter uses these components differently:

{| class="wikitable"
! BCI2000 information
! Use by the converter
|-
| Signal channels
| May be exported as BIDS EEG or iEEG electrophysiology data.
|-
| Sampling rate
| Used as the sampling frequency of the exported recording and motion data.
|-
| Channel names
| Used to name channels in the electrophysiology output.
|-
| Channel units
| Used when constructing the BIDS channel table and EDF output.
|-
| State definitions
| Used to identify states that may be mapped to events, event metadata, or continuous motion channels.
|-
| State samples
| Used to generate event timing and continuous motion data.
|-
| Parameters
| Used to obtain selected recording metadata such as sampling rate, channel names, channel units, application, signal source, and data format.
|}

Not every BCI2000 state or parameter is automatically exported. State routing is controlled by a conversion profile so that the scientific meaning of study-specific states remains under user control.

===Conversion Pipeline===

The overall conversion process is:

<pre>
BCI2000 .dat recording(s)
|
v
BCI2000Tools reader
|
+---- signal channels
|
+---- parameters
|
+---- state definitions and values
|
v
State-routing profile
|
+---- event states --------> *_events.tsv
|
+---- event metadata ------> additional event columns
|
+---- continuous states ---> motion/*.tsv
|
+---- ignored states
|
v
BIDS writers
|
+---- EEG/iEEG EDF
+---- channels.tsv
+---- JSON sidecars
+---- events.tsv
+---- motion files
+---- participants.tsv
+---- dataset_description.json
|
v
Optional BIDS validation
</pre>

For a normal conversion, the software:

# Loads the optional conversion configuration.
# Resolves subject, session, task, datatype, neural-export, preservation, and output settings.
# Normalizes BIDS labels.
# Discovers input <code>.dat</code> files.
# Sorts the files and assigns sequential BIDS run numbers.
# Loads the requested state-routing profile.
# If no profile is supplied, analyzes the first recording and generates a review-required starter profile.
# Creates a temporary staging dataset.
# Reads each BCI2000 recording.
# Extracts states referenced by the active profile.
# Generates BIDS events and/or motion data.
# Writes electrophysiology data if neural export is enabled.
# Optionally copies source data and calculates checksums.
# Optionally validates the staged BIDS dataset.
# Publishes the completed dataset.

The original <code>.dat</code> files are read-only during normal conversion.

==Supported Input==

===BCI2000 Files===

The converter accepts:

* A single BCI2000 <code>.dat</code> file.
* Multiple <code>.dat</code> files.
* A directory containing <code>.dat</code> files.
* A directory tree containing <code>.dat</code> files when recursive discovery is enabled.

For directory input, normal discovery searches the immediate directory.

Recursive discovery may be enabled with:

<pre>
--recursive
</pre>

Input recordings are sorted deterministically. Each discovered recording becomes a separate BIDS run beginning with <code>run-01</code>.

For example:

<pre>
recording1.dat -> run-01
recording2.dat -> run-02
recording3.dat -> run-03
</pre>

The converter does not currently infer recording groups from BCI2000 metadata. The supplied files are treated as recordings belonging to the subject/session/task selected for that conversion.

Duplicate source filenames are rejected even if the files originate from different directories.

===Reading BCI2000 Data===

BCI2000 files are opened using:

<pre>
BCI2000Tools.FileReader.bcistream
</pre>

The reader obtains:

* Parameters.
* State definitions.
* Sampling frequency.
* Number of samples.
* Number of channels.
* Channel names.
* Channel units.

Signal and state arrays are decoded when required by the requested conversion.

The sampling frequency is first obtained from the BCI2000 <code>SamplingRate</code> parameter. If that cannot be interpreted, the sampling frequency reported by the BCI2000Tools stream is used.

Channel names are normally obtained from:

<pre>
ChannelNames
</pre>

If valid channel names are unavailable, fallback names are generated:

<pre>
ch001
ch002
ch003
...
</pre>

Channel units are read from:

<pre>
SourceChUnits
</pre>

When units are unavailable for neural EDF output, the converter currently uses <code>uV</code> as the fallback unit.

The converter requests calibrated signal values from BCI2000Tools.

===Companion Files===

The current converter operates on information embedded in BCI2000 <code>.dat</code> files.

It does not automatically ingest companion files such as separate parameter files, video files, imaging files, or other study-specific files.

==BIDS Output==

===Supported BIDS Datatypes===

The converter currently supports:

{| class="wikitable"
! Datatype
! Purpose
! Neural export
|-
| <code>beh</code>
| Behavioral/state-only data
| No
|-
| <code>eeg</code>
| Scalp EEG recordings
| Yes
|-
| <code>ieeg</code>
| Intracranial electrophysiology
| Yes
|}

For iEEG conversion, the neural channel type may be specified as:

* <code>ECOG</code>
* <code>SEEG</code>
* <code>DBS</code>

Channels beginning with <code>ECG</code> or <code>EKG</code> are classified as ECG channels.

===Generated Dataset Structure===

A conversion containing iEEG, events, motion data, and preserved source data may produce a structure similar to:

<pre>
bids/
├── dataset_description.json
├── participants.tsv
├── participants.json
├── sub-001/
│ └── ses-01/
│ ├── ieeg/
│ │ ├── sub-001_ses-01_task-motor_run-01_ieeg.edf
│ │ ├── sub-001_ses-01_task-motor_run-01_ieeg.json
│ │ ├── sub-001_ses-01_task-motor_run-01_channels.tsv
│ │ ├── sub-001_ses-01_task-motor_run-01_events.tsv
│ │ └── sub-001_ses-01_task-motor_run-01_events.json
│ └── motion/
│ ├── sub-001_ses-01_task-motor_run-01_tracksys-unknown_motion.tsv
│ ├── sub-001_ses-01_task-motor_run-01_tracksys-unknown_motion.json
│ └── sub-001_ses-01_task-motor_run-01_tracksys-unknown_channels.tsv
├── sourcedata/
│ └── sub-001/
│ └── ses-01/
│ └── bci2000/
│ ├── recording.dat
│ └── checksums.tsv
└── code/
└── bci2000-bids/
└── auto-profile-motor.json
</pre>

The <code>code/bci2000-bids/auto-profile-*.json</code> file is generated only when automatic profile generation is used.

Behavioral-only conversion does not create a placeholder electrophysiology file.

===Dataset-Level Files===

The converter creates or maintains:

* <code>dataset_description.json</code>
* <code>participants.tsv</code>
* <code>participants.json</code>

The generated dataset description identifies the dataset as raw BIDS data and records <code>bci2000-bids</code> as conversion software.

The implementation writes BIDS version:

<pre>
1.10.1
</pre>

The participant table initially contains the BIDS participant identifier.

Study-specific clinical information is not automatically inferred from BCI2000 recordings.

==BCI2000 State Profiles==

===Purpose===

BCI2000 applications may define many study-specific states. Their names alone are not sufficient to determine their scientific meaning.

For this reason, the converter uses a '''state-routing profile''' to determine how states should be represented in BIDS.

Profiles may be written in:

* JSON.
* YAML.

A state may be assigned to:

* An event.
* An additional event column.
* A continuous motion channel.
* The ignore list.

A state should not be assigned to multiple routing categories.

===Example Profile===

A simple profile may look like:

<pre>
name: generic-motion

metadata:
tracking_system: unknown

events:
Marker:
strategy: rising_edge
trial_type: marker

motion:
PositionX:
column: position_x
type: POSITION
units: arbitrary

ignore:
- SourceTime
</pre>

In this example:

* <code>Marker</code> creates BIDS event rows.
* <code>PositionX</code> becomes a continuous BIDS motion channel.
* <code>SourceTime</code> is deliberately ignored.

===Profile Validation===

Profiles are checked before conversion.

Invalid profiles include cases such as:

* Invalid JSON or YAML.
* Unsupported event strategies.
* Duplicate state routing.
* Invalid event-column definitions.
* Duplicate event-column names.
* Reserved event-column names.
* Invalid motion definitions.
* Invalid metadata structures.

The standard BIDS event fields:

<pre>
onset
duration
trial_type
</pre>

are reserved and cannot be redefined as custom event columns.

==Automatic Profile Generation==

If a profile is not supplied, the converter may inspect the first recording and create a starter profile.

The automatic profile generator examines properties such as:

* State name.
* State bit width.
* Minimum value.
* Maximum value.
* Number of unique values.
* Number of transitions.
* Transition fraction.
* Number of nonzero samples.
* Percentage of nonzero samples.

States with names suggesting continuously varying signals such as joystick, cursor, gaze, position, or similar values may be proposed as motion channels.

Low-cardinality or event-like states may be proposed as events.

Internal-looking states such as:

* <code>SourceTime</code>
* <code>Running</code>
* <code>Recording</code>

may be proposed for exclusion.

Automatically generated profiles contain:

<pre>
"review_required": true
</pre>

and are saved inside the BIDS dataset under:

<pre>
code/bci2000-bids/
</pre>

'''Automatically generated profiles are suggestions and should be reviewed before scientific use.''' The converter cannot determine the experimental meaning of a state from its name or numeric behavior alone.

==Event Conversion==

BCI2000 states may be converted into BIDS <code>*_events.tsv</code> rows.

The base event table contains:

<pre>
onset duration trial_type
</pre>

Onsets and durations are expressed in seconds.

===Event Strategies===

The following event strategies are supported:

{| class="wikitable"
! Strategy
! Behavior
|-
| <code>rising_edge</code>
| Creates an event when the state changes from zero to nonzero.
|-
| <code>falling_edge</code>
| Creates an event when the state changes from nonzero to zero.
|-
| <code>change</code>
| Creates an event whenever the state value changes.
|-
| <code>value_change</code>
| Creates an event whenever the state value changes.
|-
| <code>nonzero_change</code>
| Creates an event when a transition results in a nonzero value.
|-
| <code>interval</code>
| Treats each continuous nonzero period as an event interval.
|}

Edge and value-change events have zero duration.

For <code>interval</code>, the duration corresponds to the length of the contiguous nonzero period.

===Additional Event Columns===

Other BCI2000 states may be mapped as additional columns associated with generated events.

For example, a task may use one state to trigger an event while states such as condition, target, block, response type, or trial number are sampled at that event and placed into additional TSV columns.

Additional nonstandard columns are described in the corresponding <code>*_events.json</code> sidecar.

An additional event-column mapping by itself does not create an event. An event rule must first define when event rows are generated.

==Motion and Continuous State Conversion==

Continuously varying BCI2000 states may be written to the BIDS <code>motion/</code> directory.

Examples may include states representing:

* Joystick position.
* Cursor position.
* Eye position.
* Gaze position.
* Limb position.
* Other continuous task or kinematic variables.

The converter does not determine these meanings automatically during normal conversion. The user specifies them through the state-routing profile.

A typical motion output consists of:

<pre>
sub-001_ses-01_task-motor_run-01_tracksys-unknown_motion.tsv
sub-001_ses-01_task-motor_run-01_tracksys-unknown_motion.json
sub-001_ses-01_task-motor_run-01_tracksys-unknown_channels.tsv
</pre>

The motion TSV is headerless.

Column information is stored in the motion channels TSV:

<pre>
name type units description
</pre>

A motion mapping may define:

* Column name.
* Motion type.
* Units.
* Description.

The associated JSON sidecar records information such as:

* Sampling frequency.
* Start time.
* Column order.
* Tracking-system name.

All motion states in one output file must contain the same number of samples.

==Neural Signal Conversion==

When neural export is enabled, BCI2000 signal channels are exported as EDF.

The converter currently supports:

* EEG EDF output.
* iEEG EDF output.

The BCI2000 signal matrix is read with calibration gains applied and converted into the orientation required by the output writer.

A corresponding BIDS channel table contains:

<pre>
name type units
</pre>

For EEG, channels normally use the BIDS channel type:

<pre>
EEG
</pre>

For iEEG, the channel type is selected from:

<pre>
ECOG
SEEG
DBS
</pre>

The electrophysiology JSON sidecar includes information such as:

* Task name.
* Sampling frequency.
* Recording duration.
* Reference.
* Source system.
* Conversion software.

The source system is identified as:

<pre>
BCI2000
</pre>

The conversion software is identified as:

<pre>
bci2000-bids
</pre>

==Installation==

===Requirements===

Python '''3.10 or newer''' is required.

The primary Python dependencies are:

* <code>numpy</code>
* <code>pyEDFlib</code>
* <code>PyYAML</code>
* <code>BCI2000Tools</code>

Tkinter is required for the graphical interface.

===Recommended Installation===

From a local checkout of the repository, create a Python virtual environment.

On macOS or Linux:

<pre>
python3 -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install -e .
</pre>

On Windows PowerShell:

<pre>
py -3.14 -m venv .venv
.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install -e .
</pre>

The package also defines installation extras for BCI2000 and YAML support:

<pre>
python -m pip install -e ".[yaml,bci2000]"
</pre>

For development:

<pre>
python -m pip install -e ".[yaml,bci2000,dev]"
</pre>

On Debian or Ubuntu systems, Tkinter may need to be installed separately:

<pre>
sudo apt install python3-tk
</pre>

The external BIDS Validator is not installed automatically with the Python package.

==Graphical Interface==

The graphical interface may be launched with:

<pre>
bci2000-bids-gui
</pre>

or:

<pre>
python -m bci2000_bids.gui
</pre>

It may also be launched from the main command:

<pre>
bci2000-bids gui
</pre>

The GUI supports:

* Selecting one or more <code>.dat</code> files.
* Selecting an input directory.
* Recursive input discovery.
* Selecting a BIDS output directory.
* Subject label entry.
* Session label entry.
* Task label entry.
* Behavioral, EEG, or iEEG datatype selection.
* ECoG, SEEG, or DBS iEEG channel-type selection.
* Enabling or disabling neural export.
* Loading an existing profile.
* Creating a profile using an interactive state-routing editor.
* Automatic starter-profile generation.
* Source preservation.
* SHA-256 checksum generation.
* Existing-output policy selection.
* Recording inspection.
* Dry runs.
* Conversion.
* Optional BIDS validation.
* Progress and status reporting.

The default GUI configuration uses:

* Session <code>01</code>.
* Datatype <code>beh</code>.
* Neural export disabled.
* BIDS validation enabled.
* Existing-output policy <code>error</code>.

==Command-Line Interface==

The command-line program is:

<pre>
bci2000-bids
</pre>

The equivalent module invocation is:

<pre>
python -m bci2000_bids
</pre>

The primary commands are:

<pre>
inspect
convert
profile
validate
gui
</pre>

===Inspect===

To inspect one BCI2000 recording without converting it:

<pre>
bci2000-bids inspect recording.dat
</pre>

Inspection reports information including:

* File name.
* Resolved path.
* Recording duration.
* Sampling frequency.
* Number of channels.
* Number of samples.
* Channel names.
* State names.
* State bit widths.
* Selected BCI2000 parameters.

Selected parameters include:

* <code>SamplingRate</code>
* <code>DataFormat</code>
* <code>Application</code>
* <code>SignalSource</code>
* <code>ChannelNames</code>
* <code>SourceChUnits</code>

===Generate a Profile===

A starter state-routing profile may be generated with:

<pre>
bci2000-bids profile recording.dat --output profile.json
</pre>

If <code>--output</code> is omitted, the generated JSON profile is printed to standard output.

The profile should be reviewed before conversion.

===Basic Conversion===

A basic iEEG conversion is:

<pre>
bci2000-bids convert recording.dat \
--output bids \
--subject 001 \
--session 01 \
--task motor \
--datatype ieeg \
--channel-type ECOG
</pre>

===Behavioral/State-Only Conversion===

To convert states without neural data:

<pre>
bci2000-bids convert recording.dat \
--output bids \
--subject 001 \
--session 01 \
--task motor \
--datatype beh \
--no-neural \
--profile profile.json
</pre>

===Directory Conversion===

To recursively discover BCI2000 files:

<pre>
bci2000-bids convert incoming/ \
--output bids/ \
--subject 001 \
--session 01 \
--task motor \
--datatype eeg \
--recursive
</pre>

===Source Preservation===

To retain the original BCI2000 recordings:

<pre>
bci2000-bids convert recording.dat \
--output bids \
--subject 001 \
--session 01 \
--task motor \
--datatype ieeg \
--channel-type ECOG \
--profile profile.json \
--preserve-source
</pre>

===Validation During Conversion===

To run BIDS validation before publishing the converted dataset:

<pre>
bci2000-bids convert recording.dat \
--output bids \
--subject 001 \
--session 01 \
--task motor \
--datatype ieeg \
--channel-type ECOG \
--validate
</pre>

===Dry Run===

A conversion may be checked without publishing the final dataset using:

<pre>
--dry-run
</pre>

A dry run performs discovery, profile/configuration resolution, run assignment, and destination checking without publishing the final converted dataset.

===Debug Logging===

The global debugging option is:

<pre>
bci2000-bids --debug ...
</pre>

<code>--debug</code> must appear before the subcommand.

==Typical Workflow==

A typical command-line workflow is:

===1. Inspect the recording===

<pre>
bci2000-bids inspect recording.dat
</pre>

===2. Generate a starter profile===

<pre>
bci2000-bids profile recording.dat --output profile.json
</pre>

===3. Review the profile===

Inspect the generated state mappings and confirm that each BCI2000 state has been assigned to the correct scientific role.

In particular, confirm which states represent:

* Experimental events.
* Event metadata.
* Continuous behavioral or motion signals.
* States that should be ignored.

===4. Perform a dry run===

<pre>
bci2000-bids convert recording.dat \
--output bids \
--subject 001 \
--session 01 \
--task motor \
--datatype ieeg \
--channel-type ECOG \
--profile profile.json \
--dry-run
</pre>

===5. Convert===

<pre>
bci2000-bids convert recording.dat \
--output bids \
--subject 001 \
--session 01 \
--task motor \
--datatype ieeg \
--channel-type ECOG \
--profile profile.json \
--preserve-source
</pre>

===6. Validate===

<pre>
bci2000-bids validate bids/
</pre>

==Configuration Files==

In addition to state-routing profiles, general conversion settings may be stored in JSON or YAML configuration files.

A configuration may contain fields such as:

* Subject.
* Session.
* Task.
* Datatype.
* Neural export.
* iEEG channel type.
* Source preservation.
* Existing-output behavior.
* Profile path.

For example:

<pre>
subject: "001"
session: "01"
task: "motor"
datatype: "beh"
preserve_source: true
profile: "generic-motion.yaml"
</pre>

A configuration may be supplied with:

<pre>
bci2000-bids convert recording.dat \
--output bids \
--config examples/configs/study.yaml
</pre>

Command-line configuration handling is still under development. Explicit <code>--subject</code> and <code>--task</code> arguments should currently be supplied for reliable noninteractive CLI use.

==Existing Output Handling==

The converter protects existing BIDS data by default.

The existing-output policy may be selected using:

<pre>
--on-existing
</pre>

Supported values are:

{| class="wikitable"
! Value
! Behavior
|-
| <code>error</code>
| Default. Stop if the target subject/session already exists.
|-
| <code>skip</code>
| Leave the existing subject/session unchanged and skip conversion.
|-
| <code>overwrite</code>
| Rebuild the requested subject/session while retaining other dataset content.
|}

The default policy is:

<pre>
error
</pre>

==Source Data Preservation==

When:

<pre>
--preserve-source
</pre>

is enabled, the original BCI2000 recording is copied to:

<pre>
sourcedata/sub-<subject>/ses-<session>/bci2000/
</pre>

For example:

<pre>
sourcedata/sub-001/ses-01/bci2000/recording.dat
</pre>

A SHA-256 checksum manifest is written as:

<pre>
sourcedata/sub-001/ses-01/bci2000/checksums.tsv
</pre>

with columns:

<pre>
filename sha256
</pre>

The preserved BCI2000 files are copies of the original recordings and are '''not anonymized by the converter'''.

Users should therefore review BCI2000 parameters and other source metadata before distributing <code>sourcedata/</code> outside the research environment.

==Data Safety==

Conversions are built in a temporary staging directory rather than directly modifying the published BIDS dataset.

When updating an existing dataset:

# The current dataset is copied into a staging location.
# New conversion output is created in staging.
# Validation may be performed against the staged dataset.
# The original dataset is retained until processing succeeds.
# The staged dataset is moved into place after successful conversion.

When replacement of an existing output root is necessary, the current output is temporarily renamed to a backup location before publication of the staged dataset.

If publication fails, the converter attempts to restore the previous dataset.

EDF files are also created through temporary output before final replacement.

Additional input checks include rejection of:

* Duplicate input basenames.
* Invalid subject labels.
* Invalid session labels.
* Invalid task labels.
* Invalid tracking-system names.
* Invalid iEEG channel types.
* Missing states required by a profile.
* Invalid signal dimensions.
* Duplicate or invalid EDF channel labels.
* Nonfinite neural samples.
* Certain EDF-incompatible signal conditions.

==BIDS Validation==

The converter includes an optional validation step.

To validate an existing converted dataset:

<pre>
bci2000-bids validate bids/
</pre>

The converter first performs basic internal checks, including confirming that:

<pre>
dataset_description.json
</pre>

exists and contains valid JSON.

When available, it then invokes the external BIDS Validator.

The [https://bids-standard.github.io/bids-validator/ official BIDS Validator] may also be used independently.

When validation is enabled during conversion, validation occurs against the staged dataset before it is published. A validation failure therefore prevents the invalid staged conversion from replacing the existing output dataset.

The external validator must currently be installed separately.

==Clinical and Participant Metadata==

The converter currently handles operational BIDS identifiers and recording metadata such as:

* Participant identifier.
* Session identifier.
* Task.
* Datatype.
* Run number.
* Sampling frequency.
* Recording duration.
* Channel names.
* Channel units.
* Neural channel type.
* Reference information.
* Motion tracking-system name.

The converter does '''not''' currently automatically extract or request study-specific clinical metadata such as:

* Diagnosis.
* Age.
* Sex.
* Handedness.
* Surgical procedure.
* Medication state.
* DBS stimulation state.
* Implant target.
* Recording location.
* Participant name.
* Medical record number.
* Date of birth.

Such metadata must be handled separately when required by a study.

==Limitations==

The current version is focused specifically on converting BCI2000 recordings and synchronized states into electrophysiology, behavioral, event, and motion components of BIDS.

The following are not currently supported:

* Imaging conversion.
* Video conversion.
* NeuroOmega file conversion.
* Automatic ingestion of BCI2000 companion files.
* Modalities other than <code>beh</code>, <code>eeg</code>, and <code>ieeg</code>.
* BrainVision output.
* FIF output.
* NIfTI output.
* Automatic grouping of recordings using BCI2000 recording metadata.
* Comprehensive export of every BCI2000 parameter into BIDS metadata.
* Automatic extraction of clinical or surgical metadata.
* Automatic anonymization of preserved BCI2000 source files.
* Automatic generation of <code>.bidsignore</code>.
* General provenance manifests beyond source checksums and generated conversion profiles.

Automatic state classification is heuristic and should not be treated as a substitute for knowledge of the experiment.

==Development and Testing==

The project contains unit and integration tests for core conversion functionality.

Current automated testing covers areas including:

* BIDS dataset initialization.
* Dataset descriptions.
* Participant-table creation.
* BIDS label normalization.
* BIDS run naming.
* Rising-edge event generation.
* Interval event generation.
* State-change event generation.
* Motion TSV output.
* Motion channel definitions.
* Duplicate state-routing rejection.
* BCI2000 parameter parsing utilities.
* Deterministic input discovery.
* Recursive input discovery.
* Synthetic state/event conversion.
* Synthetic iEEG EDF conversion.
* EDF read-back using pyEDFlib.
* Missing-unit fallback behavior.

The current integration tests use synthetic/mock BCI2000 recordings rather than decoding real clinical or experimental BCI2000 files.

Real BCI2000 files should therefore be tested and reviewed in the intended research environment before relying on a new conversion workflow for production datasets.

==BIDS Background==

[https://bids.neuroimaging.io/ BIDS] is a community-developed standard for organizing neural and associated experimental data in a consistent filesystem structure.

A typical BIDS hierarchy follows the general form:

<pre>
dataset/
└── sub-<subject>/
└── ses-<session>/
└── <datatype>/
</pre>

Within this structure, file names encode entities such as subject, session, task, and run.

The BCI2000 to BIDS Converter performs this transformation automatically for supported BCI2000 data while retaining synchronization between neural signals and selected BCI2000 states.

For the complete standard, see the [https://bids-specification.readthedocs.io/en/stable/ BIDS Specification].

==References==

# Gorgolewski KJ, Auer T, Calhoun VD, et al. [https://doi.org/10.1038/sdata.2016.44 The brain imaging data structure, a format for organizing and describing outputs of neuroimaging experiments]. ''Scientific Data''. 2016;3:160044. doi:10.1038/sdata.2016.44.
# [https://bids.neuroimaging.io/ Brain Imaging Data Structure (BIDS)].
# [https://bids-specification.readthedocs.io/en/stable/ BIDS Specification].
# [https://bids-standard.github.io/bids-validator/ BIDS Validator].

==See also==

* [[Technical Reference:BCI2000 File Format|BCI2000 File Format]]
* [[User Reference:Data File Formats|BCI2000 Data File Formats]]
* [[User Reference:BCI2000Export|BCI2000Export]]
* [[User Reference:Command Line Processing|BCI2000 Command Line Processing]]
* [[BCI2000Tools.EventRelated|BCI2000Tools and Python Data Analysis]]
* [[User Tutorial:Data Analysis|BCI2000 Data Analysis Tutorials]]
* [https://bids.neuroimaging.io/ Brain Imaging Data Structure]
* [https://bids-specification.readthedocs.io/en/stable/ BIDS Specification]
* [https://bids-standard.github.io/bids-validator/ BIDS Validator]

[[Category:Data Analysis Tools]]

FEP VisuomotorJoystickTask

2026-09-22T19:54:52Z

Aes2376:

VisuomotorJoystickTask

2026-09-22T19:54:14Z

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>

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]]
* [[Category:User Application]]

Contributions:Application

2026-09-22T19:52:27Z

Aes2376: /* Application Modules from the "private" section */

The following user application components are available in the [[Contributions:Contents|Contributions]] section of BCI2000:

==Application Modules==
*[[Contributions:MFCdemo]]: Demo application module written using the Microsoft MFC framework.
*[[Contributions:SlowWaveApp]]: Application modules for Slow Wave feedback.

*[[Contributions:ANTTask]]: An attention task application.
*[[Contributions:ANTTitration]]: A titration application to calibrate the ANTTask.
*[[Contributions:CenterOutTask]]: An implementation of the classic Center-Out task.
*[[Contributions:EglyDriverTask]]: An implementation of the Egly-Driver task.
*[[Contributions:ERPSpeller]]: A speller application similar to the P3Speller.
*[[Contributions:ForagingTask]]: A foraging movement task.
*[[Contributions:WCSTTask]]: An implementation of the Wisconsin Card Sorting Test.

==Application Modules and Filters from the "private" section==
'''NOTE:''' Access to components from the "private" section requires signing a non-disclosure agreement. Please contact brunner[at]neurotechcenter.org for more information.

*[[Contributions:gEstimFilter]]: Cortical stimulation with the gtec g.Estim PRO.
*[[VisuomotorJoystickTask]]: Center-out visuomotor reaching task using a USB HID joystick with normal and inverted cursor mappings.
*[[FEP_VisuomotorJoystickTask]]: Visuomotor joystick task with hidden mapping changes and cursor-gain manipulations for studying behavioral adaptation under changing sensorimotor contingencies.

==Interoperability==
*[[Contributions:BCI2000Command]]: Remote control of BCI2000 from the command line.

*[[Contributions:BCI2000PresentationLink]]: Using BCI2000 with the [http://www.neurobs.com/ NBS Presentation] stimulus delivery software.
*[[Contributions:BCI2000PythonBindings]]: Remote control of BCI2000 from Python scripts.
*[[Contributions:BCI2000SimulinkConnector]]: A component that exports BCI2000 data to a BCI2000 Simulink block.

==See also==
[[User Reference:Filters]]

[[Category:User Application]][[Category:Contents]]

Contributions:Application

2026-09-22T19:52:06Z

Aes2376: /* Application Filters from the "private" section */

The following user application components are available in the [[Contributions:Contents|Contributions]] section of BCI2000:

==Application Modules==
*[[Contributions:MFCdemo]]: Demo application module written using the Microsoft MFC framework.
*[[Contributions:SlowWaveApp]]: Application modules for Slow Wave feedback.

*[[Contributions:ANTTask]]: An attention task application.
*[[Contributions:ANTTitration]]: A titration application to calibrate the ANTTask.
*[[Contributions:CenterOutTask]]: An implementation of the classic Center-Out task.
*[[Contributions:EglyDriverTask]]: An implementation of the Egly-Driver task.
*[[Contributions:ERPSpeller]]: A speller application similar to the P3Speller.
*[[Contributions:ForagingTask]]: A foraging movement task.
*[[Contributions:WCSTTask]]: An implementation of the Wisconsin Card Sorting Test.

==Application Modules and Filters from the "private" section==
'''NOTE:''' Access to components from the "private" section requires signing a non-disclosure agreement. Please contact brunner[at]neurotechcenter.org for more information.

*[[Contributions:gEstimFilter]]: Cortical stimulation with the gtec g.Estim PRO.
*[[VisuomotorJoystickTask]]: Center-out visuomotor reaching task using a USB HID joystick with normal and inverted cursor mappings.
*[[FEP_VisuomotorJoystickTask]]: Visuomotor joystick task with hidden mapping changes and cursor-gain manipulations for studying behavioral adaptation under changing sensorimotor contingencies.

==Application Modules from the "private" section==
'''NOTE:''' Access to components from the "private" section requires signing a non-disclosure agreement. Please contact brunner[at]neurotechcenter.org for more information.
*[[VisuomotorJoystickTask]]: Center-out visuomotor reaching task using a USB HID joystick with normal and inverted cursor mappings.
*[[FEP_VisuomotorJoystickTask]]: Visuomotor joystick task with hidden mapping changes and cursor-gain manipulations for studying behavioral adaptation under changing sensorimotor contingencies.

==Interoperability==
*[[Contributions:BCI2000Command]]: Remote control of BCI2000 from the command line.

*[[Contributions:BCI2000PresentationLink]]: Using BCI2000 with the [http://www.neurobs.com/ NBS Presentation] stimulus delivery software.
*[[Contributions:BCI2000PythonBindings]]: Remote control of BCI2000 from Python scripts.
*[[Contributions:BCI2000SimulinkConnector]]: A component that exports BCI2000 data to a BCI2000 Simulink block.

==See also==
[[User Reference:Filters]]

[[Category:User Application]][[Category:Contents]]

Contributions:Application

2026-09-22T19:49:58Z

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

2026-09-01T16:49:27Z

Aes2376: Init