feat: microstructure price-impact & depth indicators (part 3 of 4) (#122)

* feat: effective spread microstructure indicator (part 3 of 4)

* feat: realized spread microstructure indicator (part 3 of 4)

* feat: kyle's lambda microstructure indicator (part 3 of 4)

* feat: depth slope microstructure indicator (part 3 of 4)

bindings/python/python/wickra/__init__.py

@@ -246,10 +246,15 @@ from ._wickra import (
     OrderBookImbalanceFull,
     Microprice,
     QuotedSpread,
+    DepthSlope,
     # Microstructure: trade flow
     SignedVolume,
     CumulativeVolumeDelta,
     TradeImbalance,
+    # Microstructure: price impact
+    EffectiveSpread,
+    RealizedSpread,
+    KylesLambda,
     # Risk / Performance
     SharpeRatio,
     SortinoRatio,
@@ -493,10 +498,15 @@ __all__ = [
     "OrderBookImbalanceFull",
     "Microprice",
     "QuotedSpread",
+    "DepthSlope",
     # Microstructure: trade flow
     "SignedVolume",
     "CumulativeVolumeDelta",
     "TradeImbalance",
+    # Microstructure: price impact
+    "EffectiveSpread",
+    "RealizedSpread",
+    "KylesLambda",
     # Risk / Performance
     "SharpeRatio",
     "SortinoRatio",

bindings/python/src/lib.rs

@@ -11714,6 +11714,7 @@ py_ob_indicator!(
 );
 py_ob_indicator!(PyMicroprice, wc::Microprice, "Microprice");
 py_ob_indicator!(PyQuotedSpread, wc::QuotedSpread, "QuotedSpread");
+py_ob_indicator!(PyDepthSlope, wc::DepthSlope, "DepthSlope");
 
 // Top-N imbalance carries a `levels` parameter, so it is hand-written.
 #[pyclass(
@@ -11902,6 +11903,198 @@ impl PyTradeImbalance {
     }
 }
 
+// ============================== Microstructure: Price Impact ==============================
+//
+// Price-impact indicators consume a trade paired with the mid prevailing at
+// execution. Streaming `update(price, size, is_buy, mid)` takes one such
+// trade-quote (`is_buy=True` for a buyer-initiated trade); `batch` takes four
+// equal-length arrays.
+
+fn build_trade_quote(price: f64, size: f64, is_buy: bool, mid: f64) -> PyResult<wc::TradeQuote> {
+    let trade = build_trade(price, size, is_buy)?;
+    wc::TradeQuote::new(trade, mid).map_err(map_err)
+}
+
+macro_rules! py_trade_quote_indicator {
+    ($name:ident, $inner:ty, $repr:expr) => {
+        #[pyclass(name = $repr, module = "wickra._wickra", skip_from_py_object)]
+        #[derive(Clone)]
+        struct $name {
+            inner: $inner,
+        }
+
+        #[pymethods]
+        impl $name {
+            #[new]
+            fn new() -> Self {
+                Self {
+                    inner: <$inner>::new(),
+                }
+            }
+            fn update(
+                &mut self,
+                price: f64,
+                size: f64,
+                is_buy: bool,
+                mid: f64,
+            ) -> PyResult<Option<f64>> {
+                Ok(self
+                    .inner
+                    .update(build_trade_quote(price, size, is_buy, mid)?))
+            }
+            fn batch<'py>(
+                &mut self,
+                py: Python<'py>,
+                price: Vec<f64>,
+                size: Vec<f64>,
+                is_buy: Vec<bool>,
+                mid: Vec<f64>,
+            ) -> PyResult<Bound<'py, PyArray1<f64>>> {
+                if price.len() != size.len()
+                    || size.len() != is_buy.len()
+                    || is_buy.len() != mid.len()
+                {
+                    return Err(PyValueError::new_err(
+                        "price, size, is_buy, mid must be equal length",
+                    ));
+                }
+                let mut out = Vec::with_capacity(price.len());
+                for i in 0..price.len() {
+                    let quote = build_trade_quote(price[i], size[i], is_buy[i], mid[i])?;
+                    out.push(self.inner.update(quote).unwrap_or(f64::NAN));
+                }
+                Ok(out.into_pyarray(py))
+            }
+            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!("{}()", $repr)
+            }
+        }
+    };
+}
+
+py_trade_quote_indicator!(PyEffectiveSpread, wc::EffectiveSpread, "EffectiveSpread");
+
+// Realized spread carries a `horizon` parameter, so it is hand-written.
+#[pyclass(
+    name = "RealizedSpread",
+    module = "wickra._wickra",
+    skip_from_py_object
+)]
+#[derive(Clone)]
+struct PyRealizedSpread {
+    inner: wc::RealizedSpread,
+}
+
+#[pymethods]
+impl PyRealizedSpread {
+    #[new]
+    fn new(horizon: usize) -> PyResult<Self> {
+        Ok(Self {
+            inner: wc::RealizedSpread::new(horizon).map_err(map_err)?,
+        })
+    }
+    fn update(&mut self, price: f64, size: f64, is_buy: bool, mid: f64) -> PyResult<Option<f64>> {
+        Ok(self
+            .inner
+            .update(build_trade_quote(price, size, is_buy, mid)?))
+    }
+    fn batch<'py>(
+        &mut self,
+        py: Python<'py>,
+        price: Vec<f64>,
+        size: Vec<f64>,
+        is_buy: Vec<bool>,
+        mid: Vec<f64>,
+    ) -> PyResult<Bound<'py, PyArray1<f64>>> {
+        if price.len() != size.len() || size.len() != is_buy.len() || is_buy.len() != mid.len() {
+            return Err(PyValueError::new_err(
+                "price, size, is_buy, mid must be equal length",
+            ));
+        }
+        let mut out = Vec::with_capacity(price.len());
+        for i in 0..price.len() {
+            let quote = build_trade_quote(price[i], size[i], is_buy[i], mid[i])?;
+            out.push(self.inner.update(quote).unwrap_or(f64::NAN));
+        }
+        Ok(out.into_pyarray(py))
+    }
+    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!("RealizedSpread(horizon={})", self.inner.horizon())
+    }
+}
+
+// Kyle's lambda carries a `window` parameter, so it is hand-written.
+#[pyclass(name = "KylesLambda", module = "wickra._wickra", skip_from_py_object)]
+#[derive(Clone)]
+struct PyKylesLambda {
+    inner: wc::KylesLambda,
+}
+
+#[pymethods]
+impl PyKylesLambda {
+    #[new]
+    fn new(window: usize) -> PyResult<Self> {
+        Ok(Self {
+            inner: wc::KylesLambda::new(window).map_err(map_err)?,
+        })
+    }
+    fn update(&mut self, price: f64, size: f64, is_buy: bool, mid: f64) -> PyResult<Option<f64>> {
+        Ok(self
+            .inner
+            .update(build_trade_quote(price, size, is_buy, mid)?))
+    }
+    fn batch<'py>(
+        &mut self,
+        py: Python<'py>,
+        price: Vec<f64>,
+        size: Vec<f64>,
+        is_buy: Vec<bool>,
+        mid: Vec<f64>,
+    ) -> PyResult<Bound<'py, PyArray1<f64>>> {
+        if price.len() != size.len() || size.len() != is_buy.len() || is_buy.len() != mid.len() {
+            return Err(PyValueError::new_err(
+                "price, size, is_buy, mid must be equal length",
+            ));
+        }
+        let mut out = Vec::with_capacity(price.len());
+        for i in 0..price.len() {
+            let quote = build_trade_quote(price[i], size[i], is_buy[i], mid[i])?;
+            out.push(self.inner.update(quote).unwrap_or(f64::NAN));
+        }
+        Ok(out.into_pyarray(py))
+    }
+    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!("KylesLambda(window={})", self.inner.window())
+    }
+}
+
 // ============================== Family 15: Risk / Performance ==============================
 
 #[pyclass(name = "SharpeRatio", module = "wickra._wickra", skip_from_py_object)]
