FEP VisuomotorJoystickTask

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 cursor-gain manipulation. High-gain trials change the magnitude of the relationship between joystick displacement and cursor displacement. In the current implementation this is represented explicitly as a cursor-gain condition rather than as a formal sensory-reliability variable.

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.
• Normal and configurable high cursor-gain conditions.
• 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, cursor, joystick, target, mapping, and gain logging in the BCI2000 data stream.

The participant is not informed that the mapping, gain, mapping probabilities, or experimental block structure may change.

Location

Upon the completion of an SVN update, the source code for the FEP Visuomotor Joystick Task is located in:

src/private/Application/FEP_VisuomotorJoystickTask/

The main implementation is contained in:

FEP_VisuomotorJoystickTask.cpp

with the corresponding header and build configuration in:

• FEP_VisuomotorJoystickTask.h
• CMakeLists.txt

The application is included from (prog folder):

src/private/Application/CMakeLists.txt

The CMake target is:

FEP_VisuomotorJoystickTask

The Windows executable is:

FEP_VisuomotorJoystickTask.exe

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 current FEP task is maintained under src/custom. In the inspected development checkout, the module does not currently have independent Git or SVN revision history.

The inspected 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 the BCI2000 build containing the module rather than an independent revision number for the 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 cursor gain 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 Normal versus High cursor gain.

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:

TaskCondition	Mapping	Description
0	Normal	Joystick displacement moves the cursor in the corresponding direction.
1	Inverted	Joystick displacement moves the cursor in the opposite direction on both axes.

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 Normal versus High cursor gain.

Experiment Structure

Each run proceeds in the following order:

1. Introduction.
2. Joystick sandbox.
3. Experimental block 1, if enabled.
4. Experimental block 2, if enabled.
5. Experimental block 3, if enabled.
6. Experimental block 4, if enabled.
7. Experimental block 5, if enabled.
8. Experimental block 6, if enabled.
9. Experiment completion.

Experimental block transitions are not announced to the participant.

Each experimental trial proceeds as follows:

1. The participant returns the cursor to the center.
2. The participant holds the cursor within the center region.
3. A yellow warning cue appears.
4. A pre-target delay occurs.
5. A peripheral target appears.
6. The participant moves the cursor toward the target.
7. The target is acquired.
8. A short feedback interval occurs.
9. The task advances to the next trial.

Introduction

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

The participant is shown:

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.

During the introduction:

• Introduction=1
• TutorialPhase=1
• TaskPhase=0
• 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 JoystickButtons1 advances to the sandbox.

The participant is not told about:

• Normal versus Inverted mappings.
• Mapping switches.
• Cursor-gain changes.
• 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:

Practice moving the cursor with the joystick.

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

During the sandbox:

• Introduction=1
• TutorialPhase=2
• TaskPhase=0
• TaskBlock=0
• TaskTrial=0
• TaskCondition=0
• Normal direct mapping is used.
• Cursor gain is 1.0.
• No targets are generated.
• No experimental timing phases occur.

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

1. The cursor is inside the center tolerance region.
2. 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.

When the sandbox finishes:

• Introduction becomes 0.
• TutorialPhase becomes 0.
• TaskPhase becomes 1.
• Experimental block and trial states become active.

Experimental Blocks

The task contains six predefined block roles.

There is no ExperimentMode parameter.

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

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

Block	Trial-count parameter	PriorCondition	Mapping composition
1	BaselineTrials	0, Fixed	100% Normal
2	InitialInvertedTrials	0, Fixed	100% Inverted
3	ReturnNormalTrials	0, Fixed	100% Normal
4	MixedTrials	1, HiddenMixed	Approximately 50% Normal and 50% Inverted
5	StrongPriorTrials	2, StrongNormal	Approximately 90% Normal and 10% Inverted
6	BalancedPriorTrials	3, Balanced	Approximately 50% Normal and 50% Inverted

Blocks 4 and 6

For blocks 4 and 6:

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

Block 5

Block 5 contains a strongly Normal-dominant mapping distribution.

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

The remaining trials are Normal.

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

Pseudorandomization

For blocks 4 through 6, mapping order is pseudorandomized.

The task attempts up to 64 candidate shuffles.

A candidate is preferred when:

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

The preferred maximum run length is:

max(3, unavoidableRun + 1)

where:

unavoidableRun = (majority + minority) / (minority + 1)

using integer division.

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

Cursor-gain order is shuffled independently from mapping order.

Prior Conditions

PriorCondition represents the mapping-frequency context associated with the current block.

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

