Metadata-Version: 2.4
Name: das_unsupervised
Version: 0.6.0
Summary: Tools for unsupervised classification of acoustic signals.
Home-page: https://github.com/janclemenslab/das_unsupervised
Author: Jan Clemens
Author-email: clemensjan@googlemail.com
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Classifier: License :: OSI Approved :: MIT License
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: scikit-learn
Requires-Dist: matplotlib
Requires-Dist: colorcet
Requires-Dist: seaborn
Requires-Dist: librosa>=0.11
Requires-Dist: noisereduce>=3
Requires-Dist: Pillow>=10
Requires-Dist: umap-learn
Requires-Dist: hdbscan
Requires-Dist: ipykernel
Requires-Dist: ipywidgets
Requires-Dist: jupyterlab
Requires-Dist: marimo

# Tools for unsupervised classification of acoustic signals
_DAS-unsupervised_ provides tools for pre-processing acoustic signals for unsupervised classification:

- extract waveforms or spectrograms of acoustic events from a recording
- normalize the duration, center frequency, amplitude, or sign of waveform/spectrograms

Unsupervised classification itself is performed using existing libraries:

- dimensionality reduction: [umap](https://umap-learn.readthedocs.io/)
- clustering: [hdbscan](https://hdbscan.readthedocs.io/) or [scikit-learn](https://scikit-learn.org/stable/modules/clustering.html)
- __NEW:__ interactive embedding and visualization with [marimo](https://marimo.io).

Can be used in combination with [DAS](https://github.com/janclemenslab/das), a deep learning based method for the supervised annotation of acoustic signals.



## Install via conda and uv
```shell
conda create -y -n das_unsupervised -c conda-forge python=3.13 uv
conda activate das_unsupervised
uv pip install das_unsupervised
```

## Demos
 Illustration of the workflow and the method using vocalizations from:

- [flies](demo/flies.ipynb)
- [mice](demo/mice.ipynb)
- [birds](demo/birds.ipynb)
- __NEW:__ [interactive zebra finch](interactive/interactive.py)


![](demo/banner.png)


## Acknowledgements
Code from the following open source packages was modified and integrated into das-unsupervised:

- [avgn](https://github.com/timsainb/avgn_paper) (Sainburg et al. 2020)
- [noisereduce](https://pypi.org/project/noisereduce)
- [fly pulse classifier](https://github.com/murthylab/MurthyLab_FlySongSegmenter) (Clemens et al. 2018)

Data sources:

- flies: [David Stern](https://www.janelia.org/lab/stern-lab/tools-reagents-data) (Stern, 2014)
- mice: data provided by Kurt Hammerschmidt (Ivanenko et al. 2020)
- birds: [Bengalese finch song repository](https://doi.org/10.6084/m9.figshare.4805749.v5) (Nicholson et al. 2017), [Zebra finch song repository](https://research.repository.duke.edu/concern/datasets/9k41zf38g) (Goffinet et al. 2021)


## References

1. T Sainburg, M Thielk, TQ Gentner (2020) Latent space visualization, characterization, and generation of diverse vocal communication signals. Biorxiv . [https://doi.org/10.1101/870311]()

2. J Clemens, P Coen, F Roemschied, T Perreira, D Mazumder, D Aldorando, D Pacheco, M Murthy (2018) Discovery of a New Song Mode in Drosophila Reveals Hidden Structure in the Sensory and Neural Drivers of Behavior. Current Biology 28, 2400–2412.e6 (2018). [https://doi.org/10.1016/j.cub.2018.06.011]()

3. D Stern (2014). Reported Drosophila courtship song rhythms are artifacts of data analysis. BMC Biology

4. A Ivanenko, P Watkins, MAJ van Gerven, K Hammerschmidt, B Englitz (2020) Classifying sex and strain from mouse ultrasonic vocalizations using deep learning. PLoS Comput Biol 16(6): e1007918. [https://doi.org/10.1371/journal.pcbi.1007918]()

5. D Nicholson, JE Queen, S Sober (2017). Bengalese finch song repository. [https://doi.org/10.6084/m9.figshare.4805749.v5]()
