# scikit-maad
<div align="center">
<img src="https://raw.githubusercontent.com/scikit-maad/scikit-maad/production/docs/logo/maad_key_visual_blue.png" alt="scikit-maad logo"/>
</div>
**scikit-maad** is an open source Python package dedicated to the quantitative analysis of environmental audio recordings. This package was designed to
1. load and process digital audio,
2. segment and find regions of interest,
3. compute acoustic features, and
4. estimate sound pressure level.
This workflow opens the possibility to scan large audio datasets and use powerful machine learning techniques, allowing to measure acoustic properties and identify key patterns in all kinds of soundscapes.
[](https://zenodo.org/badge/latestdoi/148142520)
[](https://pepy.tech/project/scikit-maad)
[](https://badge.fury.io/py/scikit-maad)
[](https://www.repostatus.org/#active)
[](https://GitHub.com/Naereen/StrapDown.js/graphs/commit-activity)
[](https://juleskreuer.eu/projekte/citation-badge/)
<!--[](https://www.python.org/downloads/release/python-360/)-->
## Operating Systems
`scikit-maad` seamlessly supports Linux, macOS, and Windows operating systems.
## Interpreter
`scikit-maad` requires one of these interpreters:
- Python >= 3.8 < 3.11
## Packages dependency
`scikit-maad` requires these Python packages to run:
- matplotlib >=3.6
- numpy >= 1.21
- pandas >= 1.5
- resampy >= 0.4
- scikit-image >= 0.19
- scipy >= 1.8
## Installing from PyPI
`scikit-maad` is hosted on PyPI. The easiest way to install the package is using `pip` the standard package installer for Python:
```bash
$ pip install scikit-maad
```
## Quick start
The package is imported as `maad`. To use scikit-maad tools, audio must be loaded as a numpy array. The function `maad.sound.load` is a simple and effective way to load audio from disk. For example, download the [spinetail audio example](https://raw.githubusercontent.com/scikit-maad/scikit-maad/production/data/spinetail.wav) to your working directory. You can load it and then apply any analysis to find regions of interest or characterize your audio signals:
```python
from maad import sound, rois
s, fs = sound.load('spinetail.wav')
rois.find_rois_cwt(s, fs, flims=(4500,8000), tlen=2, th=0, display=True)
```
## For advance users
### Installing from source
If you are interested in developing new features for `scikit-maad` or working with the latest version, clone and install it:
```bash
$ git clone https://github.com/scikit-maad/scikit-maad.git
$ cd scikit-maad
$ pip install --editable .
```
### Running tests
Install the test requirements:
```bash
$ pip install pytest
```
And run the tests:
```bash
$ cd scikit-maad
$ pytest
```
## Examples and documentation
- See https://scikit-maad.github.io for a complete reference manual and example gallery.
Runnin all examples requires to install the following packages :
- `scikit-learn`, a popular Python package for machine learning: [link](https://scikit-learn.org/stable/install.html)
- `librosa`, a popular package for audio and music analysis: [link](https://librosa.org/doc/latest/install.html)
- `tqdm`, a package that provides a fast, extensible progress bar for loops and other iterable tasks: [link](https://pypi.org/project/tqdm/)
- In depth information related to the Multiresolution Analysis of Acoustic Diversity implemented in scikit-maad was published in: Ulloa, J. S., Aubin, T., Llusia, D., Bouveyron, C., & Sueur, J. (2018). [Estimating animal acoustic diversity in tropical environments using unsupervised multiresolution analysis](https://doi.org/10.1016/j.ecolind.2018.03.026). Ecological Indicators, 90, 346–355
## Citing this work
If you find `scikit-maad` usefull for your research, please consider citing it as:
- Ulloa, J. S., Haupert, S., Latorre, J. F., Aubin, T., & Sueur, J. (2021). scikit‐maad: An open‐source and modular toolbox for quantitative soundscape analysis in Python. Methods in Ecology and Evolution, 2041-210X.13711. https://doi.org/10.1111/2041-210X.13711
or use our [citing file](https://raw.githubusercontent.com/scikit-maad/scikit-maad/production/CITATION.bib) for custom citation formats.
## Feedback and contributions
Improvements and new features are greatly appreciated. If you would like to contribute submitting issues, developing new features or making improvements to `scikit-maad`, please refer to our [contributors guide](https://raw.githubusercontent.com/scikit-maad/scikit-maad/production/CONTRIBUTING.md).
To create a positive social atmosphere for our community, we ask contributors to adopt and enforce our [code of conduct](https://raw.githubusercontent.com/scikit-maad/scikit-maad/production/CODE_OF_CONDUCT.md).
## About the project
In 2018, we began to translate a set of audio processing functions from Matlab to an open-source programming language, namely, Python. These functions provided the necessary tools to replicate the Multiresolution Analysis of Acoustic Diversity (MAAD), a method to estimate animal acoustic diversity using unsupervised learning (Ulloa et al., 2018). We soon realized that Python provided a suitable environment to extend these core functions and to develop a flexible toolbox for our research. During the past few years, we added over 50 acoustic indices, plus a module to estimate the sound pressure level of audio events. Furthermore, we updated, organized, and fully documented the code to make this development accessible to a much wider audience. This work was initiated by [Juan Sebastian Ulloa](https://www.researchgate.net/profile/Juan_Ulloa), supervised by Jérôme Sueur and Thierry Aubin at the [Muséum National d'Histoire Naturelle](http://isyeb.mnhn.fr/fr) and the [Université Paris Saclay](http://neuro-psi.cnrs.fr/) respectively. Python functions have been added by [Sylvain Haupert](https://www.researchgate.net/profile/Sylvain_Haupert), [Juan Felipe Latorre](https://www.researchgate.net/profile/Juan_Latorre_Gil) ([Universidad Nacional de Colombia](https://unal.edu.co/)) and Juan Sebastián Ulloa ([Instituto de Investigación de Recursos Biológicos Alexander von Humboldt](http://www.humboldt.org.co/)). For an updated list of collaborators, check the [contributors list](https://github.com/scikit-maad/scikit-maad/graphs/contributors).
## License
To support reproducible research, the package is released under the [BSD open-source licence](https://raw.githubusercontent.com/scikit-maad/scikit-maad/production/LICENSE.md), which allows unrestricted redistribution for commercial and private use.
Raw data
{
"_id": null,
"home_page": null,
"name": "scikit-maad",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "ecoacoustics, bioacoustics, ecology, sound pressure level, signal processing",
"author": null,
"author_email": "scikit-maad developers <scikit.maad@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/7a/ed/7b4f6e3be74a33cdc5a385f5c8251567c16184b011a775f2fc031e120d19/scikit_maad-1.4.1.tar.gz",
"platform": null,
"description": "\n# scikit-maad\n\n<div align=\"center\">\n <img src=\"https://raw.githubusercontent.com/scikit-maad/scikit-maad/production/docs/logo/maad_key_visual_blue.png\" alt=\"scikit-maad logo\"/>\n</div>\n\n**scikit-maad** is an open source Python package dedicated to the quantitative analysis of environmental audio recordings. This package was designed to \n1. load and process digital audio, \n2. segment and find regions of interest, \n3. compute acoustic features, and \n4. estimate sound pressure level. \n\nThis workflow opens the possibility to scan large audio datasets and use powerful machine learning techniques, allowing to measure acoustic properties and identify key patterns in all kinds of soundscapes.\n\n[](https://zenodo.org/badge/latestdoi/148142520)\n[](https://pepy.tech/project/scikit-maad)\n[](https://badge.fury.io/py/scikit-maad)\n[](https://www.repostatus.org/#active)\n[](https://GitHub.com/Naereen/StrapDown.js/graphs/commit-activity)\n[](https://juleskreuer.eu/projekte/citation-badge/)\n<!--[](https://www.python.org/downloads/release/python-360/)-->\n\n## Operating Systems\n\n`scikit-maad` seamlessly supports Linux, macOS, and Windows operating systems.\n\n## Interpreter\n\n`scikit-maad` requires one of these interpreters:\n\n- Python >= 3.8 < 3.11\n\n## Packages dependency\n\n`scikit-maad` requires these Python packages to run:\n\n- matplotlib >=3.6\n- numpy >= 1.21\n- pandas >= 1.5\n- resampy >= 0.4\n- scikit-image >= 0.19\n- scipy >= 1.8\n\n## Installing from PyPI\n\n`scikit-maad` is hosted on PyPI. The easiest way to install the package is using `pip` the standard package installer for Python:\n\n```bash\n$ pip install scikit-maad\n```\n\n## Quick start\n\nThe package is imported as `maad`. To use scikit-maad tools, audio must be loaded as a numpy array. The function `maad.sound.load` is a simple and effective way to load audio from disk. For example, download the [spinetail audio example](https://raw.githubusercontent.com/scikit-maad/scikit-maad/production/data/spinetail.wav) to your working directory. You can load it and then apply any analysis to find regions of interest or characterize your audio signals:\n\n```python\nfrom maad import sound, rois\ns, fs = sound.load('spinetail.wav')\nrois.find_rois_cwt(s, fs, flims=(4500,8000), tlen=2, th=0, display=True)\n```\n## For advance users\n### Installing from source\n\nIf you are interested in developing new features for `scikit-maad` or working with the latest version, clone and install it:\n\n```bash\n$ git clone https://github.com/scikit-maad/scikit-maad.git\n$ cd scikit-maad\n$ pip install --editable .\n```\n\n### Running tests\n\nInstall the test requirements:\n\n```bash\n$ pip install pytest\n```\n\nAnd run the tests:\n\n```bash\n$ cd scikit-maad\n$ pytest\n```\n\n## Examples and documentation\n- See https://scikit-maad.github.io for a complete reference manual and example gallery.\n\nRunnin all examples requires to install the following packages :\n- `scikit-learn`, a popular Python package for machine learning: [link](https://scikit-learn.org/stable/install.html)\n- `librosa`, a popular package for audio and music analysis: [link](https://librosa.org/doc/latest/install.html)\n- `tqdm`, a package that provides a fast, extensible progress bar for loops and other iterable tasks: [link](https://pypi.org/project/tqdm/)\n \n- In depth information related to the Multiresolution Analysis of Acoustic Diversity implemented in scikit-maad was published in: Ulloa, J. S., Aubin, T., Llusia, D., Bouveyron, C., & Sueur, J. (2018). [Estimating animal acoustic diversity in tropical environments using unsupervised multiresolution analysis](https://doi.org/10.1016/j.ecolind.2018.03.026). Ecological Indicators, 90, 346\u2013355\n\n## Citing this work\n\nIf you find `scikit-maad` usefull for your research, please consider citing it as:\n\n- Ulloa, J. S., Haupert, S., Latorre, J. F., Aubin, T., & Sueur, J. (2021). scikit\u2010maad: An open\u2010source and modular toolbox for quantitative soundscape analysis in Python. Methods in Ecology and Evolution, 2041-210X.13711. https://doi.org/10.1111/2041-210X.13711\n\nor use our [citing file](https://raw.githubusercontent.com/scikit-maad/scikit-maad/production/CITATION.bib) for custom citation formats.\n\n## Feedback and contributions\nImprovements and new features are greatly appreciated. If you would like to contribute submitting issues, developing new features or making improvements to `scikit-maad`, please refer to our [contributors guide](https://raw.githubusercontent.com/scikit-maad/scikit-maad/production/CONTRIBUTING.md). \nTo create a positive social atmosphere for our community, we ask contributors to adopt and enforce our [code of conduct](https://raw.githubusercontent.com/scikit-maad/scikit-maad/production/CODE_OF_CONDUCT.md).\n\n## About the project\nIn 2018, we began to translate a set of audio processing functions from Matlab to an open-source programming language, namely, Python. These functions provided the necessary tools to replicate the Multiresolution Analysis of Acoustic Diversity (MAAD), a method to estimate animal acoustic diversity using unsupervised learning (Ulloa et al., 2018). We soon realized that Python provided a suitable environment to extend these core functions and to develop a flexible toolbox for our research. During the past few years, we added over 50 acoustic indices, plus a module to estimate the sound pressure level of audio events. Furthermore, we updated, organized, and fully documented the code to make this development accessible to a much wider audience. This work was initiated by [Juan Sebastian Ulloa](https://www.researchgate.net/profile/Juan_Ulloa), supervised by J\u00e9r\u00f4me Sueur and Thierry Aubin at the [Mus\u00e9um National d'Histoire Naturelle](http://isyeb.mnhn.fr/fr) and the [Universit\u00e9 Paris Saclay](http://neuro-psi.cnrs.fr/) respectively. Python functions have been added by [Sylvain Haupert](https://www.researchgate.net/profile/Sylvain_Haupert), [Juan Felipe Latorre](https://www.researchgate.net/profile/Juan_Latorre_Gil) ([Universidad Nacional de Colombia](https://unal.edu.co/)) and Juan Sebasti\u00e1n Ulloa ([Instituto de Investigaci\u00f3n de Recursos Biol\u00f3gicos Alexander von Humboldt](http://www.humboldt.org.co/)). For an updated list of collaborators, check the [contributors list](https://github.com/scikit-maad/scikit-maad/graphs/contributors).\n\n## License\nTo support reproducible research, the package is released under the [BSD open-source licence](https://raw.githubusercontent.com/scikit-maad/scikit-maad/production/LICENSE.md), which allows unrestricted redistribution for commercial and private use.\n",
"bugtrack_url": null,
"license": null,
"summary": "Open-source and modular toolbox for quantitative soundscape analysis in Python",
"version": "1.4.1",
"project_urls": {
"Documentation": "https://scikit-maad.github.io/",
"Home": "https://github.com/scikit-maad/scikit-maad",
"Source": "https://github.com/scikit-maad/scikit-maad",
"Tracker": "https://github.com/scikit-maad/scikit-maad/issues"
},
"split_keywords": [
"ecoacoustics",
" bioacoustics",
" ecology",
" sound pressure level",
" signal processing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "dbc9f89050ae21c286d3216c88a23b8445e2d26066aa8467754902c156c1dbd9",
"md5": "556858ded7fddaf0771fbdf73ad98ef9",
"sha256": "b94b08dc118876ca91454c1afe8261d78228b84f5a03ef4b494c67c5f8fa95f2"
},
"downloads": -1,
"filename": "scikit_maad-1.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "556858ded7fddaf0771fbdf73ad98ef9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 157582,
"upload_time": "2024-03-27T17:21:56",
"upload_time_iso_8601": "2024-03-27T17:21:56.769713Z",
"url": "https://files.pythonhosted.org/packages/db/c9/f89050ae21c286d3216c88a23b8445e2d26066aa8467754902c156c1dbd9/scikit_maad-1.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7aed7b4f6e3be74a33cdc5a385f5c8251567c16184b011a775f2fc031e120d19",
"md5": "45cb87433aa3e5790740ba3e588b2f21",
"sha256": "cb95f9856f7b9625bafa24add44301e0f69d59a4d1bfc4d607f0f5c7f8e94e1e"
},
"downloads": -1,
"filename": "scikit_maad-1.4.1.tar.gz",
"has_sig": false,
"md5_digest": "45cb87433aa3e5790740ba3e588b2f21",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 148103,
"upload_time": "2024-03-27T17:22:14",
"upload_time_iso_8601": "2024-03-27T17:22:14.486906Z",
"url": "https://files.pythonhosted.org/packages/7a/ed/7b4f6e3be74a33cdc5a385f5c8251567c16184b011a775f2fc031e120d19/scikit_maad-1.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-27 17:22:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "scikit-maad",
"github_project": "scikit-maad",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "scikit-maad"
}
JSON