@@ -13013,10 +13206,15 @@ fn _wickra(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<PyOrderBookImbalanceFull>()?;
     m.add_class::<PyMicroprice>()?;
     m.add_class::<PyQuotedSpread>()?;
+    m.add_class::<PyDepthSlope>()?;
     // Microstructure: trade flow.
     m.add_class::<PySignedVolume>()?;
     m.add_class::<PyCumulativeVolumeDelta>()?;
     m.add_class::<PyTradeImbalance>()?;
+    // Microstructure: price impact.
+    m.add_class::<PyEffectiveSpread>()?;
+    m.add_class::<PyRealizedSpread>()?;
+    m.add_class::<PyKylesLambda>()?;
     // Family 15: Risk / Performance metrics.
     m.add_class::<PySharpeRatio>()?;
     m.add_class::<PySortinoRatio>()?;

bindings/python/tests/test_input_validation.py

@@ -211,3 +211,23 @@ def test_trade_non_positive_price_raises():
 def test_trade_batch_unequal_lengths_raise():
     with pytest.raises(ValueError):
         ta.SignedVolume().batch([100.0, 100.0], [1.0], [True, False])
+
+
+def test_effective_spread_non_positive_mid_raises():
+    with pytest.raises(ValueError):
+        ta.EffectiveSpread().update(100.0, 1.0, True, 0.0)
+
+
+def test_effective_spread_batch_unequal_lengths_raise():
+    with pytest.raises(ValueError):
+        ta.EffectiveSpread().batch([100.0, 100.0], [1.0, 1.0], [True, False], [100.0])
+
+
+def test_realized_spread_zero_horizon_raises():
+    with pytest.raises(ValueError):
+        ta.RealizedSpread(0)
+
+
+def test_kyles_lambda_window_below_two_raises():
+    with pytest.raises(ValueError):
+        ta.KylesLambda(1)

bindings/python/tests/test_known_values.py

@@ -872,6 +872,16 @@ def test_quoted_spread_reference_value():
     assert qs.update([100.0], [1.0], [101.0], [1.0]) == pytest.approx(99.50248756, abs=1e-6)
 
 
+def test_depth_slope_reference_value():
+    # Symmetric book, each side distances 1, 2 with cumulative sizes 1, 3.
+    # OLS slope of (1->1, 2->3) = 2; mean of two equal sides = 2.
+    ds = ta.DepthSlope()
+    out = ds.update([99.0, 98.0], [1.0, 2.0], [101.0, 102.0], [1.0, 2.0])
+    assert out == pytest.approx(2.0, abs=1e-9)
+    # A book with a single level per side has no slope -> 0.
+    assert ta.DepthSlope().update([100.0], [1.0], [101.0], [1.0]) == pytest.approx(0.0)
+
+
 def test_signed_volume_reference_values():
     assert ta.SignedVolume().update(100.0, 2.0, True) == pytest.approx(2.0)
     assert ta.SignedVolume().update(100.0, 3.0, False) == pytest.approx(-3.0)
@@ -889,3 +899,39 @@ def test_trade_imbalance_reference_value():
     assert ti.update(100.0, 3.0, True) is None  # warming up
     # Window full: buyVol 3, sellVol 1 -> (3 - 1) / 4 = 0.5.
     assert ti.update(100.0, 1.0, False) == pytest.approx(0.5)
+
+
+def test_effective_spread_reference_values():
+    # Buy at 100.05 vs mid 100.0: 2 * (100.05 - 100) / 100 * 10000 = 10 bps.
+    assert ta.EffectiveSpread().update(100.05, 1.0, True, 100.0) == pytest.approx(10.0)
+    # Sell at 99.95 vs mid 100.0: 2 * -1 * (99.95 - 100) / 100 * 10000 = 10 bps.
+    assert ta.EffectiveSpread().update(99.95, 1.0, False, 100.0) == pytest.approx(10.0)
+    # A buy filled below the mid is price improvement -> negative.
+    assert ta.EffectiveSpread().update(99.95, 1.0, True, 100.0) < 0.0
+
+
+def test_realized_spread_reference_value():
+    rs = ta.RealizedSpread(1)
+    assert rs.update(100.10, 1.0, True, 100.0) is None  # buffered
+    # Resolved against mid 100.20 one trade later:
+    # 2 * (+1) * (100.10 - 100.20) / 100.0 * 10000 = -20 bps (adverse selection).
+    assert rs.update(99.90, 1.0, False, 100.20) == pytest.approx(-20.0)
+
+
+def test_kyles_lambda_recovers_constant_impact():
+    # Build a tape where each trade moves the mid by exactly 0.5 per unit of
+    # signed volume -> the rolling OLS slope is 0.5.
+    impact = 0.5
+    mid = 100.0
+    price, size, is_buy, mids = [], [], [], []
+    for i in range(20):
+        buy = i % 2 == 0
+        sz = 1.0 + (i % 3)
+        signed = sz if buy else -sz
+        mid += impact * signed
+        price.append(mid)
+        size.append(sz)
+        is_buy.append(buy)
+        mids.append(mid)
+    out = ta.KylesLambda(6).batch(price, size, is_buy, mids)
+    assert out[-1] == pytest.approx(0.5, abs=1e-9)

bindings/python/tests/test_lifecycle.py

@@ -139,6 +139,7 @@ def test_orderbook_lifecycle():
         ta.OrderBookImbalanceFull(),
         ta.Microprice(),
         ta.QuotedSpread(),
+        ta.DepthSlope(),
     ]:
         assert ind.warmup_period() == 1
         assert not ind.is_ready()
