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

feat: rename CLI inference command to process

Browse Source
This commit is contained in:
mbsantiago 2026-05-06 14:32:51 +01:00
parent 831925bd95
commit 6587c6c4e5
21 changed files with 237 additions and 178 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
README.md
View File

@ -100,7 +100,7 @@ src/batdetect2/models/checkpoints/Net2DFast_UK_same.pth.tar
Example command:
```bash
batdetect2 predict directory \
batdetect2 process directory \
src/batdetect2/models/checkpoints/Net2DFast_UK_same.pth.tar \
example_data/audio \
outputs
@ -145,7 +145,7 @@ The remainder of this section is legacy reference material.
The commands below describe the legacy CLI workflow.
For new work, prefer the current docs and `batdetect2 predict`.
For new work, prefer the current docs and `batdetect2 process`.
You can run the model by opening the command line and typing:
```bash

26
docs/source/getting_started.md
View File

@ -1,19 +1,20 @@
# Getting started
If you want to run BatDetect2 on your recordings,
start with the command-line route below.
If you want to run BatDetect2 on your recordings, start with the command-line
route below.
You do not need to write Python code for a standard first run.
BatDetect2 also has a Python interface,
but that is mainly for users writing their own analysis scripts.
BatDetect2 also has a Python interface, but that is mainly for users writing
their own analysis scripts.
- Use the command-line route if you want to run an existing model or train your own model by typing commands in a terminal window.
- Use the command-line route if you want to run an existing model or train your
own model by typing commands in a terminal window.
- Use the Python route only if you already want to work in scripts or notebooks.
```{note}
If you are looking for the previous BatDetect2 workflow based on `batdetect2 detect` or `batdetect2.api`, go to {doc}`legacy/index`.
New docs default to the current `predict` CLI and `BatDetect2API` workflow.
New docs default to the current `process` CLI and `BatDetect2API` workflow.
```
If you want to try BatDetect2 before installing anything locally:
@ -27,15 +28,14 @@ If you want to try BatDetect2 before installing anything locally:
2. Use a model checkpoint.
3. Run the first tutorial on a folder of recordings.
If that is what you want,
you can ignore the Python sections for now.
If that is what you want, you can ignore the Python sections for now.
## Install BatDetect2
We recommend `uv` for both workflows.
`uv` is a tool that helps install Python software cleanly,
without mixing it into the rest of your machine.
`uv` is a tool that helps install Python software cleanly, without mixing it
into the rest of your machine.
- Use `uv tool` to install the CLI.
- Use `uv add` to add `batdetect2` as a dependency in a Python project.
@ -70,7 +70,8 @@ Go to {doc}`tutorials/run-inference-on-folder` for a complete first run.
## Choose a model checkpoint
The current command-line and Python workflows expect an explicit checkpoint path.
The current command-line and Python workflows expect an explicit checkpoint
path.
A checkpoint is the saved model file that BatDetect2 will use for prediction.
@ -85,7 +86,8 @@ In this repository checkout, an example pretrained checkpoint is available at:
src/batdetect2/models/checkpoints/Net2DFast_UK_same.pth.tar
```
Use that path in the tutorial commands if you want a concrete starting point from this source tree.
Use that path in the tutorial commands if you want a concrete starting point
from this source tree.
## Python route for users writing code

27
docs/source/how_to/choose-an-inference-input-mode.md
View File

@ -1,8 +1,9 @@
# How to choose an inference input mode
Use this guide to decide whether `predict directory`, `predict file_list`, or `predict dataset` is the right entry point for your run.
Use this guide to decide whether `process directory`, `process file_list`, or
`process dataset` is the right entry point for your run.
## Use `predict directory` when the recordings already live together
## Use `process directory` when the recordings already live together
This is the simplest choice.
@ -13,13 +14,13 @@ Use it when:
- you are doing a first pass over a folder of recordings.
```bash
batdetect2 predict directory \
batdetect2 process directory \
path/to/model.ckpt \
path/to/audio_dir \
path/to/outputs
```
## Use `predict file_list` when you need explicit control over the file set
## Use `process file_list` when you need explicit control over the file set
Use it when:
@ -30,13 +31,13 @@ Use it when:
The list file should contain one path per line.
```bash
batdetect2 predict file_list \
batdetect2 process file_list \
path/to/model.ckpt \
path/to/audio_files.txt \
path/to/outputs
```
## Use `predict dataset` when your workflow is already annotation-set driven
## Use `process dataset` when your workflow is already annotation-set driven
Use it when:
@ -45,13 +46,14 @@ Use it when:
- you want BatDetect2 to resolve recording paths from the annotation set.
```bash
batdetect2 predict dataset \
batdetect2 process dataset \
path/to/model.ckpt \
path/to/annotation_set.json \
path/to/outputs
```
The dataset command reads a `soundevent` annotation set and extracts unique recording paths before inference.
The dataset command reads a `soundevent` annotation set and extracts unique
recording paths before inference.
## Rule of thumb
@ -61,6 +63,9 @@ The dataset command reads a `soundevent` annotation set and extracts unique reco
## Related pages
- Run batch predictions: {doc}`run-batch-predictions`
- Tune inference clipping: {doc}`tune-inference-clipping`
- Predict command reference: {doc}`../reference/cli/predict`
- Run batch predictions:
{doc}`run-batch-predictions`
- Tune inference clipping:
{doc}`tune-inference-clipping`
- Process command reference:
{doc}`../reference/cli/predict`

12
docs/source/how_to/configure-audio-preprocessing.md
View File

@ -46,7 +46,7 @@ Available built-ins:
For CLI inference/evaluation, use `--audio-config`.
```bash
batdetect2 predict directory \
batdetect2 process directory \
path/to/model.ckpt \
path/to/audio_dir \
path/to/outputs \
@ -55,10 +55,12 @@ batdetect2 predict directory \
## 4) Verify quickly on a small subset
Run on a small folder first and confirm that outputs and runtime are as
expected before full-batch runs.
Run on a small folder first and confirm that outputs and runtime are as expected
before full-batch runs.
## Related pages
- Spectrogram settings: {doc}`configure-spectrogram-preprocessing`
- Preprocessing config reference: {doc}`../reference/preprocessing-config`
- Spectrogram settings:
{doc}`configure-spectrogram-preprocessing`
- Preprocessing config reference:
{doc}`../reference/preprocessing-config`

