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)
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
rootstr | Path- required. Split directory.
shufflebool- keyword-only, default=False. Shuffle the index at construction and on reshuffle.
seedint- keyword-only, default=0. Seed of the initial shuffle.
shuffle_modeLiteral['sample', 'shard']- keyword-only, default='sample'. 'sample' permutes all traces; 'shard' permutes shards and the traces within each shard.
cache_shardsint- keyword-only, default=0. Decoded shards kept in an LRU cache; 0 disables caching.
Methods
ShardedNeuronIODataset.__len__()ShardedNeuronIODataset.reshuffle()ShardedNeuronIODataset.__getitem__()ShardedNeuronIODataset.get_batch()ShardedNeuronIODataset.get_sample_ids()ShardedNeuronIODataset.get_optional_array_batch()
ShardedNeuronIODataset.len
axobench.data.ShardedNeuronIODataset.__len__() -> int
Number of indexed traces.
Returns
countint- Trace count.
ShardedNeuronIODataset.reshuffle
axobench.data.ShardedNeuronIODataset.reshuffle(seed: int) -> None
Reshuffle the index with a new seed; no effect unless shuffle=True.
Parameters
seedint- required. Shuffle seed.
ShardedNeuronIODataset.getitem
axobench.data.ShardedNeuronIODataset.__getitem__(index: int) -> NeuronIOSample
Load one trace.
Parameters
indexint- required. Position in the index.
Returns
sampleNeuronIOSample- 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]
Load several traces. Consecutive indices from the same shard are read together, so sorted indices minimize shard reads.
Parameters
indicesrange | list[int]- required. Positions in the index.
Returns
inputsnp.ndarray- float32 (batch, time, channels).
targetsnp.ndarray- float32 (batch, time, 2).
ShardedNeuronIODataset.get_sample_ids
axobench.data.ShardedNeuronIODataset.get_sample_ids(indices: range | list[int]) -> list[str]
Sample IDs of the given positions.
Parameters
indicesrange | list[int]- required. Positions in the index.
Returns
sample_idslist[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
Load an additional per-trace array, such as soma_mv or context_index, from NPZ shards.
Parameters
namestr- required. Array name in the shard.
indicesrange | list[int]- required. Positions in the index.
Returns
arraynp.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)
One trace returned by indexing a dataset.
Parameters
sample_idstr- required. Sample ID.
inputsnp.ndarray- required. Inputs, (time, channels).
targetsnp.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
Write small deterministic shards with random signed events and a synthetic target, for smoke tests only.
Parameters
rootstr | Path- required. Output directory.
shard_countint- keyword-only, default=2. Number of shards.
samples_per_shardint- keyword-only, default=8. Traces per shard.
time_stepsint- keyword-only, default=32. Steps per trace.
input_dimint- keyword-only, default=64. Input channels.
seedint- 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]
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_rootstr | Path- required. Source split directory.
output_rootstr | Path- required. Destination directory.
input_dtypenp.dtype | type- keyword-only, default=np.int8. Storage dtype of the inputs.
Returns
pathslist[Path]- Written input files.