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 dive detection and acceleration-based profiling to trip analysis and First Passage Time (FPT) analysis.

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

Dive and acceleration analysis

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

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, and flight/landing time budgets.
  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)

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

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

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 watersurface.py
python dive_parameter_analysis.py
python CWT_profile_dual.py
python trip_parameter_analysis.py
python FPT_analysis.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.
• 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.

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.