AxoBench API

Trace datasets

Signatures, parameters, return values, and source for trace datasets.

Overview

ShardedNeuronIODataset reads a split directory of NPZ shards, or of NPY shards listed in a manifest, as used by every AxoBench release. Inputs are returned as float32 (batch, time, channels) and targets as float32 (batch, time, 2). See single-neuron traces for an example.

Source revision: 496e0c1a2dfd. Export index.

ShardedNeuronIODataset

axobench.data.ShardedNeuronIODataset(root: str | Path, *, shuffle: bool=False, seed: int=0, shuffle_mode: Literal['sample', 'shard']='sample', cache_shards: int=0)

Source

Deterministic reader for a directory of shards. With a manifest.json, the index follows the manifest entries whose shards are present; otherwise every *.npz file is read in sorted order. Reading a trace decodes the input array of its whole shard.

Parameters

root str | Path
required. Split directory.
shuffle bool
keyword-only, default=False. Shuffle the index at construction and on reshuffle.
seed int
keyword-only, default=0. Seed of the initial shuffle.
shuffle_mode Literal['sample', 'shard']
keyword-only, default='sample'. 'sample' permutes all traces; 'shard' permutes shards and the traces within each shard.
cache_shards int
keyword-only, default=0. Decoded shards kept in an LRU cache; 0 disables caching.

Methods

ShardedNeuronIODataset.len

axobench.data.ShardedNeuronIODataset.__len__() -> int

Source

Number of indexed traces.

Returns

count int
Trace count.

ShardedNeuronIODataset.reshuffle

axobench.data.ShardedNeuronIODataset.reshuffle(seed: int) -> None

Source

Reshuffle the index with a new seed; no effect unless shuffle=True.

Parameters

seed int
required. Shuffle seed.

ShardedNeuronIODataset.getitem

axobench.data.ShardedNeuronIODataset.__getitem__(index: int) -> NeuronIOSample

Source

Load one trace.

Parameters

index int
required. Position in the index.

Returns

sample NeuronIOSample
Sample ID, (time, channels) inputs, and (time, 2) targets.

ShardedNeuronIODataset.get_batch

axobench.data.ShardedNeuronIODataset.get_batch(indices: range | list[int]) -> tuple[np.ndarray, np.ndarray]

Source

Load several traces. Consecutive indices from the same shard are read together, so sorted indices minimize shard reads.

Parameters

indices range | list[int]
required. Positions in the index.

Returns

inputs np.ndarray
float32 (batch, time, channels).
targets np.ndarray
float32 (batch, time, 2).

ShardedNeuronIODataset.get_sample_ids

axobench.data.ShardedNeuronIODataset.get_sample_ids(indices: range | list[int]) -> list[str]

Source

Sample IDs of the given positions.

Parameters

indices range | list[int]
required. Positions in the index.

Returns

sample_ids list[str]
Sample IDs in order.

ShardedNeuronIODataset.get_optional_array_batch

axobench.data.ShardedNeuronIODataset.get_optional_array_batch(name: str, indices: range | list[int]) -> np.ndarray | None

Source

Load an additional per-trace array, such as soma_mv or context_index, from NPZ shards.

Parameters

name str
required. Array name in the shard.
indices range | list[int]
required. Positions in the index.

Returns

array np.ndarray | None
Concatenated values, or None when a shard lacks the array or is stored as NPY files.

NeuronIOSample

axobench.data.NeuronIOSample(sample_id: str, inputs: np.ndarray, targets: np.ndarray)

Source

One trace returned by indexing a dataset.

Parameters

sample_id str
required. Sample ID.
inputs np.ndarray
required. Inputs, (time, channels).
targets np.ndarray
required. Targets, (time, 2).

Attributes

Constructor fields are retained as read-only attributes.

write_demo_shards

axobench.data.write_demo_shards(root: str | Path, *, shard_count: int=2, samples_per_shard: int=8, time_steps: int=32, input_dim: int=64, seed: int=0) -> None

Source

Write small deterministic shards with random signed events and a synthetic target, for smoke tests only.

Parameters

root str | Path
required. Output directory.
shard_count int
keyword-only, default=2. Number of shards.
samples_per_shard int
keyword-only, default=8. Traces per shard.
time_steps int
keyword-only, default=32. Steps per trace.
input_dim int
keyword-only, default=64. Input channels.
seed int
keyword-only, default=0. Random seed.

repack_shards_as_npy

axobench.data.repack_shards_as_npy(input_root: str | Path, output_root: str | Path, *, input_dtype: np.dtype | type=np.int8) -> list[Path]

Source

Repack shards as separate .npy arrays with a manifest, preserving the trace order, so arrays can be memory-mapped. Raises ValueError if input_dtype would change values.

Parameters

input_root str | Path
required. Source split directory.
output_root str | Path
required. Destination directory.
input_dtype np.dtype | type
keyword-only, default=np.int8. Storage dtype of the inputs.

Returns

paths list[Path]
Written input files.

Search guides, examples, and API signatures.