From f909da5589bf3f8f466cb6d57648dc27aae9b416 Mon Sep 17 00:00:00 2001 From: mbsantiago Date: Thu, 7 May 2026 08:36:46 +0100 Subject: [PATCH] docs: expand python workflow tutorial --- docs/source/reference/detections.md | 42 +++++ docs/source/reference/index.md | 1 + .../integrate-with-a-python-pipeline.md | 160 +++++++++++------- 3 files changed, 144 insertions(+), 59 deletions(-) create mode 100644 docs/source/reference/detections.md diff --git a/docs/source/reference/detections.md b/docs/source/reference/detections.md new file mode 100644 index 0000000..badcec2 --- /dev/null +++ b/docs/source/reference/detections.md @@ -0,0 +1,42 @@ +# Detections reference + +These are the main prediction objects returned by BatDetect2 inference methods. + +Defined in `batdetect2.postprocess.types`. + +## `ClipDetections` + +`ClipDetections` represents the predictions for one clip or one full recording. + +Fields: + +- `clip` + - the `soundevent` clip metadata for the processed audio. +- `detections` + - list of `Detection` objects for that clip. + +## `Detection` + +`Detection` represents one detected event. + +Fields: + +- `geometry` + - time-frequency geometry for the detected event. +- `detection_score` + - confidence that there is an event at this location. +- `class_scores` + - class ranking scores for the detected event. +- `features` + - per-detection feature vector from the model. + +## Related pages + +- Python tutorial: + {doc}`../tutorials/integrate-with-a-python-pipeline` +- API reference: + {doc}`api` +- What BatDetect2 predicts: + {doc}`../explanation/what-batdetect2-predicts` +- Features and embeddings: + {doc}`../explanation/extracted-features-and-embeddings` diff --git a/docs/source/reference/index.md b/docs/source/reference/index.md index b6aaf2f..f54a8bb 100644 --- a/docs/source/reference/index.md +++ b/docs/source/reference/index.md @@ -10,6 +10,7 @@ details, or Python API entries. cli/index api +detections model-config training-config logging-config diff --git a/docs/source/tutorials/integrate-with-a-python-pipeline.md b/docs/source/tutorials/integrate-with-a-python-pipeline.md index 1c62390..d31bb04 100644 --- a/docs/source/tutorials/integrate-with-a-python-pipeline.md +++ b/docs/source/tutorials/integrate-with-a-python-pipeline.md @@ -1,62 +1,50 @@ -# Tutorial: Integrate with a Python pipeline +# 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 shows a simple Python workflow for loading audio, running BatDetect2, and inspecting the detections. -This tutorial is for people who already want to work in Python. +Use it when you want to work directly in Python rather than through the CLI. -If you mainly want to run the model on recordings, -start with {doc}`run-inference-on-folder` instead. +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. +You need: -```{note} -This page is more technical than the standard first-run tutorial. -You do not need this page for a normal first use of BatDetect2. -``` +- BatDetect2 installed in your Python environment, +- at least one input audio file. -If you are working from this repository checkout, you can start with: - -```text -src/batdetect2/models/checkpoints/Net2DFast_UK_same.pth.tar -``` - -## Outcome +## What you will do 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. +- inspected detections, scores, and features, +- used lower-level audio and spectrogram methods for more control, +- identified the next API workflows for batch processing, training, fine-tuning, and evaluation. ## 1. Create the API instance -Load the checkpoint once and reuse the API object for multiple files. +For a first run, use the built-in default UK model: ```python -from pathlib import Path +from batdetect2 import BatDetect2API -from batdetect2.api_v2 import BatDetect2API - -api = BatDetect2API.from_checkpoint(Path("path/to/model.ckpt")) +# If you don't specify a checkpoint the default model will be loaded +api = BatDetect2API.from_checkpoint() ``` +If you want to use a different checkpoint later, see {doc}`../how_to/choose-a-model`. + ## 2. Run inference on one file `process_file` is the simplest Python entry point when you want one prediction object per recording. ```python -from pathlib import Path +from batdetect2 import BatDetect2API -from batdetect2.api_v2 import BatDetect2API - -api = BatDetect2API.from_checkpoint(Path("path/to/model.ckpt")) -prediction = api.process_file(Path("path/to/audio.wav")) +api = BatDetect2API.from_checkpoint() +prediction = api.process_file("path/to/audio.wav") for detection in prediction.detections: top_class = api.get_top_class_name(detection) @@ -64,21 +52,34 @@ for detection in prediction.detections: print(top_class, score) ``` -`prediction` is a `ClipDetections` object. +## 3. Understand the prediction objects -It contains: +`prediction` is a `ClipDetections` object. +See {doc}`../reference/detections` for the full reference. + +Very briefly, `ClipDetections` represents all detections for one processed clip or recording. +It includes: - 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. +- the list of detections for that clip. -## 3. Inspect class scores, not just the top class +Each item in `prediction.detections` is a `Detection` object. -If you are exploring results, -it is often useful to inspect the full ranked class-score list. +Each `Detection` includes: + +- the time-frequency geometry of the event, +- a detection score, +- the class scores, +- a feature vector. + +## 4. Inspect detection score and class scores + +The detection score and the class scores answer different questions. + +- `detection_score` is about whether the model thinks there is a call at that time-frequency location. +- `class_scores` are about which class the model prefers for that detected event. + +So a detection can have a fairly strong detection score, but still have a more uncertain class ranking. ```python for detection in prediction.detections: @@ -89,30 +90,71 @@ for detection in prediction.detections: print(f" {class_name}: {score:.3f}") ``` -This helps separate two different questions: +If you want more detail on class-score inspection, see {doc}`../how_to/inspect-class-scores-in-python`. -- "Did the model think there was a call here?" -- "If there was a call, which class did it score highest?" +## 5. Inspect the detection features -## 4. Keep the first workflow small +Each detection also carries a `features` vector. -Before scaling up, run the API on a few representative files and inspect the results manually. +These are internal model features attached to the detection. +They can be useful for things like: -This catches path issues and obviously implausible outputs early. +- exploratory visualisation, +- clustering similar detections, +- comparing detections across files, +- building downstream analysis pipelines. -## 5. Move to the right next workflow +They are useful descriptors, but they are not direct ecological labels by themselves. -Once the single-file path is working, choose the next page based on what you need: +For more detail, see {doc}`../how_to/inspect-detection-features-in-python` and {doc}`../explanation/extracted-features-and-embeddings`. -- save predictions to disk, -- inspect class scores more carefully, -- inspect detection features, -- process many files in one run. +## 6. Use lower-level audio and spectrogram methods for more control -## What to do next +If you want finer control over what gets processed and when, the API also lets you work step by step. +For example, you can load the audio yourself, inspect the waveform length, generate the spectrogram, and then run detection on that spectrogram: + +```python +from batdetect2 import BatDetect2API + +api = BatDetect2API.from_checkpoint() + +audio = api.load_audio("path/to/audio.wav") +print(audio.shape) + +spec = api.generate_spectrogram(audio) +print(spec.shape) + +detections = api.process_spectrogram(spec) +print(len(detections)) +``` + +This is helpful when you want to: + +- inspect the loaded audio before inference, +- inspect the generated spectrogram, +- control which audio segment is processed, +- run only part of the pipeline in custom code. + +You can also call `process_audio(audio)` directly if you already have the waveform array in memory. + +## 7. Use the wider API workflows + +The Python API is not only for single-file inference. +It also exposes methods for batch processing, training, evaluation, and fine-tuning. + +Examples: + +- `process_files(...)` for batch processing from Python, +- `train(...)` for training, +- `evaluate(...)` for evaluation, +- `finetune(...)` for fine-tuning. + +Useful next pages: + +- Choose a different model: {doc}`../how_to/choose-a-model` +- Run batch predictions: {doc}`../how_to/run-batch-predictions` +- Train a custom model: {doc}`train-a-custom-model` +- Evaluate on a test set: {doc}`evaluate-on-a-test-set` +- Fine-tune from a checkpoint: {doc}`../how_to/fine-tune-from-a-checkpoint` - 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`