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)

Source

Resolver for the v1 layout: / for ordinary splits and /interventions/ for conditions. Exported from axobench.benchmark.

Parameters

root str | Path
required. Dataset or evaluation root.

Methods

V1DatasetLayout.split

axobench.benchmark.selectors.V1DatasetLayout.split(name: DatasetCategory='val') -> DatasetSelector

Source

Selector for an ordinary split.

Parameters

name DatasetCategory
default='val'. One of ORDINARY_SPLITS.

Returns

selector DatasetSelector
Split selector.

V1DatasetLayout.intervention

axobench.benchmark.selectors.V1DatasetLayout.intervention(name: str) -> DatasetSelector

Source

Selector for an intervention condition; unknown names are accepted if their directory exists.

Parameters

name str
required. Condition name.

Returns

selector DatasetSelector
Condition selector.

V1DatasetLayout.default_validation

axobench.benchmark.selectors.V1DatasetLayout.default_validation() -> DatasetSelector

Source

Selector for val.

Returns

selector DatasetSelector
Validation selector.

V1DatasetLayout.available_interventions

axobench.benchmark.selectors.V1DatasetLayout.available_interventions() -> tuple[str, ...]

Source

Condition directories present, known conditions first in INTERVENTION_CONDITIONS order.

Returns

names tuple[str, ...]
Condition names.

V1DatasetLayout.validate_minimal

axobench.benchmark.selectors.V1DatasetLayout.validate_minimal(*, require_interventions: bool=False) -> None

Source

Raise FileNotFoundError unless every ordinary split, and optionally every condition, has a manifest or shards.

Parameters

require_interventions bool
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)

Source

A resolved split or intervention directory. Exported from axobench.benchmark.

Parameters

root Path
required. Directory of the split or condition.
split str | None
required. Split name, or None for a condition.
condition str
required. Split name or interventions/<name>.
intervention str | 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

Source

Open the directory as a dataset.

Parameters

cache_shards int
keyword-only, default=1. Decoded shards kept in memory.

Returns

dataset ShardedNeuronIODataset
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, ...]

Source

The frozen five-morphology v1 registry. Exported from axobench.benchmark.

Returns

morphologies tuple[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.')

Source

One registry entry of v1_morphologies; ratios and differences are relative to the reference specimen.

Parameters

specimen_id int
required. Allen specimen ID.
role str
required. Role in the morphology set.
swc_path str
required. SWC path used at generation.
line_name str
required. Cre line.
reconstruction_type str
required. Allen reconstruction type.
compatibility_score_lower_better float
required. Compatibility score against the reference.
extracted_branches int
required. Branches extracted from the reconstruction.
routed_branches int
required. Branches of the routed representation.
total_length_ratio_vs_reference float
required. Total dendritic length ratio.
routed_length_ratio_vs_reference float
required. Routed length ratio.
apical_fraction_delta_vs_reference float
required. Apical fraction difference.
radial_extent_ratio_vs_reference float
required. Radial extent ratio.
routing_shape_match bool
required. Whether the routed representation matches the reference shape.
caveat str
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, ...]

Source

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

views tuple[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)

Source

One stored view of the spike and soma target.

Parameters

name str
required. View name.
columns tuple[str, ...]
required. Column names.
units str
required. Column units.
description str
required. Definition of the view.
default_for_training bool
default=False. Whether training uses this view by default.
default_for_historical_comparison bool
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]

Source

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_count int
keyword-only, default=V1_MORPHOLOGY_COUNT = 5. Number of morphologies.
train_traces_per_morphology int
keyword-only, default=V1_TRAIN_TRACES_PER_MORPHOLOGY = 20000. Training traces per morphology; at least 8.

Returns

manifest dict[str, Any]
Manifest template.

validate_v1_manifest_template

axobench.benchmark.dataset_schema.validate_v1_manifest_template(manifest: dict[str, Any]) -> None

Source

Validate a manifest against the v1 contract without reading shards; raises ValueError on a mismatch. Exported from axobench.benchmark.

Parameters

manifest dict[str, Any]
required. Manifest dictionary.

build_diagnostic_suite_catalog

axobench.benchmark.dataset_schema.build_diagnostic_suite_catalog() -> dict[str, Any]

Source

Suites, diagnostic specifications with their attached plotters, and the row columns, as printed by axobench dataset-schema –kind diagnostics. Exported from axobench.benchmark.

Returns

catalog dict[str, Any]
suites, diagnostics, plotter_policy, and row_columns.

Search guides, examples, and API signatures.