nabat-v1-onnx

NABat ML V1 ONNX

This repository contains the original USGS NABat ML V1 TensorFlow SavedModel and the reproducible ONNX export used by OpenBat. It is an unofficial conversion, not a USGS release.

Artifact

The complete TensorFlow SavedModel is archived under upstream/saved-model/. SHA256SUMS covers the original model, exporter, locked environment, ONNX output, preprocessing reference, labels, and golden fixture.

Source and conversion

• Source repository: fort/nabat/nabat-ml.
• Source revision: a3e0b013ba6dcdabe8f98127eb1ee25974bd4649.
• Source model: prediction/tf-models/m-1.
• Conversion: TensorFlow SavedModel to ONNX opset 17 using tf2onnx.
• Export environment: CPython 3.11.15, TensorFlow 2.15.1, tf2onnx 1.16.1, ONNX 1.17.0, and ONNX Runtime 1.22.1.
• Seeded source-runtime parity: maximum absolute error 5.21540641784668e-07, with tolerance 0.0001.

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. First clone the pinned USGS revision and compare its SavedModel with the archived copy:

./scripts/fetch-upstream.sh

Then export the archived SavedModel, run the seeded TensorFlow/ONNX Runtime parity check, and require the exact ONNX bytes:

./scripts/rebuild-and-verify.sh

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.

Model contract

• Input: input, float32, NHWC [batch, 100, 100, 3], RGB.
• Output: dense_3, 31 North American classes including NOISE at index 25.
• Exact output order: labels.json.
• Region: North America.

The model does not accept raw audio. Callers must reproduce the official NABat pulse selection, spectrogram, colour mapping, and resize contract.

Preprocessing

preprocessing/README.md links directly to the pinned USGS implementation and includes an unchanged copy of spectrogram_v2.py, including the make_training_spectrogram path that produces the 100 x 100 image.

Golden fixture

golden/ contains a deterministic model-ready input tensor and its expected dense_3 output. 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 is licensed under Creative Commons Attribution 4.0 International. The upstream licence is included unchanged as LICENSE.md. The ONNX file is identified as a conversion, and the upstream citation is retained.

Suggested software citation from upstream:

Gotthold, B.S., Khalighifar, A., Chabarek, J., Straw, B.R., Reichert, B.E., 2024, North American Bat Monitoring Program: NABat Acoustic ML, version 2.0.0, U.S. Geological Survey software release, https://doi.org/10.5066/P1QBMNSF.

Limitations

• USGS has not authorized or endorsed this conversion.
• Exact preprocessing is part of the model contract.
• Source-runtime parity measures conversion fidelity, not biological accuracy.
• Geographic, recorder, habitat, and training-corpus limits must be evaluated for each deployment.