Tutorial 2: Building custom tasks#

This tutorial covers the building blocks used to assemble a custom braintools.cogtask.Task:

  1. Features and feature composition.

  2. Declarative phases and value-spec shape rules.

  3. Built-in encoders and categorical label helpers.

  4. Instance-based and class-based task definitions.

  5. Vector-output tasks.

  6. Conditional phases with masks.

  7. Custom encoders.

The examples use dt= on each task so JIT-compiled batch sampling has a stable static timestep count.

import numpy as np
import brainstate
import brainunit as u
import jax.numpy as jnp

from braintools.cogtask import (
    Task,
    concat,
    Fixation,
    Stimulus,
    Delay,
    Response,
    Cue,
    Sample,
    Test,
    If,
    Switch,
    While,
    Feature,
    FeatureSet,
    CircleFeature,
    one_hot,
    circular,
    von_mises,
    gaussian,
    scalar,
    identity,
    ctx_value,
    cos_sin,
    label,
    match_label,
    comparison_label,
)

DT = 1.0 * u.ms
brainstate.environ.set(dt=DT)

1. Features#

A Feature names one logical input or output channel and declares its width. Feature objects compose into a FeatureSet with automatic slice assignment:

  • a + b concatenates features.

  • a | b is an alias for concatenation.

  • features - 'name' returns a new set without that feature.

  • Feature(..., 'base') * n creates named copies: base_0, base_1, …

The .i property is the slice used when phases write into the full tensor.

fix = Feature(1, 'fixation')
stim = Feature(8, 'stimulus')
choice = Feature(2, 'choice')

inputs = fix + stim
outputs = fix + choice
repeated = Feature(2, 'cue') * 3
without_stim = (fix + stim + choice) - 'stimulus'

direction = CircleFeature(8, limits=(0.0, 2 * jnp.pi), name='direction')

print('inputs:', inputs, 'num =', inputs.num)
print('stimulus slice:', inputs['stimulus'].i)
print('choice slice:', outputs['choice'].i)
print('repeated:', repeated)
print('without_stim:', without_stim)
print('direction range:', float(direction.v_min), 'to', float(direction.v_max))
inputs: FeatureSet(names=['fixation', 'stimulus'], nums=[1, 8]) num = 9
stimulus slice: slice(1, 9, None)
choice slice: slice(1, 3, None)
repeated: FeatureSet(names=['cue_0', 'cue_1', 'cue_2'], nums=[2, 2, 2])
without_stim: FeatureSet(names=['fixation', 'choice'], nums=[1, 2])
direction range: 0.0 to 6.283185307179586

2. Declarative phases#

A declarative phase fills input and output buffers from dictionaries:

  • inputs={feature_name: value_spec} writes one input feature slice.

  • outputs={'label': value_spec} writes integer class labels in categorical mode.

  • outputs={feature_name: value_spec} writes output feature slices in vector mode.

  • noise={feature_name: sigma} adds Gaussian input noise scaled by sigma / sqrt(dt).

A value spec can be a scalar, a (feature.num,) array, a (duration, feature.num) array, or a callable f(ctx, feature) -> value. Compose phases with >> or concat([...]), repeat with * n, and run simultaneous phases with |.

phases = (
    Fixation(100 * u.ms, inputs={'fixation': 1.0}, outputs={'label': 0})
    >> Stimulus(
        500 * u.ms,
        inputs={
            'fixation': 1.0,
            'stimulus': circular('direction', 'coherence'),
        },
        outputs={'label': 0},
    )
    >> Delay(300 * u.ms, inputs={'fixation': 1.0}, outputs={'label': 0})
    >> Response(
        100 * u.ms,
        inputs={'fixation': 0.0},
        outputs={'label': label(lambda ctx: ctx['ground_truth'] + 1)},
    )
)

phases
Sequence(Fixation >> Stimulus >> Delay >> Response)

3. Encoders#

Encoders are helper factories that return callable value specs. They read from trial state, which is normally populated in trial_init.

Encoder

Typical state value

Notes

one_hot(key)

