Metadata-Version: 2.1
Name: lifewatch-pypam
Version: 0.3.0
Summary: Facilitate acoustic processing from underwater acoustic recorders
Home-page: https://github.com/lifewatch/pypam.git
License: GPL-3.0-or-later
Author: Clea Parcerisas
Author-email: cleap@vliz.be
Requires-Python: >=3.9,<3.12.0
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: tests
Requires-Dist: black (>=23.3.0,<24.0.0) ; extra == "dev"
Requires-Dist: certifi (>=2023.7.22,<2024.0.0)
Requires-Dist: coverage (>=7.2.5,<8.0.0) ; extra == "tests"
Requires-Dist: cryptography (>=41.0.2,<42.0.0)
Requires-Dist: dask (>=2023.9.3,<2024.0.0)
Requires-Dist: isort (>=5.12.0,<6.0.0) ; extra == "dev"
Requires-Dist: matplotlib (>=3.7.1,<4.0.0)
Requires-Dist: netcdf4 (>=1.6.4,<2.0.0)
Requires-Dist: noisereduce (>=2.0.1,<3.0.0)
Requires-Dist: numba (>=0.57.0,<0.58.0)
Requires-Dist: numpy (>=1.24.3,<2.0.0)
Requires-Dist: openpyxl (>=3.1.2,<4.0.0)
Requires-Dist: pandas (>=2.0.2,<3.0.0)
Requires-Dist: poetry (>=1.5.0,<2.0.0)
Requires-Dist: pre-commit (>=3.3.1,<4.0.0) ; extra == "dev"
Requires-Dist: pyhydrophone (>=0.1.7,<0.2.0)
Requires-Dist: pytest (>=7.3.1,<8.0.0) ; extra == "tests"
Requires-Dist: pytest-cov (>=4.1.0,<5.0.0) ; extra == "tests"
Requires-Dist: python-dateutil (>=2.8.2,<3.0.0)
Requires-Dist: python-dotenv (>=1.0.0,<2.0.0) ; extra == "tests"
Requires-Dist: pyyaml (>=6.0,<7.0) ; extra == "tests"
Requires-Dist: scikit-learn (>=1.2.2,<2.0.0)
Requires-Dist: scikit-maad (>=1.4.0,<2.0.0)
Requires-Dist: seaborn (==0.13.0)
Requires-Dist: setuptools (>=68.1.0,<69.0.0)
Requires-Dist: soundfile (>=0.12.1,<0.13.0)
Requires-Dist: syrupy (>=4.0.4,<5.0.0)
Requires-Dist: tqdm (>=4.65.0,<5.0.0)
Requires-Dist: xarray (==2023.8.0)
Project-URL: Repository, https://github.com/lifewatch/pypam.git
Description-Content-Type: text/markdown

# PyPAM
`pypam` is a python package to analyze underwater sound. 
It is made to make easier the processing of underwater data stored in audio files. 
The main classes are AcousticFile, AcousticSurvey and DataSet. The first one is a representation of a 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](https://lifewatch-pypam.readthedocs.io)

> **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 files must comply with the needs of 
[pyhydrophone](https://github.com/lifewatch/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

## Examples and documentation
See the documentation in [readthedocs](https://lifewatch-pypam.readthedocs.io) for a complete reference manual and 
example gallery. 

## 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 features (vggish and compatibility with koogu and AVES)
- Add parallel processing options 
- Add support for frequency calibration
- Support for reading detections 


## Cite
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.6044593.svg)](https://doi.org/10.5281/zenodo.6044593)

