Metadata-Version: 2.4
Name: chatter-pkg
Version: 0.1.3
Summary: A Python library for applying information theory and AI/ML models to animal communication.
Author-email: Mason Youngblood <masonyoungblood@gmail.com>
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: audiocomplib>=0.2.0
Requires-Dist: biodenoising>=0.3.3
Requires-Dist: birdnetlib>=0.18.0
Requires-Dist: denmarf>=0.3.2
Requires-Dist: dtw>=1.4.0
Requires-Dist: h5py>=3.15.1
Requires-Dist: ipykernel>=7.1.0
Requires-Dist: ipympl>=0.9.8
Requires-Dist: ipython>=9.8.0
Requires-Dist: ipywidgets>=8.1.8
Requires-Dist: librosa>=0.9.2
Requires-Dist: matplotlib>=3.10.7
Requires-Dist: noisereduce>=3.0.3
Requires-Dist: numba>=0.62.1
Requires-Dist: numpy>=2.3.5
Requires-Dist: pacmap>=0.8.0
Requires-Dist: pandas>=2.3.3
Requires-Dist: pydub>=0.25.1
Requires-Dist: pykanto>=0.1.7
Requires-Dist: scikit-learn>=1.7.2
Requires-Dist: scipy>=1.16.3
Requires-Dist: soxr>=1.0.0
Requires-Dist: tensorflow>=2.20.0
Requires-Dist: torch>=2.9.1
Requires-Dist: torchaudio>=2.9.1
Requires-Dist: tqdm>=4.67.1
Requires-Dist: transformers>=4.57.3
Dynamic: license-file

<div align="center">
<img src="https://raw.githubusercontent.com/masonyoungblood/chatter/refs/heads/main/docs/_static/logo.png" alt="chatter logo" width="300">

[Mason Youngblood](https://masonyoungblood.com/)

![PyPI - Version](https://img.shields.io/pypi/v/chatter-pkg?color=440154) ![Python Version](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fmasonyoungblood%2Fchatter%2Frefs%2Fheads%2Fmain%2Fpyproject.toml&color=414487) ![Repo Size](https://img.shields.io/github/repo-size/masonyoungblood/chatter?color=2A788E) ![License](https://img.shields.io/badge/license-MIT-22A884) ![Tests](https://img.shields.io/github/actions/workflow/status/masonyoungblood/chatter/tests.yml?branch=main&color=FDE725)

**[Full Documentation](https://masonyoungblood.github.io/chatter)**
</div>


# `chatter`: a Python library for applying information theory and AI/ML models to animal communication











Historically, analyses of sequential structure in animal communication have involved the identification of unit types (e.g. "syllables" in bird song and "notes" in whale song). This collapses continuous variation into discrete categories that align with human perception, a process that loses a great deal of the complexity and nuance present in the actual signals. Recent innovations in machine learning, such as variational autoencoders and vision transformers, allow us to bypass discretization and analyze animal communication signals directly in continuous space. `chatter` makes it easy for researchers to apply these methods to their data, to quantify features like:

- Complexity—path length of sequences in latent space per unit time.
- Predictability—predictability of a transition in latent space.
- Similarity—cosine similarity between units or sequences in latent space.
- Novelty—inverse of predicted density of units or sequences in latent space.

Additionally, `chatter` makes it easy to explore the latent space of a species' vocalizations, either statically or with an interactive plot like the one below (of syllables in Cassin's vireo song).

![embeddings](https://github.com/masonyoungblood/chatter/blob/main/docs/_static/cassins_vireo_embedding.gif?raw=true)

This project is heavily inspired by the work of folks like Nilo Merino Recalde and Tim Sainburg. Here is a list of related projects:

- Sainburg, T., Thielk, M., Gentner, T. Q. (2020). Finding, visualizing, and quantifying latent structure across diverse animal vocal repertoires. *PLOS Computational Biology*. [https://doi.org/10.1371/journal.pcbi.1008228](https://doi.org/10.1371/journal.pcbi.1008228)
- Goffinet, J., Brudner, S., Mooney, R., Pearson, J. (2021). Low-dimensional learned feature spaces quantify individual and group differences in vocal repertoires. *eLife*. [https://doi.org/10.7554/eLife.67855](https://doi.org/10.7554/eLife.67855)
- Merino Recalde, N. (2023). pykanto: a python library to accelerate research on wild bird song. *Methods in Ecology and Evolution*. [https://doi.org/10.1111/2041-210X.14155](https://doi.org/10.1111/2041-210X.14155)
- Alam, D., Zia, F., Roberts, T. F. (2024). The hidden fitness of the male zebra finch courtship song. *Nature*. [https://www.doi.org/10.1038/s41586-024-07207-4](https://www.doi.org/10.1038/s41586-024-07207-4)

Please cite `chatter` as:

- Youngblood, M. (2025). Chatter: a Python library for applying information theory and AI/ML models to animal communication (v0.1.3). *GitHub*. [https://github.com/masonyoungblood/chatter](https://github.com/masonyoungblood/chatter)

```bibtex
@software{youngblood_chatter_2025,
   author = {Youngblood, Mason},
   title = {Chatter: a Python library for applying information theory and AI/ML models to animal communication},
   version = {v0.1.3},
   date = {2025},
   publisher = {GitHub},
   url = {https://github.com/masonyoungblood/chatter}
}
```

# Installing `chatter`

`chatter` should always be installed inside a new virtual environment. To create an environment using `conda` you can run:

```bash
conda create -n chatter python==3.13.3
```

Then, you can activate the environment and install from GitHub using `pip` or `uv`:

```bash
conda activate chatter
pip install chatter-pkg
```

```bash
conda activate chatter
uv pip install chatter-pkg
```

Note that `chatter` uses `torch` as its machine learning backend, and was developed to use GPU acceleration on Apple Silicon. If you run into issues with compatibility, please look into the `torch` [documentation](https://docs.pytorch.org/docs/main/index.html) before opening an issue on GitHub.
