AxoBench API

Error anatomy

Signatures, parameters, return values, and source for error anatomy.

Overview

error_anatomy breaks a prediction’s errors down by spike outcome, time from the nearest teacher spike, teacher firing rate, frequency band, and morphology, on the evaluator’s scored traces with its threshold, spike events, action-potential windows, and relevance. plot_error_anatomy draws the result and writes a standalone pgfplots version. Import from axobench.benchmark.error_anatomy and axobench.benchmark.plots. Error anatomy explains how to read each part.

Source revision: 496e0c1a2dfd. Export index.

error_anatomy

axobench.benchmark.error_anatomy.error_anatomy(prediction: np.ndarray, target: np.ndarray, *, raw_soma_mv: np.ndarray | None=None, trace_ids: list[str] | None=None, config: EvaluationConfig | None=None) -> dict[str, Any]

Source

Break a prediction’s errors down on the scored traces of evaluate_predictions, with the same calibration, spike threshold, predicted events, action-potential windows, relevance, and subthreshold masks. Sections: spike events (hits, misses, and false spikes within HIT_TOLERANCE_STEPS, F1 per tolerance, timing errors of matched events), spike-triggered mean voltage of teacher and model around isolated hit, missed, and false spikes, subthreshold error by time since the last and until the next teacher spike (bins 0-5, 5-10, 10-25, 25-50, 50-100, 100+ ms and none), skills by teacher firing rate (0-1, 1-3, 3-6, 6+ Hz) and by morphology, and subthreshold skill by frequency band (0-1, 1-5, 5-10, 10-25, 25-50, 50-100, 100+ Hz). Exported from axobench.benchmark.

Parameters

prediction np.ndarray
required. Model outputs shaped (trace, time, 2), in calibration-then-scoring order; at least two traces.
target np.ndarray
required. Teacher targets in the same order.
raw_soma_mv np.ndarray | None
keyword-only, default=None. Optional unclipped teacher soma voltage in millivolts, shaped (trace, time); replaces the voltage reconstructed from the target.
trace_ids list[str] | None
keyword-only, default=None. Sample IDs, one per trace; the text before the first ':' is the morphology or cell-type group.
config EvaluationConfig | None
keyword-only, default=None. Evaluation settings; None uses EvaluationConfig().

Returns

anatomy dict[str, Any]
JSON-serializable: config, calibration_samples, scored_samples, spike_threshold, overall, spike_events, spike_triggered_average, subthreshold_by_spike_distance, by_teacher_rate, subthreshold_by_frequency, and by_morphology. Times are in steps or ms and voltages in mV.

reweight_to_rate_distribution

axobench.benchmark.error_anatomy.reweight_to_rate_distribution(anatomy: dict[str, Any], reference: dict[str, Any] | Mapping[str, float]) -> dict[str, Any]

Source

Skills of an error anatomy with its traces reweighted to another distribution over teacher firing-rate bins. Each trace is weighted by the reference share of its bin divided by the bin’s own share; bins absent from the reference get weight zero, so the comparison covers the common support. Relevance and references stay those of the anatomy’s own block. Exported from axobench.benchmark.

Parameters

anatomy dict[str, Any]
required. Result of error_anatomy to reweight.
reference dict[str, Any] | Mapping[str, float]
required. Another error_anatomy result, whose scored-trace shares per rate bin are used, or a mapping from bin label ('0-1', '1-3', '3-6', '6+') to share.

Returns

skills dict[str, Any]
voltage_sera_skill, voltage_sera_ceiling_skill, voltage_sera_skill_of_ceiling, subthreshold_skill, mean_f1, and the bins used. Raises ValueError when a weighted bin has no traces or no bin is shared.

Constants

HIT_TOLERANCE_STEPS = 2
Timing tolerance in steps within which a predicted spike counts as a hit of a teacher spike. Source
STA_LAGS_STEPS = (-10, 40)
First and last lag of the spike-triggered averages, in steps; events count as isolated when no other event of the same train falls in this window. Source

plot_error_anatomy

axobench.benchmark.plots.plot_error_anatomy(anatomy: dict[str, Any], output: str | Path, *, formats: tuple[str, ...]=PLOT_FORMATS, tikz: bool=True) -> list[str]

Source

Plot an error_anatomy result in four panels: spike-triggered voltage of teacher and model around hit, missed, and false spikes; share of retained steps and of squared subthreshold error by time since the last teacher spike; skill by teacher firing rate; and subthreshold skill by frequency band. Uses apply_paper_plot_style.

Parameters

anatomy dict[str, Any]
required. Result of error_anatomy.
output str | Path
required. Output path without suffix; each format is written with its own suffix.
formats tuple[str, ...]
keyword-only, default=PLOT_FORMATS = ('svg', 'pdf', 'png'). File formats passed to Matplotlib, for example ('pdf', 'png') or ('svg',).
tikz bool
keyword-only, default=True. Also write a standalone pgfplots .tex file of the same panels.

Returns

paths list[str]
Written figure paths, followed by the .tex path when tikz is set.

apply_paper_plot_style

axobench.benchmark.plots.apply_paper_plot_style() -> None

Source

Set the Matplotlib style of AxoBench figures: STIX serif text at 7 to 8 pt, despined axes without grid, the Okabe-Ito palette, white background, text kept as text in PDF and SVG, and 300 dpi PNG. A style file named by the AXOBENCH_PAPER_STYLE environment variable is applied first.

Search guides, examples, and API signatures.