Skip to content

WIP

Thanks for your interest in PBP. This documentation is still a work in progress 🚧. Please get in touch if you have any questions or suggestions.

MBARI PBP

The mbari-pbp package allows to process ocean audio data archives to daily analysis products of hybrid millidecade spectra using PyPAM.

You can use PBP by directly running the included CLI the programs, as well as a dependency in your own Python code.

Features:

  • Audio metadata extraction for managed timekeeping
    • Start and duration of recognized wav and flac sound files either locally or in cloud (JSON)
    • Coverage plot of sound recordings
  • Audio file processing
    • Frequency and psd array output
    • Concatenation of processed 1-minute segments for daily product
    • Calibration with given sensitivity file (NetCDF), or flat sensitivity value
  • Data products
    • NetCDF with metadata
    • Summary plot
  • Cloud processing
    • Inputs can be downloaded from and uploaded to S3
    • Inputs can be downloaded from public GCS bucket
    • Outputs can be uploaded to GCS

Installation

You will use a shell (terminal on macOS or Linux, PowerShell on Windows) to run audio data processing jobs using PBP.

We recommend installing PBP using Conda. If you already have Anaconda installed, you can use it. If not, download and install Miniconda for your operating system. Miniconda is all that is needed, and it is about one tenth the size of a full Anaconda installation. After installation, on some systems, you can confirm that conda is available with:

which conda

Create a directory where you will install the PBP software, for example: /Users/YourUserName/pbp.

Create an environment.yml file in the pbp directory, with this content: 

name: pbp
channels:
  - conda-forge
dependencies:
  - python=3.11
  - hdf5
  - netcdf4
  - libsndfile
  - pip
  - pip:
      - mbari-pbp

From within the terminal, while you are in your newly created pbp directory, issue this command: 

conda env create

Activate your PBP processing environment with this command: 

conda activate pbp

Notice that the prompt of the shell was augmented with (pbp) preceding the original prompt.

You can check the PBP version: 

pbp-hmb-gen --version

You are now ready to process passive acoustic monitoring data to hybrid millidecade spectra using PBP.

Typically, within this top level directory for processing, you will also have a metadata directory (calibration data for hydrophones, etc.), and scripts for processing (shell scripts or python scripts). PBP creates some directory structures as needed during initial operation (json directory for storing temporal metadata for processing jobs).

Updating PBP

To update PBP to the latest version, while your pbp conda environment is activated, run this command: 

pip install --upgrade mbari-pbp

If changes are needed to the conda environment (for example, new dependencies), after revising the environment.yml file, you can update the pbp conda environment with this command: 

conda env update

If you want to install the package from source and have already installed with the pip install mbari-pbp command, you can install the package from source with the following command. This will get the latest version 🚧 from the main branch. 

pip install --no-cache-dir --force-reinstall git+https://github.com/mbari-org/pbp.git

Programs

The package includes the following CLI programs:

Program Description
pbp-meta-gen Generate JSON files with audio metadata.
pbp-hmb-gen Main HMB generation program.
pbp-cloud Program for cloud based processing.
pbp-hmb-plot Utility program to plot resulting HMB product.

References