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/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)