Value	Name	Meaning
0	Fixed	Fixed-mapping context used in blocks 1 through 3.
1	HiddenMixed	Approximately balanced hidden mapping context used in block 4.
2	StrongNormal	Strongly Normal-dominant mapping context used in block 5.
3	Balanced	Approximately balanced mapping context used in block 6.

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

Joystick Input

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

The application reads:

• JoystickXpos
• JoystickYpos
• JoystickButtons1

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

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

taskJoystick = round(BCIJoystick * 1023 / 32767)

The converted value is normalized internally:

rawPosition = taskJoystick / 1023

The FEP application does not itself enable joystick logging.

Joystick logging should therefore be enabled using BCI2000's LogJoystick option.

See LogJoystick.

Joystick-to-Cursor Mapping

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

cursorX = rawX
cursorY = rawY

The mapping transformation used for target-directed movement is activated at target onset.

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.
• Current cursor gain.

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, Normal Gain

For a Normal trial with gain 1.0:

cursorX = joystickX / 1023
cursorY = joystickY / 1023

Inverted Mapping, Normal Gain

For an Inverted trial:

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

Both axes are inverted.

Normal Mapping, High Gain

For a Normal high-gain trial:

cursorX = anchorCursorX
          + HighCursorGain * (joystickX - anchorJoystickX) / 1023

cursorY = anchorCursorY
          + HighCursorGain * (joystickY - anchorJoystickY) / 1023

Inverted Mapping, High Gain

For an Inverted high-gain trial:

cursorX = anchorCursorX
          - HighCursorGain * (joystickX - anchorJoystickX) / 1023

cursorY = anchorCursorY
          - HighCursorGain * (joystickY - anchorJoystickY) / 1023

Cursor coordinates are constrained to the valid display range.

Cursor Gain

The task contains two cursor-gain conditions.

CursorGainCondition	Condition	Gain
0	Normal	1.0
1	High	HighCursorGain

The default value of HighCursorGain is:

1.5

High gain:

• Applies to both X and Y axes.
• Multiplies joystick displacement relative to the target-onset anchor.
• Is used only in randomized blocks 4 through 6.
• Is shuffled independently from mapping condition.
• Is not visually cued to the participant.

The current implementation does not define a SensoryReliability state or parameter.

Return-to-Anchor Behavior

After an Inverted or High-gain 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.

Mapping Switches

A mapping switch occurs when:

next trial TaskCondition != completed trial TaskCondition

Gain changes alone do not produce mapping-switch events.

Mapping switches occur only at trial boundaries.

They do not occur:

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

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

MappingSwitch

MappingSwitch is an event-like state.

It is:

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

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

TrialsSinceMappingSwitch

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

Behavior is:

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

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

Use MappingSwitch or a transition in TaskCondition to identify mapping changes.

Example

Consider the following mapping sequence:

Normal -> Normal -> Inverted -> Inverted

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

Trial	TaskCondition	MappingSwitch	TrialsSinceMappingSwitch	PriorCondition
Normal	0	0	Depends on previous trial history	1
Normal	0	0	Previous value + 1	1
Inverted	1	1 on the transition processing block	0	1
Inverted	1	0	1	1

Target Generation

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

TargetAngle ranges from:

0 through 3599

The value represents tenths of a degree:

angle in degrees = TargetAngle / 10

Targets therefore span:

0.0 through 359.9 degrees

Target coordinates are generated according to:

TargetX = 0.5 + 0.3 * cos(angle)
TargetY = 0.5 + 0.4 * sin(angle)

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

Targets:

• Are black.
• Are visually identical across all mapping conditions.
• Are visually identical across gain conditions.
• Are not determined by mapping condition.
• Are not determined by gain 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.

Trial Phases

The current experimental phase is stored in TaskPhase.

Value	Phase	Description	Participant display
0	Introduction / Sandbox	No active experimental trial	Introduction text or sandbox
1	WaitingForCenter	Waiting for cursor to enter the center region	Cursor, gray center, cross
2	HoldingCenter	Required uninterrupted center hold	Cursor, 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:

TaskPhase == 5

Movement onset may be identified by a rising transition of:

MovementStarted

Target acquisition is identified by:

TargetHit == 1

Participant Display

The participant-facing window contains:

• A light background.
• A black cursor.
• A black central cross.
• A gray center marker.
• A larger yellow warning marker.
• A black peripheral target.
• An experimental progress indicator.
• Introduction and sandbox instructions.
• An experiment-completion message.

The participant receives no explicit visual indication of:

• Current mapping.
• Current gain.
• Mapping switches.
• PriorCondition.
• Block number.
• Trial number.
• Block transitions.
• Mapping probabilities.

The target remains black across conditions.

There is no explicit success-color cue. The target disappears after successful acquisition.

Diagnostic Window

A separate Qt diagnostic window titled:

