diff --git a/README.md b/README.md index d421875..6035eb7 100644 --- a/README.md +++ b/README.md @@ -1,247 +1,137 @@ # BatDetect2 -Code for - detecting and - classifying bat - echolocation - calls in high - frequency audio - recordings. + + + +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},