pypam is a python package to analyze underwater sound.
It is made to make easier the processing of underwater data stored in audio files in chunks.
The main classes are AcousticFile, AcousticSurvey and DataSet. The first one is a representation of an audio file
together with all the metadata needed to process the data (such as hydrophone used).
The second one is the representation of a folder where all the files are stored for one deployment.
Here we consider a deployment as a measurement interval corresponding to the time when a hydrophone was in the water,
without changing any recording parameters.
The Dataset is a combination of different AcousticSurveys in one dataset. This is to be used if the user has made
several deployments and wants to process them with the same parameters.
Then pypam allows to go through all the audio files from the deployments only with one line of code and store
the output in netCDF files, including metadata. The package can be used to analyze a single file,
a folder with files or a group of different deployments.
pypam deals with the calibration directly, so the output obtained is already in uPa or dB!
All the documentation can be found on readthedocs
Warning This package is under active development, use with caution.
Installation
Using pip distribution
pip install lifewatch-pypam
Using git clone
- Clone the package
git clone https://github.com/lifewatch/pypam.git
- Use poetry to install the project dependencies
poetry install - Build the project
poetry build
News from version 0.3.0
In version 0.2.0 we removed the detectors, because there are better maintained packages for these purposes. In version 0.2.1 we added the frequency-dependent calibration! In version 0.3.0 we changed quite some plot function to make them more flexible with other data products. We also changed the mean functions to median, so the output in db is the same than the output in uPa
Quickstart
The package is imported as pypam. The audio file names must comply with the needs of
pyhydrophone to be able to read the datetime information.
The user can choose a window chunk size (parameter binsize, in seconds), so all the features / methods are applied to that window. If set to None, the operations are performed along an entire file.
The available methods and features are:
- Acoustic Indices:
- ACI
- BI
- SH
- TH
- NDSI
- AEI
- ADI
- Zero crossing (average)
- BN peaks
- time-domain features:
- rms
- dynamic_range
- sel
- peak
- rms_envelope
- spectrum_slope
- correlation coefficient
- frequency-domain
- spectrogram (also octave bands spectrogram)
- spectrum (density or power)
- 1/n-octave bands
- hybrid millidecade bands
- long-term spectrogram
- time and frequency
- SPD
Futhermore, there are several plotting functions
- SPD
- spectrum with standard deviation
- boxplots of time series aggregated data
- daily patterns
- LTSA
and some signal-based operations:
- Signal operations
- Noise reduction
- Downsample
- Band filter
- Envelope
- DC noise removal
PyPAM wrappers
PBP (PyPAM Based Processing) is a wrapper for PyPAM to make its use to compute hybrid millidecade bands more effective. PBP allows for local or cloud computing. For more information, you can find it in this repository.
Examples and documentation
See the documentation in readthedocs for a complete reference manual and example gallery.
In this collection of notebooks, some extra examples can be found of how to use pypam (under development).
Under development
Planned:
- Add function to generate files per included folder (too big deployments)
- Add options for the user to choose what to do when the blocksize is not multiple of the frames, and to deal with time keeping
- Add a logger that logs the code that was run and the warnings together with the output
- Add deep learning feature extraction (vggish and compatibility with koogu and AVES)
- Add parallel processing options
- Add support for frequency calibration
- Support for reading detections
Cite
Parcerisas, C. (2023). PyPAM: a package to process long-term underwater acoustics data in chunks (0.3.0). Zenodo. https://doi.org/10.5281/zenodo.10037826
Acknowledgements
We want to thank Stan Panier for the beautiful logo. This project was possible due to the funding on LifeWatch Belgium
Metadata
Release files for lifewatch-pypam 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| lifewatch_pypam-1.0.0.tar.gz | 63.1 kB | Without provenance | Details for lifewatch_pypam-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| lifewatch_pypam-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for lifewatch_pypam-1.0.0-py3-none-any.whl |
Total release size: 131.9 kB
Release files / lifewatch_pypam-1.0.0.tar.gz
| Download URL | lifewatch_pypam-1.0.0.tar.gz |
|---|---|
| Size | 63.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
514ccb02955f7a465cf712f801b240b05ba1523fb1e74a1ce46ef7863b07a530
|
|
BLAKE2b-256 checksum How to use checksums |
9dda357f45a5502d9409ef16953546384792f99bc602de72efafbee7f559da3f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.4.1 CPython/3.12.3 Linux/6.8.0-117-generic
|
Release files / lifewatch_pypam-1.0.0-py3-none-any.whl
| Download URL | lifewatch_pypam-1.0.0-py3-none-any.whl |
|---|---|
| Size | 68.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
76b8c3c453d3fedaa9bef9c1d4a911814e9f1ab1b3b1d1628403e086dac685c3
|
|
BLAKE2b-256 checksum How to use checksums |
8183eeeacca5b0c8f597d815ccf1bb859bccd03722140fdc32f0a8150b378aef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.4.1 CPython/3.12.3 Linux/6.8.0-117-generic
|
Security for lifewatch-pypam 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.