AxoBench API
Dataset layout and schema
Signatures, parameters, return values, and source for dataset layout and schema.
Overview
V1DatasetLayout resolves the split and intervention directories of an evaluation root. The schema module records the v1 split names, intervention conditions, morphology registry, target views, and diagnostic suite catalog.
Source revision: 496e0c1a2dfd. Export index.
V1DatasetLayout
axobench.benchmark.selectors.V1DatasetLayout(root: str | Path)
Resolver for the v1 layout: axobench.benchmark.
Parameters
rootstr | Path- required. Dataset or evaluation root.
Methods
V1DatasetLayout.split()V1DatasetLayout.intervention()V1DatasetLayout.default_validation()V1DatasetLayout.available_interventions()V1DatasetLayout.validate_minimal()
V1DatasetLayout.split
axobench.benchmark.selectors.V1DatasetLayout.split(name: DatasetCategory='val') -> DatasetSelector
Selector for an ordinary split.
Parameters
nameDatasetCategory- default='val'. One of ORDINARY_SPLITS.
Returns
selectorDatasetSelector- Split selector.
V1DatasetLayout.intervention
axobench.benchmark.selectors.V1DatasetLayout.intervention(name: str) -> DatasetSelector
Selector for an intervention condition; unknown names are accepted if their directory exists.
Parameters
namestr- required. Condition name.
Returns
selectorDatasetSelector- Condition selector.
V1DatasetLayout.default_validation
axobench.benchmark.selectors.V1DatasetLayout.default_validation() -> DatasetSelector
Selector for val.
Returns
selectorDatasetSelector- Validation selector.
V1DatasetLayout.available_interventions
axobench.benchmark.selectors.V1DatasetLayout.available_interventions() -> tuple[str, ...]
Condition directories present, known conditions first in INTERVENTION_CONDITIONS order.
Returns
namestuple[str, ...]- Condition names.
V1DatasetLayout.validate_minimal
axobench.benchmark.selectors.V1DatasetLayout.validate_minimal(*, require_interventions: bool=False) -> None
Raise FileNotFoundError unless every ordinary split, and optionally every condition, has a manifest or shards.
Parameters
require_interventionsbool- keyword-only, default=False. Also require the five conditions.
DatasetSelector
axobench.benchmark.selectors.DatasetSelector(root: Path, split: str | None, condition: str, intervention: str | None = None)
A resolved split or intervention directory. Exported from axobench.benchmark.
Parameters
rootPath- required. Directory of the split or condition.
splitstr | None- required. Split name, or None for a condition.
conditionstr- required. Split name or interventions/<name>.
interventionstr | None- default=None. Condition name, or None for a split.
Attributes
Constructor fields are retained as read-only attributes.
Methods
DatasetSelector.load
axobench.benchmark.selectors.DatasetSelector.load(*, cache_shards: int=1) -> ShardedNeuronIODataset
Open the directory as a dataset.
Parameters
cache_shardsint- keyword-only, default=1. Decoded shards kept in memory.
Returns
datasetShardedNeuronIODataset- Reader for the directory.
Constants
ORDINARY_SPLITS = ('train', 'val', 'test', 'private-test')- Ordinary split names of the v1 layout; private-test is not released. Source
INTERVENTION_CONDITIONS = ('event_dropout', 'exc_dropout', 'inh_dropout', 'temporal_jitter', 'site_silence')- Released intervention conditions. Source
V1_MORPHOLOGY_COUNT = 5- Morphologies in the v1 single-neuron release. Source
V1_TRAIN_TRACES_PER_MORPHOLOGY = 20000- Training traces per morphology in v1. Source
DIAGNOSTIC_SUITES = ('teacher-qc', 'trace-core', 'state-dynamics', 'spike-behavior', 'feature-fidelity', 'mechanistic-response', 'morphology-contrast', 'intervention-response', 'metric-decoupling', 'target-view-audit', 'robustness-directionality', 'protocol-coverage', 'adapter-fairness', 'paper-summary', 'full')- Suite names accepted by diagnostic contexts. Source
DIAGNOSTIC_ROW_COLUMNS = ('diagnostic', 'suite', 'model_id', 'teacher_id', 'morphology_id', 'split', 'condition', 'intervention', 'trace_id', 'state', 'metric', 'value', 'unit', 'n')- Columns required in every diagnostic row. Source
v1_morphologies
axobench.benchmark.dataset_schema.v1_morphologies() -> tuple[MorphologySpec, ...]
The frozen five-morphology v1 registry. Exported from axobench.benchmark.
Returns
morphologiestuple[MorphologySpec, ...]- Specimen, role, Cre line, and shape ratios per morphology.
MorphologySpec
axobench.benchmark.dataset_schema.MorphologySpec(specimen_id: int, role: str, swc_path: str, line_name: str, reconstruction_type: str, compatibility_score_lower_better: float, extracted_branches: int, routed_branches: int, total_length_ratio_vs_reference: float, routed_length_ratio_vs_reference: float, apical_fraction_delta_vs_reference: float, radial_extent_ratio_vs_reference: float, routing_shape_match: bool, caveat: str = 'Allen metadata marks this reconstruction dendrite-only.')
One registry entry of v1_morphologies; ratios and differences are relative to the reference specimen.
Parameters
specimen_idint- required. Allen specimen ID.
rolestr- required. Role in the morphology set.
swc_pathstr- required. SWC path used at generation.
line_namestr- required. Cre line.
reconstruction_typestr- required. Allen reconstruction type.
compatibility_score_lower_betterfloat- required. Compatibility score against the reference.
extracted_branchesint- required. Branches extracted from the reconstruction.
routed_branchesint- required. Branches of the routed representation.
total_length_ratio_vs_referencefloat- required. Total dendritic length ratio.
routed_length_ratio_vs_referencefloat- required. Routed length ratio.
apical_fraction_delta_vs_referencefloat- required. Apical fraction difference.
radial_extent_ratio_vs_referencefloat- required. Radial extent ratio.
routing_shape_matchbool- required. Whether the routed representation matches the reference shape.
caveatstr- default='Allen metadata marks this reconstruction dendrite-only.'. Reconstruction caveat.
Attributes
Constructor fields are retained as read-only attributes.
default_target_views
axobench.benchmark.dataset_schema.default_target_views() -> tuple[TargetViewSpec, ...]
Declared target views: neuronio_clipped_normalized for training and historical comparison, and raw_soma_mv for clipping diagnostics and spike-shape analysis. Exported from axobench.benchmark.
Returns
viewstuple[TargetViewSpec, ...]- Target view declarations.
TargetViewSpec
axobench.benchmark.dataset_schema.TargetViewSpec(name: str, columns: tuple[str, ...], units: str, description: str, default_for_training: bool = False, default_for_historical_comparison: bool = False)
One stored view of the spike and soma target.
Parameters
namestr- required. View name.
columnstuple[str, ...]- required. Column names.
unitsstr- required. Column units.
descriptionstr- required. Definition of the view.
default_for_trainingbool- default=False. Whether training uses this view by default.
default_for_historical_comparisonbool- default=False. Whether historical comparisons use this view.
Attributes
Constructor fields are retained as read-only attributes.
build_v1_dataset_manifest_template
axobench.benchmark.dataset_schema.build_v1_dataset_manifest_template(*, morphology_count: int=V1_MORPHOLOGY_COUNT, train_traces_per_morphology: int=V1_TRAIN_TRACES_PER_MORPHOLOGY) -> dict[str, Any]
The v1 manifest contract as JSON-like data: categories, morphologies, target views, trace shape, and default diagnostic selectors. Non-training splits hold one eighth of the training traces per morphology. Exported from axobench.benchmark.
Parameters
morphology_countint- keyword-only, default=V1_MORPHOLOGY_COUNT = 5. Number of morphologies.
train_traces_per_morphologyint- keyword-only, default=V1_TRAIN_TRACES_PER_MORPHOLOGY = 20000. Training traces per morphology; at least 8.
Returns
manifestdict[str, Any]- Manifest template.
validate_v1_manifest_template
axobench.benchmark.dataset_schema.validate_v1_manifest_template(manifest: dict[str, Any]) -> None
Validate a manifest against the v1 contract without reading shards; raises ValueError on a mismatch. Exported from axobench.benchmark.
Parameters
manifestdict[str, Any]- required. Manifest dictionary.
build_diagnostic_suite_catalog
axobench.benchmark.dataset_schema.build_diagnostic_suite_catalog() -> dict[str, Any]
Suites, diagnostic specifications with their attached plotters, and the row columns, as printed by axobench dataset-schema –kind diagnostics. Exported from axobench.benchmark.
Returns
catalogdict[str, Any]- suites, diagnostics, plotter_policy, and row_columns.