Package: batdetect2
BatDetect2Code for detecting and classifying bat echolocation calls in high frequency audio recordings.Getting startedPython EnvironmentWe 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 fromhere. Create a new environment and activate it:condacreate-y--namebatdetect2python==3.10
condaactivatebatdetect2If you already have Python installed (version >= 3.8,< 3.11) and prefer using virtual environments then:python-mvenv.venvsource.venv/bin/activateInstalling BatDetect2You can use pip to installbatdetect2:pipinstallbatdetect2Alternatively, 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.pipinstall.Make sure you have the environment activated before installingbatdetect2.Try the modelYou can try a demo of the model (for UK species) onhuggingface.Alternatively, clickhereto run the model using Google Colab. You can also run this notebook locally.Running the model on your own dataAfter following the above steps to install the code you can run the model on your own data.Using the command lineYou can run the model by opening the command line and typing:batdetect2detectAUDIO_DIRANN_DIRDETECTION_THRESHOLDe.g.batdetect2detectexample_data/audio/example_data/anns/0.3AUDIO_DIRis the path on your computer to the audio wav files of interest.ANN_DIRis the path on your computer where the model predictions will be saved. The model will output both.csvand.jsonresults for each audio file.DETECTION_THRESHOLDis 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.csvfiles:batdetect2 detect example_data/audio/ example_data/anns/ 0.3 --spec_featuresYou can also specify which model to use by setting the--model_pathargument. 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.tarUsing the Python APIIf you prefer to process your data within a Python script then you can use thebatdetect2Python API.frombatdetect2importapiAUDIO_FILE="example_data/audio/20170701_213954-MYOMYS-LR_0_0.5.wav"# Process a whole fileresults=api.process_file(AUDIO_FILE)# Or, load audio and compute spectrogramsaudio=api.load_audio(AUDIO_FILE)spec=api.generate_spectrogram(audio)# And process the audio or the spectrogram with the modeldetections,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 analysis pipeline.Training the model on your own dataTake a look at the steps outlined in finetuning readmeherefor a description of how to train your own model.Data and annotationsThe 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 availablehere.WarningThe 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.FAQFor more information please consult ourFAQ.ReferenceIf you find our work useful in your research please consider citing our paper which you can findhere:@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  Barataudm, 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}
}AcknowledgementsThanks to all the contributors who spent time collecting and annotating audio data.TODOsRelease the code and pretrained modelRelease the datasets and annotations used the experiments in the paperAdd the scripts used to generate the tables and figures from the paper