@@ -172,3 +173,37 @@ def test_trade_imbalance_lifecycle_and_repr():
     ti.reset()
     assert not ti.is_ready()
     assert repr(ta.TradeImbalance(4)) == "TradeImbalance(window=4)"
+
+
+def test_effective_spread_lifecycle():
+    es = ta.EffectiveSpread()
+    assert es.warmup_period() == 1
+    assert not es.is_ready()
+    es.update(100.05, 1.0, True, 100.0)
+    assert es.is_ready()
+    es.reset()
+    assert not es.is_ready()
+
+
+def test_realized_spread_lifecycle_and_repr():
+    rs = ta.RealizedSpread(3)
+    assert rs.warmup_period() == 4
+    assert not rs.is_ready()
+    for _ in range(4):
+        rs.update(100.0, 1.0, True, 100.0)
+    assert rs.is_ready()
+    rs.reset()
+    assert not rs.is_ready()
+    assert repr(ta.RealizedSpread(5)) == "RealizedSpread(horizon=5)"
+
+
+def test_kyles_lambda_lifecycle_and_repr():
+    kl = ta.KylesLambda(3)
+    assert kl.warmup_period() == 4
+    assert not kl.is_ready()
+    for i in range(4):
+        kl.update(100.0 + i, 1.0 + (i % 2), i % 2 == 0, 100.0 + i)
+    assert kl.is_ready()
+    kl.reset()
+    assert not kl.is_ready()
+    assert repr(ta.KylesLambda(7)) == "KylesLambda(window=7)"

