API Reference: Processors

class biologger_sim.processors.streaming.StreamingProcessor(filt_len: int = 48, freq: int = 16, debug_level: int = 0, locked_attachment_roll_deg: float | None = None, locked_attachment_pitch_deg: float | None = None, locked_mag_offset_x: float | None = None, locked_mag_offset_y: float | None = None, locked_mag_offset_z: float | None = None, locked_mag_sphere_radius: float | None = None, ema_fast_alpha: float = 0.2, ema_slow_alpha: float = 0.02, ema_cross_threshold: float = 0.5, zmq_publisher: ZMQPublisher | None = None, eid: int | None = None, sim_id: str = 'default', tag_id: str = 'unknown', **kwargs: Any)

Bases: BiologgerProcessor

Causal (real-time) streaming processor for digital twin and on-tag simulation.

This processor uses strictly causal filters (looking only at past data) to simulate what a tag could compute in real-time. It enables selective logging and behavioral response simulation.

Features: - Causal Gsep (Gravity Separation): Uses trailing window mean for static acceleration. - Locked Calibration: Uses pre-determined attachment angles and mag offsets. - EMA Crossover: Fast/Slow Exponential Moving Average for behavioral state detection. - R-Equivalent Pitch/Roll: Uses same geometric formulas as Lab mode but on causal data. - Sparse Depth Handling: Implements causal sample-and-hold (fill-forward) for

datasets with sparse pressure sensors.

Comparison to Lab Mode: - Lab Mode: Centered filter (looks forward/backward), maximal accuracy, 1.5s delay. - Streaming Mode: Causal filter (looks backward only), ~0.5-1° lag, 0 delay.

calibrate_from_batch_data() → None

No-op for StreamingProcessor as it uses locked calibration.

get_current_state() → dict[str, Any]

Get current state.

get_performance_summary() → dict[str, Any]

Get performance metrics.

process(data: dict[str, Any] | ndarray) → dict[str, Any]

Process a single record.

Parameters:

data – Dictionary containing sensor data.

Returns:

Processed record with derived metrics.

reset() → None

Reset processor state.

update_config(config_updates: dict[str, Any]) → None

Update runtime config.

class biologger_sim.processors.lab.PostFactoProcessor(filt_len: int = 48, freq: int = 16, debug_level: int = 0, r_exact_mode: bool = False, compute_attachment_angles: bool = True, locked_attachment_roll_deg: float | None = None, locked_attachment_pitch_deg: float | None = None, compute_mag_offsets: bool = True, locked_mag_offset_x: float | None = None, locked_mag_offset_y: float | None = None, locked_mag_offset_z: float | None = None, locked_mag_sphere_radius: float | None = None, depth_cfg: DepthConfig | None = None, zmq_publisher: ZMQPublisher | None = None, eid: int | None = None, sim_id: str | None = None, tag_id: str = 'unknown', clock_source: ClockSource = ClockSource.FIXED_FREQ, **kwargs: Any)

Bases: BiologgerProcessor

Post-facto (non-causal) biologger processor for R-compatibility.

This processor uses R’s centered moving average filter (filter(sides=2, circular=TRUE)) to achieve exact tie-out with the gRumble R package. Unlike StreamingProcessor which uses causal lfilter (trailing window), this uses a centered window looking both forward and backward in time, which is only possible for post-hoc analysis.

Memory Footprint:

• Fixed size: O(filt_len) samples (48 samples @ 16Hz for 3s window)

• Independent of dataset size (unlike batch/ which loads all data)

Validation Target:

• <0.1° error vs R (pitch, roll, heading)

• Exact ODBA/VeDBA match

calibrate_from_batch_data() → None

Perform batch calibration from collected data.

This should be called after the first pass through the dataset in r_exact_mode. Computes attachment angles and magnetometer offsets from full dataset.

get_current_state() → dict[str, Any]

Get current processor state.

get_output_schema() → list[str]

Get list of output fields (R-compatible expanded schema).

get_performance_summary() → dict[str, Any]

Get performance metrics.

process(data: dict[str, Any] | ndarray) → dict[str, Any]

Process a single record using non-causal filtfilt.

Parameters:

data – Raw sensor record (dict or array)

Returns:

Dictionary with processed state, or minimal state if record is skipped.

reset() → None

Reset processor to initial state.

update_config(config_updates: dict[str, Any]) → None

Update processor configuration.