FEP Visuomotor Joystick Diagnostics

is displayed to the experimenter.

During experimental trials it displays information including:

• Current task stage.
• Original block number.
• Overall trial number.
• Total number of active trials.
• Trial number within the current block.
• Current Normal or Inverted mapping.
• Current Normal or High cursor-gain condition.
• Actual gain value.
• Whether the current trial followed a mapping switch.
• Trials since the most recent mapping switch.
• Current task phase.
• Target angle.
• Target coordinates.
• Raw BCI2000 joystick states.
• Converted joystick coordinates.
• Current cursor coordinates.
• Movement-started status.
• Reaction time.
• Movement time.
• Total time.
• Reset/status information.

PriorCondition is recorded in the data stream but is not currently displayed in the diagnostic window.

Diagnostic Controls

The diagnostic window provides:

RESET CURRENT TRIAL

There is no diagnostic Continue button for the introduction or sandbox.

Trial Reset

A trial may be manually reset during:

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

Reset is unavailable during:

• Feedback.
• Finished.
• Introduction.
• Sandbox.

Resetting a trial:

• Returns the task to WaitingForCenter.
• Restarts the phase timer.
• Clears movement-onset timing.
• Clears target-onset timing.
• Clears MovementStarted.
• Clears TargetHit.
• Produces a TrialReset pulse.
• Clears timing states.
• Resets baseline accumulation.
• Keeps the same target.
• Keeps the same mapping.
• Keeps the same gain.
• Keeps the same block number.
• Keeps the same trial number.
• Keeps PriorCondition.
• Keeps TrialsSinceMappingSwitch.
• Does not rebuild or reshuffle the experimental sequence.

TrialReset lasts for one processing block.

Timing Measurements

Timing uses std::chrono::steady_clock.

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

Movement Onset

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

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

abs(currentX - baselineX) > 8

or:

abs(currentY - baselineY) > 8

Reaction Time

Reaction time is measured from:

target onset -> movement onset

and stored in:

ReactionTimeMs

Movement Time

Movement time is measured from:

movement onset -> target acquisition

and stored in:

MovementTimeMs

Total Time

Total time is measured from:

target onset -> target acquisition

and stored in:

TotalTimeMs

Timing values are expressed in rounded milliseconds.

Timing states remain populated through the Feedback phase.

Parameters

Experiment Structure

Parameter	Type	Default	Range	Description
BaselineTrials	Integer	20	0-10000	Number of Normal trials in block 1
InitialInvertedTrials	Integer	5	0-10000	Number of Inverted trials in block 2
ReturnNormalTrials	Integer	5	0-10000	Number of Normal trials in block 3
MixedTrials	Integer	20	0-10000	Number of approximately balanced trials in block 4
StrongPriorTrials	Integer	20	0-10000	Number of Normal-dominant trials in block 5
BalancedPriorTrials	Integer	20	0-10000	Number of approximately balanced trials in block 6

At least one trial must be configured across the six block parameters.

HighCursorGain

Gain used during High cursor-gain trials.

Type: floating point

Default:

1.5

Range:

1.0-5.0

Normal gain is fixed at 1.0.

CenterHoldSeconds

Required center-hold duration.

Type: floating point

Default:

3.0

seconds.

Range:

0.0-60.0

seconds.

WarningSeconds

Duration of the yellow warning interval.

Default:

0.5

seconds.

PreTargetDelaySeconds

Delay between the warning interval and target onset.

Default:

0.5

seconds.

FeedbackSeconds

Duration of the feedback interval following target acquisition.

Default:

0.5

seconds.

StimulusDisplay

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

Default:

0

On Windows systems, available monitors are enumerated by the application.

States

State	Width	Initial Value	Meaning
CursorX	10 bit	512	Participant-visible horizontal cursor coordinate
CursorY	10 bit	512	Participant-visible vertical cursor coordinate
TaskPhase	3 bit	0	Current task phase
TaskCondition	1 bit	0	0 Normal, 1 Inverted
TargetAngle	12 bit	0	Target angle in tenths of a degree
TargetX	10 bit	512	Horizontal target coordinate
TargetY	10 bit	512	Vertical target coordinate
TaskBlock	8 bit	0	Current experimental block role
TaskTrial	16 bit	0	Overall experimental trial number
MovementStarted	1 bit	0	Indicates detected movement onset
TargetHit	1 bit	0	Target-acquisition event
TrialReset	1 bit	0	Manual-reset event
MappingSwitch	1 bit	0	Mapping-change event
TrialsSinceMappingSwitch	16 bit	0	Trials since the most recent mapping switch
PriorCondition	2 bit	0	Current block-level prior context
CursorGainCondition	1 bit	0	0 Normal gain, 1 High gain
Introduction	1 bit	0	1 during introduction or sandbox
TutorialPhase	4 bit	0	0 experiment, 1 introduction, 2 sandbox
ReactionTimeMs	32 bit	0	Reaction time in milliseconds
MovementTimeMs	32 bit	0	Movement time in milliseconds
TotalTimeMs	32 bit	0	Total target-directed time in milliseconds