bindings/python/tests/test_new_indicators.py

@@ -1890,6 +1890,7 @@ def test_orderbook_indicators_streaming_equals_batch():
         ta.OrderBookImbalanceFull,
         ta.Microprice,
         ta.QuotedSpread,
+        ta.DepthSlope,
     ):
         batch = make().batch(snaps)
         streamer = make()
@@ -1918,3 +1919,23 @@ def test_tradeflow_indicators_streaming_equals_batch():
         )
         assert batch.shape == (n,)
         assert _eq_nan(batch, streamed)
+
+
+def test_price_impact_indicators_streaming_equals_batch():
+    n = 40
+    mid = np.array([100.0 + 0.5 * math.sin(i * 0.4) for i in range(n)], dtype=np.float64)
+    is_buy = [i % 2 == 0 for i in range(n)]
+    # Aggressive trades print across the mid in the aggressor's direction.
+    price = np.array(
+        [mid[i] + (0.02 if is_buy[i] else -0.02) for i in range(n)], dtype=np.float64
+    )
+    size = np.array([1.0 + (i % 5) for i in range(n)], dtype=np.float64)
+    for make in (ta.EffectiveSpread, lambda: ta.RealizedSpread(4), lambda: ta.KylesLambda(5)):
+        batch = make().batch(price, size, is_buy, mid)
+        streamer = make()
+        streamed = np.array(
+            [streamer.update(price[i], size[i], is_buy[i], mid[i]) for i in range(n)],
+            dtype=np.float64,
+        )
+        assert batch.shape == (n,)
+        assert _eq_nan(batch, streamed)

