Shearwater Dive Analysis

This page provides Python scripts for analysing biologging data downloaded from BiP, particularly depth, temperature, and acceleration data recorded from seabirds, with a particular focus on shearwaters. The workflow consists of three scripts: watersurface.py for water-surface offset correction, dive_parameter_analysis.py for dive detection and parameter extraction, and CWT_profile_dual.py for continuous wavelet transform (CWT) analysis of selected acceleration signals.

Quick Start

  1. Download and run watersurface.py to correct near-surface depth offset.
  2. Run dive_parameter_analysis.py to detect dives and calculate dive parameters.
  3. Run CWT_profile_dual.py to examine time–frequency structure in selected acceleration signals during focal dive periods.

For first-time users, we recommend following the scripts in this order and reading the corresponding user guides before running each script.

Available Scripts and User Guides

Recommended Workflow

  1. watersurface.py: correct near-surface depth offset before dive analysis.
  2. dive_parameter_analysis.py: detect dives and calculate dive-by-dive metrics.
  3. CWT_profile_dual.py: analyse oscillatory acceleration patterns during selected dive periods.

Expected Input Data

These scripts are intended for BiP-derived CSV files and assume BiP-compatible column names. Typical required variables include:

  • time
  • depth
  • temperature (required for some workflows, optional for others)
  • acceleration_longitudinal
  • acceleration_dorso_ventral
  • acceleration_lateral (if available)

Depending on the logger and BiP export format, equivalent acceleration column names may also be supported. Please check each user guide for details.

Requirements

These scripts were developed in Anaconda (tested with conda 25.1.0). Please install the required Python libraries before running the scripts.

Required libraries by script

  • watersurface.py: numpy, pandas, matplotlib
  • dive_parameter_analysis.py: numpy, pandas, matplotlib
  • CWT_profile_dual.py: numpy, pandas, matplotlib, PyWavelets

If these libraries are not yet installed, they can be installed in a dedicated conda environment as shown below.

Important Note on Environment Compatibility

Environment compatibility errors may occur when the installed NumPy version (for example, 2.x) does not match the version against which internal C-extension modules used by packages such as pandas or pyarrow were compiled (often 1.x). To avoid these dependency conflicts, we strongly recommend creating a dedicated Anaconda environment for BiP analysis.

Recommended Solution: Create a Dedicated Anaconda Environment

Modifying the existing base environment may affect other projects. It is therefore safer to create a separate environment for BiP-related analyses.

1. Create a new environment

conda create -n bip-analysis python=3.11 numpy=1.26.4 pandas matplotlib pywavelets -y

2. Activate the environment

conda activate bip-analysis

3. Run the scripts

python watersurface.py
python dive_parameter_analysis.py
python CWT_profile_dual.py

Usage Notes

  • Please read the corresponding user guide before running each script.
  • CWT analysis should generally be restricted to periods in which dives are known to occur. Running CWT_profile_dual.py over the full deployment can be computationally intensive and may make the resulting time–frequency plots harder to interpret.
  • A practical strategy is to first identify dive periods using dive_parameter_analysis.py or the overview time series, and then apply CWT_profile_dual.py only to the focal interval.
  • The scripts are intended for BiP-derived CSV files and assume BiP-compatible column names.
  • Outputs include CSV files and diagnostic figures that should be checked visually before interpreting the results.

Citation and Reproducibility

If you use these scripts in a publication, please cite the associated study and indicate that the scripts and user guides were obtained from the BiP Help portal. For reproducibility, we also recommend reporting the script name, version, and download date used in the analysis.