feat: cross-asset / pairwise indicators (5 new) (#109)

* feat(core): add PairwiseBeta cross-asset indicator Rolling OLS slope of one asset's log-returns on another's. Unlike Beta, which regresses the raw inputs it is fed, PairwiseBeta differences consecutive prices into log-returns internally -- the conventional way to measure cross-asset beta, where a beta on price levels would be dominated by the shared trend. Two-series Indicator<Input = (f64, f64)>, exposed in Rust, Python, Node and WASM, with unit/known-value/streaming tests and a pair fuzz target. * feat(core): add PairSpreadZScore cross-asset indicator Standardised log-spread ln(a) - beta*ln(b) of a pair, where beta is a rolling-OLS hedge ratio and the spread is z-scored over its own look-back. The canonical mean-reversion / statistical-arbitrage entry signal, with independent beta_period and z_period windows. Two-series Indicator<Input = (f64, f64)>, exposed in Rust, Python, Node and WASM, with sign/known-value/streaming tests and a pair fuzz target. * feat(core): add LeadLagCrossCorrelation cross-asset indicator Reports the integer offset k in [-max_lag, max_lag] that maximises |corr(a[t], b[t+k])|, answering which of two assets leads the other and by how many bars. A positive lag means a leads b. Fully causal: a's window is held centred while b's window slides across the buffered history, so every lag is evaluated only against data already seen. Struct output { lag, correlation }, exposed in Rust, Python, Node and WASM with lead-detection/streaming tests and a pair fuzz driver. * feat(core): add Cointegration (Engle-Granger + ADF) indicator Rolling pairs-trading screen: an OLS hedge ratio of a on b, the spread (residual) a - (alpha + beta*b), and an augmented Dickey-Fuller t-statistic on the spread with configurable lags. A strongly negative statistic flags a mean-reverting, tradeable spread. Includes a small Gaussian-elimination solver for the augmented regression. Struct output { hedge_ratio, spread, adf_stat }, exposed in Rust, Python, Node and WASM with stationarity/hedge-ratio/streaming tests and a pair fuzz driver. * feat(core): add RelativeStrengthAB cross-asset indicator Comparative relative strength of two assets: the ratio line a/b together with its moving average and its RSI, the classic asset-vs-asset / asset-vs-index rotation screen. Composes the existing Sma and Rsi over the ratio; a zero denominator or non-finite price is skipped. Struct output { ratio, ratio_ma, ratio_rsi }, exposed in Rust, Python, Node and WASM with flat/rising-ratio/streaming tests and a pair fuzz driver. * test(cointegration): cover ADF guard branches The ADF helper's short-series and degrees-of-freedom guards and the zero-dispersion (perfect AR) path are unreachable through the public Cointegration API (period >= 2*adf_lags + 4), so exercise them with direct unit tests on adf_no_constant. The second linear solve cannot be singular once the coefficient solve on the same matrix has succeeded, so it now uses expect() instead of a dead error branch.
2026-06-01 13:45:21 +02:00
parent 1ab9bc70d1
commit 0b85142ad1
20 changed files with 3008 additions and 77 deletions
@@ -10751,6 +10751,383 @@ impl PyBeta {
    }
 }