25
docs/source/how_to/run-batch-predictions.md
View File

@ -1,14 +1,15 @@
# How to run batch predictions
# How to run batch processing
This guide shows practical command patterns for directory-based and file-list
prediction runs.
processing runs.
Use it after you already know which input mode you want and need concrete command templates for a repeatable batch run.
Use it after you already know which input mode you want and need concrete
command templates for a repeatable batch run.
## Predict from a directory
## Process a directory
```bash
batdetect2 predict directory \
batdetect2 process directory \
path/to/model.ckpt \
path/to/audio_dir \
path/to/outputs
@ -16,27 +17,29 @@ batdetect2 predict directory \
Use this when BatDetect2 should discover the audio files for you.
## Predict from a file list
## Process a file list
```bash
batdetect2 predict file_list \
batdetect2 process file_list \
path/to/model.ckpt \
path/to/audio_files.txt \
path/to/outputs
```
Use this when another part of your workflow already produced the exact recording list to process.
Use this when another part of your workflow already produced the exact recording
list to process.
## Predict from a dataset config
## Process a dataset config
```bash
batdetect2 predict dataset \
batdetect2 process dataset \
path/to/model.ckpt \
path/to/annotation_set.json \
path/to/outputs
```
Use this when your project already has a `soundevent` annotation set and you want to extract unique recording paths from it.
Use this when your project already has a `soundevent` annotation set and you
want to extract unique recording paths from it.
## Useful options

31
docs/source/how_to/save-predictions-in-different-output-formats.md
View File

@ -1,22 +1,27 @@
# How to save predictions in different output formats
Use this guide when you need BatDetect2 outputs in a specific representation for downstream tools.
Use this guide when you need BatDetect2 outputs in a specific representation for
downstream tools.
## Choose the format that matches the job
Current built-in output formats include:
- `raw`: one NetCDF file per clip, best for rich structured outputs,
- `parquet`: tabular storage for data analysis workflows,
- `soundevent`: prediction-set JSON for soundevent-style tooling,
- `batdetect2`: legacy per-recording JSON output.
- `raw`:
one NetCDF file per clip, best for rich structured outputs,
- `parquet`:
tabular storage for data analysis workflows,
- `soundevent`:
prediction-set JSON for soundevent-style tooling,
- `batdetect2`:
legacy per-recording JSON output.
## Select a format from the CLI
Use `--format` for quick experiments.
```bash
batdetect2 predict directory \
batdetect2 process directory \
path/to/model.ckpt \
path/to/audio_dir \
path/to/outputs \
@ -25,7 +30,8 @@ batdetect2 predict directory \
## Use an outputs config for repeatable runs
Use an outputs config when you want reproducible control over format and transforms.
Use an outputs config when you want reproducible control over format and
transforms.
Example:
@ -43,7 +49,7 @@ transform:
Run with:
```bash
batdetect2 predict directory \
batdetect2 process directory \
path/to/model.ckpt \
path/to/audio_dir \
path/to/outputs \
@ -59,6 +65,9 @@ batdetect2 predict directory \
## Related pages
- Outputs config reference: {doc}`../reference/outputs-config`
- Output formats reference: {doc}`../reference/output-formats`
- Output transforms reference: {doc}`../reference/output-transforms`
- Outputs config reference:
{doc}`../reference/outputs-config`
- Output formats reference:
{doc}`../reference/output-formats`
- Output transforms reference:
{doc}`../reference/output-transforms`

13
docs/source/how_to/tune-detection-threshold.md
View File

@ -4,7 +4,8 @@ Use this guide to compare detection outputs at different threshold values.
The goal is not to find a universal threshold.
The goal is to choose a threshold that fits your reviewed local data and the project trade-off between missed calls and false positives.
The goal is to choose a threshold that fits your reviewed local data and the
project trade-off between missed calls and false positives.
## 1) Start with a baseline run
@ -12,12 +13,12 @@ Run an initial prediction workflow and keep outputs in a dedicated folder.
## 2) Sweep threshold values
Run `predict` multiple times with different thresholds (for example `0.1`,
Run `process` multiple times with different thresholds (for example `0.1`,
`0.3`, `0.5`) and compare output counts and quality on the same validation
subset.
```bash
batdetect2 predict directory \
batdetect2 process directory \
path/to/model.ckpt \
path/to/audio_dir \
path/to/outputs_thr_03 \
@ -26,7 +27,8 @@ batdetect2 predict directory \
Keep each threshold run in a separate output directory.
That makes it easier to compare counts and inspect example files without mixing results.
That makes it easier to compare counts and inspect example files without mixing
results.
## 3) Validate against known calls
@ -38,7 +40,8 @@ Check both:
- obvious false positives,
- obvious missed calls.
If class interpretation matters downstream, inspect class ranking behavior as well, not just detection counts.
If class interpretation matters downstream, inspect class ranking behavior as
well, not just detection counts.
## 4) Record your chosen setting

