lionel/batdetect2
1
0
Fork 0
mirror of https://github.com/macaodha/batdetect2.git synced 2026-05-22 22:32:18 +02:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: expand inference tutorial examples and model selection guidance

Browse Source
This commit is contained in:
mbsantiago 2026-05-07 07:09:49 +01:00
parent 94746b5f3b
commit 214fbdb7cc
4 changed files with 278 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

112
docs/source/how_to/choose-a-model.md Normal file
View File

@ -0,0 +1,112 @@
# How to choose a model
Use this guide when you want to choose which model checkpoint BatDetect2 loads.
You can choose a model in both the CLI and the Python API.
## Where you can choose the model
In the CLI, use `--model` with commands that load a checkpoint, including:
- `batdetect2 process`
- `batdetect2 evaluate`
- `batdetect2 train`
- `batdetect2 finetune`
In Python, pass the model source to `BatDetect2API.from_checkpoint(...)`.
If you do not choose a model, BatDetect2 uses the built-in default UK model.
## Use a local checkpoint path
Use a local path when you already have a checkpoint file on disk.
CLI example:
```bash
batdetect2 process directory \
path/to/audio \
path/to/outputs \
--model path/to/model.ckpt
```
Python example:
```python
from batdetect2.api_v2 import BatDetect2API
api = BatDetect2API.from_checkpoint("path/to/model.ckpt")
```
## Use a bundled checkpoint alias
BatDetect2 also supports bundled checkpoint aliases.
The built-in UK model is available as `uk_same`.
The alias `batdetect2_uk_same` also works.
CLI example:
```bash
batdetect2 process directory \
path/to/audio \
path/to/outputs \
--model uk_same
```
Python example:
```python
from batdetect2.api_v2 import BatDetect2API
api = BatDetect2API.from_checkpoint("uk_same")
```
## Use a Hugging Face URI
You can also load a checkpoint from Hugging Face with a URI like:
```text
hf://owner/repo/path/to/model.ckpt
```
This needs the optional Hugging Face dependency to be installed.
For example, install it with `pip install batdetect2[huggingface]`.
CLI example:
```bash
batdetect2 process directory \
path/to/audio \
path/to/outputs \
--model hf://owner/repo/path/to/model.ckpt
```
Python example:
```python
from batdetect2.api_v2 import BatDetect2API
api = BatDetect2API.from_checkpoint(
"hf://owner/repo/path/to/model.ckpt"
)
```
## Choose the right source
- Use a local path when you already have a checkpoint file.
- Use an alias when you want one of the bundled models.
- Use a Hugging Face URI when the checkpoint lives in a Hugging Face repo.
## Related pages
- Run inference on a folder:
{doc}`../tutorials/run-inference-on-folder`
- `BatDetect2API` reference:
{doc}`../reference/api`
- Process command reference:
{doc}`../reference/cli/predict`
- Train a custom model:
{doc}`../tutorials/train-a-custom-model`
- Fine-tune from a checkpoint:
{doc}`fine-tune-from-a-checkpoint`

7
docs/source/how_to/index.md
View File

