Package: bambird
bambird packageUnsupervised classification to improve the quality of a bird song recording datasetOpen audio databases such asXeno-Cantoare widely used to build datasets to explore bird song repertoire or to train models for automatic bird sound classification by deep learning algorithms. However, such databases suffer from the fact that bird sounds are weakly labelled: a species name is attributed to each audio recording without timestamps that provide the temporal localization of the bird song of interest.
Manual annotations can solve this issue, but they are time consuming, expert-dependent, and cannot run on large datasets. Another solution consists in using a labelling function that automatically segments audio recordings before assigning a label to each segmented audio sample. Although labelling functions were introduced to expedite strong label assignment, their classification performance remains mostly unknown.
To address this issue and reduce label noise (wrong label assignment) in large bird song datasets, we introduce a data-centric novel labelling function composed of three successive steps: 1) time-frequency sound unit segmentation, 2) feature computation for each sound unit, and 3) classification of each sound unit as bird song or noise with either an unsupervised DBSCAN algorithm or the supervised BirdNET neural network.
The labelling function was optimized, validated, and tested on the songs of 44 West-Palearctic common bird species. We first showed that the segmentation of bird songs alone aggregated from 10% to 83% of label noise depending on the species. We also demonstrated that our labelling function was able to significantly reduce the initial label noise present in the dataset by up to a factor of three. Finally, we discuss different opportunities to design suitable labelling functions to build high-quality animal vocalizations with minimum expert annotation effort.Based on this work, we proposebambird, an open source Python package that provides a complete workflow to create your own labelling function to build cleaner bird song recording dataset.bambirdis mostly based onscikit-maadpackageInstallationbambird dependencies:scikit-maad >= 1.3.12librosascikit-learnkneedhdbscantqdmumap-learnbambirdis hosted on PyPI. To install, run the following command in your Python environment:$pipinstallbambirdTo install the latest version from source clone the master repository and from the top-level folder call:$gitclonehttps://github.com/ear-team/bambird.git&&cdbambird
$pipinstall-e.FunctionsThe functions available in the package are:
from config.pyload_config: Load the configuration file to set all the parameters of bambirdfrom dataset.pyquery_xc: Query metadata from Xeno-Canto website with audiofile depending on the search terms. The audio recordings metadata are grouped and stored in a dataframe.download_xc: Download the audio files from Xeno-Canto based on the input dataframe.  It will create directories for each species if neededgrab_audio_to_df: create a dataframe with all recordings in the directory.  The first column name corresponds to full path to the filename. The second column name correspond to the filename alone without the extensionchange_path:  change the path to the audio in the dataframe. This is usefull when the audio are moved from their original placefrom segmentation.pyextract_rois_core: function called by single_file_extract_rois. Define a specific process to extract Rois. In this case, the function extract the most energetic part of songs/calls.extract_rois_full_sig:f unction called by single_file_extract_rois. Define a specific process to extract Rois. In this case, the function extract the full songs/calls.single_file_extract_rois: Extract all Rois in a single audio filemulticpu_extract_rois: Extract all Rois in the dataset (multiple audio files)from features.pycompute_features: Compute features of a single Roi such as shape (wavelets), centroid and bandwidthmulticpu_compute_features: Compute features such as shape (wavelets), centroid and bandwidth of all Rois in the dataset (multiple audio files)from cluster.pyfind_cluster:  Clustering of ROIs.  Use DBSCAN or HDSCAN clustering method for several reasons :
* DBSCAN does not need the number of clusters to do the clustering
* DBSCAN is able to deal with noise and keep them outside any clusters.
So, the goal of the clustering is to aggregate similar ROIs
which might correspond to the main call or song of a species. If several
clusters are found, which means that we might have ROIs corresponding to
different calls and/or songs for the species, we can keep the cluster with
the highest number of ROIs or all the clusters.cluster_eval:   Evaluation of the clustering (requires annotations or any other files to compare with the result of the clustering)overlay_rois: Overlay Rois with colors and number depending on the cluster number or the label.mark_rois: Add a marker to the audio filenames of each Roi depending on the result of the evaluation of the clustering (TN, FN, TP, FP)unmark_rois: Remove the markersExamples and documentationSee the directory "example" to find scripts to run the labelling function on a collection of birds species or on a single fileMore example scripts will be available soon oncolabworkflow single speciesFull description of the packagescikit-maad:https://doi.org/10.1111/2041-210X.13711Online reference manual and example gallery ofscikit-maadhere.In depth information related to the Multiresolution Analysis of Acoustic Diversity implemented in scikit-maad was published in: Ulloa, J. S., Aubin, T., Llusia, D., Bouveyron, C., & Sueur, J. (2018).Estimating animal acoustic diversity in tropical environments using unsupervised multiresolution analysis. Ecological Indicators, 90, 346–355Citing this workIf you findbambirdusefull for your research, please consider citing it as:Michaud, F.,  Sueur, J., Le Cesne, M., & Haupert, S. (2022).Unsupervised classification to improve the quality of a bird song recording dataset. Ecological Informatics, xx, xxx–xxxContributions and bug reportImprovements and new features are greatly appreciated. If you would like to contribute developing new features or making improvements to the available package, please refer to ourwiki. Bug reports and especially tested patches may be submitted directly to thebug tracker.