mirror of
https://github.com/macaodha/batdetect2.git
synced 2026-05-22 22:32:18 +02:00
docs: polish README overview and links
This commit is contained in:
mbsantiago
parent
855a79853b
commit
69d8e2d228
266
README.md
266
README.md
@ -1,247 +1,137 @@
|
||||
# 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.
|
||||
|
||||
<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.
|
||||
|
||||
> [!WARNING]
|
||||
> BatDetect2 2.0.1 is out.
|
||||
> `batdetect2` 2.0.1 is out.
|
||||
> There are many changes and new recommended workflows.
|
||||
> 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.
|
||||
> 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.
|
||||
> 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.
|
||||
|
||||
## What BatDetect2 is useful for
|
||||
## What is BatDetect2
|
||||
|
||||
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.
|
||||
BatDetect2 is a deep learning model for detecting and classifying bat
|
||||
echolocation calls.
|
||||
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
|
||||
validation or expert interpretation.
|
||||
This repository also holds `batdetect2`, a Python-based tool to run, train,
|
||||
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
|
||||
with:
|
||||
We have [extensive documentation](docs/source/index.md) on how to use
|
||||
`batdetect2`.
|
||||
See our [getting started](docs/source/getting_started.md) guide and then jump
|
||||
into any of our tutorials:
|
||||
|
||||
- getting started:
|
||||
`docs/source/getting_started.md`
|
||||
- first tutorial:
|
||||
- Run the model on a folder of recordings:
|
||||
`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
|
||||
`batdetect2.api`, use the legacy docs section and migration guide in the docs
|
||||
site.
|
||||
### Try the model
|
||||
|
||||
## 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
|
||||
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
|
||||
1. Demo of the model (for UK species) on
|
||||
[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)
|
||||
to run the model using Google Colab.
|
||||
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
|
||||
batdetect2 detect AUDIO_DIR ANN_DIR DETECTION_THRESHOLD
|
||||
uvx batdetect2
|
||||
```
|
||||
e.g.
|
||||
|
||||
or if you want to install it permanently:
|
||||
|
||||
```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.
|
||||
`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.
|
||||
and test it with
|
||||
|
||||
There are also optional arguments, e.g. you can request that the model outputs
|
||||
features (i.e. estimated call parameters) such as duration, max_frequency, etc.
|
||||
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 ...
|
||||
```bash
|
||||
batdetect2
|
||||
```
|
||||
|
||||
You can integrate the detections or the extracted features to your custom
|
||||
analysis pipeline.
|
||||
### Run BatDetect2 on a folder of recordings
|
||||
|
||||
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
|
||||
Take a look at the training tutorial in the docs site first.
|
||||
Example command:
|
||||
|
||||
If you are working from this repository checkout, start with
|
||||
`docs/source/tutorials/train-a-custom-model.md`.
|
||||
```bash
|
||||
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
|
||||
|
||||
The raw audio data and annotations used to train the models in the paper will be
|
||||
added soon.
|
||||
The audio interface used to annotate audio data for training and evaluation is
|
||||
available [here](https://github.com/macaodha/batdetect2_GUI).
|
||||
|
||||
`batdetect2` supports annotations in various formats and is compatible with the
|
||||
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
|
||||
|
||||
The models developed and shared as part of this repository should be used with
|
||||
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.
|
||||
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
|
||||
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
|
||||
|
||||
For more information please consult our [FAQ](docs/source/faq.md).
|
||||
|
||||
|
||||
## 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
|
||||
[here](https://www.biorxiv.org/content/10.1101/2022.12.14.520490v1):
|
||||
|
||||
```
|
||||
@article{batdetect2_2022,
|
||||
title = {Towards a General Approach for Bat Echolocation Detection and Classification},
|
||||
|
||||
Loading…
Reference in New Issue
Block a user