BatDetect2

Code for detecting and classifying bat echolocation calls in high-frequency
audio recordings.

[!WARNING]
batdetect2 2.0.0b1 is out.
This is a beta release and we are gathering user feedback.
If you run into issues or have feedback on the new workflows, please use the
GitHub issues page to let us know.

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.

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.

What is BatDetect2

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.

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.

Getting Started

We have extensive documentation on how to use
batdetect2.

The docs site is still being built and will be live soon.
If you want a quick peek for now, see the docs/ folder in this repository.

See our getting started guide and then jump
into any of our tutorials:

• 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

Try the model

If you want to try the model for UK bat species without installing anything, you
can try the following:

1. Demo of the model (for UK species) on
   huggingface.

2. Alternatively, click
   here
   to run the model using Google Colab.
   You can also run this notebook locally.

Installing BatDetect2

[!NOTE]
2.0.0b1 is a pre-release on PyPI.
You may need to request it explicitly by version, for example:

uvx --from batdetect2==2.0.0b1 batdetect2
uv tool install batdetect2==2.0.0b1
pip install batdetect2==2.0.0b1

If you have uv installed (if not, we recommend it; follow the instructions
here), then you can
run batdetect2 one-off with

uvx batdetect2

or if you want to install it permanently:

uv tool install batdetect2

and test it with

batdetect2

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.

Example command:

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:

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.
batdetect2 supports annotations in various formats and is compatible with the
outputs of whombat and this
earlier version.
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
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.

Reference

If you find our work useful in your research, please consider citing our paper,
which you can find
here:

@article{batdetect2_2022,
    title     = {Towards a General Approach for Bat Echolocation Detection and Classification},
    author    = {Mac Aodha, Oisin and  Mart\'{i}nez Balvanera, Santiago and  Damstra, Elise and  Cooke, Martyn and  Eichinski, Philip and  Browning, Ella and  Barataud, Michel and  Boughey, Katherine and  Coles, Roger and  Giacomini, Giada and MacSwiney G., M. Cristina and  K. Obrist, Martin and Parsons, Stuart and  Sattler, Thomas and  Jones, Kate E.},
    journal   = {bioRxiv},
    year      = {2022}
}

Acknowledgements

Thanks to all the contributors who spent time collecting and annotating audio
data.