@ -1,12 +1,15 @@
# How-to Guides
How-to guides help you answer practical questions once you are past the first tutorial.
How-to guides help you answer practical questions once you are past the first
tutorial.
Use this section when you already know the basic workflow and want help with one specific task.
Use this section when you already know the basic workflow and want help with one
specific task.
```{toctree}
:maxdepth: 1
choose-a-model
choose-an-inference-input-mode
run-batch-predictions
tune-inference-clipping

221
docs/source/tutorials/run-inference-on-folder.md
View File

@ -1,120 +1,217 @@
# Tutorial: Run BatDetect2 on a folder of audio files
# Run BatDetect2 on a folder of audio files
This tutorial walks through a first end-to-end inference run with the CLI.
This tutorial shows how to run BatDetect2 on a folder of recordings from the command line.
It is the default starting point for new users.
Use it when you want a first pass over a folder of audio recordings and want to see what BatDetect2 finds.
Use it when you want to run an existing model on a folder of recordings and
quickly check what BatDetect2 found.
If you want to follow the tutorial exactly, you can use the example recordings that come with the repository.
## Before you start
- BatDetect2 installed in your environment.
- A folder containing `.wav` files.
- A model checkpoint path.
You need:
A checkpoint is the saved model file that BatDetect2 uses to make predictions.
- BatDetect2 installed.
- A folder containing supported audio files.
- A place to save the results.
If you are working from this repository checkout, you can use:
If you have not installed BatDetect2 yet, start with {doc}`../getting_started`.
```text
src/batdetect2/models/checkpoints/Net2DFast_UK_same.pth.tar
## Optional: use the repository example files
If you want to follow the steps with the same paths shown here, clone the repository and move into it:
```bash
git clone https://github.com/macaodha/batdetect2.git
cd batdetect2
```
## Outcome
Then you can use these example paths from the repository root.
## What you will do
By the end of this tutorial you will have:
- run `batdetect2 process directory`,
- saved predictions to disk,
- checked that BatDetect2 wrote output files,
- identified the next pages to use for tuning or customization.
- checked that BatDetect2 wrote the files you expected,
- tried a second run with a higher detection threshold,
- identified the next pages to use if you want to customise the run.
## 1. Choose your input and output paths
## 1. Choose your input and output folders
Pick three paths:
Pick:
- the checkpoint to use,
- the directory containing your audio files,
- an output directory where BatDetect2 will save its results.
- the folder containing your audio files,
- an output folder where BatDetect2 should save results.
Example layout:
```text
project/
model.pth.tar
audio/
file_001.wav
file_002.wav
outputs/
```
## 2. Run processing on the directory
If `outputs/` does not exist yet, that is fine.
BatDetect2 can create it.
Use this command when you want BatDetect2 to scan a folder of recordings
automatically.
If you are using the repository example files, your layout already looks like this:
```text
batdetect2/
example_data/
audio/
20170701_213954-MYOMYS-LR_0_0.5.wav
20180530_213516-EPTSER-LR_0_0.5.wav
20180627_215323-RHIFER-LR_0_0.5.wav
```
## 2. Run BatDetect2 on the folder
For a first run, use the built-in default UK model:
```bash
batdetect2 process directory \
path/to/model.pth.tar \
path/to/audio_dir \
path/to/audio \
path/to/outputs
```
If you are using the repository example files, run:
```bash
batdetect2 process directory \
example_data/audio \
example_outputs/first_run
```
What this does:
- loads the checkpoint,
- finds audio files in `audio_dir`,
- splits recordings into smaller pieces internally when needed,
- saves result files to `outputs`.
- looks for supported audio files in `path/to/audio`,
- runs the model on each recording,
- saves the results in `path/to/outputs`.
## 3. Verify that outputs were written
You do not need to choose a model for this first run.
If you do nothing, BatDetect2 uses the built-in default UK model.
After the command completes, inspect the output directory.
If you want to use a different model later, see {doc}`../how_to/choose-a-model`.
For a first run, the important check is simple:
## 3. Check the output files
- did BatDetect2 create result files,
- are they in the output directory you expected,
- did it process the recordings you meant to analyze.
After the command finishes, look in your output folder.
Different workflows can save results in different file formats.
By default, the CLI writes predictions in the `batdetect2` output format.
This is a JSON-based format used for BatDetect2-style outputs.
You do not need to learn those details for the first run.
With the default settings, you will usually see one `.json` file and one `_detections.csv` file per recording.
If you later need to choose a specific output format, go to
{doc}`../how_to/save-predictions-in-different-output-formats`.
For the repository example run, that means files like:
## 4. Inspect predictions
```text
example_outputs/first_run/
20170701_213954-MYOMYS-LR_0_0.5.wav.json
20170701_213954-MYOMYS-LR_0_0.5.wav_detections.csv
20180530_213516-EPTSER-LR_0_0.5.wav.json
20180530_213516-EPTSER-LR_0_0.5.wav_detections.csv
20180627_215323-RHIFER-LR_0_0.5.wav.json
20180627_215323-RHIFER-LR_0_0.5.wav_detections.csv
```
Start with a small subset of representative files.
One of the JSON files will look roughly like this:
Check:
```json
{
"annotated": false,
"annotation": [
{
"class": "Rhinolophus ferrumequinum",
"class_prob": 0.889,
"det_prob": 0.889,
"end_time": 0.0668,
"event": "Echolocation",
"high_freq": 84857,
"individual": "-1",
"low_freq": 67578,
"start_time": 0.0
}
]
}
```
- whether detections were written for the expected recordings,
- whether output counts are plausible,
- whether the model is obviously too sensitive or too conservative,
- whether the predicted classes look broadly reasonable for your data.
Very briefly:
Do not treat the first run as validated ecological output.
- `annotated: false` means this is a prediction file, not a reviewed annotation file.
- `annotation` holds the list of detections.
- Each detection includes a predicted class, detection score, class score, time bounds, and frequency bounds.
The first run is a workflow check.
For more detail, see {doc}`../explanation/interpreting-formatted-outputs`.
If you want to save results in another format, see {doc}`../how_to/save-predictions-in-different-output-formats`.
Validation comes next.
## 4. Run the same folder with a higher threshold
## 5. Tune only after you have a baseline
If you want, you can also run the same folder again with a higher detection threshold and save that run in a separate output folder.
If the first run is too noisy or misses obvious calls, tune thresholds on a
reviewed subset rather than changing settings blindly across the full dataset.
```bash
batdetect2 process directory \
path/to/audio \
path/to/outputs_threshold_05 \
--detection-threshold 0.5
```
Use {doc}`../how_to/tune-detection-threshold` for that process.
Concrete example:
## What to do next
```bash
batdetect2 process directory \
example_data/audio \
example_outputs/threshold_05 \
--detection-threshold 0.5
```
- If you need a different input mode, use
{doc}`../how_to/choose-an-inference-input-mode`.
- If you want to tune sensitivity, use
{doc}`../how_to/tune-detection-threshold`.
- If you already write code and want more control from Python, use
{doc}`integrate-with-a-python-pipeline`.
- If you need full command details, use {doc}`../reference/cli/predict`.
Keeping this in a separate folder makes it easy to compare runs later.
## 5. Run the model on a list of recordings
If you only want to process selected recordings, use `file_list`.
The list file should contain one recording path per line.
Example `audio_files.txt`:
```text
path/to/audio/file_001.wav
path/to/audio/file_002.wav
path/to/audio/file_010.wav
```
Repository example:
```text
example_data/audio/20170701_213954-MYOMYS-LR_0_0.5.wav
example_data/audio/20180530_213516-EPTSER-LR_0_0.5.wav
```
Then run:
```bash
batdetect2 process file_list \
path/to/audio_files.txt \
path/to/selected_outputs
```
Concrete example:
```bash
batdetect2 process file_list \
example_data/audio_files.txt \
example_outputs/selected_outputs
```
This is useful when your recordings are spread across folders, or when you only want to run a chosen subset.
## Common next steps
- If your recordings are not all in one folder, or you want to compare input modes, see {doc}`../how_to/choose-an-inference-input-mode`.
- If you want to save results in another format, see {doc}`../how_to/save-predictions-in-different-output-formats`.
- If you want to choose a different model, see {doc}`../how_to/choose-a-model`.
- If you already write code and want more control from Python, see {doc}`integrate-with-a-python-pipeline`.
- If you want the full command reference, including `--model`, see {doc}`../reference/cli/predict`.

2
example_data/audio_files.txt Normal file
View File

@ -0,0 +1,2 @@
example_data/audio/20170701_213954-MYOMYS-LR_0_0.5.wav
example_data/audio/20180530_213516-EPTSER-LR_0_0.5.wav