OneTwoThreeGo

class braintools.cogtask.OneTwoThreeGo(t_fixation=(Quantity(400., 'ms'), Quantity(100., 'ms'), Quantity(800., 'ms')), t_target=(Quantity(1000., 'ms'), Quantity(500., 'ms'), Quantity(1500., 'ms')), t_stimulus=Quantity(100., 'ms'), intervals=(Quantity(600., 'ms'), Quantity(700., 'ms'), Quantity(800., 'ms'), Quantity(900., 'ms'), Quantity(1000., 'ms')), t_response=Quantity(1000., 'ms'), **kwargs)

1-2-3-Go interval reproduction task.

Three brief pulses (“1”, “2”, “3”) are separated by the same sample interval; the subject must respond (“go”) one interval after the third pulse, i.e. reproduce the interval from two samples of it. This is the 1-2-3-Go timing paradigm of Egger et al. [1], an extension of the Ready-Set-Go interval-production task (see Remington et al. [2]), as implemented by the OneTwoThreeGo environment of NeuroGym [3].

Structure: Fixation >> Target >> S1 >> Interval1 >> S2 >> Interval2 >> S3 >> Interval3 >> Response

Parameters:

• t_fixation (Any) – Fixation period. A Quantity gives a fixed duration; a tuple (mean, min, max) of Quantities samples it per trial from a truncated exponential (default: (400, 100, 800) ms, as in NeuroGym).

• t_target (Any) – Period during which the target is shown before the first pulse; same format as t_fixation (default: (1000, 500, 1500) ms).

• t_stimulus (Quantity) – Duration of each of the three pulses (default: 100 ms).

• intervals (Sequence[Quantity]) – Sample intervals; one is drawn uniformly per trial and used for the three inter-pulse gaps (default: 600, 700, 800, 900, 1000 ms).

• t_response (Quantity) – Response period, which starts exactly one interval after the third pulse (default: 1000 ms).

• **kwargs – Forwarded to Task (e.g. seed, dt).

Raises:

ValueError – If intervals is empty or not positive, or t_fixation / t_target is neither a Quantity nor a valid (mean, min, max) tuple.

See also

ReadySetGo

Interval reproduction from a single sample interval.

Notes

Inputs (3 channels): fixation (1 for the whole trial; the subject must time the response itself, there is no go cue), stimulus (1 during the three pulses s1, s2, s3) and target (1 from the target period to the end of the trial).

Labels (categorical, 2 classes): 0 (hold) until the end of interval3 and 1 (go) during the response period, whose onset is the target response time end(s3) + interval.

Trial state: interval (ms) and, when sampled, fixation_duration and target_duration (ms).

The fixation, target and interval periods have per-trial durations, so the task runs in packed (variable-length) mode: buffers have the static length max_trial_duration() and info['mask'] (or batch_sample(..., return_mask=True)) marks the valid steps. batch_sample runs under jax.jit and vmap.

Differences from NeuroGym. NeuroGym trains the response with a reward that decays with the error between produced and true interval (margin prod_margin); here the task is supervised through the labels, and the go label covers the whole response period.

References

[1]

Egger, S. W., Remington, E. D., Chang, C.-J., & Jazayeri, M. (2019). Internal models of sensorimotor integration regulate cortical dynamics. Nature Neuroscience, 22(11), 1871-1882.

[2]

Remington, E. D., Narain, D., Hosseini, E. A., & Jazayeri, M. (2018). Flexible sensorimotor computations through rapid reconfiguration of cortical dynamics. Neuron, 98(5), 1005-1019.

[3]

Molano-Mazon, M., et al. (2022). NeuroGym: An open resource for developing and sharing neuroscience tasks. PsyArXiv.

Examples

>>> import brainunit as u
>>> import numpy as np
>>> import braintools
>>> task = braintools.cogtask.OneTwoThreeGo(seed=0, dt=10.0 * u.ms)
>>> task.num_inputs, task.num_outputs
(3, 2)
>>> task.max_trial_duration()
660
>>> X, Y, info = task.sample_trial(0)
>>> X.shape, Y.shape
((660, 3), (660,))
>>> spans = {name: (int(s), int(e)) for name, s, e in info['phase_history']}
>>> interval_steps = int(info['trial_state']['interval'] / 10.0)
>>> spans['response'][0] == spans['s3'][1] + interval_steps
True
>>> np.unique(np.asarray(Y)[spans['response'][0]:spans['response'][1]])
array([1], dtype=int32)
>>>
>>> X, Y, mask = task.batch_sample(4, return_mask=True)
>>> X.shape, mask.shape
((660, 4, 3), (660, 4))

define_features()

Define input and output features.

Override in subclass for class-based task definition.

Return type:

Tuple

Returns:

• input_features (Feature or FeatureSet) – Input feature definitions.

• output_features (Feature or FeatureSet) – Output feature definitions.

define_phases()

Define the phase structure.

Override in subclass for class-based task definition.

Returns:

The task phase structure (single phase or composition).

Return type:

Phase

trial_init(ctx)

Initialize trial-level state.

Override in subclass to set up trial parameters like ground_truth, stimulus indices, etc.

Parameters:

ctx (Context) – Trial context to populate with state.

Return type:

None