integer class index

Uses feature.num unless num_classes= is given.

circular(key, coherence_key)

angle in radians

Set as_index=True for discrete direction indices.

von_mises(key, ...)

discrete direction index

Defaults to as_index=True; set as_index=False for radians.

cos_sin(key, num_dirs, repeats)

discrete direction index

Requires feature.num == 2 * repeats.

gaussian(key, sigma=...)

scalar

Gaussian bump over evenly spaced centers.

scalar(key, scale, offset)

scalar

Broadcasts one scalar to the whole feature.

identity(key)

array or scalar

Passes through a context value after shape checking.

ctx_value(key, default=...)

any value

Raw lookup, useful for precomputed values.

encoder_demo = Task(
    phases=Stimulus(
        4 * u.ms,
        inputs={
            'stimulus': von_mises('sample_idx', num_dirs=8),
            'fixation': scalar('fixation_level'),
        },
        outputs={'label': label('ground_truth')},
    ),
    input_features=fix + stim,
    output_features=outputs,
    trial_init=lambda ctx: ctx.update(
        sample_idx=2,
        fixation_level=0.25,
        ground_truth=1,
    ),
    num_classes=3,
    dt=DT,
)

X_demo, Y_demo, _ = encoder_demo.sample_trial(0)
print('first input row:', np.round(np.asarray(X_demo[0]), 3))
print('labels:', np.asarray(Y_demo))
first input row: [0.25  0.56  0.774 1.    0.774 0.56  0.507 0.5   0.507]
labels: [1 1 1 1]

4. Label helpers#

Categorical tasks reserve the output key 'label'. The helper constructors keep label specs explicit and JIT-friendly:

  • label(0) emits a constant class id.

  • label('ground_truth') reads a class id from ctx['ground_truth'].

  • label(lambda ctx: ...) computes a class id from trial state.

  • match_label('is_match') emits 1 for match trials and 2 otherwise.

  • comparison_label('is_greater') emits 1 for greater and 2 otherwise.

Use label('key') for context lookups. A bare string value is not a context lookup: outputs={'label': 'ground_truth'} raises a ValueError when the trial is sampled.

label_task = Task(
    phases=concat([
        Fixation(2 * u.ms, inputs={'fixation': 1.0}, outputs={'label': label(0)}),
        Response(2 * u.ms, outputs={'label': match_label('is_match')}),
        Response(2 * u.ms, outputs={'label': comparison_label('is_greater')}),
    ]),
    input_features=FeatureSet(fix),
    output_features=outputs,
    trial_init=lambda ctx: ctx.update(is_match=True, is_greater=False),
    num_classes=3,
    dt=DT,
)

_, Y_label, _ = label_task.sample_trial(0)
print('labels:', np.asarray(Y_label))
labels:
 [0 0 1 1 2 2]

5. Instance-based tasks#

The smallest complete recipe is:

  1. Define input and output features.

  2. Define the phase structure.

  3. Define trial_init(ctx) to populate per-trial state.

  4. Construct Task(...).

Keep values written by trial_init as Python scalars or JAX arrays so the same logic works inside batch_sample.

def trial_init(ctx):
    ground_truth = ctx.rng.choice(2)
    directions = jnp.asarray([0.0, jnp.pi])
    ctx['ground_truth'] = ground_truth
    ctx['coherence'] = 51.2
    ctx['direction'] = directions[ground_truth]


instance_task = Task(
    phases=phases,
    input_features=inputs,
    output_features=outputs,
    trial_init=trial_init,
    seed=0,
    num_classes=3,
    dt=DT,
)

X, Y, info = instance_task.sample_trial(0)
print('X.shape =', X.shape)
print('Y.shape =', Y.shape)
print('num_classes =', instance_task.num_classes)
print('trial_state keys =', sorted(info['trial_state']))
X.shape = (1000, 9)
Y.shape = (1000,)
num_classes = 3
trial_state keys = ['coherence', 'direction', 'ground_truth', 'output_mode', 'trial_index']

6. Class-based tasks#

