soundscapy 0.8.2

A python library for analysing and visualising soundscape assessments.

Soundscapy

A python library for analysing and visualising soundscape assessments.

Installation

Soundscapy can be installed with pip:

pip install soundscapy

Upgrading from 0.7.x? v0.8.2 is the long-overdue stable release that consolidates the entire v0.8.0rc* and v0.8.2.dev* pre-release line. Several APIs have changed (most notably the new ISOPlot plotting API). See the migration guide before upgrading.

Optional Dependencies

Soundscapy splits its functionality into optional modules to reduce the number of dependencies required for basic functionality. By default, Soundscapy includes the survey data processing and plotting functionality.

If you would like to use the binaural audio processing and psychoacoustics functionality, you will need to install the optional audio dependency:

pip install "soundscapy[audio]"

If you would like to use the R-backed SPI and SATP functionality, install the optional r dependency:

pip install "soundscapy[r]"

R-backed features also require a local R installation and the external sn R package:

R -q -e "install.packages('sn')"

CircE is bundled with Soundscapy as embedded R scripts, so you do not need to install CircE separately from GitHub.

To install all optional dependencies, use the following command:

pip install "soundscapy[all]"

Examples

We are currently working on writing more comprehensive examples and documentation, please bear with us in the meantime.

Tutorials for using Soundscapy can be found in the documentation.

Acknowledgements

The newly added Binaural analysis functionality relies directly on three acoustic analysis libraries:

• Acoustic Toolbox for the standard environmental and building acoustics metrics,
• scikit-maad for the bioacoustics and ecological soundscape metrics, and
• MoSQITo for the psychoacoustics metrics. We thank each of these packages for their great work in making advanced acoustic analysis more accessible.

Citation

If you are using Soundscapy in your research, please help our scientific visibility by citing our work! Please include a citation to our accompanying paper:

Mitchell, A., Aletta, F., & Kang, J. (2022). How to analyse and represent quantitative soundscape data. JASA Express Letters, 2, 37201. https://doi.org/10.1121/10.0009794

Development Plans

Soundscapy is under active development as we add features and refine the API. The package now covers survey processing, the new layered ISOPlot plotting API, binaural and psychoacoustic audio analysis, and R-backed circumplex SEM (SATP) and Soundscape Perception Indices (SPI) modules. Some planned improvements are:

• Simplify the plotting options
• Possibly improve how the plots and data are handled - a more OOP approach would be good.
• Add appropriate tests and documentation.
• Bug fixes, particularly around setting color palettes.

Large planned feature additions are:

• Add better methods for cleaning datasets, including robust outlier exclusion and imputation.
• Add handling of .wav files.
• Integrate environmental acoustic and psychoacoustic batch processing. This will involve using existing packages (e.g. MoSQito, python-acoustics) to do the metric calculations, but adding useful functionality for processing any files at once, tieing them to a specific survey response, and implementing a configuration file for maintaining consistent analysis settings.
• Integrate the predictive modelling results from the SSID team's research to enable a single pipelined from recording -> psychoacoustics -> predicted soundscape perception (this is very much a pie-in-the-sky future plan, which may not be possible).

Contributing

If you would like to contribute or if you have any bugs you have found while using `Soundscapy', please feel free to get in touch or submit an issue or pull request!

Please see CONTRIBUTING.md for contribution guidelines.