bindings/python/tests/test_smoke.py

@@ -108,6 +108,7 @@ def test_orderbook_indicators_construct_and_emit():
         ta.OrderBookImbalanceFull(),
         ta.Microprice(),
         ta.QuotedSpread(),
+        ta.DepthSlope(),
     ]
     for ind in indicators:
         out = ind.update(*snapshot)
@@ -135,3 +136,21 @@ def test_tradeflow_batch_returns_one_value_per_trade():
     out = ta.CumulativeVolumeDelta().batch(price, size, is_buy)
     assert out.shape == (6,)
     assert out.dtype == np.float64
+
+
+def test_price_impact_indicators_construct_and_emit():
+    # Price-impact indicators take a trade paired with the prevailing mid.
+    assert isinstance(ta.EffectiveSpread().update(100.05, 1.0, True, 100.0), float)
+    # RealizedSpread buffers until its horizon elapses.
+    assert ta.RealizedSpread(1).update(100.05, 1.0, True, 100.0) is None
+
+
+def test_price_impact_batch_returns_one_value_per_trade():
+    price = np.array([100.05, 99.95, 100.10, 99.90])
+    size = np.array([1.0, 2.0, 1.0, 2.0])
+    is_buy = [True, False, True, False]
+    mid = np.full(4, 100.0)
+    for ind in (ta.EffectiveSpread(), ta.RealizedSpread(2), ta.KylesLambda(2)):
+        out = ind.batch(price, size, is_buy, mid)
+        assert out.shape == (4,)
+        assert out.dtype == np.float64

bindings/python/tests/test_streaming_vs_batch.py

@@ -231,3 +231,20 @@ def test_tradeflow_streaming_matches_batch():
         dtype=np.float64,
     )
     assert _equal_with_nan(batch, streamed)
+
+
+def test_price_impact_streaming_matches_batch():
+    n = 30
+    mid = np.array([100.0 + 0.25 * math.sin(i * 0.5) for i in range(n)], dtype=np.float64)
+    is_buy = [i % 3 != 0 for i in range(n)]
+    price = np.array(
+        [mid[i] + (0.03 if is_buy[i] else -0.03) for i in range(n)], dtype=np.float64
+    )
+    size = np.array([1.0 + (i % 4) for i in range(n)], dtype=np.float64)
+    batch = ta.EffectiveSpread().batch(price, size, is_buy, mid)
+    streamer = ta.EffectiveSpread()
+    streamed = np.array(
+        [streamer.update(price[i], size[i], is_buy[i], mid[i]) for i in range(n)],
+        dtype=np.float64,
+    )
+    assert _equal_with_nan(batch, streamed)