Data

Tools

Indexes

Applications

Experiments

Open Source Science

lifewatch-pypam

Python Passive Acoustic Analysis tool for Passive Acoustic Monitoring (PAM)

https://github.com/lifewatch/pypam

Science Score: 67.0%

This score indicates how likely this project is to be science-related based on various indicators:

  • ✓
    CITATION.cff file
    Found CITATION.cff file
  • ✓
    codemeta.json file
    Found codemeta.json file
  • ✓
    .zenodo.json file
    Found .zenodo.json file
  • ✓
    DOI references
    Found 5 DOI reference(s) in README
  • ✓
    Academic publication links
    Links to: zenodo.org
  • ○
    Committers with academic emails
  • ○
    Institutional organization owner
  • ○
    JOSS paper metadata
  • ○
    Scientific vocabulary similarity
    Low similarity (17.7%) to scientific vocabulary
Last synced: 6 months ago · JSON representation ·

Repository

Python Passive Acoustic Analysis tool for Passive Acoustic Monitoring (PAM)

Basic Info
  • Host: GitHub
  • Owner: lifewatch
  • License: gpl-3.0
  • Language: Python
  • Default Branch: main
  • Size: 78.1 MB
Statistics
  • Stars: 46
  • Watchers: 11
  • Forks: 8
  • Open Issues: 22
  • Releases: 8
Created almost 5 years ago · Last pushed 8 months ago
Metadata Files
Readme License Citation

README.md


main PyPI Downloads DOI

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

bash pip install lifewatch-pypam

Using git clone

  1. Clone the package bash git clone https://github.com/lifewatch/pypam.git
  2. Use poetry to install the project dependencies bash poetry install
  3. Build the project bash 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 - dynamicrange - sel - peak - rmsenvelope - 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


Owner

  • Name: LifeWatch.be
  • Login: lifewatch
  • Kind: organization
  • Email: info@lifewatch.be
  • Location: Belgium

Citation (CITATION.cff) 

cff-version: 1.2.0
message: "If you use this software, please cite it as below."
authors:
  - family-names: Parcerisas
    given-names: Clea
    orcid: https://orcid.org/0000-0001-7466-0288
title: "PyPAM: a package to process long-term underwater acoustics data in chunks"
version: 0.1.10
doi: 10.5281/zenodo.7584847
date-released: 2023-03-16

GitHub Events

Total
  • Create event: 4
  • Release event: 1
  • Issues event: 13
  • Watch event: 11
  • Delete event: 11
  • Issue comment event: 26
  • Push event: 34
  • Pull request review event: 1
  • Pull request event: 22
Last Year
  • Create event: 4
  • Release event: 1
  • Issues event: 13
  • Watch event: 11
  • Delete event: 11
  • Issue comment event: 26
  • Push event: 34
  • Pull request review event: 1
  • Pull request event: 22

Committers

Last synced: almost 3 years ago

All Time
  • Total Commits: 258
  • Total Committers: 7
  • Avg Commits per committer: 36.857
  • Development Distribution Score (DDS): 0.473
Top Committers
Name Email Commits
Clea Parcerisas c****p@v****e 136
Clea Parcerisas c****s@g****m 71
Carlos Rueda c****a@m****g 27
Clea Parcerisas c****s@v****e 13
Paul Focke p****e@v****e 5
dependabot[bot] 4****]@u****m 4
Bart Vanhoorne b****e@v****e 2
Committer Domains (Top 20 + Academic)
vliz.be: 4 mbari.org: 1

Issues and Pull Requests

Last synced: 6 months ago

All Time
  • Total issues: 56
  • Total pull requests: 97
  • Average time to close issues: 3 months
  • Average time to close pull requests: 2 days
  • Total issue authors: 9
  • Total pull request authors: 6
  • Average comments per issue: 1.05
  • Average comments per pull request: 0.3
  • Merged pull requests: 88
  • Bot issues: 0
  • Bot pull requests: 34
Past Year
  • Issues: 5
  • Pull requests: 18
  • Average time to close issues: N/A
  • Average time to close pull requests: 6 days
  • Issue authors: 4
  • Pull request authors: 4
  • Average comments per issue: 0.0
  • Average comments per pull request: 0.06
  • Merged pull requests: 11
  • Bot issues: 0
  • Bot pull requests: 7
View more stats
Top Authors
Issue Authors
  • cparcerisas (28)
  • carueda (13)
  • SimLrt32 (6)
  • ryjombari (3)
  • JeroHub (2)
  • LennertSchepers (1)
  • JPalmerK (1)
  • bramcuyx (1)
  • silviaurraa (1)
  • dependabot[bot] (1)
  • caplinje-NOAA (1)
Pull Request Authors
  • dependabot[bot] (50)
  • cparcerisas (35)
  • carueda (14)
  • SimLrt32 (12)
  • JotaFan (5)
  • caplinje-NOAA (3)
Top Labels
Issue Labels
enhancement (16) bug (9) dependencies (5) documentation (2) question (1)
Pull Request Labels
dependencies (50) python (4) documentation (2)

Packages

  • Total packages: 1
  • Total downloads:
    • pypi 273 last-month
  • Total dependent packages: 1
  • Total dependent repositories: 1
  • Total versions: 11
  • Total maintainers: 1
pypi.org: lifewatch-pypam

Facilitate acoustic processing from underwater acoustic recorders

  • Versions: 11
  • Dependent Packages: 1
  • Dependent Repositories: 1
  • Downloads: 273 Last month
Rankings
Dependent packages count: 10.1%
Stargazers count: 13.3%
Forks count: 14.2%
Average: 18.8%
Dependent repos count: 21.6%
Downloads: 34.9%
Maintainers (1)
cparcerisas
Last synced: 7 months ago

Dependencies

.github/workflows/ci.yml actions
  • actions/checkout v3 composite
  • actions/setup-python v4 composite
.github/workflows/publish.yml actions
  • JRubics/poetry-publish v1.17 composite
  • actions/checkout v3.5.2 composite
poetry.lock pypi
  • 134 dependencies
pyproject.toml pypi
  • black ^23.3.0
  • certifi ^2023.7.22
  • coverage ^7.2.5
  • cryptography ^41.0.2
  • isort ^5.12.0
  • matplotlib ^3.7.1
  • netcdf4 ^1.6.4
  • noisereduce ^2.0.1
  • numba ^0.57.0
  • numpy ^1.24.3
  • openpyxl ^3.1.2
  • pandas ^2.0.2
  • poetry ^1.5.0
  • pre-commit ^3.3.1
  • pyhydrophone ^0.1.7
  • pytest ^7.3.1
  • pytest-cov ^4.1.0
  • python >=3.8.1, <3.12.0
  • python-dateutil ^2.8.2
  • python-dotenv ^1.0.0
  • pyyaml ^6.0
  • scikit-learn ^1.2.2
  • scikit-maad ^1.4.0
  • seaborn ^0.12.2
  • setuptools ^68.1.0
  • soundfile ^0.12.1
  • syrupy ^4.0.4
  • tqdm ^4.65.0
  • xarray 2023.01.0