+// ============================== PairwiseBeta ==============================
+
+#[pyclass(name = "PairwiseBeta", module = "wickra._wickra", skip_from_py_object)]
+#[derive(Clone)]
+struct PyPairwiseBeta {
+    inner: wc::PairwiseBeta,
+}
+
+#[pymethods]
+impl PyPairwiseBeta {
+    #[new]
+    #[pyo3(signature = (period=20))]
+    fn new(period: usize) -> PyResult<Self> {
+        Ok(Self {
+            inner: wc::PairwiseBeta::new(period).map_err(map_err)?,
+        })
+    }
+    fn update(&mut self, a: f64, b: f64) -> Option<f64> {
+        self.inner.update((a, b))
+    }
+    /// Batch over two equally-sized numpy arrays of prices: `a` and `b`.
+    fn batch<'py>(
+        &mut self,
+        py: Python<'py>,
+        a: PyReadonlyArray1<'py, f64>,
+        b: PyReadonlyArray1<'py, f64>,
+    ) -> PyResult<Bound<'py, PyArray1<f64>>> {
+        let xs = a
+            .as_slice()
+            .map_err(|_| PyValueError::new_err(NON_CONTIGUOUS))?;
+        let ys = b
+            .as_slice()
+            .map_err(|_| PyValueError::new_err(NON_CONTIGUOUS))?;
+        if xs.len() != ys.len() {
+            return Err(PyValueError::new_err("a and b must be equal length"));
+        }
+        let mut out = Vec::with_capacity(xs.len());
+        for i in 0..xs.len() {
+            out.push(self.inner.update((xs[i], ys[i])).unwrap_or(f64::NAN));
+        }
+        Ok(out.into_pyarray(py))
+    }
+    #[getter]
+    fn period(&self) -> usize {
+        self.inner.period()
+    }
+    fn reset(&mut self) {
+        self.inner.reset();
+    }
+    fn is_ready(&self) -> bool {
+        self.inner.is_ready()
+    }
+    fn warmup_period(&self) -> usize {
+        self.inner.warmup_period()
+    }
+    fn __repr__(&self) -> String {
+        format!("PairwiseBeta(period={})", self.inner.period())
+    }
+}
+
+// ============================== PairSpreadZScore ==============================
+
+#[pyclass(
+    name = "PairSpreadZScore",
+    module = "wickra._wickra",
+    skip_from_py_object
+)]
+#[derive(Clone)]
+struct PyPairSpreadZScore {
+    inner: wc::PairSpreadZScore,
+}
+
+#[pymethods]
+impl PyPairSpreadZScore {
+    #[new]
+    #[pyo3(signature = (beta_period=20, z_period=20))]
+    fn new(beta_period: usize, z_period: usize) -> PyResult<Self> {
+        Ok(Self {
+            inner: wc::PairSpreadZScore::new(beta_period, z_period).map_err(map_err)?,
+        })
+    }
+    fn update(&mut self, a: f64, b: f64) -> Option<f64> {
+        self.inner.update((a, b))
+    }
+    /// Batch over two equally-sized numpy arrays of prices: `a` and `b`.
+    fn batch<'py>(
+        &mut self,
+        py: Python<'py>,
+        a: PyReadonlyArray1<'py, f64>,
+        b: PyReadonlyArray1<'py, f64>,
+    ) -> PyResult<Bound<'py, PyArray1<f64>>> {
+        let xs = a
+            .as_slice()
+            .map_err(|_| PyValueError::new_err(NON_CONTIGUOUS))?;
+        let ys = b
+            .as_slice()
+            .map_err(|_| PyValueError::new_err(NON_CONTIGUOUS))?;
+        if xs.len() != ys.len() {
+            return Err(PyValueError::new_err("a and b must be equal length"));
+        }
+        let mut out = Vec::with_capacity(xs.len());
+        for i in 0..xs.len() {
+            out.push(self.inner.update((xs[i], ys[i])).unwrap_or(f64::NAN));
+        }
+        Ok(out.into_pyarray(py))
+    }
+    #[getter]
+    fn beta_period(&self) -> usize {
+        self.inner.beta_period()
+    }
+    #[getter]
+    fn z_period(&self) -> usize {
+        self.inner.z_period()
+    }
+    fn reset(&mut self) {
+        self.inner.reset();
+    }
+    fn is_ready(&self) -> bool {
+        self.inner.is_ready()
+    }
+    fn warmup_period(&self) -> usize {
+        self.inner.warmup_period()
+    }
+    fn __repr__(&self) -> String {
+        format!(
+            "PairSpreadZScore(beta_period={}, z_period={})",
+            self.inner.beta_period(),
+            self.inner.z_period()
+        )
+    }
+}
+
+// ============================== LeadLagCrossCorrelation ==============================
+
+#[pyclass(
+    name = "LeadLagCrossCorrelation",
+    module = "wickra._wickra",
+    skip_from_py_object
+)]
+#[derive(Clone)]
+struct PyLeadLagCrossCorrelation {
+    inner: wc::LeadLagCrossCorrelation,
+}
+
+#[pymethods]
+impl PyLeadLagCrossCorrelation {
+    #[new]
+    #[pyo3(signature = (window=20, max_lag=10))]
+    fn new(window: usize, max_lag: usize) -> PyResult<Self> {
+        Ok(Self {
+            inner: wc::LeadLagCrossCorrelation::new(window, max_lag).map_err(map_err)?,
+        })
+    }
+    /// Returns `(lag, correlation)` or `None` during warmup. A positive lag
+    /// means `a` leads `b`.
+    fn update(&mut self, a: f64, b: f64) -> Option<(i64, f64)> {
+        self.inner.update((a, b)).map(|o| (o.lag, o.correlation))
+    }
+    /// Batch over two equally-sized numpy arrays. Returns a 2D array of shape
+    /// `(n, 2)` with columns `[lag, correlation]`. Warmup rows are NaN.
+    fn batch<'py>(
+        &mut self,
+        py: Python<'py>,
+        a: PyReadonlyArray1<'py, f64>,
+        b: PyReadonlyArray1<'py, f64>,
+    ) -> PyResult<Bound<'py, PyArray2<f64>>> {
+        let xs = a
+            .as_slice()
+            .map_err(|_| PyValueError::new_err(NON_CONTIGUOUS))?;
+        let ys = b
+            .as_slice()
+            .map_err(|_| PyValueError::new_err(NON_CONTIGUOUS))?;
+        if xs.len() != ys.len() {
+            return Err(PyValueError::new_err("a and b must be equal length"));
+        }
+        let n = xs.len();
+        let mut out = vec![f64::NAN; n * 2];
+        for i in 0..n {
+            if let Some(o) = self.inner.update((xs[i], ys[i])) {
+                out[i * 2] = o.lag as f64;
+                out[i * 2 + 1] = o.correlation;
+            }
+        }
+        Ok(numpy::ndarray::Array2::from_shape_vec((n, 2), out)
+            .expect("shape consistent")
+            .into_pyarray(py))
+    }
+    #[getter]
+    fn window(&self) -> usize {
+        self.inner.window()
+    }
+    #[getter]
+    fn max_lag(&self) -> usize {
+        self.inner.max_lag()
+    }
+    fn reset(&mut self) {
+        self.inner.reset();
+    }
+    fn is_ready(&self) -> bool {
+        self.inner.is_ready()
+    }
+    fn warmup_period(&self) -> usize {
+        self.inner.warmup_period()
+    }
+    fn __repr__(&self) -> String {
+        format!(
+            "LeadLagCrossCorrelation(window={}, max_lag={})",
+            self.inner.window(),
+            self.inner.max_lag()
+        )
+    }
+}
+
+// ============================== Cointegration ==============================
+
+#[pyclass(name = "Cointegration", module = "wickra._wickra", skip_from_py_object)]
+#[derive(Clone)]
+struct PyCointegration {
+    inner: wc::Cointegration,
+}
+
+#[pymethods]
+impl PyCointegration {
+    #[new]
+    #[pyo3(signature = (period=30, adf_lags=1))]
+    fn new(period: usize, adf_lags: usize) -> PyResult<Self> {
+        Ok(Self {
+            inner: wc::Cointegration::new(period, adf_lags).map_err(map_err)?,
+        })
+    }
+    /// Returns `(hedge_ratio, spread, adf_stat)` or `None` during warmup.
+    fn update(&mut self, a: f64, b: f64) -> Option<(f64, f64, f64)> {
+        self.inner
+            .update((a, b))
+            .map(|o| (o.hedge_ratio, o.spread, o.adf_stat))
+    }
+    /// Batch over two equally-sized numpy arrays. Returns a 2D array of shape
+    /// `(n, 3)` with columns `[hedge_ratio, spread, adf_stat]`. Warmup rows are
+    /// NaN.
+    fn batch<'py>(
+        &mut self,
+        py: Python<'py>,
+        a: PyReadonlyArray1<'py, f64>,
+        b: PyReadonlyArray1<'py, f64>,
+    ) -> PyResult<Bound<'py, PyArray2<f64>>> {
+        let xs = a
+            .as_slice()
+            .map_err(|_| PyValueError::new_err(NON_CONTIGUOUS))?;
+        let ys = b
+            .as_slice()
+            .map_err(|_| PyValueError::new_err(NON_CONTIGUOUS))?;
+        if xs.len() != ys.len() {
+            return Err(PyValueError::new_err("a and b must be equal length"));
+        }
+        let n = xs.len();
+        let mut out = vec![f64::NAN; n * 3];
+        for i in 0..n {
+            if let Some(o) = self.inner.update((xs[i], ys[i])) {
+                out[i * 3] = o.hedge_ratio;
+                out[i * 3 + 1] = o.spread;
+                out[i * 3 + 2] = o.adf_stat;
+            }
+        }
+        Ok(numpy::ndarray::Array2::from_shape_vec((n, 3), out)
+            .expect("shape consistent")
+            .into_pyarray(py))
+    }
+    #[getter]
+    fn period(&self) -> usize {
+        self.inner.period()
+    }
+    #[getter]
+    fn adf_lags(&self) -> usize {
+        self.inner.adf_lags()
+    }
+    fn reset(&mut self) {
+        self.inner.reset();
+    }
+    fn is_ready(&self) -> bool {
+        self.inner.is_ready()
+    }
+    fn warmup_period(&self) -> usize {
+        self.inner.warmup_period()
+    }
+    fn __repr__(&self) -> String {
+        format!(
+            "Cointegration(period={}, adf_lags={})",
+            self.inner.period(),
+            self.inner.adf_lags()
+        )
+    }
+}
+
+// ============================== RelativeStrengthAB ==============================
+
+#[pyclass(
+    name = "RelativeStrengthAB",
+    module = "wickra._wickra",
+    skip_from_py_object
+)]
+#[derive(Clone)]
+struct PyRelativeStrengthAB {
+    inner: wc::RelativeStrengthAB,
+}
+
+#[pymethods]
+impl PyRelativeStrengthAB {
+    #[new]
+    #[pyo3(signature = (ma_period=20, rsi_period=14))]
+    fn new(ma_period: usize, rsi_period: usize) -> PyResult<Self> {
+        Ok(Self {
+            inner: wc::RelativeStrengthAB::new(ma_period, rsi_period).map_err(map_err)?,
+        })
+    }
+    /// Returns `(ratio, ratio_ma, ratio_rsi)` or `None` during warmup.
+    fn update(&mut self, a: f64, b: f64) -> Option<(f64, f64, f64)> {
+        self.inner
+            .update((a, b))
+            .map(|o| (o.ratio, o.ratio_ma, o.ratio_rsi))
+    }
+    /// Batch over two equally-sized numpy arrays. Returns a 2D array of shape
+    /// `(n, 3)` with columns `[ratio, ratio_ma, ratio_rsi]`. Warmup rows are
+    /// NaN.
+    fn batch<'py>(
+        &mut self,
+        py: Python<'py>,
+        a: PyReadonlyArray1<'py, f64>,
+        b: PyReadonlyArray1<'py, f64>,
+    ) -> PyResult<Bound<'py, PyArray2<f64>>> {
+        let xs = a
+            .as_slice()
+            .map_err(|_| PyValueError::new_err(NON_CONTIGUOUS))?;
+        let ys = b
+            .as_slice()
+            .map_err(|_| PyValueError::new_err(NON_CONTIGUOUS))?;
+        if xs.len() != ys.len() {
+            return Err(PyValueError::new_err("a and b must be equal length"));
+        }
+        let n = xs.len();
+        let mut out = vec![f64::NAN; n * 3];
+        for i in 0..n {
+            if let Some(o) = self.inner.update((xs[i], ys[i])) {
+                out[i * 3] = o.ratio;
+                out[i * 3 + 1] = o.ratio_ma;
+                out[i * 3 + 2] = o.ratio_rsi;
+            }
+        }
+        Ok(numpy::ndarray::Array2::from_shape_vec((n, 3), out)
+            .expect("shape consistent")
+            .into_pyarray(py))
+    }
+    #[getter]
+    fn ma_period(&self) -> usize {
+        self.inner.ma_period()
+    }
+    #[getter]
+    fn rsi_period(&self) -> usize {
+        self.inner.rsi_period()
+    }
+    fn reset(&mut self) {
+        self.inner.reset();
+    }
+    fn is_ready(&self) -> bool {
+        self.inner.is_ready()
+    }
+    fn warmup_period(&self) -> usize {
+        self.inner.warmup_period()
+    }
+    fn __repr__(&self) -> String {
+        format!(
+            "RelativeStrengthAB(ma_period={}, rsi_period={})",
+            self.inner.ma_period(),
+            self.inner.rsi_period()
+        )
+    }
+}
+
 // ============================== SpearmanCorrelation ==============================

 #[pyclass(
@@ -12236,6 +12613,11 @@ fn _wickra(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
    m.add_class::<PyHurstExponent>()?;
    m.add_class::<PyPearsonCorrelation>()?;
    m.add_class::<PyBeta>()?;
+    m.add_class::<PyPairwiseBeta>()?;
+    m.add_class::<PyPairSpreadZScore>()?;
+    m.add_class::<PyLeadLagCrossCorrelation>()?;
+    m.add_class::<PyCointegration>()?;
+    m.add_class::<PyRelativeStrengthAB>()?;
    m.add_class::<PySpearmanCorrelation>()?;
    m.add_class::<PyValueArea>()?;
    m.add_class::<PyInitialBalance>()?;