vak
A neural network framework for animal acoustic communication and bioacoustics.
https://github.com/vocalpy/vak
Category: Biosphere
Sub Category: Bioacoustics and Acoustic Data Analysis
Keywords
animal-communication animal-vocalizations bioacoustic-analysis bioacoustics birdsong python python3 pytorch spectrograms speech-processing torch torchvision vocalizations
Keywords from Contributors
vectors charts changed-file orchestration profiles simulator csv transforms keras alert
Last synced: about 2 hours ago
JSON representation
Repository metadata
A neural network framework for researchers studying acoustic communication
- Host: GitHub
- URL: https://github.com/vocalpy/vak
- Owner: vocalpy
- License: bsd-3-clause
- Created: 2019-03-03T11:34:38.000Z (about 6 years ago)
- Default Branch: main
- Last Pushed: 2025-04-08T18:57:46.000Z (22 days ago)
- Last Synced: 2025-04-20T08:08:02.490Z (10 days ago)
- Topics: animal-communication, animal-vocalizations, bioacoustic-analysis, bioacoustics, birdsong, python, python3, pytorch, spectrograms, speech-processing, torch, torchvision, vocalizations
- Language: Python
- Homepage: https://vak.readthedocs.io
- Size: 196 MB
- Stars: 82
- Watchers: 3
- Forks: 18
- Open Issues: 130
- Releases: 44
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff
README.md
A neural network framework for researchers studying acoustic communication
vak
is a Python framework for neural network models,
designed for researchers studying acoustic communication:
how and why animals communicate with sound.
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:
- Make it easier for researchers studying acoustic communication to
apply neural network algorithms to their data - Provide a common framework that will facilitate benchmarking neural
network algorithms on tasks related to acoustic communication
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:
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
To learn more about the goals and design of vak,
please see this talk from the SciPy 2023 conference,
and the associated Proceedings paper
here.
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:
pip
with $ pip install vak
conda
with $ 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.
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
vak
?
How can I use my data with Please see the How-To Guides in the documentation here:
https://vak.readthedocs.io/en/latest/howto/index.html
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 both the Proceedings paper and the software.
Proceedings paper (BiBTex)
@inproceedings{nicholson2023vak,
title={vak: a neural network framework for researchers studying animal acoustic communication},
author={Nicholson, David and Cohen, Yarden},
booktitle={Python in Science Conference},
pages={59--67},
year={2023}
}
Software
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?
Contributors ✨
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
Citation (CITATION.cff)
# This CITATION.cff file was generated with cffinit. # Visit https://bit.ly/cffinit to generate yours today! cff-version: 1.2.0 title: vak message: >- a neural network toolbox for animal vocalizations and bioacoustics type: software authors: - given-names: David family-names: Nicholson email: nicholdav@gmail.com affiliation: Emory University orcid: 'https://orcid.org/0000-0002-4261-4719' - given-names: Yarden family-names: Cohen orcid: 'https://orcid.org/0000-0002-8149-6954' affiliation: Weizmann Institute email: yardencsmail@gmail.com identifiers: - type: doi value: 10.5281/zenodo.5828090 repository-code: 'https://github.com/NickleDave/vak' url: 'https://vak.readthedocs.io' repository-artifact: 'https://pypi.org/project/vak/' keywords: - python - animal vocalizations - neural networks - bioacoustics license: BSD-3-Clause commit: ad802dcad34b524533b765e5dfb3709b308a3152 version: 0.4.2 date-released: '2022-03-29'
Owner metadata
- Name: VocalPy
- Login: vocalpy
- Email:
- Kind: organization
- Description:
- Website: https://forum.vocalpy.org/
- Location:
- Twitter:
- Company:
- Icon url: https://avatars.githubusercontent.com/u/99543036?v=4
- Repositories: 8
- Last ynced at: 2023-08-21T08:10:23.154Z
- Profile URL: https://github.com/vocalpy
GitHub Events
Total
- Create event: 4
- Release event: 1
- Issues event: 12
- Watch event: 5
- Delete event: 1
- Issue comment event: 36
- Push event: 15
- Pull request event: 10
- Fork event: 1
Last Year
- Create event: 4
- Release event: 1
- Issues event: 12
- Watch event: 5
- Delete event: 1
- Issue comment event: 36
- Push event: 15
- Pull request event: 10
- Fork event: 1
Committers metadata
Last synced: 1 day ago
Total Commits: 2,576
Total Committers: 10
Avg Commits per committer: 257.6
Development Distribution Score (DDS): 0.212
Commits in past year: 32
Committers in past year: 4
Avg Commits per committer in past year: 8.0
Development Distribution Score (DDS) in past year: 0.5
Name | Commits | |
---|---|---|
David Nicholson | n****e | 2031 |
NickleDave | n****v@g****m | 431 |
allcontributors[bot] | 4****] | 57 |
yardencsGitHub | y****c@b****u | 51 |
milaXT | 1****T | 1 |
kaiyaprovost | 1****t | 1 |
Luke Poeppel | l****l@g****m | 1 |
Khoa | 5****7 | 1 |
Ja-sonYun | k****7@g****m | 1 |
Ikko Ashimine | e****r@g****m | 1 |
Committer domains:
- bu.edu: 1
Issue and Pull Request metadata
Last synced: 1 day ago
Total issues: 160
Total pull requests: 89
Average time to close issues: 7 months
Average time to close pull requests: 4 days
Total issue authors: 16
Total pull request authors: 8
Average comments per issue: 1.56
Average comments per pull request: 0.79
Merged pull request: 81
Bot issues: 0
Bot pull requests: 17
Past year issues: 31
Past year pull requests: 21
Past year average time to close issues: 16 days
Past year average time to close pull requests: 30 minutes
Past year issue authors: 5
Past year pull request authors: 3
Past year average comments per issue: 1.42
Past year average comments per pull request: 0.19
Past year merged pull request: 21
Past year bot issues: 0
Past year bot pull requests: 5
Top Issue Authors
- NickleDave (137)
- athenasyarifa (3)
- harshidapancholi (3)
- yardencsGitHub (3)
- henricombrink (2)
- milaXT (2)
- meriablue (1)
- nhoglen (1)
- cantonsir (1)
- wendtalexander (1)
- avanikop (1)
- vivinastase (1)
- danielmk (1)
- kalleknast (1)
- ItamarFruchter (1)
Top Pull Request Authors
- NickleDave (65)
- allcontributors[bot] (17)
- marisbasha (2)
- nosrednab (1)
- zhileiz1992 (1)
- milaXT (1)
- TrellixVulnTeam (1)
- Ja-sonYun (1)
Top Issue Labels
- ENH: enhancement (47)
- BUG (23)
- DOC: documentation (17)
- Models (11)
- TST: testing (8)
- CLN: clean / refactor (7)
- DEV: development (5)
- CI: continuous integration (3)
- api (1)
- dependencies (1)
- Metrics (1)
- Datasets (1)
Top Pull Request Labels
- DOC: documentation (1)
Package metadata
- Total packages: 2
-
Total downloads:
- pypi: 1,539 last-month
- Total dependent packages: 2 (may contain duplicates)
- Total dependent repositories: 1 (may contain duplicates)
- Total versions: 49
- Total maintainers: 1
pypi.org: vak
A neural network framework for researchers studying acoustic communication
- Homepage:
- Documentation: https://vak.readthedocs.io
- Licenses: BSD License
- Latest release: 1.0.3 (published 6 months ago)
- Last Synced: 2025-04-29T16:02:26.654Z (1 day ago)
- Versions: 45
- Dependent Packages: 1
- Dependent Repositories: 1
- Downloads: 1,539 Last month
-
Rankings:
- Dependent packages count: 3.271%
- Stargazers count: 8.458%
- Forks count: 9.146%
- Average: 11.971%
- Downloads: 16.746%
- Dependent repos count: 22.233%
- Maintainers (1)
conda-forge.org: vak
- Homepage: https://pypi.org/project/vak/
- Licenses: BSD-3-Clause
- Latest release: 0.6.0 (published almost 3 years ago)
- Last Synced: 2025-04-01T02:11:26.094Z (30 days ago)
- Versions: 4
- Dependent Packages: 1
- Dependent Repositories: 0
-
Rankings:
- Dependent packages count: 28.82%
- Dependent repos count: 34.025%
- Average: 36.017%
- Stargazers count: 39.052%
- Forks count: 42.171%
Dependencies
- SoundFile >=0.10.3
- attrs >=19.3.0
- crowsetta >=5.0.1
- dask >=2.10.1
- evfuncs >=0.3.4
- joblib >=0.14.1
- matplotlib >=3.3.3
- numpy >=1.18.1
- pandas >=1.0.1
- pynndescent >=0.5.10
- pytorch-lightning >=2.0.7
- scipy >=1.4.1
- tensorboard >=2.8.0
- toml >=0.10.2
- torch >= 2.0.1
- torchvision >=0.15.2
- tqdm >=4.42.1
- umap-learn >=0.5.3
- actions/checkout v2 composite
- actions/setup-python v2 composite
- codecov/codecov-action v3 composite
- excitedleigh/setup-nox v2.1.0 composite
Score: 15.00065522002922