AxoBench API
axobench CLI
Every subcommand, option, and default of the axobench command.
Usage
axobench <command> --help
The axobench command converts and inspects data and writes diagnostic rows; it does not load models. AxoSim checkpoints are evaluated with axosim-evaluate-model, and other models through the Python evaluator. Errors in file paths or values exit with status 2 and print the message.
make-demo-data
Write deterministic synthetic shards for smoke tests.
Options
--outputstr · required- Output directory.
--samplesint · default=8- Traces per shard.
--shardsint · default=1- Number of shards.
--time-stepsint · default=32- Steps per trace.
--input-dimint · default=64- Input channels.
--seedint · default=0- Random seed.
make-arbor-hetero-data
Simulate heterogeneous Arbor cable cells into shards; requires the sim extra (Arbor 0.11).
Options
--configstr · default=None- JSON file whose keys are option names of this command; explicit flags take precedence.
--outputstr · default=None- Output directory; required unless set in --config.
--samplesint · default=128- Traces when --splits is not given.
--shardsint · default=1- Shards when --splits is not given.
--splitsstr · default=None- Comma-separated NAME:SAMPLES pairs written as separate split directories.
--shards-per-splitint · default=1- Shards per split with --splits.
--time-stepsint · default=6000- Steps per trace.
--input-dimint · default=1278- Input channels.
--branchesint · default=45- Dendritic branches of the cable cell.
--integration-dt-msfloat · default=0.025- Simulator integration step in ms.
--input-protocolstr · default='arbor_poisson'- Input event generator. Choices: arbor_poisson, neuronio_smoothed.
--synapse-routingstr · default='branch'- Synapse placement: one site per branch, or distributed sites. Choices: branch, distributed.
--distributed-sites-per-polarityint · default=None- Sites per sign with distributed routing.
--spike-label-modestr · default='threshold_crossing'- How output spikes are labeled. Choices: threshold_crossing, local_peak.
--spike-peak-threshold-mvfloat · default=-25.0- Voltage threshold of spike labels in mV.
--base-event-rate-hzfloat · default=2.0- Baseline input event rate in Hz.
--burst-probabilityfloat · default=0.015- Probability of an input burst.
--burst-event-rate-hzfloat · default=35.0- Input event rate during bursts in Hz.
--arbor-gpu-idint · default=0- GPU used by Arbor.
--cpu-onlyflag · default=False- Use Arbor's CPU context.
--arbor-threadsint · default=1- Arbor CPU threads.
--sim-batch-sizeint · default=32- Independent cells per Arbor simulation.
--seedint · default=0- Random seed.
--param-overridesstr · default=None- JSON object, or a path to one, overriding heterogeneity parameters for all traces.
--reportstr · default=None- Optional path for a copy of the generation report.
convert-neuronio
Convert raw NeuronIO pickles to deterministic shards.
Options
--inputstr · required- Raw file or directory searched for *sim__* files.
--outputstr · required- Output directory.
--shard-sizeint · default=128- Traces per shard.
--window-sizeint · default=None- Optional window length.
--window-strideint · default=None- Window stride; defaults to the window length.
--ignore-startint · default=0- First window start when windowing.
repack-shards
Repack shards as sliceable .npy arrays with a manifest.
Options
--inputstr · required- Source split directory.
--outputstr · required- Destination directory.
--input-dtypestr · default='int8'- Storage dtype of the inputs; values must be preserved. Choices: int8, float32.
benchmark-profile
Print an axis/default profile as JSON.
Options
--namestr · default='paper-default'- Profile name. Choices: smoke, paper-default, teacher-screen.
--planflag · default=False- Print the expanded axis-composition plan.
--costflag · default=False- Print only the local capacity estimate.
dataset-schema
Print the v1 manifest template or the diagnostic suite catalog as JSON.
Options
--kindstr · default='manifest'- manifest for the template, diagnostics for the suite catalog. Choices: manifest, diagnostics.
benchmark-rows
Write teacher QC or teacher intervention rows for an evaluation root.
Options
--modestr · default='teacher-qc'- teacher-qc rows or intervention rows. Choices: teacher-qc, intervention.
--dataset-rootstr · required- Evaluation root.
--selectorstr · default='val'- Read val or an intervention condition. Choices: val, intervention.
--interventionstr · default='event_dropout'- Condition name with --selector intervention.
--pair-pathstr · default=None- Pair file outside the v1 layout; used with --mode intervention.
--outputstr · required- Rows file: .json, .jsonl, or .csv.
--summary-outputstr · default=None- Optional summary: .md or .json.
--suitesstr · default='teacher-qc'- Comma-separated suites.
--morphology-idstr · default='unknown'- Morphology label of the rows.
--teacher-idstr · default='teacher'- Teacher label.
--max-samplesint · default=None- Maximum traces or pairs, read from the start.
--cache-shardsint · default=1- Decoded shards kept in memory.
--ignore-startint · default=500- Initial steps excluded.
--soma-scalefloat · default=0.1- Scale of the soma target coordinate.
--soma-bias-mvfloat · default=-67.7- Millivolt offset of the soma target coordinate.
--calibrated-spike-thresholdfloat · default=None- Spike threshold recorded with the rows.
diagnostic-audits
Derive audit rows from saved comparison artifacts.
Options
--teacher-grounded-rowsstr · default=None- Teacher-grounded comparison rows.
--local-stability-rowsstr · default=None- Local stability rows.
--perturbation-rowsstr · default=None- Perturbation rows.
--pretrained-summary-rowsstr · default=None- Pretrained-model summary rows.
--teacher-protocolstr · default=None- Teacher protocol JSON.
--outputstr · required- Rows file: .json, .jsonl, or .csv.
--summary-outputstr · default=None- Optional summary: .md or .json.
--suitesstr · default='metric-decoupling,target-view-audit,robustness-directionality,protocol-coverage,adapter-fairness,paper-summary'- Comma-separated audit suites.
--model-idstr · default='analysis'- Model label.
--teacher-idstr · default='teacher'- Teacher label.
--morphology-idstr · default='mixed'- Morphology label.
--splitstr · default='analysis'- Split label.
--conditionstr · default='analysis'- Condition label.
diagnostic-plots
Write the audit figures and tables from saved audit summaries.
Options
--canonical-summarystr · required- Canonical audit summary JSON.
--mechanistic-summarystr · required- Mechanistic response summary JSON.
--sparse-event-summarystr · required- Sparse-event sensitivity summary JSON.
--point-rowsstr · required- Point metric rows.
--tcn-summarystr, repeatable · required- TCN preprocessing summary JSON; repeatable.
--morphology-contrast-rowsstr · default=None- Optional morphology contrast rows.
--neuronio-intervention-rowsstr · default=None- Optional NeuronIO intervention rows.
--neuronio-intervention-rootstr · default=None- Optional NeuronIO intervention directory.
--output-dirstr · required- Output directory.
--formatsstr · default='svg,pdf,png'- Comma-separated figure formats.
error-anatomy
Break a cached prediction’s errors down by spike outcome, spike distance, firing rate, frequency band, and morphology; writes error-anatomy.json, the figure, and error-anatomy.tex, and prints the overall skills.
Options
--cachestr · required- Evaluation cache from write_model_evaluation_cache, or any NPZ with a prediction array.
--targetsstr · default=None- NPZ with target and optional raw_soma_mv and trace_ids; defaults to the cache file. Must match the cache's target hash and trace IDs when the cache records them.
--outputstr · required- Output directory.
--ignore-startint · default=None- Initial steps excluded; defaults to the cache protocol's value, else 500.
--calibration-fractionfloat · default=None- Fraction of traces used for threshold calibration; defaults to the cache protocol's value, else 0.25.
--formatsstr · default='pdf,png'- Comma-separated figure formats.
benchmark-v1
Run the teacher bundle on an evaluation root: QC, routing, intervention, and morphology-contrast rows.
Options
--dataset-rootstr · required- Evaluation root.
--output-dirstr · required- Output directory.
--suitestr · default='paper-summary'- Suite profile. Choices: teacher-qc, paper-summary, full.
--intervention-pair-globstr, repeatable · default=[]- Glob of pair files outside the v1 layout; repeatable.
--morphology-idstr · default='unknown'- Morphology label of the val rows.
--teacher-idstr · default='teacher'- Teacher label.
--max-val-samplesint · default=None- Maximum validation traces.
--max-intervention-samplesint · default=None- Maximum pairs per condition and morphology.
--cache-shardsint · default=1- Decoded shards kept in memory.
--ignore-startint · default=500- Initial steps excluded.
--soma-scalefloat · default=0.1- Scale of the soma target coordinate.
--soma-bias-mvfloat · default=-67.7- Millivolt offset of the soma target coordinate.
--calibrated-spike-thresholdfloat · default=None- Spike threshold recorded with the rows.
--no-summariesflag · default=True- Write only machine-readable rows and the manifest.