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: polish docs entry points and metadata

Browse Source
This commit is contained in:
mbsantiago 2026-05-06 20:58:55 +01:00
parent df9f21b594
commit fbb48c4d87
3 changed files with 66 additions and 108 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

114
docs/source/getting_started.md
View File

@ -1,52 +1,38 @@
# Getting started
If you want to run BatDetect2 on your recordings, start with the command-line
route below.
BatDetect2 can be used in two ways: through the `batdetect2` command line interface (CLI), or as the `batdetect2` Python package.
The CLI route does not require coding.
You run commands in the terminal and, in some cases, write configuration files.
The Python route gives you more flexibility and lets you integrate the model into your own workflows or experiments.
For most common use cases, both routes give you the same results.
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 `process` CLI and `BatDetect2API` workflow.
```
## Try it out
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)
## The simplest route for most users
## Installation
1. Install BatDetect2.
2. Use a model checkpoint.
3. Run the first tutorial on a folder of recordings.
To use `batdetect2` on your machine, you need to install it first.
We recommend using `uv` for that.
`uv` is a tool that helps manage Python software cleanly, without mixing it into the rest of your machine.
Install `uv` first by following the [installation instructions](https://docs.astral.sh/uv/getting-started/installation/).
If that is what you want, you can ignore the Python sections for now.
### One-off usage
## Install BatDetect2
If you are not ready to install `batdetect2` permanently, you can try it with:
We recommend `uv` for both workflows.
```bash
uvx batdetect2
```
`uv` is a tool that helps install Python software cleanly, without mixing it
into the rest of your machine.
This still downloads the code and dependencies and runs them on your machine, but the environment is temporary.
- Use `uv tool` to install the CLI.
- Use `uv add` to add `batdetect2` as a dependency in a Python project.
### Install the CLI
Install `uv` first by following their
[installation instructions](https://docs.astral.sh/uv/getting-started/installation/).
## Install the CLI
The following installs `batdetect2` in its own small environment and makes the
`batdetect2` command available on your machine.
If you want the `batdetect2` CLI to always be available in your terminal, run:
```bash
uv tool install batdetect2
@ -61,65 +47,45 @@ uv tool upgrade batdetect2
Verify the CLI is available:
```bash
batdetect2 --help
batdetect2
```
Run your first workflow:
You can then run your first workflow.
See {doc}`tutorials/run-inference-on-folder` for more details.
Go to {doc}`tutorials/run-inference-on-folder` for a complete first run.
### Add it to your Python project
## Choose a model checkpoint
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:
If you are using BatDetect2 from Python code and already manage your projects with `uv`, you can add it with:
```bash
uv add batdetect2
```
This keeps your project settings and installed packages in sync.
If you want to upgrade it later:
### Alternative with `pip`
```bash
uv add -U batdetect2
```
If you prefer `pip`, create and activate a virtual environment first:
#### Alternative with `pip`
If you prefer `pip`, you can use:
```bash
pip install batdetect2
```
It is a good idea to create a separate virtual environment first so this does not interfere with other Python environments.
```bash
python -m venv .venv
source .venv/bin/activate
```
Then install from PyPI:
```bash
pip install batdetect2
```
## What's next
- Run your first workflow on a folder of recordings:
{doc}`tutorials/run-inference-on-folder`
- If you write code and want the Python route:
{doc}`tutorials/integrate-with-a-python-pipeline`
- Run your first workflow on a folder of recordings: {doc}`tutorials/run-inference-on-folder`
- 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`
- To understand the model and its outputs, go to {doc}`explanation/index`

58
docs/source/index.md
View File

@ -4,50 +4,42 @@ Welcome to the BatDetect2 documentation.
## What is BatDetect2?
`batdetect2` detects bat echolocation calls in audio recordings.
`batdetect2` is a deep learning model and software package for detecting and
classifying bat echolocation calls in high-frequency 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.
You can use it from the command line or from Python, depending on how much
control you need.
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 scans a recording, finds sounds that look like bat
calls, and returns one result for each detected call.
Each result can include where the call appears in the recording, shown as a box
with start and end time and the lowest and highest frequency, how confident the
model is that it found a call, and how strongly it matches the available
classes.
The current default model is trained for 17 UK species.
The built-in default model is trained for 17 UK species.
The package also supports custom training, fine-tuning, evaluation, and more
advanced workflows 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:
For more detail 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`
- 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.
```
## What can I do with it?
- I want to run the model on my recordings:
{doc}`tutorials/run-inference-on-folder`
- I write code and want to use it from 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`
```{note}
Looking for the previous BatDetect2 workflow?
See {doc}`legacy/index`.

2
pyproject.toml
View File

@ -37,10 +37,10 @@ classifiers = [
"Intended Audience :: Science/Research",
"Natural Language :: English",
"Operating System :: OS Independent",
"Programming Language :: Python :: 3.9",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
"Programming Language :: Python :: 3.13",
"Topic :: Scientific/Engineering :: Artificial Intelligence",
"Topic :: Software Development :: Libraries :: Python Modules",
"Topic :: Multimedia :: Sound/Audio :: Analysis",