.. Biologger Pseudotrack documentation master file

====================================
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.

.. image:: https://img.shields.io/badge/python-3.11+-blue.svg
   :target: https://www.python.org/downloads/
   :alt: Python Version

.. image:: https://img.shields.io/badge/license-MIT-green.svg
   :target: https://github.com/lhzn-io/biologger-pseudotrack/blob/main/LICENSE
   :alt: License

.. image:: https://img.shields.io/badge/github-lhzn--io/biologger--pseudotrack-181717.svg?logo=github
   :target: https://github.com/lhzn-io/biologger-pseudotrack
   :alt: 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
===========

.. code-block:: bash

   # 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 :doc:`getting_started` for detailed installation and usage instructions.

Documentation
=============

.. toctree::
   :maxdepth: 2
   :caption: Contents

   getting_started
   pipelines

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:**

- `Wilson et al. (2006) <https://doi.org/10.1111/j.1365-2656.2006.01127.x>`_ - Dynamic body acceleration and activity-specific metabolic rate
- `Shepard et al. (2008) <https://doi.org/10.3354/esr00084>`_ - Static vs dynamic acceleration separation
- `Leos-Barajas et al. (2016) <https://doi.org/10.1111/2041-210X.12657>`_ - HMM behavioral classification methodology

Acknowledgments
===============

This project is developed in support of the `WHOI Marine Predators Group <https://marinepredators.whoi.edu/>`_ 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:

- `Braun et al. (2023) <https://doi.org/10.1002/eap.2893>`_ - Building use-inspired species distribution models using multiple data types
- `Arostegui et al. (2024) <https://doi.org/10.1016/j.dsr.2024.104386>`_ - Advancing the frontier of fish geolocation into the ocean's midwaters
- `Arostegui et al. (2025) <https://doi.org/10.1093/icesjms/fsaf001>`_ - Argos satellite transmitters enable billfish research at finer scales

License
=======

MIT License - Copyright © 2025

Contact
=======

- **Maintainer**: Daniel Fry
- **Principal Investigator**: Dr. Camrin Braun (WHOI)
- **Issues**: https://github.com/lhzn-io/biologger-pseudotrack/issues

Indices and tables
==================

* :ref:`genindex`
* :ref:`search`