Skip to content

helios-fusion-engine

Model-agnostic probabilistic fusion of heterogeneous space-weather model outputs. This is the public framework of HELIOS Artifact C (the fusion engine). Trained weights, BMA priors fitted on Table 3-1 events, and equipment transfer functions live in the private helios-fusion-internal companion repo and are NOT shipped with this package.

What the framework provides

  • Bayesian Model Averaging orchestrator with rolling-window skill-weight updates and explicit handling of missing component models.
  • Reliability calibrators — isotonic (proposal-default), Platt (rejected, retained for comparison), and severity-stratified isotonic (one calibrator per Kp severity stratum).
  • Conformal prediction wrappers — split conformal (marginal coverage) and Mondrian conformal (per-stratum coverage).
  • Evaluation harness — CCMC-compatible metrics (HSS, TSS, POD, FAR, Brier, CRPS) with bootstrap 95% CIs and reliability-diagram slope.
  • Typed records for fusion lineage compatible with the upcoming helios-provenance-spec.

What the framework does NOT provide

  • No trained weights. Callers supply BMA weights at construction time, or fit them at runtime via BMAOrchestrator.update_weights.
  • No equipment transfer functions. The GNSS slice (proposal Obj. 4) builds on top of this framework but ships separately.
  • No kill-gate execution. The kill-gate runner lives in helios-program/orchestration/kill_gate.py and consumes this framework's EvalReport.

Status

  • v0.1.0 — public framework first release.
  • See architecture.md for the BMA + isotonic + conformal composition and the rationale for that stack.
  • See baselines.md for the "best individual component model" baseline definition.
  • See the 01-synthetic-bma-demo.ipynb notebook for a runnable end-to-end demonstration on synthetic data.

Quickstart

pip install helios-fusion-engine

import numpy as np
from helios_fusion.bma import BMAOrchestrator
from helios_fusion.calibration import SeverityStratifiedCalibrator
from helios_fusion.conformal import MondrianConformalRegressor
from helios_fusion.eval import evaluate

# 1) Define BMA weights and fuse
bma = BMAOrchestrator(weights={"UMASEP": 0.4, "SEPMOD": 0.3, "SEP_Scoreboard_A": 0.3})
# fused = bma.fuse([umasep_output, sepmod_output, scoreboard_a_output])

# 2) Calibrate
cal = SeverityStratifiedCalibrator()
# cal.fit(train_fused_probs, train_truth, train_strata)
# calibrated = cal.transform(test_fused_probs, test_strata)

# 3) Conformal interval
cp = MondrianConformalRegressor()
# cp.fit(train_fused_probs, train_truth, train_strata)
# intervals = cp.predict_interval(test_fused_probs, test_strata, alpha=0.1)

# 4) Score
# report = evaluate(test_fused_probs, test_truth, test_strata)
# report.aggregate.hss.point         # HSS point estimate
# report.aggregate.hss.ci_low / ci_high  # bootstrap 95% CI
# report.aggregate.reliability_slope  # H2 quantity (target |slope - 1| <= 0.15)

License

Apache 2.0 — see LICENSE.