For reusable, parameterized tasks, subclass Task and override define_features, define_phases, and trial_init. Constructor keyword arguments such as num_stimuli=, seed=, dt=, and num_classes= are handled by the base class.

Override get_trial_meta when you want batch_sample(..., return_meta=True) to return a compact, numeric metadata pytree.

class MyDMS(Task):
    t_fixation = 200 * u.ms
    t_sample = 400 * u.ms
    t_delay = 600 * u.ms
    t_response = 200 * u.ms
    num_stimuli = 8

    def define_features(self):
        fix = Feature(1, 'fixation')
        stim = Feature(self.num_stimuli, 'stimulus')
        choice = Feature(2, 'choice')
        return fix + stim, fix + choice

    def define_phases(self):
        return concat([
            Fixation(
                self.t_fixation,
                inputs={'fixation': 1.0},
                outputs={'label': 0},
            ),
            Sample(
                self.t_sample,
                name='sample',
                inputs={
                    'fixation': 1.0,
                    'stimulus': von_mises('sample_idx', num_dirs=self.num_stimuli),
                },
                outputs={'label': 0},
            ),
            Delay(
                self.t_delay,
                inputs={'fixation': 1.0},
                outputs={'label': 0},
            ),
            Test(
                self.t_sample,
                name='test',
                inputs={
                    'fixation': 1.0,
                    'stimulus': von_mises('test_idx', num_dirs=self.num_stimuli),
                },
                outputs={'label': 0},
            ),
            Response(
                self.t_response,
                inputs={'fixation': 0.0},
                outputs={'label': match_label('is_match')},
            ),
        ])

    def trial_init(self, ctx):
        sample_idx = ctx.rng.choice(self.num_stimuli)
        is_match = ctx.rng.uniform() < 0.5
        non_match_idx = (
            sample_idx + 1 + ctx.rng.choice(self.num_stimuli - 1)
        ) % self.num_stimuli
        ctx['sample_idx'] = sample_idx
        ctx['is_match'] = is_match
        ctx['test_idx'] = jnp.where(is_match, sample_idx, non_match_idx)

    def get_trial_meta(self, trial_state):
        return {
            'sample_idx': trial_state['sample_idx'],
            'test_idx': trial_state['test_idx'],
            'is_match': trial_state['is_match'],
        }


dms_task = MyDMS(num_stimuli=16, seed=42, num_classes=3, dt=DT)
X, Y, mask, meta = dms_task.batch_sample(4, return_mask=True, return_meta=True)
print('X.shape =', X.shape)
print('Y.shape =', Y.shape)
print('mask.shape =', mask.shape)
print('meta:', {k: np.asarray(v) for k, v in meta.items()})
X.shape = (1800, 4, 17)
Y.shape = (1800, 4)
mask.shape = (1800, 4)
meta: {'is_match': array([ True, False, False,  True]), 'sample_idx': array([ 5,  0,  6, 15], dtype=int32), 'test_idx': array([ 5,  6,  9, 15], dtype=int32)}

7. Vector-output tasks#

Pass output_mode='vector' when the target is a dense vector or population code rather than integer class labels. In vector mode, each phase writes named output features directly. Features omitted from a phase stay at zero.

fix_in = Feature(1, 'fixation')
stim_in = Feature(16, 'stimulus')
fix_out = Feature(1, 'fixation_out')
dir_out = Feature(16, 'direction_out')

vector_task = Task(
    phases=concat([
        Fixation(
            200 * u.ms,
            inputs={'fixation': 1.0},
            outputs={'fixation_out': 1.0},
        ),
        Stimulus(
            500 * u.ms,
            inputs={
                'fixation': 1.0,
                'stimulus': von_mises('sample_idx', num_dirs=16),
            },
            outputs={'fixation_out': 1.0},
        ),
        Delay(
            800 * u.ms,
            inputs={'fixation': 1.0},
            outputs={'fixation_out': 1.0},
        ),
        Response(
            400 * u.ms,
            inputs={'fixation': 0.0},
            outputs={'direction_out': von_mises('sample_idx', num_dirs=16)},
        ),
    ]),
    input_features=fix_in + stim_in,
    output_features=fix_out + dir_out,
    output_mode='vector',
    trial_init=lambda ctx: ctx.update(sample_idx=ctx.rng.choice(16)),
    seed=0,
    dt=DT,
)

