Struct KalmanHedgeRatio 

pub struct KalmanHedgeRatio { /* private fields */ }

Dynamic hedge ratio between two series, estimated online with a Kalman filter.

Each update takes one (a, b) price pair and treats the linear relation aₜ = αₜ + βₜ·bₜ + noise as a state-space model whose hidden state [βₜ, αₜ] follows a random walk. The filter updates the state from every observation, so the hedge ratio adapts continuously instead of being a flat OLS slope over a fixed window:

state    xₜ = [βₜ, αₜ],   drifts as a random walk with covariance Vw·I
observe  aₜ = [bₜ, 1]·xₜ + εₜ,   Var(εₜ) = observation_var
Vw = delta / (1 − delta)

delta controls how fast the hedge ratio is allowed to move: a larger delta tracks regime changes faster but is noisier; a smaller delta is smoother but slower. observation_var is the measurement-noise variance. The reported spread (the filter’s forecast error) is the mean-reverting signal a pairs trade fades — the Kalman analogue of the crate::Cointegration residual, but with a hedge ratio that breathes.

The filter emits an estimate from the first update (warmup of one bar); early estimates are diffuse and settle as observations accumulate. Each update is O(1) over the fixed 2×2 covariance.

Example

use wickra_core::{Indicator, KalmanHedgeRatio};

let mut k = KalmanHedgeRatio::new(1e-2, 1e-3).unwrap();
let mut last = None;
for t in 0..400 {
    // `b` sweeps a wide range so the slope and intercept are identifiable.
    let b = 100.0 + (f64::from(t) * 0.5).sin() * 95.0;
    last = k.update((2.0 * b + 5.0, b)); // a = 2·b + 5
}
let out = last.unwrap();
assert!((out.hedge_ratio - 2.0).abs() < 0.05);
assert!(out.spread.abs() < 0.05);

Implementations

impl KalmanHedgeRatio

pub fn new(delta: f64, observation_var: f64) -> Result<Self>

Construct a new Kalman hedge-ratio filter.

delta is the state-drift ratio in (0, 1); observation_var is the measurement-noise variance (> 0).

Errors

Returns Error::InvalidParameter if delta is not in (0, 1) or if observation_var is not strictly positive (both must also be finite).

pub const fn delta(&self) -> f64

Configured state-drift ratio delta.

pub const fn observation_var(&self) -> f64

Configured measurement-noise variance.

Trait Implementations

impl Clone for KalmanHedgeRatio

fn clone(&self) -> KalmanHedgeRatio

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for KalmanHedgeRatio

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Indicator for KalmanHedgeRatio

type Input = (f64, f64)

Type of one input data point (typically f64 for a price, or Candle / Tick).

type Output = KalmanHedgeRatioOutput

Type of one output value.

fn update(&mut self, input: (f64, f64)) -> Option<KalmanHedgeRatioOutput>

Feed one new data point into the indicator and return the freshly computed output, or None if the indicator is still warming up.

fn reset(&mut self)

Reset all internal state, leaving the indicator equivalent to a freshly constructed instance with the same parameters.

fn warmup_period(&self) -> usize

Number of inputs required before the first non-None output can be produced.

fn is_ready(&self) -> bool

Whether the indicator has emitted at least one value since the last reset.

fn name(&self) -> &'static str

Stable, human-readable indicator name. Used by chaining and diagnostics.