34
docs/source/how_to/tune-inference-clipping.md
View File

@ -1,6 +1,7 @@
# How to tune inference clipping
Use this guide when long recordings need to be split into smaller clips during inference.
Use this guide when long recordings need to be split into smaller clips during
inference.
## What clipping controls
@ -8,14 +9,19 @@ Use this guide when long recordings need to be split into smaller clips during i
Key fields are:
- `duration`: clip duration in seconds,
- `overlap`: overlap between adjacent clips,
- `max_empty`: how much empty padding is allowed,
- `discard_empty`: whether empty clips are dropped.
- `duration`:
clip duration in seconds,
- `overlap`:
overlap between adjacent clips,
- `max_empty`:
how much empty padding is allowed,
- `discard_empty`:
whether empty clips are dropped.
## Start from the defaults
Use the built-in clipping behavior first unless you already know you need something else.
Use the built-in clipping behavior first unless you already know you need
something else.
Only tune clipping when:
@ -25,7 +31,7 @@ Only tune clipping when:
## Override clipping with an inference config
Create an inference config file and pass it to `predict` or `evaluate`.
Create an inference config file and pass it to `process` or `evaluate`.
Example:
@ -43,7 +49,7 @@ loader:
Run with:
```bash
batdetect2 predict directory \
batdetect2 process directory \
path/to/model.ckpt \
path/to/audio_dir \
path/to/outputs \
@ -52,12 +58,16 @@ batdetect2 predict directory \
## Validate clipping changes on a small reviewed subset
Changing clipping changes what the model sees per batch and can change how events near clip boundaries behave.
Changing clipping changes what the model sees per batch and can change how
events near clip boundaries behave.
Check a reviewed subset before applying clipping changes to a full project.
## Related pages
- Inference config reference: {doc}`../reference/inference-config`
- Run batch predictions: {doc}`run-batch-predictions`
- Understanding the pipeline: {doc}`../explanation/pipeline-overview`
- Inference config reference:
{doc}`../reference/inference-config`
- Run batch predictions:
{doc}`run-batch-predictions`
- Understanding the pipeline:
{doc}`../explanation/pipeline-overview`

28
docs/source/index.md
View File

@ -6,25 +6,20 @@ Welcome to the BatDetect2 documentation.
`batdetect2` detects bat echolocation calls in audio recordings.
It can help you screen large collections of recordings,
find files that need expert review,
and support ecology and conservation work where manual review alone would be slow.
It can help you screen large collections of recordings, find files that need
expert review, and support ecology and conservation work where manual review
alone would be slow.
In practice,
BatDetect2 takes recordings,
looks for likely bat calls,
draws a box around each detected event,
and scores the most likely class for that event.
In practice, BatDetect2 takes recordings, looks for likely bat calls, draws a
box around each detected event, and scores the most likely class for that event.
The current default model is trained for 17 UK species.
The library also supports custom training,
fine-tuning,
evaluation,
and more advanced use from Python.
The library also supports custom training, fine-tuning, evaluation, and more
advanced use from Python.
For details on the underlying approach, see the pre-print:
[Towards a General Approach for Bat Echolocation Detection and Classification](https://www.biorxiv.org/content/10.1101/2022.12.14.520490v1)
[Towards a General Approach for Bat Echolocation Detection and Classification](https://www.biorxiv.org/content/10.1101/2022.12.14.520490v1)
## A good first use for BatDetect2
@ -56,7 +51,7 @@ Always validate on reviewed local data before using results for ecological infer
```{note}
Looking for the previous BatDetect2 workflow?
See {doc}`legacy/index`.
The legacy docs are still available, but new workflows should use `batdetect2 predict` and `BatDetect2API`.
The legacy docs are still available, but new workflows should use `batdetect2 process` and `BatDetect2API`.
```
## How to use this site
@ -65,8 +60,7 @@ Start with {doc}`getting_started` if you are new.
Then choose the section that matches what you need.
If you are here mainly to run the model on recordings,
start with Tutorials.
If you are here mainly to run the model on recordings, start with Tutorials.
| Section | Best for | Start here |
| --- | --- | --- |
@ -81,7 +75,7 @@ start with Tutorials.
- GitHub repository:
[macaodha/batdetect2](https://github.com/macaodha/batdetect2)
- Questions, bug reports, and feature requests:
[GitHub Issues](https://github.com/macaodha/batdetect2/issues)
[GitHub Issues](https://github.com/macaodha/batdetect2/issues)
- Common questions:
{doc}`faq`
- Want to contribute?

10
docs/source/legacy/cli-detect.md
View File

@ -4,7 +4,7 @@ This page documents the previous CLI workflow based on `batdetect2 detect`.
```{warning}
This is legacy documentation.
For new workflows, use `batdetect2 predict directory` instead.
For new workflows, use `batdetect2 process directory` instead.
If you are migrating, start with {doc}`migration-guide`.
```
@ -27,7 +27,7 @@ Common legacy options included:
The closest current CLI entry point is:
```bash
batdetect2 predict directory \
batdetect2 process directory \
path/to/model.ckpt \
path/to/audio_dir \
path/to/outputs
@ -35,5 +35,7 @@ batdetect2 predict directory \
## Related pages
- Migration guide: {doc}`migration-guide`
- Current predict docs: {doc}`../reference/cli/predict`
- Migration guide:
{doc}`migration-guide`
- Current process docs:
{doc}`../reference/cli/predict`

