Skip to main content

a neural network toolbox for animal vocalizations and bioacoustics

Project description



A neural network framework for animal acoustic communication and bioacoustics

DOI

All Contributors

PyPI version License Build Status codecov

vak is a Python framework for neural network models, designed for researchers studying animal acoustic communication and bioacoustics. Many people will be familiar with work in this area on animal vocalizations such as birdsong, bat calls, and even human speech. Neural network models have provided a powerful new tool for researchers in this area, as in many other fields.

The library has two main goals:

  1. Make it easier for researchers studying animal vocalizations to apply neural network algorithms to their data
  2. Provide a common framework that will facilitate benchmarking neural network algorithms on tasks related to animal vocalizations

Currently, the main use is an automatic annotation of vocalizations and other animal sounds. By annotation, we mean something like the example of annotated birdsong shown below:

spectrogram of birdsong with syllables annotated

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.
Please see the eLife article here: https://elifesciences.org/articles/63853

For more background on animal acoustic communication and deep learning, and how these intersect with related fields like computational ethology and neuroscience, please see the "About" section below.

Installation

Short version:

with pip

$ pip install vak

with conda

$ conda install vak -c pytorch -c conda-forge
$ #                  ^ notice additional channel!

Notice that for conda you specify two channels, and that the pytorch channel should come first, so it takes priority when installing the dependencies pytorch and torchvision.

For more details, please see: https://vak.readthedocs.io/en/latest/get_started/installation.html

We 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 may require some troubleshooting. A good place to start is by searching the issues.

Usage

Tutorial

Currently the easiest way to work with vak is through the command line. terminal showing vak help command output

You run it with configuration files, using one of a handful of commands.

For more details, please see the "autoannotate" tutorial here:
https://vak.readthedocs.io/en/latest/get_started/autoannotate.html

How can I use my data with vak?

Please see the How-To Guides in the documentation here: https://vak.readthedocs.io/en/latest/howto/index.html faq.html#faq

Support / Contributing

For help, please begin by checking out the Frequently Asked Questions:
https://vak.readthedocs.io/en/latest/faq.html.

To ask a question about vak, discuss its development, or share how you are using it, please start a new "Q&A" topic on the VocalPy forum with the vak tag:
https://forum.vocalpy.org/

To report a bug, or to request a feature, please use the issue tracker on GitHub:
https://github.com/vocalpy/vak/issues

For a guide on how you can contribute to vak, please see: https://vak.readthedocs.io/en/latest/development/index.html

Citation

If you use vak for a publication, please cite its DOI:
DOI

License

License
is here.

About

Are humans unique among animals? We speak languages, but is speech somehow like other animal behaviors, such as birdsong? Questions like these are answered by studying how animals communicate with sound. This research requires cutting edge computational methods and big team science across a wide range of disciplines, including ecology, ethology, bioacoustics, psychology, neuroscience, linguistics, and genomics ^1^3. As in many other domains, this research is being revolutionized by deep learning algorithms ^1^3. Deep neural network models enable answering questions that were previously impossible to address, in part because these models automate analysis of very large datasets. Within the study of animal acoustic communication, multiple models have been proposed for similar tasks, often implemented as research code with different libraries, such as Keras and Pytorch. This situation has created a real need for a framework that allows researchers to easily benchmark models and apply trained models to their own data. To address this need, we developed vak. We originally developed vak to benchmark a neural network model, TweetyNet ^4, that automates annotation of birdsong by segmenting spectrograms. TweetyNet and vak have been used in both neuroscience ^6^8 and bioacoustics ^9. For additional background and papers that have used vak, please see: https://vak.readthedocs.io/en/latest/reference/about.html

"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?

Yes.

Contributors โœจ

Thanks goes to these wonderful people (emoji key):

avanikop
avanikop

๐Ÿ›
Luke Poeppel
Luke Poeppel

๐Ÿ“–
yardencsGitHub
yardencsGitHub

๐Ÿ’ป ๐Ÿค” ๐Ÿ“ข ๐Ÿ““ ๐Ÿ’ฌ
David Nicholson
David Nicholson

๐Ÿ› ๐Ÿ’ป ๐Ÿ”ฃ ๐Ÿ“– ๐Ÿ’ก ๐Ÿค” ๐Ÿš‡ ๐Ÿšง ๐Ÿง‘โ€๐Ÿซ ๐Ÿ“† ๐Ÿ‘€ ๐Ÿ’ฌ ๐Ÿ“ข โš ๏ธ โœ…
marichard123
marichard123

๐Ÿ“–
Therese Koch
Therese Koch

๐Ÿ“– ๐Ÿ›
alyndanoel
alyndanoel

๐Ÿค”
adamfishbein
adamfishbein

๐Ÿ“–
vivinastase
vivinastase

๐Ÿ› ๐Ÿ““
kaiyaprovost
kaiyaprovost

๐Ÿ’ป ๐Ÿค”
ymk12345
ymk12345

๐Ÿ› ๐Ÿ“–
neuronalX
neuronalX

๐Ÿ› ๐Ÿ“–
Khoa
Khoa

๐Ÿ“–
sthaar
sthaar

๐Ÿ“– ๐Ÿ› ๐Ÿค”
yangzheng-121
yangzheng-121

๐Ÿ› ๐Ÿค”
lmpascual
lmpascual

๐Ÿ“–
ItamarFruchter
ItamarFruchter

๐Ÿ“–
Hjalmar K. Turesson
Hjalmar K. Turesson

๐Ÿ› ๐Ÿค”
nhoglen
nhoglen

๐Ÿ›

This project follows the all-contributors specification. Contributions of any kind welcome!

Project details


Download files

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

Source Distribution

vak-0.8.2.tar.gz (1.2 MB view hashes)

Uploaded Source

Built Distribution

vak-0.8.2-py3-none-any.whl (145.4 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page