Tutorial 2: Building custom tasks#
This tutorial covers the building blocks used to assemble a custom
braintools.cogtask.Task:
Features and feature composition.
Declarative phases and value-spec shape rules.
Built-in encoders and categorical label helpers.
Instance-based and class-based task definitions.
Vector-output tasks.
Conditional phases with masks.
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 + bconcatenates features.a | bis an alias for concatenation.features - 'name'returns a new set without that feature.Feature(..., 'base') * ncreates 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 bysigma / 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 |
|---|---|---|
|
integer class index |
Uses |
|
angle in radians |
Set |
|
discrete direction index |
Defaults to |
|
discrete direction index |
Requires |
|
scalar |
Gaussian bump over evenly spaced centers. |
|
scalar |
Broadcasts one scalar to the whole feature. |
|
array or scalar |
Passes through a context value after shape checking. |
|
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 fromctx['ground_truth'].label(lambda ctx: ...)computes a class id from trial state.match_label('is_match')emits1for match trials and2otherwise.comparison_label('is_greater')emits1for greater and2otherwise.
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:
Define input and output features.
Define the phase structure.
Define
trial_init(ctx)to populate per-trial state.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.cogtaskunder API Reference) lists every pre-built task, encoder, phase, and utility with full parameter docs.