mirror of
https://github.com/macaodha/batdetect2.git
synced 2026-05-22 22:32:18 +02:00
docs: align docs entry points with current workflows
This commit is contained in:
mbsantiago
parent
da113eaea8
commit
9635a858bd
91
README.md
91
README.md
@ -1,11 +1,40 @@
|
||||
# BatDetect2
|
||||
<img style="display: block-inline;" width="64" height="64" src="assets/bat_icon.png"> Code for detecting and classifying bat echolocation calls in high frequency audio recordings.
|
||||
|
||||
## Getting started
|
||||
### Python Environment
|
||||
## What BatDetect2 is useful for
|
||||
|
||||
We recommend using an isolated Python environment to avoid dependency issues. Choose one
|
||||
of the following options:
|
||||
BatDetect2 can help you screen recordings for bat calls,
|
||||
find recordings that need expert review,
|
||||
and compare model outputs across sites or projects with appropriate caution.
|
||||
|
||||
It is best used as a tool to support ecological work,
|
||||
not as a replacement for validation or expert interpretation.
|
||||
|
||||
## Start here
|
||||
|
||||
If you want the simplest current workflow,
|
||||
use the documentation site and start with:
|
||||
|
||||
- getting started: `docs/source/getting_started.md`
|
||||
- first tutorial: `docs/source/tutorials/run-inference-on-folder.md`
|
||||
|
||||
The current docs default to:
|
||||
|
||||
- the current command-line workflow: `batdetect2 predict`
|
||||
- the current Python workflow: `batdetect2.api_v2.BatDetect2API`
|
||||
|
||||
If you need the previous workflow based on `batdetect2 detect` or `batdetect2.api`,
|
||||
use the legacy docs section and migration guide in the docs site.
|
||||
|
||||
## Install BatDetect2
|
||||
|
||||
If you already use Python,
|
||||
activate the environment where you want BatDetect2 to live.
|
||||
|
||||
If not,
|
||||
create a fresh one first so BatDetect2 stays separate from other software on your machine.
|
||||
|
||||
Two common options are:
|
||||
|
||||
* Install the Anaconda Python 3.10 distribution for your operating system from [here](https://www.continuum.io/downloads). Create a new environment and activate it:
|
||||
|
||||
@ -14,7 +43,7 @@ conda create -y --name batdetect2 python==3.10
|
||||
conda activate batdetect2
|
||||
```
|
||||
|
||||
* If you already have Python installed (version >= 3.8,< 3.11) and prefer using virtual environments then:
|
||||
* If you already have Python installed (version >= 3.10,< 3.14), you can create a fresh environment with:
|
||||
|
||||
```bash
|
||||
python -m venv .venv
|
||||
@ -37,6 +66,43 @@ pip install .
|
||||
|
||||
Make sure you have the environment activated before installing `batdetect2`.
|
||||
|
||||
## Run BatDetect2 on a folder of recordings
|
||||
|
||||
Once installed,
|
||||
the simplest current workflow is to run BatDetect2 on a folder of `.wav` files.
|
||||
|
||||
If you are working from this repository checkout,
|
||||
you can use this example checkpoint path:
|
||||
|
||||
```text
|
||||
src/batdetect2/models/checkpoints/Net2DFast_UK_same.pth.tar
|
||||
```
|
||||
|
||||
Example command:
|
||||
|
||||
```bash
|
||||
batdetect2 predict directory \
|
||||
src/batdetect2/models/checkpoints/Net2DFast_UK_same.pth.tar \
|
||||
example_data/audio \
|
||||
outputs
|
||||
```
|
||||
|
||||
This will scan the audio files in `example_data/audio`
|
||||
and save model outputs to `outputs`.
|
||||
|
||||
For the full beginner walkthrough,
|
||||
use `docs/source/tutorials/run-inference-on-folder.md`.
|
||||
|
||||
## Legacy workflow
|
||||
|
||||
The sections below are kept only for people maintaining older BatDetect2 scripts and analysis pipelines.
|
||||
|
||||
If you are new to BatDetect2,
|
||||
stop here and use the current docs and command above.
|
||||
|
||||
If you really do need the older workflow,
|
||||
the reference material is below.
|
||||
|
||||
|
||||
## Try the model
|
||||
1) You can try a demo of the model (for UK species) on [huggingface](https://huggingface.co/spaces/macaodha/batdetect2).
|
||||
@ -48,9 +114,15 @@ Make sure you have the environment activated before installing `batdetect2`.
|
||||
|
||||
After following the above steps to install the code you can run the model on your own data.
|
||||
|
||||
The remainder of this section is legacy reference material.
|
||||
|
||||
|
||||
### Using the command line
|
||||
|
||||
The commands below describe the legacy CLI workflow.
|
||||
|
||||
For new work, prefer the current docs and `batdetect2 predict`.
|
||||
|
||||
You can run the model by opening the command line and typing:
|
||||
```bash
|
||||
batdetect2 detect AUDIO_DIR ANN_DIR DETECTION_THRESHOLD
|
||||
@ -73,6 +145,10 @@ You can also specify which model to use by setting the `--model_path` argument.
|
||||
|
||||
### Using the Python API
|
||||
|
||||
The examples below describe the legacy Python API.
|
||||
|
||||
For new work, prefer `batdetect2.api_v2.BatDetect2API` and the current docs site.
|
||||
|
||||
If you prefer to process your data within a Python script then you can use the `batdetect2` Python API.
|
||||
|
||||
```python
|
||||
@ -98,7 +174,10 @@ You can integrate the detections or the extracted features to your custom analys
|
||||
|
||||
|
||||
## Training the model on your own data
|
||||
Take a look at the steps outlined in finetuning readme [here](batdetect2/finetune/readme.md) for a description of how to train your own model.
|
||||
Take a look at the training tutorial in the docs site first.
|
||||
|
||||
If you are working from this repository checkout,
|
||||
start with `docs/source/tutorials/train-a-custom-model.md`.
|
||||
|
||||
|
||||
## Data and annotations
|
||||
|
||||
@ -1,14 +1,19 @@
|
||||
# Explanation
|
||||
# Understanding
|
||||
|
||||
Explanation pages describe why BatDetect2 behaves as it does and how to reason
|
||||
about trade-offs.
|
||||
Understanding pages explain how BatDetect2 works, what its outputs mean, and how to reason about trade-offs.
|
||||
|
||||
Use this section when you want help interpreting the tool, not just running it.
|
||||
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
|
||||
what-batdetect2-predicts
|
||||
interpreting-formatted-outputs
|
||||
extracted-features-and-embeddings
|
||||
model-output-and-validation
|
||||
postprocessing-and-thresholds
|
||||
pipeline-overview
|
||||
preprocessing-consistency
|
||||
target-encoding-and-decoding
|
||||
evaluation-concepts-and-matching
|
||||
```
|
||||
|
||||
@ -1,22 +1,41 @@
|
||||
# Getting started
|
||||
|
||||
BatDetect2 is both a command line tool (CLI) and a Python library.
|
||||
If you want to run BatDetect2 on your recordings,
|
||||
start with the command-line route below.
|
||||
|
||||
- Use the CLI if you want to run existing models or train your own models from
|
||||
the terminal.
|
||||
- Use the Python package if you want to integrate BatDetect2 into your own
|
||||
scripts, notebooks, or analysis pipeline.
|
||||
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.
|
||||
|
||||
- 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.
|
||||
```
|
||||
|
||||
If you want to try BatDetect2 before installing anything locally:
|
||||
|
||||
- [Hugging Face demo (UK species)](https://huggingface.co/spaces/macaodha/batdetect2)
|
||||
- [Google Colab notebook](https://colab.research.google.com/github/macaodha/batdetect2/blob/master/batdetect2_notebook.ipynb)
|
||||
|
||||
## Prerequisites
|
||||
## The simplest route for most users
|
||||
|
||||
1. Install BatDetect2.
|
||||
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.
|
||||
|
||||
## Install BatDetect2
|
||||
|
||||
We recommend `uv` for both workflows.
|
||||
`uv` is a fast Python package and environment manager that keeps installs
|
||||
isolated and reproducible.
|
||||
|
||||
`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.
|
||||
@ -26,8 +45,8 @@ Install `uv` first by following their
|
||||
|
||||
## Install the CLI
|
||||
|
||||
The following installs `batdetect2` in an isolated tool environment and exposes
|
||||
the `batdetect2` command on your machine.
|
||||
The following installs `batdetect2` in its own small environment and makes the
|
||||
`batdetect2` command available on your machine.
|
||||
|
||||
```bash
|
||||
uv tool install batdetect2
|
||||
@ -49,16 +68,34 @@ Run your first workflow:
|
||||
|
||||
Go to {doc}`tutorials/run-inference-on-folder` for a complete first run.
|
||||
|
||||
## Integrate with your Python project
|
||||
## Choose a model checkpoint
|
||||
|
||||
If you are using BatDetect2 from Python code, add it to your project
|
||||
dependencies:
|
||||
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.
|
||||
|
||||
You can use:
|
||||
|
||||
- a checkpoint you trained yourself, or
|
||||
- a checkpoint distributed with your installation or repository checkout.
|
||||
|
||||
In this repository checkout, an example pretrained checkpoint is available at:
|
||||
|
||||
```text
|
||||
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.
|
||||
|
||||
## Python route for users writing code
|
||||
|
||||
If you are using BatDetect2 from Python code, add it to your Python project:
|
||||
|
||||
```bash
|
||||
uv add batdetect2
|
||||
```
|
||||
|
||||
This keeps dependency metadata and the environment in sync.
|
||||
This keeps your project settings and installed packages in sync.
|
||||
|
||||
### Alternative with `pip`
|
||||
|
||||
@ -77,7 +114,10 @@ pip install batdetect2
|
||||
|
||||
## What's next
|
||||
|
||||
- Run your first detection workflow:
|
||||
- Run your first workflow on a folder of recordings:
|
||||
{doc}`tutorials/run-inference-on-folder`
|
||||
- For practical task recipes, go to {doc}`how_to/index`
|
||||
- For command and option details, go to {doc}`reference/cli/index`
|
||||
- If you write code and want the Python route:
|
||||
{doc}`tutorials/integrate-with-a-python-pipeline`
|
||||
- For common practical tasks, go to {doc}`how_to/index`
|
||||
- For detailed command help, go to {doc}`reference/cli/index`
|
||||
- To understand outputs and trade-offs, go to {doc}`explanation/index`
|
||||
|
||||
@ -1,12 +1,22 @@
|
||||
# How-to Guides
|
||||
|
||||
How-to guides help you complete specific tasks while working.
|
||||
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.
|
||||
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
|
||||
choose-an-inference-input-mode
|
||||
run-batch-predictions
|
||||
tune-inference-clipping
|
||||
tune-detection-threshold
|
||||
inspect-class-scores-in-python
|
||||
inspect-detection-features-in-python
|
||||
save-predictions-in-different-output-formats
|
||||
fine-tune-from-a-checkpoint
|
||||
choose-and-configure-evaluation-tasks
|
||||
interpret-evaluation-outputs
|
||||
configure-aoef-dataset
|
||||
import-legacy-batdetect2-annotations
|
||||
configure-audio-preprocessing
|
||||
|
||||
@ -1,63 +1,87 @@
|
||||
# Home
|
||||
|
||||
Welcome to the batdetect2 docs.
|
||||
Welcome to the BatDetect2 documentation.
|
||||
|
||||
## What is batdetect2?
|
||||
## What is BatDetect2?
|
||||
|
||||
`batdetect2` is a bat echolocation detection model.
|
||||
It detects each individual echolocation call in an input spectrogram, draws a
|
||||
box around each call event, and predicts the most likely species for that call.
|
||||
A recording can contain many calls from different species.
|
||||
`batdetect2` detects bat echolocation calls in audio recordings.
|
||||
|
||||
The current default model is trained for 17 UK species but you can also train
|
||||
new models from your own annotated data.
|
||||
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.
|
||||
|
||||
For details on the approach please read our pre-print:
|
||||
[Towards a General Approach for Bat Echolocation Detection and Classification](https://www.biorxiv.org/content/10.1101/2022.12.14.520490v1)
|
||||
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.
|
||||
|
||||
## What you can do
|
||||
The current default model is trained for 17 UK species.
|
||||
|
||||
- Run inference on your recordings and export predictions for downstream
|
||||
analysis:
|
||||
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)
|
||||
|
||||
## A good first use for BatDetect2
|
||||
|
||||
BatDetect2 is a good fit when you want to:
|
||||
|
||||
- scan many recordings for likely bat activity,
|
||||
- prioritize files for expert review,
|
||||
- compare outputs across projects with appropriate caution,
|
||||
- build reviewed local datasets for later model improvement.
|
||||
|
||||
It is not a substitute for validation.
|
||||
|
||||
## Main user journeys
|
||||
|
||||
- I want to run the model on my recordings:
|
||||
{doc}`tutorials/run-inference-on-folder`
|
||||
- Train a custom model on your own annotated data:
|
||||
{doc}`tutorials/train-a-custom-model`
|
||||
- Evaluate model performance on a held-out test set:
|
||||
{doc}`tutorials/evaluate-on-a-test-set`
|
||||
- Integrate batdetect2 into Python scripts and notebooks:
|
||||
- I write code and want to use Python:
|
||||
{doc}`tutorials/integrate-with-a-python-pipeline`
|
||||
- I want to train or fine-tune a custom model:
|
||||
{doc}`tutorials/train-a-custom-model`
|
||||
- I want to evaluate a trained model on held-out data:
|
||||
{doc}`tutorials/evaluate-on-a-test-set`
|
||||
|
||||
```{warning}
|
||||
Treat outputs as model predictions, not ground truth.
|
||||
Always validate on reviewed local data before using results for ecological
|
||||
inference.
|
||||
Always validate on reviewed local data before using results for ecological inference.
|
||||
```
|
||||
|
||||
## Where to start
|
||||
```{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`.
|
||||
```
|
||||
|
||||
If you are new, start with {doc}`getting_started`.
|
||||
## How to use this site
|
||||
|
||||
For a low-code path, go to {doc}`tutorials/index`.
|
||||
If you are Python-savvy and want more control, go to {doc}`how_to/index` and
|
||||
{doc}`reference/index`.
|
||||
Start with {doc}`getting_started` if you are new.
|
||||
|
||||
Each section has a different purpose:
|
||||
some pages teach by example, some focus on practical tasks, some are lookup
|
||||
material, and some explain trade-offs.
|
||||
Then choose the section that matches what you need.
|
||||
|
||||
| Section | Best for | Start here |
|
||||
| ------------- | ------------------------------------------- | ------------------------ |
|
||||
| Tutorials | Learning by doing | {doc}`tutorials/index` |
|
||||
| How-to guides | Solving practical tasks | {doc}`how_to/index` |
|
||||
| Reference | Looking up commands, configs, and APIs | {doc}`reference/index` |
|
||||
| Explanation | Understanding design choices and trade-offs | {doc}`explanation/index` |
|
||||
If you are here mainly to run the model on recordings,
|
||||
start with Tutorials.
|
||||
|
||||
| Section | Best for | Start here |
|
||||
| --- | --- | --- |
|
||||
| Tutorials | Step-by-step routes for the most common tasks | {doc}`tutorials/index` |
|
||||
| How-to guides | Answers to specific practical questions | {doc}`how_to/index` |
|
||||
| Reference | Detailed command and settings help | {doc}`reference/index` |
|
||||
| Understanding | Concepts, interpretation, and trade-offs | {doc}`explanation/index` |
|
||||
| Legacy | Previous workflow and migration guidance | {doc}`legacy/index` |
|
||||
|
||||
## Get in touch
|
||||
|
||||
- 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?
|
||||
@ -65,7 +89,7 @@ material, and some explain trade-offs.
|
||||
|
||||
## Cite this work
|
||||
|
||||
If you use batdetect2 in research, please cite:
|
||||
If you use BatDetect2 in research, please cite:
|
||||
|
||||
Mac Aodha, O., Martinez Balvanera, S., Damstra, E., et al.
|
||||
(2022).
|
||||
@ -82,6 +106,7 @@ tutorials/index
|
||||
how_to/index
|
||||
reference/index
|
||||
explanation/index
|
||||
legacy/index
|
||||
```
|
||||
|
||||
```{toctree}
|
||||
|
||||
@ -1,12 +1,20 @@
|
||||
# Reference documentation
|
||||
|
||||
Reference pages provide factual, complete descriptions of commands,
|
||||
configuration, and data structures.
|
||||
Reference pages are the detailed lookup pages.
|
||||
|
||||
Use this section when you need exact command options, setting names, output details, or Python API entries.
|
||||
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
|
||||
cli/index
|
||||
api
|
||||
app-config
|
||||
inference-config
|
||||
evaluation-config
|
||||
outputs-config
|
||||
output-formats
|
||||
output-transforms
|
||||
data-sources
|
||||
preprocessing-config
|
||||
postprocess-config
|
||||
|
||||
@ -1,7 +1,12 @@
|
||||
# Tutorials
|
||||
|
||||
Tutorials are for learning by doing. They provide a single, reproducible path
|
||||
to a concrete outcome.
|
||||
Tutorials are the default learning path.
|
||||
|
||||
Each tutorial follows one recommended route from start to finish.
|
||||
|
||||
Use tutorials when you want the simplest route to a concrete outcome.
|
||||
|
||||
Use {doc}`../how_to/index` when you need to customize a workflow.
|
||||
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
|
||||
Loading…
Reference in New Issue
Block a user