9
docs/source/legacy/index.md
View File

@ -2,12 +2,15 @@
This section documents the previous BatDetect2 workflow.
Use these pages if you need to keep working with the older `batdetect2 detect` command or the older `batdetect2.api` interface.
Use these pages if you need to keep working with the older `batdetect2 detect`
command or the older `batdetect2.api` interface.
For new projects, we recommend the current workflow:
- CLI: `batdetect2 predict`
- Python: `batdetect2.api_v2.BatDetect2API`
- CLI:
`batdetect2 process`
- Python:
`batdetect2.api_v2.BatDetect2API`
If you are moving from the older workflow, start with {doc}`migration-guide`.

41
docs/source/legacy/migration-guide.md
View File

@ -1,6 +1,7 @@
# Migration guide: legacy to current workflows
Use this guide when moving from the previous BatDetect2 workflow to the current CLI and API.
Use this guide when moving from the previous BatDetect2 workflow to the current
CLI and API.
## Who should migrate now
@ -9,31 +10,37 @@ You should migrate if:
- you are starting a new workflow,
- you want the current docs path,
- you want the newer CLI and API surface,
- you are maintaining code that does not depend on the exact legacy JSON or feature outputs.
- you are maintaining code that does not depend on the exact legacy JSON or
feature outputs.
You may need the legacy workflow a bit longer if:
- downstream tooling depends on the exact old output structure,
- you rely on older notebooks built around `batdetect2.api`,
- you depend on legacy feature extraction outputs without a validated replacement yet.
- you depend on legacy feature extraction outputs without a validated
replacement yet.
## CLI mapping
- `batdetect2 detect AUDIO_DIR ANN_DIR DETECTION_THRESHOLD`
-> `batdetect2 predict directory MODEL_PATH AUDIO_DIR OUTPUT_PATH --detection-threshold ...`
- `batdetect2 detect AUDIO_DIR ANN_DIR DETECTION_THRESHOLD` -> `batdetect2
process directory MODEL_PATH AUDIO_DIR OUTPUT_PATH --detection-threshold ...`
Main changes:
- the model path is now a positional argument on the `predict` subcommand,
- the current workflow expects an explicit checkpoint path rather than silently relying on the old default CLI behavior,
- the model path is now a positional argument on the `process` subcommand,
- the current workflow expects an explicit checkpoint path rather than silently
relying on the old default CLI behavior,
- output formatting is configurable,
- threshold override is an option rather than a required positional argument,
- there are separate subcommands for directory, file-list, and dataset-driven inference.
- there are separate subcommands for directory, file-list, and dataset-driven
inference.
## Python API mapping
- old: `import batdetect2.api as api`
- current: `from batdetect2.api_v2 import BatDetect2API`
- old:
`import batdetect2.api as api`
- current:
`from batdetect2.api_v2 import BatDetect2API`
Typical migration shape:
@ -51,7 +58,7 @@ Useful replacements:
- legacy `process_file` -> current `BatDetect2API.process_file`
- legacy `process_audio` -> current `BatDetect2API.process_audio`
- legacy `process_spectrogram` -> current `BatDetect2API.process_spectrogram`
- legacy one-off batch loops -> current `process_files` or CLI `predict`
- legacy one-off batch loops -> current `process_files` or CLI `process`
## Output and terminology changes
@ -78,7 +85,8 @@ Before replacing a legacy workflow in production or research analysis, validate:
- that outputs are being saved in the right format,
- that downstream code reads the new outputs correctly,
- that feature-related assumptions still hold,
- that evaluation and ecological interpretation are unchanged only where you have actually verified that.
- that evaluation and ecological interpretation are unchanged only where you
have actually verified that.
## Migration checklist
@ -91,6 +99,9 @@ Before replacing a legacy workflow in production or research analysis, validate:
## Related pages
- Current getting started: {doc}`../getting_started`
- Current tutorials: {doc}`../tutorials/index`
- Current API reference: {doc}`../reference/api`
- Current getting started:
{doc}`../getting_started`
- Current tutorials:
{doc}`../tutorials/index`
- Current API reference:
{doc}`../reference/api`

