Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

Functions for working with this data repository: https://figshare.com/articles/BirdsongRecognition/3470165

Project description

koumura

Functions for working with data from the following repository: https://figshare.com/articles/BirdsongRecognition/3470165

The repository contains .wav files of Bengalese finch song from ten birds and annotation for the songs in .xml files.

This repository provides a great resource, and was used to benchmark a sliding window-based neural network for segmenting and labeling the elements of birdsong, as described in the following paper:
Koumura, Takuya, and Kazuo Okanoya.
"Automatic recognition of element classes and boundaries in the birdsong with variable sequences."
PloS one 11.7 (2016): e0159188.
https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0159188

The code for the network can be found here:
https://github.com/takuya-koumura/birdsong-recognition

The original code was released under the GNU license:
https://github.com/takuya-koumura/birdsong-recognition/blob/master/LICENSE

The koumura module is used with the conbirt package to make the repository a dataset available in the hybrid-vocal-classifier and songdeck libraries.

It's called koumura because that's the last name of the first author on the paper, and because I am too lazy to type PyBirdsongRecognition.

Installation

$ pip install koumura

Usage

The main thing that koumura gives you is easy access to the annotation, without having to deal with the .xml file format.

To access the annotation in the Annotation.xml files for each bird, use the parse_xml function.

>>> from koumura import parse_xml
>>> seq_list = parse_xml(xml_file='./Bird0/Annotation.xml', concat_seqs_into_songs=False)
>>> seq_list[0]
Sequence from 0.wav with position 32000 and length 43168
>>> seq_list[0].syls[:3]
[Syllable labeled 0 at position 2240 with length 2688, Syllable labeled 0 at position 8256 with length 2784, Syllable labeled 0 at position 14944 with length 2816]  

Notice that this package preserves the abstraction of the original code, where syllables and sequences of syllables are represented as objects. This can be helpful if you are trying to replicate functionality from that code.
Importantly, each song is broken up into a number of "sequences". You can set the flag concat_seqs_into_songs to True if you want parse_xml to concatenate sequences by song (.wav file), so that each Sequence is actually all the sequences from one song.
If you are using the annotation to work with the dataset for some other purpose, you may find it more convenient to work with some other format. For that, please check out the conbirt package, which converts this annotation format and others to a tidy comma-separated value format.

The koumura package also provides a convenience function to load the annotation for an individual song, load_song_annot. This is basically a wrapper around parse_xml that filters out the songs you don't want.

>>> from koumura import load_song_annot
>>> wav1 = load_song_annot(wav_file='1.wav')
>>> print(wav1)                                                                                                  
Sequence from 1.wav with position 32000 and length 214176  

Getting Help

Please feel free to raise an issue here:
https://github.com/NickleDave/koumura/issues

License

BSD License.

Citation

If you use this module, please cite the DOI: DOI

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for koumura, version 0.1.1a1
Filename, size File type Python version Upload date Hashes
Filename, size koumura-0.1.1a1-py3-none-any.whl (9.6 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size koumura-0.1.1a1.tar.gz (10.7 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page