Getting Started

Installation

From Source (Recommended)

git clone https://github.com/lhzn-io/biologger-sim.git
cd biologger-sim
micromamba env create -f environment.yml
micromamba activate biologger-sim
pip install -e .

Basic Usage

Command-Line Interface

# Run simulation (streaming mode)
python -m biologger_sim --config config/Swordfish-RED001_20220812_19A0564-causal.yaml

# Run lab analysis (post-facto mode)
python -m biologger_sim --config config/Swordfish-RED001_20220812_19A0564-postfacto.yaml

Python API

from biologger_sim.processors.lab import PostFactoProcessor

# Create post-facto processor
processor = PostFactoProcessor(
    filt_len=48,
    freq=16,
    r_exact_mode=True
)

# Process data (example)
# result = processor.process(record)

Configuration

The pipeline uses YAML configuration files. Example configurations are provided in the config/ directory:

Swordfish-RED001_20220812_19A0564-causal.yaml - Real-time simulation
Swordfish-RED001_20220812_19A0564-postfacto.yaml - Lab analysis

Calibration Modes

Both pipelines share a unified calibration: config block with three modes:

Progressive (adaptive default): Accumulates calibration data online using exponential moving averages. Memory-efficient, suitable for real-time processing. Converges within first 2-3 minutes of deployment.
Fixed (pre-computed values): Uses locked calibration parameters from prior runs. Fastest processing (single-pass, no calibration overhead). Requires prior calibration from batch_compute or R analysis.
Batch Compute (post-facto only): Two-pass processing: collect full dataset, compute calibrations, reprocess. Matches R gRumble’s colMeans() and MagOffset() exactly. Validation target: <0.1° error vs. R reference implementation.

Next Steps

See Pipeline Architecture: Lab vs Simulation for detailed pipeline architecture
Check Omniverse Visualization for Omniverse setup