X_time, Y_time = vector_task.batch_sample(8)
X_batch, Y_batch = vector_task.batch_sample(8, time_first=False)
print('time_first=True :', X_time.shape, Y_time.shape)
print('time_first=False:', X_batch.shape, Y_batch.shape)
print('num_classes =', vector_task.num_classes)
time_first=True : (1900, 8, 17) (1900, 8, 17)
time_first=False: (8, 1900, 17) (8, 1900, 17)
num_classes = None

8. Conditional phases with If and Switch#

If and Switch make the task variable-length internally, so tasks containing them use packed buffers. Call batch_sample(..., return_mask=True) when you need to distinguish valid timesteps from padding.

For If, return a Python bool or a scalar JAX boolean from the condition. Do not wrap traced values with bool(...); that breaks under JIT/vmap.

For Switch under batch_sample, use integer case keys when the selector returns a traced value. String keys are fine for eager sample_trial when the selector is concrete, but traced strings are not a JAX value type.

def branch_trial_init(ctx):
    sample_idx = ctx.rng.choice(8)
    is_match = (jnp.asarray(ctx['trial_index']) % 2) == 0
    ctx['sample_idx'] = sample_idx
    ctx['is_match'] = is_match
    ctx['test_idx'] = jnp.where(is_match, sample_idx, (sample_idx + 1) % 8)


branch_task = Task(
    phases=concat([
        Fixation(50 * u.ms, inputs={'fixation': 1.0}, outputs={'label': 0}),
        Sample(
            80 * u.ms,
            inputs={'fixation': 1.0, 'stimulus': von_mises('sample_idx', num_dirs=8)},
            outputs={'label': 0},
        ),
        Delay(100 * u.ms, inputs={'fixation': 1.0}, outputs={'label': 0}),
        Test(
            80 * u.ms,
            inputs={'fixation': 1.0, 'stimulus': von_mises('test_idx', num_dirs=8)},
            outputs={'label': 0},
        ),
        If(
            condition=lambda ctx: ctx['is_match'],
            then=Response(60 * u.ms, outputs={'label': 1}, name='match_response'),
            else_=Response(60 * u.ms, outputs={'label': 2}, name='nonmatch_response'),
        ),
    ]),
    input_features=fix + stim,
    output_features=outputs,
    trial_init=branch_trial_init,
    seed=1,
    num_classes=3,
    dt=DT,
)

X_if, Y_if, mask_if = branch_task.batch_sample(6, return_mask=True)
print('is_variable_length =', branch_task.is_variable_length)
print('X.shape =', X_if.shape, 'Y.shape =', Y_if.shape, 'mask.shape =', mask_if.shape)
print('valid steps per trial =', np.asarray(mask_if.sum(axis=0)))
print('response label at final step =', np.asarray(Y_if[-1]))
is_variable_length = True
X.shape = (370, 6, 9) Y.shape = (370, 6) mask.shape = (370, 6)
valid steps per trial = [370 370 370 370 370 370]
response label at final step = [1 2 1 2 1 2]
switch_task = Task(
    phases=concat([
        Fixation(20 * u.ms, inputs={'fixation': 1.0}, outputs={'label': 0}),
        Switch(
            selector=lambda ctx: jnp.asarray(ctx['rule'], dtype=jnp.int32),
            cases={
                0: Cue(
                    30 * u.ms,
                    name='rule_0',
                    inputs={'rule': one_hot('rule', num_classes=3)},
                    outputs={'label': 1},
                ),
                1: Cue(
                    60 * u.ms,
                    name='rule_1',
                    inputs={'rule': one_hot('rule', num_classes=3)},
                    outputs={'label': 2},
                ),
                2: Cue(
                    90 * u.ms,
                    name='rule_2',
                    inputs={'rule': one_hot('rule', num_classes=3)},
                    outputs={'label': 3},
                ),
            },
        ),
    ]),
    input_features=Feature(1, 'fixation') + Feature(3, 'rule'),
    output_features=Feature(1, 'fixation') + Feature(3, 'choice'),
    trial_init=lambda ctx: ctx.update(rule=jnp.asarray(ctx['trial_index']) % 3),
    seed=0,
    num_classes=4,
    dt=DT,
)