External Joystick States

State	Description
JoystickXpos	Raw horizontal joystick position
JoystickYpos	Raw vertical joystick position
JoystickButtons1	Joystick button used to advance the introduction and sandbox

The application also accesses the standard BCI2000 Running state when ending the experiment.

States Not Present in the Current Implementation

The current implementation does not define:

• DisplayedCursorX
• DisplayedCursorY
• SensoryReliability
• PracticeTrial
• TaskBlockType

Cursor Coordinates

CursorX and CursorY represent the final cursor coordinates actually displayed to the participant.

These coordinates include any:

• Mapping inversion.
• High-gain transformation.
• Return-to-anchor transformation.
• Display-boundary clipping.

The same coordinates are used for:

• Drawing the participant-visible cursor.
• Center detection.
• Target-hit detection.
• BCI2000 state recording.
• Diagnostic display.

The application does not record a separate untransformed cursor trajectory.

A direct joystick-equivalent trajectory may be reconstructed offline from JoystickXpos and JoystickYpos.

Data Recording

The task records its behavioral variables as synchronized BCI2000 states in the standard .dat file.

Recorded information includes:

• Participant-visible cursor trajectory.
• Joystick trajectory, when joystick logging is enabled.
• Trial phase.
• Mapping condition.
• Cursor-gain condition.
• Target angle.
• Target coordinates.
• Experimental block.
• Experimental trial number.
• Movement onset.
• Target acquisition.
• Trial resets.
• Mapping switches.
• Trials since the most recent mapping switch.
• Prior-condition category.
• Introduction and sandbox status.
• Reaction time.
• Movement time.
• Total time.

The application passes signal channels through unchanged.

Output = Input;

Secondary Output

The current implementation does not write an application-specific:

• CSV file.
• JSON file.
• Text results file.
• Database.

There is no ResultsFile parameter.

Offline Analysis Notes

Measurement or Event	Recommended Identification
Experimental samples	Introduction == 0
Introduction	Introduction == 1 and TutorialPhase == 1
Sandbox	Introduction == 1 and TutorialPhase == 2
Active experimental trial	Introduction == 0, TaskTrial > 0, and TaskPhase from 1 through 6
Target onset	Transition into TaskPhase == 5
Movement onset	Rising transition of MovementStarted
Target acquisition	TargetHit == 1
Normal mapping	TaskCondition == 0
Inverted mapping	TaskCondition == 1
Normal gain	CursorGainCondition == 0
High gain	CursorGainCondition == 1
Mapping switch	MappingSwitch == 1
Trials since switch	TrialsSinceMappingSwitch
Previous mapping	Previous trial's TaskCondition
Prior context	PriorCondition
Experimental block	TaskBlock
Overall trial	TaskTrial
Target angle	TargetAngle / 10 degrees
Target position	TargetX and TargetY
Joystick trajectory	JoystickXpos and JoystickYpos
Participant-visible cursor trajectory	CursorX and CursorY
Reaction time	ReactionTimeMs
Movement time	MovementTimeMs
Total time	TotalTimeMs
Manual reset	TrialReset == 1
Experiment completion	TaskPhase == 7

Event-Like States

The following states are one-processing-block events:

• MappingSwitch
• TargetHit
• TrialReset

MovementStarted differs from these states because it remains high from movement onset through the remainder of the trial and Feedback phase.

Differences from USBHIDJoystickTask

Retained

• BCI2000 ApplicationBase 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:

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

Added

The FEP task adds:

• Six predefined experimental block roles.
• Hidden Normal and Inverted mappings.
• Unannounced mapping switches.
• MappingSwitch.
• TrialsSinceMappingSwitch.
• PriorCondition.
• CursorGainCondition.
• HighCursorGain.
• Normal versus High cursor gain.
• 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.
• PriorCondition 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.
• High cursor gain is implemented as a gain manipulation rather than as a state explicitly named sensory reliability.
• There is no separately recorded latent or untransformed cursor trajectory.
• Physical display geometry depends on the configured participant monitor and BCI2000 window dimensions.

References

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

See also

• Visuomotor Joystick Task
• Logging Input
• LogJoystick
• Module Command Line Options
• ApplicationWindow Class
• BCI2000 File Format
• ApplicationBase Class