Struct PairSpreadZScore 

pub struct PairSpreadZScore { /* private fields */ }

Z-score of the log-spread ln(a) − β·ln(b) between two assets.

This is the canonical mean-reversion / statistical-arbitrage signal for a pair. Each update receives one (a, b) pair of raw prices and the indicator does two things:

1. Hedge ratio. A rolling ordinary-least-squares regression of ln(a) on ln(b) over the trailing beta_period samples gives the slope β = cov(ln a, ln b) / var(ln b). The instantaneous spread is the residual against the origin, s = ln(a) − β·ln(b).
2. Standardisation. The spread is then z-scored over the trailing z_period spreads: z = (s − mean_s) / std_s.

A large positive z means a is rich relative to b (sell the spread); a large negative z means a is cheap (buy the spread); z near zero means the pair is at its typical relationship. The two windows are independent: beta_period controls how much history the hedge ratio adapts over, and z_period controls the look-back for the mean and dispersion of the spread.

Each update is O(1): five running sums maintain the rolling OLS and two more maintain the rolling spread mean/variance. A flat ln(b) window has zero variance and the hedge ratio is undefined; β is then taken as 0, reducing the spread to ln(a). A flat spread window (zero dispersion) yields a z-score of 0 rather than NaN.

Prices must be strictly positive and finite for the logarithm to be defined; a non-positive or non-finite price is skipped (it does not enter either window), exactly as a real feed would discard a bad tick.

Example

use wickra_core::{Indicator, PairSpreadZScore};

let mut zs = PairSpreadZScore::new(2, 2).unwrap();
// A flat benchmark gives hedge ratio 0, so the spread is just ln(a); with
// a 2-sample z-window the z-score collapses to the sign of the last move.
let mut last = None;
for a in [100.0, 100.0, 110.0, 120.0] {
    last = zs.update((a, 100.0));
}
assert!((last.unwrap() - 1.0).abs() < 1e-9);

Implementations

impl PairSpreadZScore

pub fn new(beta_period: usize, z_period: usize) -> Result<Self>

Construct a new pair spread z-score.

beta_period is the look-back for the rolling hedge ratio; z_period is the look-back for standardising the spread.

Errors

Returns Error::InvalidPeriod if either period is below 2 (variance needs at least two points).

pub const fn beta_period(&self) -> usize

Look-back of the rolling hedge-ratio regression.

pub const fn z_period(&self) -> usize

Look-back of the rolling spread standardisation.

Trait Implementations

impl Clone for PairSpreadZScore

fn clone(&self) -> PairSpreadZScore

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for PairSpreadZScore

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

Formats the value using the given formatter.

impl Indicator for PairSpreadZScore

type Input = (f64, f64)

(a, b) price pair.

type Output = f64

Type of one output value.

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

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.