Tutorial 1: Quickstart with braintools.cogtask#
braintools.cogtask is a modular framework for building cognitive-task data
for neural-network training and computational neuroscience simulations. This
quickstart uses a fixed-length perceptual decision-making task and covers the
current API for:
Importing
cogtaskand choosing a time step.Sampling one reproducible trial from a pre-built task.
Sampling JIT/
vmap-friendly batches for training loops.Reading
X,Y, metadata, masks, and class counts.Changing the sampling time step without relying on stale JIT shapes.
1. Setup#
Task durations are specified in real time, such as 1500 * u.ms, and are
resolved to integer timesteps through a dt. You can set an ambient default
with brainstate.environ.set(dt=...). For code that uses the JIT-compiled
batch_sample method, prefer passing dt= to the task constructor so the
static timestep count is tied to the task object itself.
import numpy as np
import brainstate
import brainunit as u
from braintools import cogtask
DT = 1.0 * u.ms
brainstate.environ.set(dt=DT)
2. Create a pre-built task#
Pre-built tasks are exported from braintools.cogtask. Their constructors
accept paradigm-specific parameters, such as stimulus duration and number of
choices, plus common Task options such as seed=, dt=, output_mode=, and
num_classes=.
Here we use categorical output mode, the default. The target Y is a 1-D array
of integer class labels over time.
def make_pdm(dt=DT, seed=0):
return cogtask.PerceptualDecisionMaking(
t_stimulus=1500 * u.ms,
num_choices=2,
seed=seed,
dt=dt,
)
task = make_pdm()
task
Task(name=PerceptualDecisionMaking, inputs=9, outputs=3, output_mode=categorical)
3. Sample one trial#
sample_trial(index) returns (X, Y, info):
X: input tensor with shape(T, num_inputs).Y: target tensor with shape(T,)in categorical mode, or(T, num_outputs)in vector mode.info: Python-side metadata withphase_history,trial_state,dt,index, andmask.
For this fixed-length task, info['mask'] is None. Variable-length tasks use
a boolean mask; Tutorial 3 covers that path in detail.
X, Y, info = task.sample_trial(0)
print('X.shape =', X.shape)
print('Y.shape =', Y.shape)
print('num_inputs =', task.num_inputs)
print('num_outputs =', task.num_outputs)
print('num_classes =', task.num_classes)
print('info keys =', sorted(info))
print("info['mask'] =", info['mask'])
X.shape = (1700, 9)
Y.shape = (1700,)
num_inputs = 9
num_outputs = 3
num_classes = 3
info keys = ['dt', 'index', 'mask', 'phase_history', 'trial_state']
info['mask'] = None
num_outputs is the width of the output FeatureSet.
In categorical mode, model heads should usually use task.num_classes, because
Y stores class ids rather than dense output vectors.
phase_history is useful for debugging task timing. Each entry is
(name, start, end) in timesteps. Compound composition nodes (Sequence,
Parallel, Repeat, …) are recorded too, after their children, with their own
full span – here the top-level Sequence covers the whole trial.
for name, start, end in info['phase_history']:
print(f'{name:<12s} [{start:4d} : {end:4d})')
fixation [ 0 : 100)
stimulus [ 100 : 1600)
response [1600 : 1700)
Sequence [ 0 : 1700)
state = info['trial_state']
print('trial_index =', int(state['trial_index']))
print('ground_truth =', int(state['ground_truth']))
print('coherence =', f"{float(state['coherence']):.1f}")
print('stimulus_direction =', f"{float(state['stimulus_direction']):.3f}")
trial_index = 0
ground_truth = 0
coherence = 25.6
stimulus_direction = 0.000
4. Sample batches for training#
batch_sample(B) is the JIT/vmap-compiled entry point. It returns time-first
arrays by default, matching common RNN conventions.
Call |
Returned shapes |
|---|---|
|
|
|
|
|
|
|
adds |
|
adds batched metadata from |
return_mask=True also works for fixed-length tasks; the returned mask is all
True. That makes it convenient to write one training loop for fixed- and
variable-length tasks.
Xb, Yb, mask = task.batch_sample(32, return_mask=True)
print('Xb.shape =', Xb.shape)
print('Yb.shape =', Yb.shape)
print('mask.shape =', mask.shape)
print('all mask entries valid?', bool(np.asarray(mask).all()))
Xb.shape = (1700, 32, 9)
Yb.shape = (1700, 32)
mask.shape = (1700, 32)
all mask entries valid? True
Reproducible batches#
When Task is constructed with seed=N, each trial uses
jax.random.fold_in(PRNGKey(N), index) as its per-trial random key. Two calls
with the same start_index produce identical batches; advancing start_index
gives a fresh, non-overlapping slice of trials.
X1, Y1 = task.batch_sample(8, start_index=0)
X2, Y2 = task.batch_sample(8, start_index=0)
X3, Y3 = task.batch_sample(8, start_index=8)
same_start = (
np.array_equal(np.asarray(X1), np.asarray(X2))
and np.array_equal(np.asarray(Y1), np.asarray(Y2))
)
next_start_differs = not np.array_equal(np.asarray(X1), np.asarray(X3))
print('same start_index identical?', same_start)
print('next start_index differs?', next_start_differs)
same start_index identical? True
next start_index differs? True
Streaming batches through training#
A typical training loop increments start_index by batch_size at every step.
Passing return_mask=True from the start keeps the loop compatible with both
fixed- and variable-length tasks.
batch_size = 16
num_steps = 4
for step in range(num_steps):
Xb, Yb, mask = task.batch_sample(
batch_size,
start_index=step * batch_size,
return_mask=True,
)
# train_step(model, Xb, Yb, mask)
print(
f'step {step:>2d} X={Xb.shape} Y={Yb.shape} mask={mask.shape}'
)
step 0 X=(1700, 16, 9) Y=(1700, 16) mask=(1700, 16)
step 1 X=(1700, 16, 9) Y=(1700, 16) mask=(1700, 16)
step 2 X=(1700, 16, 9) Y=(1700, 16) mask=(1700, 16)
step 3 X=(1700, 16, 9) Y=(1700, 16) mask=(1700, 16)
5. Change dt safely#
The real-time phase durations stay fixed when dt changes; only the number of
timesteps changes. Because batch_sample is JIT-compiled and returns static
shapes, create a task with the desired dt instead of wrapping repeated batch
calls on the same task in different ambient brainstate.environ.context(dt=...)
blocks.
fine_task = make_pdm(dt=0.5 * u.ms)
coarse_task = make_pdm(dt=2.0 * u.ms)
X_fine, _ = fine_task.batch_sample(4)
X_coarse, _ = coarse_task.batch_sample(4)
print('dt=0.5 ms -> T =', X_fine.shape[0])
print('dt=2.0 ms -> T =', X_coarse.shape[0])
dt=0.5 ms -> T = 3400
dt=2.0 ms -> T = 850
6. Where to next#
Tutorial 2 - Building custom tasks: phase composition, features, encoders, label helpers, and class-based
Tasksubclasses.Tutorial 3 - Variable-length trial sequences:
VariableDuration, conditional control flow, packed buffers, masks, and masked losses.API reference: see
braintools.cogtaskin the API Reference section for the full list of pre-built tasks, encoders, phases, and utilities.