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)
One identified native input trace and its two-channel target trace.
Parameters
sample_idstr- required. Persistent trace identity from the shard's sample_ids array.
inputsnp.ndarray- required. One native input trace, shaped (time,input_channels).
targetsnp.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)
Deterministic reader for pre-sharded NeuronIO-style NPZ files.
Parameters
rootstr | Path- required. Dataset shard directory or manifest root.
shufflebool- keyword-only, default=False. Enable deterministic reordering controlled by seed and shuffle_mode.
seedint- keyword-only, default=0. Random seed for the declared operation.
shuffle_modeLiteral['sample', 'shard']- keyword-only, default='sample'. Choose sample-level or shard-level reordering.
cache_shardsint- keyword-only, default=0. Maximum cached shards; zero disables the cache.
Methods
ShardedNeuronIODataset.__len__()ShardedNeuronIODataset.reshuffle()ShardedNeuronIODataset.__getitem__()ShardedNeuronIODataset.get_batch()ShardedNeuronIODataset.get_sample_ids()ShardedNeuronIODataset.get_optional_array_batch()ShardedNeuronIODataset.get_shard_sequence_length()
ShardedNeuronIODataset.len
axosim.data.ShardedNeuronIODataset.__len__() -> int
Return the number of indexed samples.
Returns
int
ShardedNeuronIODataset.reshuffle
axosim.data.ShardedNeuronIODataset.reshuffle(seed: int) -> None
Reorder the enabled sampling index using the supplied seed.
Parameters
seedint- required. Random seed for the declared operation.
Returns
resultNone- No return value.
ShardedNeuronIODataset.getitem
axosim.data.ShardedNeuronIODataset.__getitem__(index: int) -> NeuronIOSample
Read one sample and its input/target contract.
Returns NeuronIOSample with sample_id, inputs (T,C), and targets (T,2).
Parameters
indexint- 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]
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
indicesrange | list[int]- required. Requested dataset sample indices.
Returns
inputsnp.ndarray- Native inputs with shape (batch,time,input_channels).
targetsnp.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]
Return the sample identities associated with the selected indices.
Parameters
indicesrange | 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
Return an optional per-sample array from NPZ shards when present.
Parameters
namestr- required. Name of the optional shard array or declared record.
indicesrange | 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
Read the input time dimension without materializing a shard array.
Parameters
shard_idxint- 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)
Enumerate fixed-size windows from another NeuronIO-style dataset.
Parameters
baseShardedNeuronIODataset- required.
window_sizeint- keyword-only, required. Native timesteps per extracted window.
strideint | None- keyword-only, default=None. Distance between selected positions in the relevant sequence.
start_offsetint- keyword-only, default=0. Native timestep index before the first selected window.
Methods
DeterministicWindowDataset.__len__()DeterministicWindowDataset.__getitem__()DeterministicWindowDataset.get_batch()DeterministicWindowDataset.get_sample_ids()
DeterministicWindowDataset.len
axosim.data.DeterministicWindowDataset.__len__() -> int
Return the number of indexed samples.
Returns
int
DeterministicWindowDataset.getitem
axosim.data.DeterministicWindowDataset.__getitem__(index: int) -> NeuronIOSample
Read one sample and its input/target contract.
Parameters
indexint- 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]
Read the requested input and target arrays as a batch.
Parameters
indicesrange | list[int]- required. Requested dataset sample indices.
Returns
inputsnp.ndarray- Native inputs with shape (batch,time,input_channels).
targetsnp.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]
Return the sample identities associated with the selected indices.
Parameters
indicesrange | 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)
Sample deterministic random windows from cached full-trace shards.
Parameters
baseShardedNeuronIODataset- required.
window_sizeint- keyword-only, default=500. Native timesteps per extracted window.
start_offsetint- keyword-only, default=500. Native timestep index before the first selected window.
samples_per_epochint | None- keyword-only, default=None. Number of training window presentations requested per epoch.
batch_sizeint- keyword-only, default=8. Examples processed per batch.
shard_reuse_batchesint- keyword-only, default=1. Number of consecutive batches sampled before advancing to another shard.
sequence_lengthint | None- keyword-only, default=None. Native timestep count of a trace.
seedint- keyword-only, default=0. Random seed for the declared operation.
cache_full_shardsbool- keyword-only, default=True. Retain complete shard arrays rather than only selected data.
Methods
RandomFullTraceWindowDataset.__len__()RandomFullTraceWindowDataset.reshuffle()RandomFullTraceWindowDataset.__getitem__()RandomFullTraceWindowDataset.get_batch()RandomFullTraceWindowDataset.get_sample_ids()
RandomFullTraceWindowDataset.len
axosim.data.RandomFullTraceWindowDataset.__len__() -> int
Return the number of indexed samples.
Returns
int
RandomFullTraceWindowDataset.reshuffle
axosim.data.RandomFullTraceWindowDataset.reshuffle(seed: int) -> None
Reorder the enabled sampling index using the supplied seed.
Parameters
seedint- required. Random seed for the declared operation.
Returns
resultNone- No return value.
RandomFullTraceWindowDataset.getitem
axosim.data.RandomFullTraceWindowDataset.__getitem__(index: int) -> NeuronIOSample
Read one sample and its input/target contract.
Parameters
indexint- 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]
Read the requested input and target arrays as a batch.
Parameters
indicesrange | list[int]- required. Requested dataset sample indices.
Returns
inputsnp.ndarray- Native inputs with shape (batch,time,input_channels).
targetsnp.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]
Return the sample identities associated with the selected indices.
Parameters
indicesrange | 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)
Deterministic port of the official NeuronIO file/simulation/time sampling policy.
Parameters
baseShardedNeuronIODataset- required.
window_sizeint- keyword-only, default=500. Native timesteps per extracted window.
start_offsetint- keyword-only, default=500. Native timestep index before the first selected window.
samples_per_epochint | None- keyword-only, default=None. Number of training window presentations requested per epoch.
batch_sizeint- keyword-only, default=8. Examples processed per batch.
file_load_fractionfloat- keyword-only, default=0.3. Fraction of each shard made available to the sampling path.
source_simulationsint- keyword-only, default=128. Number of source simulations included by the dataset declaration.
sequence_lengthint | None- keyword-only, default=None. Native timestep count of a trace.
seedint- keyword-only, default=0. Random seed for the declared operation.
cache_full_shardsbool- keyword-only, default=True. Retain complete shard arrays rather than only selected data.
Methods
OfficialStyleFullTraceWindowDataset.__len__()OfficialStyleFullTraceWindowDataset.reshuffle()OfficialStyleFullTraceWindowDataset.__getitem__()OfficialStyleFullTraceWindowDataset.get_batch()OfficialStyleFullTraceWindowDataset.get_sample_ids()
OfficialStyleFullTraceWindowDataset.len
axosim.data.OfficialStyleFullTraceWindowDataset.__len__() -> int
Return the number of indexed samples.
Returns
int
OfficialStyleFullTraceWindowDataset.reshuffle
axosim.data.OfficialStyleFullTraceWindowDataset.reshuffle(seed: int) -> None
Reorder the enabled sampling index using the supplied seed.
Parameters
seedint- required. Random seed for the declared operation.
Returns
resultNone- No return value.
OfficialStyleFullTraceWindowDataset.getitem
axosim.data.OfficialStyleFullTraceWindowDataset.__getitem__(index: int) -> NeuronIOSample
Read one sample and its input/target contract.
Parameters
indexint- 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]
Read the requested input and target arrays as a batch.
Parameters
indicesrange | list[int]- required. Requested dataset sample indices.
Returns
inputsnp.ndarray- Native inputs with shape (batch,time,input_channels).
targetsnp.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]
Return the sample identities associated with the selected indices.
Parameters
indicesrange | 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
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
rootstr | Path- required. Dataset shard directory or manifest root.
shard_countint- keyword-only, default=2. Number of synthetic shard files to write.
samples_per_shardint- keyword-only, default=8. Synthetic sample count in each generated shard.
time_stepsint- keyword-only, default=32. Native sequence horizon.
input_dimint- keyword-only, default=64. Native input-channel count.
seedint- keyword-only, default=0. Random seed for the declared operation.
Returns
pathslist[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]
Repack existing shards as sliceable .npy arrays with identical sample order.
Parameters
input_rootstr | Path- required. Directory containing the source dataset shards.
output_rootstr | Path- required. Directory receiving converted dataset shards.
input_dtypenp.dtype | type- keyword-only, default=np.int8. Stored NumPy dtype of the converted input arrays.
Returns
list[Path]