Tutorial: Integrate with a Python pipeline

This tutorial shows a minimal Python workflow for loading audio, running batdetect2, and collecting detections for downstream analysis.

This tutorial is for people who already want to work in Python.

If you mainly want to run the model on recordings, start with {doc}run-inference-on-folder instead.

Before you start

BatDetect2 installed in your Python environment.
A model checkpoint.
At least one input audio file.

This page is more technical than the standard first-run tutorial.
You do not need this page for a normal first use of BatDetect2.

If you are working from this repository checkout, you can start with:

src/batdetect2/models/checkpoints/Net2DFast_UK_same.pth.tar

Outcome

By the end of this tutorial you will have:

created a BatDetect2API object,
run inference on one file,
inspected the top class, class-score list, and detection score,
identified where to go next for feature extraction, saving predictions, and batch workflows.

1. Create the API instance

Load the checkpoint once and reuse the API object for multiple files.

from pathlib import Path

from batdetect2.api_v2 import BatDetect2API

api = BatDetect2API.from_checkpoint(Path("path/to/model.ckpt"))

2. Run inference on one file

process_file is the simplest Python entry point when you want one prediction object per recording.

from pathlib import Path

from batdetect2.api_v2 import BatDetect2API

api = BatDetect2API.from_checkpoint(Path("path/to/model.ckpt"))
prediction = api.process_file(Path("path/to/audio.wav"))

for detection in prediction.detections:
    top_class = api.get_top_class_name(detection)
    score = detection.detection_score
    print(top_class, score)

prediction is a ClipDetections object.

It contains:

the clip metadata,
a list of detections,
a box for each detected event,
one detection score per event,
a full list of class scores per event,
a feature vector per event.

3. Inspect class scores, not just the top class

If you are exploring results, it is often useful to inspect the full ranked class-score list.

for detection in prediction.detections:
    print("top class:", api.get_top_class_name(detection))
    print("detection score:", detection.detection_score)
    print("class scores:")
    for class_name, score in api.get_class_scores(detection):
        print(f"  {class_name}: {score:.3f}")

This helps separate two different questions:

"Did the model think there was a call here?"
"If there was a call, which class did it score highest?"

4. Keep the first workflow small

Before scaling up, run the API on a few representative files and inspect the results manually.

This catches path issues and obviously implausible outputs early.

5. Move to the right next workflow

Once the single-file path is working, choose the next page based on what you need:

save predictions to disk,
inspect class scores more carefully,
inspect detection features,
process many files in one run.

What to do next

API reference: {doc}../reference/api
Inspect ranked class scores: {doc}../how_to/inspect-class-scores-in-python
Inspect detection features: {doc}../how_to/inspect-detection-features-in-python
Save predictions to disk: {doc}../how_to/save-predictions-in-different-output-formats
Learn the CLI happy path: {doc}run-inference-on-folder

3.4 KiB Raw Blame History