a neural network toolbox for animal vocalizations and bioacoustics
Project description
vak
a neural network toolbox for animal vocalizations and bioacoustics
vak
is a library for researchers studying animal vocalizations--such as
birdsong, bat calls, and even human speech--although it may be useful
to anyone working with bioacoustics data.
While there are many important reasons to study bioacoustics, the scope of vak
is limited to questions related to vocal learning,
"the ability to modify acoustic and syntactic sounds, acquire new sounds via imitation, and produce vocalizations"
(Wikipedia).
Research questions related to vocal learning cut across a wide range of fields
including neuroscience, phsyiology, molecular biology, genomics, ecology, and evolution
(Wirthlin et al. 2019).
vak
has two main goals:
- make it easier for researchers studying animal vocalizations to apply neural network algorithms to their data
- provide a common framework that will facilitate benchmarking neural network algorithms on tasks related to animal vocalizations
Currently the main use is automated annotation of vocalizations and other animal sounds,
using artificial neural networks.
By annotation, we mean something like the example of annotated birdsong shown below:
You give vak
training data in the form of audio or spectrogram files with annotations,
and then vak
helps you train neural network models
and use the trained models to predict annotations for new files.
We developed vak
to benchmark a neural network model we call tweetynet
.
See pre-print here: https://www.biorxiv.org/content/10.1101/2020.08.28.272088v2.full.pdf
We would love to help you use vak
to benchmark your own model.
If you have questions, please feel free to raise an issue.
Installation
Short version:
$ pip install vak
For the long version detail, please see: https://vak.readthedocs.io/en/latest/get_started/installation.html
We currently test vak
on Ubuntu and MacOS. We have run on Windows and
know of other users successfully running vak
on that operating system,
but installation on Windows will probably require some troubleshooting.
A good place to start is by searching the issues.
Usage
Training models to segment and label vocalizations
Currently the easiest way to work with vak
is through the command line.
You run it with config.toml
files, using one of a handful of commands.
For more details, please see the "autoannotate" tutorial here:
https://vak.readthedocs.io/en/latest/tutorial/autoannotate.html
Data and folder structures
To train models, you provide training data in the form of audio or spectrograms files, and annotations for those files.
Spectrograms and labels
The package can generate spectrograms from .wav
files or .cbin
audio files.
It can also accept spectrograms in the form of Matlab .mat
or Numpy .npz
files.
The locations of these files are specified in the config.toml
file.
The annotations are parsed by a separate library, crowsetta
, that
aims to handle common formats like Praat textgrid
files, and enable
researchers to easily work with formats they may have developed in their
own labs. For more information please see:
https://crowsetta.readthedocs.io/en/latest/
https://github.com/NickleDave/crowsetta
Preparing training files
It is possible to train on any manually annotated data but there are some useful guidelines:
- Use as many examples as possible - The results will just be better. Specifically, this code will not label correctly syllables it did not encounter while training and will most probably generalize to the nearest sample or ignore the syllable.
- Use noise examples - This will make the code very good in ignoring noise.
- Examples of syllables on noise are important - It is a good practice to start with clean recordings. The code will not perform miracles and is most likely to fail if the audio is too corrupt or masked by noise. Still, training with examples of syllables on the background of cage noises will be beneficial.
Predicting annotations for audio
You can predict annotations for audio files by creating a config.toml
file with a [PREDICT] section.
For more details, please see the "autoannotate" tutorial here:
https://vak.readthedocs.io/en/latest/tutorial/autoannotate.html
Support / Contributing
Currently we are handling support through the issue tracker on GitHub:
https://github.com/NickleDave/vak/issues
Please raise an issue there if you run into trouble.
That would be a great place to start if you are interested in contributing, as well.
Citation
If you use vak for a publication, please cite its DOI:
License
is here.
Misc
"Why this name, vak?"
It has only three letters, so it is quick to type, and it wasn't taken on pypi yet. Also I guess it has something to do with speech. "vak" rhymes with "squawk" and "talk".
Does your library have any poems?
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.