Metadata-Version: 2.1
Name: songdkl
Version: 0.3.1
Summary: automated quantitation of vocal learning in songbirds
Author: David Mets
Author-email: David Nicholson <nickledave@users.noreply.github.com>
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Classifier: License :: OSI Approved :: BSD License
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Dist: dask >=2022.12.0
Requires-Dist: numpy >=1.19.4
Requires-Dist: scipy >=1.5.4
Requires-Dist: matplotlib >= 3.3.3
Requires-Dist: rich >=12.5.1
Requires-Dist: scikit-image >= 0.19.3
Requires-Dist: scikit-learn >= 0.24.0
Requires-Dist: zarr >=2.13.3
Requires-Dist: flit ; extra == "dev"
Requires-Dist: twine ; extra == "dev"
Requires-Dist: songdkl[tests, docs] ; extra == "dev"
Requires-Dist: jupyterlab >=3.0.3 ; extra == "docs"
Requires-Dist: Sphinx >= 3.4.1 ; extra == "docs"
Requires-Dist: pandas >= 1.4.4 ; extra == "tests"
Requires-Dist: pytest >= 6.2.1 ; extra == "tests"
Requires-Dist: pytest-cov >=2.12.0 ; extra == "tests"
Requires-Dist: pytest-console-scripts >= 1.3.1 ; extra == "tests"
Project-URL: Home, https://github.com/NickleDave/songdkl
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: tests

# songdkl
[![Continuous Integration Status](https://github.com/NickleDave/songdkl/actions/workflows/ci.yml/badge.svg)](https://github.com/NickleDave/songdkl/actions/workflows/ci.yml/badge.svg)
## About
automated quantitation of vocal learning in the songbird

As described in:  
Mets, David G., and Michael S. Brainard.  
"An automated approach to the quantitation of vocalizations and vocal learning in the songbird."  
PLoS computational biology 14.8 (2018): e1006437.  
<https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1006437&rev=2>

Data for demo and testing is from the following Dryad data package:  
Mets, David G.; Brainard, Michael S. (2019), 
Data from: An automated approach to the quantitation of vocalizations and vocal learning in the songbird., 
Dryad, Dataset, <https://doi.org/10.5061/dryad.8tn4660>  
Dataset can be downloaded here:  
<https://datadryad.org/stash/dataset/doi:10.5061/dryad.8tn4660>

## Installation
### as a user
`$ pip install songdkl`  
We recommend installing into a virtual environment, 
in order to capture the compute environment for computational projects.
For more information and good practices, please see:  
<https://the-turing-way.netlify.app/reproducible-research/renv.html>

### as a developer
This project uses the library [nox](https://nox.thea.codes/en/stable/) 
as a [task runner](https://scikit-hep.org/developer/tasks), 
to automate tasks like setting up a development environment.
Each task is represented as what nox calls a "session", 
and you can run a session by invoking nox 
at the command-line with the name of the session.

So, to set up a virtual environment for development 
with `songdkl` installed in "editable" mode, 
run the "dev" session.

We suggest using [pipx](https://github.com/pypa/pipx) 
to install nox in an isolated environment, 
so that nox can be accessed system-wide without affecting 
anything else on your machine.

1. Install [`pipx`](), e.g. with [brew](https://github.com/pypa/pipx#on-macos)
   (and [brew works on Linux too](https://docs.brew.sh/Homebrew-on-Linux))
2. Install nox with pipx: `pipx install nox`
3. Use nox to run the `dev` session: `nox -s dev`
4. Activate the virtual environment: `. ./.venv/bin/activate` (and/or tell your IDE to use it)

## Usage
`songdkl` provides a command-line interface (cli) 
that allows the user to run the program from the terminal.

The cli makes two commands available:
* `calculate`, to compute the songdkl between two directories of songs, e.g., from 2 birds  
  `$ songdkl calculate bird1_dir bird2_dir`

* `numsyls`, to estimate the number of syllables in a bird's song  
  `$ songdkl numsyls bird1_dir`

For details on usage, please run `songdkl --help`.

## Citation
If you use this software, please cite the DOI:  
[![DOI](https://zenodo.org/badge/157573537.svg)](https://zenodo.org/badge/latestdoi/157573537)

Please also cite the original paper:
Mets, David G., and Michael S. Brainard.  
"An automated approach to the quantitation of vocalizations and vocal learning in the songbird."  
PLoS computational biology 14.8 (2018): e1006437.  
<https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1006437&rev=2>
```
@article{mets2018automated,
  title={An automated approach to the quantitation of vocalizations and vocal learning in the songbird},
  author={Mets, David G and Brainard, Michael S},
  journal={PLoS computational biology},
  volume={14},
  number={8},
  pages={e1006437},
  year={2018},
  publisher={Public Library of Science San Francisco, CA USA}
}
```
If you use the accompanying Dryad dataset, please cite that as well:  
Mets, David G.; Brainard, Michael S. (2019), 
Data from: An automated approach to the quantitation of vocalizations and vocal learning in the songbird., 
Dryad, Dataset, <https://doi.org/10.5061/dryad.8tn4660>  

