Biologger Pseudotrack Documentation

Python pipeline for processing biologger sensor data from marine animals

Biologger Pseudotrack processes accelerometer, magnetometer, and gyroscope data from animal-borne tags to generate pseudotracks (dead-reckoning trajectories) and infer behavioral states. The pipeline supports both real-time adaptive sensor fusion for field deployments and post-facto batch analysis for scientific publications.

Python Version License GitHub Repository

Features

✅ From Lab to Deployment: Dual Processing Pipelines

  • Post-Facto: Non-causal batch analysis for validation and scientific publications

  • Adaptive Sensor Fusion: Real-time causal processing for field deployments

✅ Modular Sensor Fusion Architecture

  • Pluggable fusion algorithm interface for custom implementations

  • Accelerometer/magnetometer calibration, correction, and integration for 3D track estimation

  • Online adaptive attachment angle calibration with convergence detection

  • Hard-iron magnetometer calibration with sphere-fitting

  • In progress: Madgwick-inspired filter (accelerometer/magnetometer only; full Madgwick when gyroscope available)

  • In progress: Kalman filter (optimal state estimation)

✅ Data-Driven Behavioral Classification

  • Unsupervised HMM-based state discovery (no species assumptions)

  • Threshold classifiers for fast activity-level detection

  • Pluggable classifier interface for custom implementations

  • Post-hoc interpretation: states emerge from data, not predefined categories

✅ Production-Ready

  • Fixed memory footprint, O(1) space complexity (adaptive mode)

  • Target: 300-500 records/second (single core, x86)

  • Target: TBD records/second (multi-core / Jetson Nano - placeholder)

  • Comprehensive logging and performance telemetry

Quick Start

# Install from source
git clone https://github.com/lhzn-io/biologger-pseudotrack.git
cd biologger-pseudotrack
pip install -e .

# Process swordfish deployment
python -m biologger_pseudotrack --config examples/swordfish_config.yml

See Getting Started for detailed installation and usage instructions.

Documentation

Contents

Species Supported

Pre-configured processing pipelines for:

  • Swordfish (Xiphias gladius) - Deep diving pelagic predator

  • Whale Shark (Rhincodon typus) - Filter feeding ram ventilator

Custom species configurations can be created via YAML configuration files.

Scientific Background

This package implements dead-reckoning algorithms for reconstructing animal movement from biologger sensor data, building on foundational work in marine biologging and movement ecology.

Key Publications:

Acknowledgments

This project is developed in support of the WHOI Marine Predators Group under the direction of Dr. Camrin D. Braun.

Research on satellite telemetry, species distribution modeling, and geolocation methods for marine animals provides the scientific foundation for this pipeline:

License

MIT License - Copyright © 2025

Contact

Indices and tables