4
docs/source/reference/cli/detect_legacy.rst
View File

@ -4,13 +4,13 @@ Legacy detect command
.. warning::
``batdetect2 detect`` is a legacy compatibility command.
Prefer ``batdetect2 predict directory`` for new workflows.
Prefer ``batdetect2 process directory`` for new workflows.
Migration at a glance
---------------------
- Legacy: ``batdetect2 detect AUDIO_DIR ANN_DIR DETECTION_THRESHOLD``
- Current: ``batdetect2 predict directory MODEL_PATH AUDIO_DIR OUTPUT_PATH``
- Current: ``batdetect2 process directory MODEL_PATH AUDIO_DIR OUTPUT_PATH``
with optional ``--detection-threshold``
.. click:: batdetect2.cli.compat:detect

8
docs/source/reference/cli/index.md
View File

@ -7,7 +7,7 @@ for the full option list.
| Command | Use it for | Required positional args |
| --- | --- | --- |
| `batdetect2 predict` | Run prediction on audio | Depends on subcommand (`directory`, `file_list`, `dataset`) |
| `batdetect2 process` | Run inference on audio | Depends on subcommand (`directory`, `file_list`, `dataset`) |
| `batdetect2 data` | Inspect and convert dataset configs | Depends on subcommand (`summary`, `convert`) |
| `batdetect2 train` | Train or fine-tune models | `TRAIN_DATASET` |
| `batdetect2 finetune` | Fine-tune a checkpoint on new targets | `TRAIN_DATASET` plus `--targets` |
@ -19,13 +19,13 @@ for the full option list.
- Global CLI options are documented in {doc}`base`.
- Paths with spaces should be wrapped in quotes.
- Input audio is expected to be mono.
- `predict` uses the optional `--detection-threshold` override.
- `process` uses the optional `--detection-threshold` override.
- `finetune` defaults to the bundled `uk_same` checkpoint if `--model` is not
provided.
```{warning}
`batdetect2 detect` is a legacy command.
Prefer `batdetect2 predict directory` for new workflows.
Prefer `batdetect2 process directory` for new workflows.
```
## Related pages
@ -39,7 +39,7 @@ Prefer `batdetect2 predict directory` for new workflows.
:maxdepth: 1
Base command and global options <base>
Predict command group <predict>
Process command group <predict>
Data command group <data>
Train command <train>
Finetune command <finetune>

