batdetect2-uk-same-onnx

BatDetect2 UK same ONNX

Noncommercial only. The source checkpoint is CC BY-NC 4.0. Commercial use or distribution requires separate permission from the rights holder.

This repository contains the original BatDetect2 UK same checkpoint and the reproducible ONNX export used by OpenBat. It is an unofficial conversion, not a BatDetect2 release.

UK same is the paper's evaluation split where test files come from the same UK recording data sources represented in training. It contrasts with UK different, which holds out a complete recording source to measure transfer to unseen conditions. See the BatDetect2 paper.

Artifact

Source and conversion

• Source repository: macaodha/batdetect2.
• Source revision: 9e2697458d3b3b03c30ccd7e49ed5409c8ac330d.
• Source checkpoint: src/batdetect2/models/checkpoints/batdetect2_uk_same.ckpt.
• Conversion: PyTorch checkpoint to ONNX opset 17.
• Export environment: CPython 3.11.15, BatDetect2 2.0.0b3, PyTorch 2.13.0, ONNX 1.22.0, and ONNX Runtime 1.28.0.
• Seeded source-runtime parity: detection maximum absolute error 1.0579824447631836e-06; class maximum absolute error 5.364418029785156e-07; tolerance 0.0001.

The original checkpoint is archived byte-identically under upstream/. The exact exporter is in scripts/, the complete uv lock is in environment/, and PROVENANCE.json records the source and output contract.

Reproduce the conversion

The rebuild requires Git, uv, and CPython 3.11.15. Fetch the pinned BatDetect2 revision, compare its checkpoint with the archived copy, then run the locked exporter and parity check:

./scripts/fetch-upstream.sh
./scripts/rebuild-and-verify.sh --accept-noncommercial-license

The explicit flag acknowledges that the checkpoint and conversion remain subject to CC BY-NC 4.0. The first run downloads the checksum-locked Python environment. Output goes to the ignored .repro/output/ directory. A passing rebuild establishes byte identity and seeded runtime agreement; it does not validate classification accuracy.

The .ckpt file is a Python/PyTorch checkpoint. Treat it as trusted upstream archival input and do not load checkpoints from untrusted sources. Use the ONNX file for ordinary inference.

Model contract

• Input: input, float32, NCHW [1, 1, 128, 256], mono spectrogram.
• Outputs: detection_probs [1, 1, 128, 256] and class_probs [1, 17, 128, 256].
• Exact class order: labels.json.
• Region: United Kingdom.

The model does not accept raw audio. Callers must reproduce the BatDetect2 spectrogram and normalization contract.

Preprocessing

preprocessing/README.md links directly to the pinned BatDetect2 implementation and includes an unchanged copy of its complete preprocess package.

Golden fixture

golden/ contains a deterministic model-ready spectrogram tensor and expected detection and class outputs. It checks the published model contract separately from raw-audio preprocessing.

uv run --project golden --frozen --python 3.11.15 python scripts/verify_golden.py

The generation seed, runtime versions, hashes, and tolerances are recorded in golden/manifest.json.

Licence and attribution

The upstream project and checkpoint are licensed under Creative Commons Attribution-NonCommercial 4.0 International. The upstream licence is included unchanged as LICENSE.md, and the ONNX file is identified as a conversion.

Upstream reference:

Mac Aodha, O. et al. (2023), “Towards a General Approach for Bat Echolocation Detection and Classification,” bioRxiv, https://www.biorxiv.org/content/10.1101/2022.12.14.520490v2.

Limitations

• The original authors have not authorized or endorsed this conversion.
• It is noncommercial-only unless separate rights are obtained.
• Exact preprocessing is part of the model contract.
• Source-runtime parity measures conversion fidelity, not biological accuracy.
• The model is geographically scoped and should not be treated as a global classifier.