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 README overview and links

Browse Source
This commit is contained in:
mbsantiago 2026-05-06 16:50:45 +01:00
parent 855a79853b
commit 69d8e2d228
1 changed files with 78 additions and 188 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

266
README.md
View File

@ -1,247 +1,137 @@
# BatDetect2 # BatDetect2
<img style="display:
block-inline;" width="64" height="64" src="assets/bat_icon.png">Code for <img style="display:block-inline;" width="64" height="64" src="assets/bat_icon.png">
detecting and
classifying bat Code for detecting and classifying bat echolocation calls in high-frequency
echolocation audio recordings.
calls in high
frequency audio
recordings.
> [!WARNING] > [!WARNING]
> BatDetect2 2.0.1 is out. > `batdetect2` 2.0.1 is out.
> There are many changes and new recommended workflows. > There are many changes and new recommended workflows.
> We have left the previous `batdetect2.api` module intact, but if you run > We have left the previous `batdetect2.api` module intact, but if you run
> into issues or want to upgrade, see the migration guide in the docs site. > into issues or want to upgrade, see the
> [migration guide](docs/source/legacy/migration-guide.md) in the docs site.
> >
> This update also ships with a refreshed default model. > This update also ships with a refreshed default model.
> It was trained in the same way and on the same data as before, but you > It was trained in the same way and on the same data as before, but you should still expect small output differences in some cases.
> should still expect small output differences in some cases.
## What BatDetect2 is useful for ## What is BatDetect2
BatDetect2 can help you screen recordings for bat calls, find recordings that BatDetect2 is a deep learning model for detecting and classifying bat
need expert review, and compare model outputs across sites or projects with echolocation calls.
appropriate caution. The model generates multiple predictions for each input recording by providing a
bounding box and predicted class for each individual call within it.
It is best used as a tool to support ecological work, not as a replacement for This repository also holds `batdetect2`, a Python-based tool to run, train,
validation or expert interpretation. finetune and evaluate BatDetect2-type models, including the built-in model for
detecting UK bat species.
You can use the tool from the command line (terminal) or from Python as needed.
## Start here ## Getting Started
If you want the simplest current workflow, use the documentation site and start We have [extensive documentation](docs/source/index.md) on how to use
with: `batdetect2`.
See our [getting started](docs/source/getting_started.md) guide and then jump
into any of our tutorials:
- getting started: - Run the model on a folder of recordings:
`docs/source/getting_started.md`
- first tutorial:
`docs/source/tutorials/run-inference-on-folder.md` `docs/source/tutorials/run-inference-on-folder.md`
- Train your own model:
`docs/source/tutorials/train-a-custom-model.md`
- Evaluate your model:
`docs/source/tutorials/evaluate-on-a-test-set.md`
- Fine-tune a model:
`docs/source/tutorials/integrate-with-a-python-pipeline.md`
If you need the previous workflow based on `batdetect2 detect` or ### Try the model
`batdetect2.api`, use the legacy docs section and migration guide in the docs
site.
## Install BatDetect2 If you want to try the model for UK bat species without installing anything, you
can try the following:
If you already use Python, activate the environment where you want BatDetect2 to 1. Demo of the model (for UK species) on
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:
```bash
conda create -y --name batdetect2 python==3.10
conda activate batdetect2
```
* If you already have Python installed (version >= 3.10,< 3.14), you can create
a fresh environment with:
```bash
python -m venv .venv
source .venv/bin/activate
```
### Installing BatDetect2
You can use pip to install `batdetect2`:
```bash
pip install batdetect2
```
Alternatively, download this code from the repository (by clicking on the green
button on top right) and unzip it.
Once unzipped, run this from extracted folder.
```bash
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 process 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). [huggingface](https://huggingface.co/spaces/macaodha/batdetect2).
2) Alternatively, click 2. Alternatively, click
[here](https://colab.research.google.com/github/macaodha/batdetect2/blob/master/batdetect2_notebook.ipynb) [here](https://colab.research.google.com/github/macaodha/batdetect2/blob/master/batdetect2_notebook.ipynb)
to run the model using Google Colab. to run the model using Google Colab.
You can also run this notebook locally. You can also run this notebook locally.
### Installing BatDetect2
## Running the model on your own data If you have `uv` installed (if not, we recommend it; follow the instructions
[here](https://docs.astral.sh/uv/getting-started/installation/)), then you can
run `batdetect2` one-off with
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 process`.
You can run the model by opening the command line and typing:
```bash ```bash
batdetect2 detect AUDIO_DIR ANN_DIR DETECTION_THRESHOLD uvx batdetect2
``` ```
e.g.
or if you want to install it permanently:
```bash ```bash
batdetect2 detect example_data/audio/ example_data/anns/ 0.3 uv tool install batdetect2
``` ```
`AUDIO_DIR` is the path on your computer to the audio wav files of interest. and test it with
`ANN_DIR` is the path on your computer where the model predictions will be
saved.
The model will output both `.csv` and `.json` results for each audio file.
`DETECTION_THRESHOLD` is a number between 0 and 1 specifying the cut-off
threshold applied to the calls.
A smaller number will result in more calls detected, but with the chance of
introducing more mistakes.
There are also optional arguments, e.g. you can request that the model outputs ```bash
features (i.e. estimated call parameters) such as duration, max_frequency, etc. batdetect2
by setting the flag `--spec_features`.
These will be saved as `*_spec_features.csv` files:
`batdetect2 detect example_data/audio/ example_data/anns/ 0.3 --spec_features`
You can also specify which model to use by setting the `--model_path` argument.
If not specified, it will default to using a model trained on UK data e.g.
`batdetect2 detect example_data/audio/ example_data/anns/ 0.3 --model_path
models/Net2DFast_UK_same.pth.tar`
### 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
from batdetect2 import api
AUDIO_FILE = "example_data/audio/20170701_213954-MYOMYS-LR_0_0.5.wav"
# Process a whole file
results = api.process_file(AUDIO_FILE)
# Or, load audio and compute spectrograms
audio = api.load_audio(AUDIO_FILE)
spec = api.generate_spectrogram(audio)
# And process the audio or the spectrogram with the model
detections, features, spec = api.process_audio(audio)
detections, features = api.process_spectrogram(spec)
# Do something else ...
``` ```
You can integrate the detections or the extracted features to your custom ### Run BatDetect2 on a folder of recordings
analysis pipeline.
Once installed, you can run BatDetect2 on a folder of `.wav` files.
By default it will use the model trained on UK data.
## Training the model on your own data Example command:
Take a look at the training tutorial in the docs site first.
If you are working from this repository checkout, start with ```bash
`docs/source/tutorials/train-a-custom-model.md`. batdetect2 process directory example_data/audio outputs
```
This will scan the audio files in `example_data/audio` and save model outputs to
`outputs`.
If you have your own model checkpoint, you can use it:
```bash
batdetect2 process directory --model path/to/checkpoint.ckpt example_data/audio outputs
```
For the full walkthrough, use
`docs/source/tutorials/run-inference-on-folder.md`.
## Data and annotations ## Data and annotations
The raw audio data and annotations used to train the models in the paper will be The raw audio data and annotations used to train the models in the paper will be
added soon. added soon.
The audio interface used to annotate audio data for training and evaluation is `batdetect2` supports annotations in various formats and is compatible with the
available [here](https://github.com/macaodha/batdetect2_GUI). outputs of [`whombat`](https://github.com/mbsantiago/whombat/) and this
[earlier version](https://github.com/macaodha/batdetect2_GUI).
If you're interested in supporting another format, please reach out or submit a
PR.
## Warning ## Warning
The models developed and shared as part of this repository should be used with The models developed and shared as part of this repository should be used with
caution. caution.
While they have been evaluated on held out audio data, great care should be While they have been evaluated on held-out audio data, great care should be
taken when using the model outputs for any form of biodiversity assessment. taken when using the model outputs for any form of biodiversity assessment.
Your data may differ, and as a result it is very strongly recommended that you Your data may differ, and as a result it is very strongly recommended that you
validate the model first using data with known species to ensure that the validate the model first using data with known species to ensure that the
outputs can be trusted. outputs can be trusted.
If you train a model, make the best effort to be transparent about its training
and evaluation data, and inform downstream users about its limitations.
## FAQ ## FAQ
For more information please consult our [FAQ](docs/source/faq.md). For more information please consult our [FAQ](docs/source/faq.md).
## Reference ## Reference
If you find our work useful in your research please consider citing our paper
If you find our work useful in your research, please consider citing our paper,
which you can find which you can find
[here](https://www.biorxiv.org/content/10.1101/2022.12.14.520490v1): [here](https://www.biorxiv.org/content/10.1101/2022.12.14.520490v1):
``` ```
@article{batdetect2_2022, @article{batdetect2_2022,
title = {Towards a General Approach for Bat Echolocation Detection and Classification}, title = {Towards a General Approach for Bat Echolocation Detection and Classification},