API reference

Trace datasets

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

Overview

NeuronIO shards store inputs (samples, time, channels), targets (samples, time, 2), and sample identities. Dataset samples expose one (time, channels) input and one (time, 2) target. get_batch returns batched NumPy arrays. Window datasets preserve sample identity while selecting native time windows; preserve context boundaries when splitting data.

Source revision: caef7be03abd. Public export index.

NeuronIOSample

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

Source

One identified native input trace and its two-channel target trace.

Parameters

sample_id str
required. Persistent trace identity from the shard's sample_ids array.
inputs np.ndarray
required. One native input trace, shaped (time,input_channels).
targets np.ndarray
required. One spike/soma target trace, shaped (time,2).

Attributes

Constructor fields are retained as read-only attributes.

ShardedNeuronIODataset

axosim.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 pre-sharded NeuronIO-style NPZ files.

Parameters

root str | Path
required. Dataset shard directory or manifest root.
shuffle bool
keyword-only, default=False. Enable deterministic reordering controlled by seed and shuffle_mode.
seed int
keyword-only, default=0. Random seed for the declared operation.
shuffle_mode Literal['sample', 'shard']
keyword-only, default='sample'. Choose sample-level or shard-level reordering.
cache_shards int
keyword-only, default=0. Maximum cached shards; zero disables the cache.

Methods

ShardedNeuronIODataset.len

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

Source

Return the number of indexed samples.

Returns

int

ShardedNeuronIODataset.reshuffle

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

Source

Reorder the enabled sampling index using the supplied seed.

Parameters

seed int
required. Random seed for the declared operation.

Returns

result None
No return value.

ShardedNeuronIODataset.getitem

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

Source

Read one sample and its input/target contract.

Returns NeuronIOSample with sample_id, inputs (T,C), and targets (T,2).

Parameters

index int
required. Index of one dataset sample.

Returns

NeuronIOSample

ShardedNeuronIODataset.get_batch

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

Source

Read the requested input and target arrays as a batch.

Returns (inputs,targets) NumPy arrays with shapes (B,T,C) and (B,T,2). Selected shard windows must have compatible lengths for stacking.

Parameters

indices range | list[int]
required. Requested dataset sample indices.

Returns

inputs np.ndarray
Native inputs with shape (batch,time,input_channels).
targets np.ndarray
Spike and soma targets with shape (batch,time,2).

ShardedNeuronIODataset.get_sample_ids

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

Source

Return the sample identities associated with the selected indices.

Parameters

indices range | list[int]
required. Requested dataset sample indices.

Returns

list[str]

ShardedNeuronIODataset.get_optional_array_batch

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

Source

Return an optional per-sample array from NPZ shards when present.

Parameters

name str
required. Name of the optional shard array or declared record.
indices range | list[int]
required. Requested dataset sample indices.

Returns

np.ndarray \| None

ShardedNeuronIODataset.get_shard_sequence_length

axosim.data.ShardedNeuronIODataset.get_shard_sequence_length(shard_idx: int) -> int

Source

Read the input time dimension without materializing a shard array.

Parameters

shard_idx int
required. Index of the shard in the dataset manifest.

Returns

int

DeterministicWindowDataset

axosim.data.DeterministicWindowDataset(base: ShardedNeuronIODataset, *, window_size: int, stride: int | None=None, start_offset: int=0)

Source

Enumerate fixed-size windows from another NeuronIO-style dataset.

Parameters

base ShardedNeuronIODataset
required.
window_size int
keyword-only, required. Native timesteps per extracted window.
stride int | None
keyword-only, default=None. Distance between selected positions in the relevant sequence.
start_offset int
keyword-only, default=0. Native timestep index before the first selected window.

Methods

DeterministicWindowDataset.len

axosim.data.DeterministicWindowDataset.__len__() -> int

Source

Return the number of indexed samples.

Returns

int

DeterministicWindowDataset.getitem

axosim.data.DeterministicWindowDataset.__getitem__(index: int) -> NeuronIOSample

Source

Read one sample and its input/target contract.

Parameters

index int
required. Index of one dataset sample.

Returns

NeuronIOSample

DeterministicWindowDataset.get_batch

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

Source

Read the requested input and target arrays as a batch.

Parameters

indices range | list[int]
required. Requested dataset sample indices.

Returns

inputs np.ndarray
Native inputs with shape (batch,time,input_channels).
targets np.ndarray
Spike and soma targets with shape (batch,time,2).

DeterministicWindowDataset.get_sample_ids

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

Source

Return the sample identities associated with the selected indices.

Parameters

indices range | list[int]
required. Requested dataset sample indices.

Returns

list[str]

RandomFullTraceWindowDataset

axosim.data.RandomFullTraceWindowDataset(base: ShardedNeuronIODataset, *, window_size: int=500, start_offset: int=500, samples_per_epoch: int | None=None, batch_size: int=8, shard_reuse_batches: int=1, sequence_length: int | None=None, seed: int=0, cache_full_shards: bool=True)

Source

Sample deterministic random windows from cached full-trace shards.

Parameters

base ShardedNeuronIODataset
required.
window_size int
keyword-only, default=500. Native timesteps per extracted window.
start_offset int
keyword-only, default=500. Native timestep index before the first selected window.
samples_per_epoch int | None
keyword-only, default=None. Number of training window presentations requested per epoch.
batch_size int
keyword-only, default=8. Examples processed per batch.
shard_reuse_batches int
keyword-only, default=1. Number of consecutive batches sampled before advancing to another shard.
sequence_length int | None
keyword-only, default=None. Native timestep count of a trace.
seed int
keyword-only, default=0. Random seed for the declared operation.
cache_full_shards bool
keyword-only, default=True. Retain complete shard arrays rather than only selected data.