8
docs/source/reference/cli/predict.rst
View File

@ -1,7 +1,7 @@
Predict command
Process command
===============
Use ``batdetect2 predict`` to run prediction on audio.
Use ``batdetect2 process`` to run inference on audio.
Choose a subcommand based on how you want to provide the input:
@ -12,6 +12,6 @@ Choose a subcommand based on how you want to provide the input:
Use ``--detection-threshold`` when you want to override the configured
threshold for one run.
.. click:: batdetect2.cli.inference:predict
:prog: batdetect2 predict
.. click:: batdetect2.cli.inference:process
:prog: batdetect2 process
:nested: full

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

@ -4,7 +4,8 @@ This tutorial walks through a first end-to-end inference run with the CLI.
It is the default starting point for new users.
Use it when you want to run an existing model on a folder of recordings and quickly check what BatDetect2 found.
Use it when you want to run an existing model on a folder of recordings and
quickly check what BatDetect2 found.
## Before you start
@ -24,7 +25,7 @@ src/batdetect2/models/checkpoints/Net2DFast_UK_same.pth.tar
By the end of this tutorial you will have:
- run `batdetect2 predict directory`,
- run `batdetect2 process directory`,
- saved predictions to disk,
- checked that BatDetect2 wrote output files,
- identified the next pages to use for tuning or customization.
@ -48,12 +49,13 @@ project/
outputs/
```
## 2. Run prediction on the directory
## 2. Run processing on the directory
Use this command when you want BatDetect2 to scan a folder of recordings automatically.
Use this command when you want BatDetect2 to scan a folder of recordings
automatically.
```bash
batdetect2 predict directory \
batdetect2 process directory \
path/to/model.pth.tar \
path/to/audio_dir \
path/to/outputs
@ -70,8 +72,7 @@ What this does:
After the command completes, inspect the output directory.
For a first run,
the important check is simple:
For a first run, the important check is simple:
- did BatDetect2 create result files,
- are they in the output directory you expected,
@ -81,8 +82,8 @@ Different workflows can save results in different file formats.
You do not need to learn those details for the first run.
If you later need to choose a specific output format,
go to {doc}`../how_to/save-predictions-in-different-output-formats`.
If you later need to choose a specific output format, go to
{doc}`../how_to/save-predictions-in-different-output-formats`.
## 4. Inspect predictions
@ -103,13 +104,17 @@ Validation comes next.
## 5. Tune only after you have a baseline
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.
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.
Use {doc}`../how_to/tune-detection-threshold` for that process.
## What to do next
- 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 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`.

4
src/batdetect2/cli/__init__.py
View File

@ -3,7 +3,7 @@ from batdetect2.cli.compat import detect
from batdetect2.cli.data import data
from batdetect2.cli.evaluate import evaluate_command
from batdetect2.cli.finetune import finetune_command
from batdetect2.cli.inference import predict
from batdetect2.cli.inference import process
from batdetect2.cli.train import train_command
__all__ = [
@ -13,7 +13,7 @@ __all__ = [
"train_command",
"finetune_command",
"evaluate_command",
"predict",
"process",
]

19
src/batdetect2/cli/base.py
View File

@ -2,6 +2,8 @@
import click
from batdetect2.cli.ascii import BATDETECT_ASCII_ART
__all__ = [
"cli",
]
@ -9,29 +11,30 @@ __all__ = [
INFO_STR = """
BatDetect2
Input audio should be mono.
Wrap paths that contain spaces in quotes.
For long recordings, split audio into shorter files before running
prediction.
"""
@click.group()
@click.group(invoke_without_command=True)
@click.option(
"-v",
"--verbose",
count=True,
help="Increase verbosity. -v for INFO, -vv for DEBUG.",
)
def cli(verbose: int = 0):
@click.pass_context
def cli(ctx: click.Context, verbose: int = 0):
"""Run the BatDetect2 CLI.
Use subcommands to run prediction, training, evaluation, and dataset
Use subcommands to run processing, training, evaluation, and dataset
utilities.
"""
click.echo(INFO_STR)
if ctx.invoked_subcommand is None:
click.echo(BATDETECT_ASCII_ART)
click.echo(ctx.get_help())
ctx.exit()
from batdetect2.logging import enable_logging
enable_logging(verbose)
# click.echo(BATDETECT_ASCII_ART)

11
src/batdetect2/cli/compat.py
View File

@ -1,4 +1,5 @@
import os
import warnings
import click
@ -15,7 +16,7 @@ DEFAULT_MODEL_PATH = os.path.join(
@cli.command(
short_help="Legacy detection command.",
epilog=(
"Deprecated workflow. Prefer `batdetect2 predict directory` for "
"Deprecated workflow. Prefer `batdetect2 process directory` for "
"new analyses."
),
)
@ -91,11 +92,17 @@ def detect(
Note
----
This command is kept for backwards compatibility. Prefer
`batdetect2 predict directory` for new workflows.
`batdetect2 process directory` for new workflows.
"""
from batdetect2 import api
from batdetect2.utils.detector_utils import save_results_to_file
message = (
"The `batdetect2 detect` command is deprecated. Prefer "
"`batdetect2 process directory` for new analyses."
)
click.secho(f"WARNING: {message}", fg="yellow", err=True)
click.echo(f"Loading model: {args['model_path']}")
model, params = api.load_model(args["model_path"])

28
src/batdetect2/cli/inference.py
View File

@ -13,11 +13,11 @@ if TYPE_CHECKING:
from batdetect2.inference import InferenceConfig
from batdetect2.outputs import OutputsConfig
__all__ = ["predict"]
__all__ = ["process"]
@cli.group(name="predict", short_help="Run prediction workflows.")
def predict() -> None:
@cli.group(name="process", short_help="Run processing workflows.")
def process() -> None:
"""Run model inference on audio.
Choose a subcommand based on how you want to provide input audio.
@ -25,7 +25,7 @@ def predict() -> None:
def common_predict_options(func):
"""Attach options shared by all ``predict`` subcommands."""
"""Attach options shared by all ``process`` subcommands."""
@click.option(
"--audio-config",
@ -186,9 +186,9 @@ def _run_prediction(
)
@predict.command(
@process.command(
name="directory",
short_help="Predict on audio files in a directory.",
short_help="Process audio files in a directory.",
)
@click.argument("model_path", type=str)
@click.argument("audio_dir", type=click.Path(exists=True))
@ -207,9 +207,9 @@ def predict_directory_command(
format_name: str | None,
detection_threshold: float | None,
) -> None:
"""Run prediction on all supported audio files in a directory.
"""Run processing on all supported audio files in a directory.
This command scans ``audio_dir`` for audio files, runs prediction, and
This command scans ``audio_dir`` for audio files, runs processing, and
saves the results to ``output_path``.
"""
from soundevent.audio.files import get_audio_files
@ -230,9 +230,9 @@ def predict_directory_command(
)
@predict.command(
@process.command(
name="file_list",
short_help="Predict on paths listed in a text file.",
short_help="Process paths listed in a text file.",
)
@click.argument("model_path", type=str)
@click.argument("file_list", type=click.Path(exists=True))
@ -251,7 +251,7 @@ def predict_file_list_command(
format_name: str | None,
detection_threshold: float | None,
) -> None:
"""Run prediction on audio files listed in a text file.
"""Run processing on audio files listed in a text file.
The text file should contain one audio path per line. Empty lines are
ignored.
@ -278,9 +278,9 @@ def predict_file_list_command(
)
@predict.command(
@process.command(
name="dataset",
short_help="Predict on recordings from a dataset config.",
short_help="Process recordings from a dataset config.",
)
@click.argument("model_path", type=str)
@click.argument("dataset_path", type=click.Path(exists=True))
@ -299,7 +299,7 @@ def predict_dataset_command(
format_name: str | None,
detection_threshold: float | None,
) -> None:
"""Run prediction on recordings referenced in a dataset file.
"""Run processing on recordings referenced in a dataset file.
Recording paths are read from the dataset and each recording is processed
once.

42
tests/test_cli/test_predict.py
View File

@ -1,4 +1,4 @@
"""Behavior tests for predict CLI workflows."""
"""Behavior tests for process CLI workflows."""
from pathlib import Path
@ -9,10 +9,10 @@ from soundevent import data, io
from batdetect2.cli import cli
def test_cli_predict_help() -> None:
"""User story: discover available predict modes."""
def test_cli_process_help() -> None:
"""User story: discover available process modes."""
result = CliRunner().invoke(cli, ["predict", "--help"])
result = CliRunner().invoke(cli, ["process", "--help"])
assert result.exit_code == 0
assert "directory" in result.output
@ -21,19 +21,19 @@ def test_cli_predict_help() -> None:
@pytest.mark.slow
def test_cli_predict_directory_runs_on_real_audio(
def test_cli_process_directory_runs_on_real_audio(
tmp_path: Path,
tiny_checkpoint_path: Path,
single_audio_dir: Path,
) -> None:
"""User story: run prediction for all files in a directory."""
"""User story: process all files in a directory."""
output_path = tmp_path / "predictions"
result = CliRunner().invoke(
cli,
[
"predict",
"process",
"directory",
str(tiny_checkpoint_path),
str(single_audio_dir),
@ -52,12 +52,12 @@ def test_cli_predict_directory_runs_on_real_audio(
assert len(list(output_path.glob("*.json"))) == 1
def test_cli_predict_file_list_runs_on_real_audio(
def test_cli_process_file_list_runs_on_real_audio(
tmp_path: Path,
tiny_checkpoint_path: Path,
single_audio_dir: Path,
) -> None:
"""User story: run prediction from an explicit list of files."""
"""User story: process an explicit list of files."""
audio_file = next(single_audio_dir.glob("*.wav"))
file_list = tmp_path / "files.txt"
@ -68,7 +68,7 @@ def test_cli_predict_file_list_runs_on_real_audio(
result = CliRunner().invoke(
cli,
[
"predict",
"process",
"file_list",
str(tiny_checkpoint_path),
str(file_list),
@ -87,12 +87,12 @@ def test_cli_predict_file_list_runs_on_real_audio(
assert len(list(output_path.glob("*.json"))) == 1
def test_cli_predict_dataset_runs_on_aoef_metadata(
def test_cli_process_dataset_runs_on_aoef_metadata(
tmp_path: Path,
tiny_checkpoint_path: Path,
single_audio_dir: Path,
) -> None:
"""User story: predict from AOEF dataset metadata file."""
"""User story: process from AOEF dataset metadata file."""
audio_file = next(single_audio_dir.glob("*.wav"))
recording = data.Recording.from_file(audio_file)
@ -103,7 +103,7 @@ def test_cli_predict_dataset_runs_on_aoef_metadata(
)
annotation_set = data.AnnotationSet(
name="test",
description="predict dataset test",
description="process dataset test",
clip_annotations=[data.ClipAnnotation(clip=clip, sound_events=[])],
)
@ -115,7 +115,7 @@ def test_cli_predict_dataset_runs_on_aoef_metadata(
result = CliRunner().invoke(
cli,
[
"predict",
"process",
"dataset",
str(tiny_checkpoint_path),
str(dataset_path),
@ -142,7 +142,7 @@ def test_cli_predict_dataset_runs_on_aoef_metadata(
("soundevent", "*.json", True),
],
)
def test_cli_predict_directory_supports_output_format_override(
def test_cli_process_directory_supports_output_format_override(
tmp_path: Path,
tiny_checkpoint_path: Path,
single_audio_dir: Path,
@ -157,7 +157,7 @@ def test_cli_predict_directory_supports_output_format_override(
result = CliRunner().invoke(
cli,
[
"predict",
"process",
"directory",
str(tiny_checkpoint_path),
str(single_audio_dir),
@ -180,12 +180,12 @@ def test_cli_predict_directory_supports_output_format_override(
assert len(list(output_path.glob(expected_pattern))) >= 1
def test_cli_predict_dataset_deduplicates_recordings(
def test_cli_process_dataset_deduplicates_recordings(
tmp_path: Path,
tiny_checkpoint_path: Path,
single_audio_dir: Path,
) -> None:
"""User story: duplicated recording entries are predicted once."""
"""User story: duplicated recording entries are processed once."""
audio_file = next(single_audio_dir.glob("*.wav"))
recording = data.Recording.from_file(audio_file)
@ -215,7 +215,7 @@ def test_cli_predict_dataset_deduplicates_recordings(
result = CliRunner().invoke(
cli,
[
"predict",
"process",
"dataset",
str(tiny_checkpoint_path),
str(dataset_path),
@ -234,7 +234,7 @@ def test_cli_predict_dataset_deduplicates_recordings(
assert len(list(output_path.glob("*.nc"))) == 1
def test_cli_predict_rejects_unknown_output_format(
def test_cli_process_rejects_unknown_output_format(
tmp_path: Path,
tiny_checkpoint_path: Path,
single_audio_dir: Path,
@ -245,7 +245,7 @@ def test_cli_predict_rejects_unknown_output_format(
result = CliRunner().invoke(
cli,
[
"predict",
"process",
"directory",
str(tiny_checkpoint_path),
str(single_audio_dir),