Core Processors

The biologger-sim package is built around a pluggable processor architecture that allows researchers to switch between real-time (causal) and post-facto (acausal) processing logic.

Processor Types: Lab vs. Simulation

The system supports two primary processor types designed for different stages of the research lifecycle:

Processor Comparison

Feature

PostFactoProcessor (Acausal)

StreamingProcessor (Causal)

Primary Goal

Highest possible accuracy (Lab)

On-tag real-time execution

Processing

Multi-pass, assumes lookahead

Single-pass, strictly causal

Filter Style

filtfilt (Zero-phase)

lfilter (IIR/Butterworth)

Memory

Full record set (O(N))

Fixed window (O(1))

Hardware

High-performance workstations

Resource-constrained tags

—

PostFactoProcessor (Acausal)

The PostFactoProcessor is the reference implementation used in Lab Mode (configured via strict_r_parity: true). It is optimized for scientific validation and retrospective analysis.

Provenance & Portability

This processor is a direct Python port of established R-based biologger analysis scripts (specifically from the gRumble and biologger-pseudotrack ecosystems). Its primary purpose is to maintain a “Gold Standard” baseline for verifying real-time algorithm performance.

Methodology: Batch Retrospective Analysis

Unlike the streaming version, this processor has access to the entire dataset simultaneously, allowing for high-accuracy acausal techniques:

  1. Full Dataset Buffering: All sensor records are loaded into a collection buffer before any analysis begins.

  2. Batch Calibration: - Attachment Angles: Computes body-frame alignment by averaging the gravity vector across the entire deployment. - Magnetometer: Fits a sphere to the total magnetic sample cloud to find precise hard-iron offsets.

  3. Zero-Phase Filtering: Uses a centered moving average (R-style filter(sides=2)) or filtfilt to eliminate phase shift and group delay.

  4. Acausal Interpolation: Uses linear interpolation to fill gaps in pressure sensor or velocity data before smoothing.

  5. Velocity Decoupling: A key mechanical distinction is how it handles motion: - Horizontal Integration: Constant speed (typically 1.0 m/s) is integrated purely in the horizontal plane (X-Y). - Vertical Derivation: Vertical velocity is derived post-hoc from the rate of change of smoothed depth data. - Impact: Because the 1.0 m/s speed is forced into the 2D plane, the animal’s total trajectory length is effectively overestimated during steep maneuvers compared to a 3D-aware model.

—

StreamingProcessor (Causal)

The StreamingProcessor is the core of the Digital Twin mode. It simulates the constraints of a physical biologger tag where data arrives one sample at a time and future data is unknown.

Methodology: The Causal Pipeline (11 Steps plus Terrain)

The processor follows a strictly sequential, low-latency pipeline:

  1. Input Acquisition: Raw acceleration (0.1g counts), magnetometer, and pressure depth.

  2. Attachment Correction: Fixed roll/pitch rotation to align sensor axes with the animal’s body.

  3. Causal Gsep: 3-second trailing window for gravity separation (Static vs. Dynamic).

  4. Dead Reckoning Timing: Dynamic dt calculation to handle sensor jitter.

  5. R-Style Orientation: Pitch/Roll from gravity using legacy-compatible formulas.

  6. World Frame Transform: Body-to-World (NED) rotation of acceleration.

  7. High-Pass Filtering: 4th-order causal bias removal for vertical acceleration.

  8. INS Depth Estimation: 2-state Kalman Filter nowcast (fusing Baro + Accel).

  9. Multi-Scale Smoothing: Activity-weighted blending of Fast/Slow EMAs for depth.

  10. Magnetometer & Heading: Hard-iron compensated, tilt-corrected heading estimation.

  11. Dead Reckoning Integration: Updates position using heading and speed (constant or ODBA-scaled). Unlike the Lab mode, this model is designed to support 3D-aware displacement.

  12. Terrain & Altitude Processing: Estimates GPS coordinates from a designated starting origin and dead-reckoned displacement, queries the central topobathysim elevation service at a standardized 50m resolution (Zoom 11), and computes the animal’s height above the seafloor to stream to the visualizer.

Configuration Parameters

Streaming processors are configured via the entities section in the simulation YAML:

  • filt_len: (Default: 48) Length of the causal Gsep window (in samples).

  • freq: (Default: 16) Sampling frequency for filters and integration.

  • locked_attachment_roll_deg / locked_attachment_pitch_deg: Fixed calibration angles.

  • locked_mag_offset_x/y/z / locked_mag_sphere_radius: Hard-iron calibration parameters.

Advantages & Inherent Disadvantages

Advantages:

  • Real-Time Visibility: Allows for “nowcasting” depth and position with zero lag.

  • Portability: Code is designed to be easily transcribed to C/C++/Warp for embedded tags.

  • Scalability: Can simulate hundreds of entities in parallel due to fixed memory overhead.

Disadvantages (The Cost of Causality):

  • Filter Phase Shift: Causal filters (like Butterworth) introduce a small group delay in the signal.

  • Initialization (Warmup): Requires a short “warmup” period (e.g., 3s) for averaging windows to fill.

  • Noise Sensitivity: Lacks the benefit of centered averaging (filtfilt), making signals inherently noisier than their lab counterparts.

—