Methods

RandomFullTraceWindowDataset.len

axosim.data.RandomFullTraceWindowDataset.__len__() -> int

Source

Return the number of indexed samples.

Returns

int

RandomFullTraceWindowDataset.reshuffle

axosim.data.RandomFullTraceWindowDataset.reshuffle(seed: int) -> None

Source

Reorder the enabled sampling index using the supplied seed.

Parameters

seed int
required. Random seed for the declared operation.

Returns

result None
No return value.

RandomFullTraceWindowDataset.getitem

axosim.data.RandomFullTraceWindowDataset.__getitem__(index: int) -> NeuronIOSample

Source

Read one sample and its input/target contract.

Parameters

index int
required. Index of one dataset sample.

Returns

NeuronIOSample

RandomFullTraceWindowDataset.get_batch

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

Source

Read the requested input and target arrays as a batch.

Parameters

indices range | list[int]
required. Requested dataset sample indices.

Returns

inputs np.ndarray
Native inputs with shape (batch,time,input_channels).
targets np.ndarray
Spike and soma targets with shape (batch,time,2).

RandomFullTraceWindowDataset.get_sample_ids

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

Source

Return the sample identities associated with the selected indices.

Parameters

indices range | list[int]
required. Requested dataset sample indices.

Returns

list[str]

OfficialStyleFullTraceWindowDataset

axosim.data.OfficialStyleFullTraceWindowDataset(base: ShardedNeuronIODataset, *, window_size: int=500, start_offset: int=500, samples_per_epoch: int | None=None, batch_size: int=8, file_load_fraction: float=0.3, source_simulations: int=128, sequence_length: int | None=None, seed: int=0, cache_full_shards: bool=True)

Source

Deterministic port of the official NeuronIO file/simulation/time sampling policy.

Parameters

base ShardedNeuronIODataset
required.
window_size int
keyword-only, default=500. Native timesteps per extracted window.
start_offset int
keyword-only, default=500. Native timestep index before the first selected window.
samples_per_epoch int | None
keyword-only, default=None. Number of training window presentations requested per epoch.
batch_size int
keyword-only, default=8. Examples processed per batch.
file_load_fraction float
keyword-only, default=0.3. Fraction of each shard made available to the sampling path.
source_simulations int
keyword-only, default=128. Number of source simulations included by the dataset declaration.
sequence_length int | None
keyword-only, default=None. Native timestep count of a trace.
seed int
keyword-only, default=0. Random seed for the declared operation.
cache_full_shards bool
keyword-only, default=True. Retain complete shard arrays rather than only selected data.

Methods

OfficialStyleFullTraceWindowDataset.len

axosim.data.OfficialStyleFullTraceWindowDataset.__len__() -> int

Source

Return the number of indexed samples.

Returns

int

OfficialStyleFullTraceWindowDataset.reshuffle

axosim.data.OfficialStyleFullTraceWindowDataset.reshuffle(seed: int) -> None

Source

Reorder the enabled sampling index using the supplied seed.

Parameters

seed int
required. Random seed for the declared operation.

Returns

result None
No return value.

OfficialStyleFullTraceWindowDataset.getitem

axosim.data.OfficialStyleFullTraceWindowDataset.__getitem__(index: int) -> NeuronIOSample

Source

Read one sample and its input/target contract.

Parameters

index int
required. Index of one dataset sample.

Returns

NeuronIOSample

OfficialStyleFullTraceWindowDataset.get_batch

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

Source

Read the requested input and target arrays as a batch.

Parameters

indices range | list[int]
required. Requested dataset sample indices.

Returns

inputs np.ndarray
Native inputs with shape (batch,time,input_channels).
targets np.ndarray
Spike and soma targets with shape (batch,time,2).

OfficialStyleFullTraceWindowDataset.get_sample_ids

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

Source

Return the sample identities associated with the selected indices.

Parameters

indices range | list[int]
required. Requested dataset sample indices.

Returns

list[str]

write_demo_shards

axosim.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

Create small deterministic NeuronIO-style shards for smoke tests.

Creates deterministic synthetic shard files for pipeline checks. The generated targets are not biological reference data. Returns written shard paths.

Parameters

root str | Path
required. Dataset shard directory or manifest root.
shard_count int
keyword-only, default=2. Number of synthetic shard files to write.
samples_per_shard int
keyword-only, default=8. Synthetic sample count in each generated shard.
time_steps int
keyword-only, default=32. Native sequence horizon.
input_dim int
keyword-only, default=64. Native input-channel count.
seed int
keyword-only, default=0. Random seed for the declared operation.

Returns

paths list[Path]
Written synthetic shard paths. These shards exercise the reader and trainer contracts.

Examples

Create synthetic shards to verify the reader contract before using biological data.

from tempfile import TemporaryDirectory
from axosim.data import ShardedNeuronIODataset, write_demo_shards

with TemporaryDirectory() as directory:
    write_demo_shards(directory, samples_per_shard=2, time_steps=12, input_dim=6)
    inputs, targets = ShardedNeuronIODataset(directory).get_batch([0, 1])
    print(inputs.shape, targets.shape)
(2, 12, 6) (2, 12, 2)

repack_shards_as_npy

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

Source

Repack existing shards as sliceable .npy arrays with identical sample order.

Parameters

input_root str | Path
required. Directory containing the source dataset shards.
output_root str | Path
required. Directory receiving converted dataset shards.
input_dtype np.dtype | type
keyword-only, default=np.int8. Stored NumPy dtype of the converted input arrays.

Returns

list[Path]

Search guides, examples, and API signatures.