Package: vocalpy
A core package for acoustic communication research in PythonThere are many great software tools for researchers studying acoustic communication in animals[^1].
But our research groups work with a wide range of different data formats: for audio, for array data, for annotations.
This means we write a lot of low-level code to deal with those formats,
and then our code for analyses istightly coupledto those formats.
In turn, this makes it hard for other groups to read our code,
and it takes a real investment to understand our analyses, workflows and pipelines.
It also means that it requires significant work to translate from a
pipeline or analysis worked out by a scientist-coder in a Jupyter notebook
into a generalized, robust service provided by an application.In particular, acoustic communication researchers working with the Python programming language face these problems.
How can our scripts and libraries talk to each other?
Luckily, Python is a great glue language! Let's use it to solve these problems.The goals of VocalPy are to:make it easy to work with a wide array of data formats: audio, array (spectrograms, features), annotationprovide classes that represent commonly-used data types: audio, spectograms, features, annotationsprovide classes that represent common processes and steps in pipelines: segmenting audio, computing spectrograms,
extracting featuresmake it easier for scientist-coders to flexibly and iteratively build datasets,
without needing to deal directly with a database if they don't want tomake it possible to re-use code you have already written for your own research groupand finally:make code easier to share and read across research groups, by providing these classes, andidiomiaticways
of coding with them; think of VocalPy as an interoperability layer and a common languagefacilitate collaboration between scientist-coders writing imperative analysis scripts andresearch software engineersdeveloping libraries and applicationsApaper introducing VocalPy and its designhas been accepted atForum Acusticum 2023as part of the session "Open-source software and cutting-edge applications in bio-acoustics",
and will be published in the proceedings.[^1]: For a curated collection, seehttps://github.com/rhine3/bioacoustics-software.FeaturesData types for acoustic communication data: audio, spectrogram, annotations, featuresThevocalpy.Audiodata typeWorks with a wide array of audio formats, thanks tosoundfile.Also works with the cbin audio format saved by the LabView app EvTAF used by many neuroscience labs studying birdsong,
thanks toevfuncs.>>>importvocalpyasvoc>>>data_dir=('tests/data-for-tests/source/audio_wav_annot_birdsongrec/Bird0/Wave/')>>>wav_paths=voc.paths.from_dir(data_dir,'wav')>>>audios=[voc.Audio.read(wav_path)forwav_pathinwav_paths]>>>print(audios[0])vocalpy.Audio(data=array([3.0517...66210938e-04]),samplerate=32000,channels=1),path=tests/data-for-tests/source/audio_wav_annot_birdsongrec/Bird0/Wave/0.wav)Thevocalpy.Spectrogramdata typeSave expensive-to-compute spectrograms to array files, so you don't regenerate them over and over again>>>importvocalpyasvoc>>>data_dir=('tests/data-for-tests/generated/spect_npz/')>>>spect_paths=voc.paths.from_dir(data_dir,'wav.npz')>>>spects=[voc.Spectrogram.read(spect_path)forspect_pathinspect_paths]>>>print(spects[0])vocalpy.Spectrogram(data=array([[3.463...7970774e-14]]),frequencies=array([0....7.5,16000.]),times=array([0.008,...7.648,7.65]),path=PosixPath('tests/data-for-tests/generated/spect_npz/0.wav.npz'),audio_path=None)Thevocalpy.Annotationdata typeLoad many different annotation formats using the pyOpenSci packagecrowsetta>>>importvocalpyasvoc>>>data_dir=('tests/data-for-tests/source/audio_cbin_annot_notmat/gy6or6/032312/')>>>notmat_paths=voc.paths.from_dir(data_dir,'.not.mat')>>>annots=[voc.Annotation.read(notmat_path,format='notmat')fornotmat_pathinnotmat_paths]>>>print(annots[1])Annotation(data=Annotation(annot_path=PosixPath('tests/data-for-tests/source/audio_cbin_annot_notmat/gy6or6/032312/gy6or6_baseline_230312_0809.141.cbin.not.mat'),notated_path=PosixPath('tests/data-for-tests/source/audio_cbin_annot_notmat/gy6or6/032312/gy6or6_baseline_230312_0809.141.cbin'),seq=<Sequencewith57segments>),path=PosixPath('tests/data-for-tests/source/audio_cbin_annot_notmat/gy6or6/032312/gy6or6_baseline_230312_0809.141.cbin.not.mat'))Classes for common steps in your pipelines and workflowsASegmenterfor segmentation into sequences of units>>>importevfuncs>>>importvocalpyasvoc>>>data_dir=('tests/data-for-tests/source/audio_cbin_annot_notmat/gy6or6/032312/')>>>cbin_paths=voc.paths.from_dir(data_dir,'cbin')>>>audios=[voc.Audio.read(cbin_path)forcbin_pathincbin_paths]>>>segment_params={'threshold':1500,'min_syl_dur':0.01,'min_silent_dur':0.006}>>>segmenter=voc.Segmenter(callback=evfuncs.segment_song,segment_params=segment_params)>>>seqs=segmenter.segment(audios,parallelize=True)[########################################] | 100% Completed | 122.91 ms>>>print(seqs[1])Sequence(units=[Unit(onset=2.19075,offset=2.20428125,label='-',audio=None,spectrogram=None),Unit(onset=2.35478125,offset=2.38815625,label='-',audio=None,spectrogram=None),Unit(onset=2.8410625,offset=2.86715625,label='-',audio=None,spectrogram=None),Unit(onset=3.48234375,offset=3.49371875,label='-',audio=None,spectrogram=None),Unit(onset=3.57021875,offset=3.60296875,label='-',audio=None,spectrogram=None),Unit(onset=3.64403125,offset=3.67721875,label='-',audio=None,spectrogram=None),Unit(onset=3.72228125,offset=3.74478125,label='-',audio=None,spectrogram=None),Unit(onset=3.8036875,offset=3.8158125,label='-',audio=None,spectrogram=None),Unit(onset=3.82328125,offset=3.83646875,label='-',audio=None,spectrogram=None),Unit(onset=4.13759375,offset=4.16346875,label='-',audio=None,spectrogram=None),Unit(onset=4.80278125,offset=4.814,label='-',audio=None,spectrogram=None),Unit(onset=4.908125,offset=4.922875,label='-',audio=None,spectrogram=None),Unit(onset=4.9643125,offset=4.992625,label='-',audio=None,spectrogram=None),Unit(onset=5.039625,offset=5.0506875,label='-',audio=None,spectrogram=None),Unit(onset=5.10165625,offset=5.1385,label='-',audio=None,spectrogram=None),Unit(onset=5.146875,offset=5.16203125,label='-',audio=None,spectrogram=None),Unit(onset=5.46390625,offset=5.49409375,label='-',audio=None,spectrogram=None),Unit(onset=6.14503125,offset=6.1565625,label='-',audio=None,spectrogram=None),Unit(onset=6.31003125,offset=6.346125,label='-',audio=None,spectrogram=None),Unit(onset=6.38996875,offset=6.4018125,label='-',audio=None,spectrogram=None),Unit(onset=6.46053125,offset=6.4796875,label='-',audio=None,spectrogram=None),Unit(onset=6.83525,offset=6.8643125,label='-',audio=None,spectrogram=None)],method='segment_song',segment_params={'threshold':1500,'min_syl_dur':0.01,'min_silent_dur':0.006},audio=vocalpy.Audio(data=None,samplerate=None,channels=None),path=tests/data-for-tests/source/audio_cbin_annot_notmat/gy6or6/032312/gy6or6_baseline_230312_0809.141.cbin),spectrogram=None)ASpectrogramMakerfor computing spectrograms>>>importvocalpyasvoc>>>wav_paths=voc.paths.from_dir('wav')>>>audios=[voc.Audio(wav_path)forwav_pathinwav_paths]>>>spect_params={'fft_size':512,'step_size':64}>>>spect_maker=voc.SpectrogramMaker(spect_params=spect_params)>>>spects=spect_maker.make(audios,parallelize=True)Datasets you flexibly build from pipelines and convert to databasesThevocalpy.datasetmodule contains classes that represent common types of datasetsYou make these classes with outputs of your pipelines, e.g. alistofvocalpy.Sequences
orvocalpy.SpectrogramsBecause of the design ofvocalpy, these datasets capture key metadata from your pipeline:parameters and data provenance details;
e.g., what parameters did you use to segment? What audio file did this sequence come from?Then you can save the dataset along with metadata to databases, or later load from databasesvocalpycomes with built-in support for persisting toSQLite,
a lightweight, efficient single-file database format.
It is the only database file formatrecommended by the US Library of Congress for archival data,
and it'sbuilt into Python-- no need to install separate database software like MySQLASequenceDatasetfor common analyses of sequences of units>>>importevfuncs>>>importvocalpyasvoc>>>data_dir='tests/data-for-tests/source/audio_cbin_annot_notmat/gy6or6/032312/'>>>cbin_paths=voc.paths.from_dir(data_dir,'cbin')>>>audios=[voc.Audio.read(cbin_path)forcbin_pathincbin_paths]>>>segment_params={'threshold':1500,'min_syl_dur':0.01,'min_silent_dur':0.006,}>>>segmenter=voc.Segmenter(callback=evfuncs.segment_song,segment_params=segment_params)>>>seqs=segmenter.segment(audios)>>>seq_dataset=voc.dataset.SequenceDataset(sequences=seqs)>>>seq_dataset.to_sqlite(db_name='gy6or6-032312.db',replace=True)>>>print(seq_dataset)SequenceDataset(sequences=[Sequence(units=[Unit(onset=2.18934375,offset=2.21,label='-',audio=None,spectrogram=None),Unit(onset=2.346125,offset=2.373125,label='-',audio=None,spectrogram=None),Unit(onset=2.50471875,offset=2.51546875,label='-',audio=None,spectrogram=None),Unit(onset=2.81909375,offset=2.84740625,label='-',audio=None,spectrogram=None),...>>># test that we can load the dataset>>>seq_dataset_loaded=voc.dataset.SequenceDataset.from_sqlite(db_name='gy6or6-032312.db')>>>seq_dataset_loaded==seq_datasetTrueInstallationWithpip$ conda create -n vocalpy python=3.10
$ conda activate vocalpy
$ pip install vocalpyWithconda$ conda create -n vocalpy python=3.10
$ conda activate vocalpy    
$ conda install vocalpy -c conda-forgeFor more detail seeGetting Started - InstallationSupportTo report a bug or request a feature (such as a new annotation format),
please use the issue tracker on GitHub:https://github.com/vocalpy/vocalpy/issuesTo ask a question about vocalpy, discuss its development,
or share how you are using it,
please start a new topic on the VocalPy forum
with the vocalpy tag:https://forum.vocalpy.org/ContributeCode of conductPlease note that this project is released with aContributor Code of Conduct.
By participating in this project you agree to abide by its terms.Contributing GuidelinesBelow we provide some quick links,
but you can learn more about how you can help and give feedbackby reading ourContributing Guide.To ask a question about vocalpy, discuss its development,
or share how you are using it,
please start a new "Q&A" topic on the VocalPy forum
with the vocalpy 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/vocalpy/issuesCHANGELOGYou can see project history and work in progress in theCHANGELOGLicenseThe project is licensed under theBSD license.CitationIf you use vocalpy, please cite the DOI:Contributors ✨Thanks goes to these wonderful people (emoji key):Ralph Emilio Peterson🤔📓📖🐛💻This project follows theall-contributorsspecification. Contributions of any kind welcome!