X_sw, Y_sw, mask_sw = switch_task.batch_sample(6, return_mask=True)
print('valid steps per trial =', np.asarray(mask_sw.sum(axis=0)))
print('last valid labels =', [int(Y_sw[int(mask_sw[:, i].sum()) - 1, i]) for i in range(6)])
valid steps per trial = [ 50  80 110  50  80 110]
last valid labels = [1, 2, 3, 1, 2, 3]

9. Looping with While#

While(condition, body, max_iterations) repeatedly executes body until the condition returns False, capped by max_iterations. It allocates buffers for the maximum possible length and uses info['mask'] to mark the actual length.

Current limitation: a data-dependent While condition is intended for eager sample_trial. Under batch_sample, conditions that depend on traced random or per-trial values raise a clear NotImplementedError. Use a bounded Repeat or VariableDuration when you need JIT/vmap-friendly batched sampling.

def increment_counter(ctx):
    ctx['counter'] = int(ctx.get('counter', 0)) + 1


while_task = Task(
    phases=While(
        condition=lambda ctx: int(ctx.get('counter', 0)) < ctx['target_count'],
        body=Stimulus(
            25 * u.ms,
            inputs={'stimulus': 1.0},
            outputs={'label': 1},
            on_exit=increment_counter,
        ),
        max_iterations=5,
    ),
    input_features=Feature(1, 'stimulus'),
    output_features=Feature(1, 'choice'),
    trial_init=lambda ctx: ctx.update(counter=0, target_count=3),
    seed=0,
    num_classes=2,
    dt=DT,
)

X_while, Y_while, info_while = while_task.sample_trial(0)
print('allocated steps =', X_while.shape[0])
print('valid steps =', int(np.asarray(info_while['mask']).sum()))
print('iterations =', info_while['trial_state']['while_total_iterations'])
allocated steps = 125
valid steps = 75
iterations = 3

10. Custom encoders#

Any callable with signature f(ctx, feature) -> value is a valid value spec. Return one of these shapes:

  • A scalar, broadcast to (duration, feature.num).

  • A 1-D array with shape (feature.num,), broadcast along time.

  • A 2-D array with shape (duration, feature.num), written directly.

For fixed-duration phases, ctx.phase_duration is the number of timesteps in the current phase. Variable-length custom encoders should follow the packed buffer details in Tutorial 3.

def ramping_pulse(start_val, stop_val):
    def encode(ctx, feature):
        ramp = jnp.linspace(start_val, stop_val, ctx.phase_duration)
        return jnp.broadcast_to(ramp[:, None], (ctx.phase_duration, feature.num))

    encode.__name__ = f'ramping_pulse({start_val}, {stop_val})'
    return encode


ramp_task = Task(
    phases=Stimulus(
        5 * u.ms,
        inputs={'stimulus': ramping_pulse(0.0, 1.0)},
        outputs={'label': 0},
    ),
    input_features=Feature(2, 'stimulus'),
    output_features=Feature(1, 'choice'),
    num_classes=1,
    dt=DT,
)

X_ramp, _, _ = ramp_task.sample_trial(0)
print(np.round(np.asarray(X_ramp), 2))
[[0.   0.  ]
 [0.25 0.25]
 [0.5  0.5 ]
 [0.75 0.75]
 [1.   1.  ]]

Where to next#

  • Tutorial 3 - Variable-length trial sequences covers VariableDuration, packed buffers, masks, and masked losses.

  • The API reference (braintools.cogtask under API Reference) lists every pre-built task, encoder, phase, and utility with full parameter docs.