Shearwater Biologging Data Analysis

This page provides a collection of Python scripts for analysing biologging data downloaded from BiP, focusing on movement, diving behaviour, and activity patterns of seabirds, particularly shearwaters. The scripts cover multiple data types, including GPS, depth, temperature, and acceleration data, and support analyses ranging from trip analysis and First Passage Time (FPT) analysis to dive detection and acceleration-based profiling.

The page includes several scripts that can be used independently or in combination:

GPS-based movement analysis

  • trip_parameter_analysis.py
    Identifies foraging trips based on GPS data and calculates trip-level metrics, including trip duration, maximum distance from the colony, total travel distance, flight/landing time budgets, and bearing to the maximum-distance point.
    Download script
    User guide (PDF)
  • FPT_analysis.py
    Performs First Passage Time (FPT) analysis using GPS trajectories to quantify area-restricted search (ARS) behaviour and identify characteristic spatial scales of movement.
    Download script
    User guide (PDF)

Dive and acceleration analysis

  • watersurface.py
    Applies water-surface offset correction to depth data, improving the accuracy of dive measurements.
    Download script (Coming soon)
    User guide (PDF): Coming soon
  • dive_parameter_analysis.py
    Detects dives, extracts dive parameters, calculates VeDBA-based metrics, and produces summary plots and CSV outputs.
    Download script (Coming soon)
    User guide (PDF): Coming soon
  • CWT_profile_dual.py
    Performs dual-signal continuous wavelet transform (CWT) analysis and produces overview and zoomed time–frequency plots.
    Download script (Coming soon)
    User guide (PDF): Coming soon

Together, these scripts provide an integrated framework for analysing biologging data across multiple temporal and spatial scales, enabling researchers to investigate both movement ecology (e.g., foraging trips and search strategies) and behavioural processes (e.g., diving and flight activity).

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

  • trip_parameter_analysis.py: pandas, numpy, matplotlib, pyproj
  • FPT_analysis.py: pandas, numpy, matplotlib, pyproj
  • watersurface.py: numpy, pandas, matplotlib
  • dive_parameter_analysis.py: pandas, numpy, matplotlib
  • CWT_profile_dual.py: pandas, numpy, 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 pyproj -y

2. Activate the environment

conda activate bip-analysis

3. Run the scripts

Run only the scripts relevant to the data types included in your BiP export.

python trip_parameter_analysis.py
python FPT_analysis.py

# Dive and acceleration scripts will be added later
# watersurface.py
# dive_parameter_analysis.py
# CWT_profile_dual.py

Usage Notes

  • Please read the corresponding user guide before running each script.
  • The scripts are intended for BiP-derived CSV files and assume BiP-compatible column names.
  • For GPS-based analyses, users should visually inspect the input track and output figures to confirm that abnormal positions or long recording gaps do not affect interpretation.
  • Outputs include CSV files and diagnostic figures that should be checked visually before interpreting the results.
  • Dive and acceleration analysis scripts will be released separately with their associated publication.

Citation and Reproducibility

If you use these scripts in a publication, please cite the relevant BiP paper 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.