diff --git a/README.md b/README.md index b49d9ed..024a523 100644 --- a/README.md +++ b/README.md @@ -1,62 +1,122 @@ # 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. +## Getting started + +### Python Environment + +We recommend using an isolated Python environment to avoid dependency issues. Choose one +of the following options: + +* 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.8,< 3.11) and prefer using virtual environments then: + +```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 unziped, run this from extracted folder. + +```bash +pip install . +``` + +Make sure you have the environment activated before installing `batdetect2`. + +## Try the model +1) You can try a demo of the model (for UK species) on [huggingface](https://huggingface.co/spaces/macaodha/batdetect2). + +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. -### Getting started -1) Install the Anaconda Python 3.10 distribution for your operating system from [here](https://www.continuum.io/downloads). -2) Download this code from the repository (by clicking on the green button on top right) and unzip it. -3) Create a new environment and install the required packages: -`conda create -y --name batdetect2 python==3.10` -`conda activate batdetect2` -`conda install --file requirements.txt` +## Running the model on your own data -### Try the model -1) You can try a demo of the model (for UK species) on [huggingface](https://huggingface.co/spaces/macaodha/batdetect2). +After following the above steps to install the code you can run the model on your own data. -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. +### Using the command line + +You can run the model by opening the command line and typing: +```bash +batdetect2 detect AUDIO_DIR ANN_DIR DETECTION_THRESHOLD +``` +e.g. +```bash +batdetect2 detect example_data/audio/ example_data/anns/ 0.3 +``` + +`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. + +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: +`python run_batdetect.py 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. +`python run_batdetect.py example_data/audio/ example_data/anns/ 0.3 --model_path models/Net2DFast_UK_same.pth.tar` -### Running the model on your own data -After following the above steps to install the code you can run the model on your own data by opening the command line where the code is located and typing: -`python run_batdetect.py AUDIO_DIR ANN_DIR DETECTION_THRESHOLD` -e.g. -`python run_batdetect.py example_data/audio/ example_data/anns/ 0.3` +### Using the Python API + +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) + +# Load audio and compute spectrograms +audio = api.load_audio(AUDIO_FILE) +spec = api.generate_spectrogram(audio) + +# Process the audio or the spectrogram with the model +detections, features, spec = api.process_audio(audio) +detections, features = api.process_spectrogram(spec) + +# You can integrate the detections or the extracted features +# to your custom analysis pipeline +# ... +``` + +## Training the model on your own data +Take a look at the steps outlined in fintuning readme [here](bat_detect/finetune/readme.md) for a description of how to train your own model. -`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. - -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: -`python run_batdetect.py 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. -`python run_batdetect.py example_data/audio/ example_data/anns/ 0.3 --model_path models/Net2DFast_UK_same.pth.tar` +## 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). -### Training the model on your own data -Take a look at the steps outlined in fintuning readme [here](bat_detect/finetune/readme.md) for a description of how to train your own model. - - -### 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). - - -### Warning +## 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. -### FAQ -For more information please consult our [FAQ](faq.md). +## FAQ +For more information please consult our [FAQ](faq.md). -### Reference +## Reference 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, @@ -67,8 +127,8 @@ If you find our work useful in your research please consider citing our paper wh } ``` -### Acknowledgements -Thanks to all the contributors who spent time collecting and annotating audio data. +## Acknowledgements +Thanks to all the contributors who spent time collecting and annotating audio data. ### TODOs