feat(family-16): add ValueArea + InitialBalance + OpeningRange (#52)

* feat(family-16): add ValueArea + InitialBalance + OpeningRange

Opens family #16 (Market Profile) with the three OHLCV-compatible scalar /
multi-output indicators:

- ValueArea(period, bin_count, value_area_pct) -> {poc, vah, val}.
  Rolling bin-approximation volume profile over the last `period`
  candles. Each candle's volume is spread uniformly across [low, high];
  POC is the bin with highest cumulative volume; the value area expands
  symmetrically from POC and always absorbs the higher-volume neighbour
  next, until `value_area_pct` (default 0.70) of total volume is
  enclosed. Defaults (20, 50, 0.70).

- InitialBalance(period) -> {high, low}. Tracks session-opening high
  and low over the first `period` bars, then locks. Default period = 12
  (one-hour IB on 5-minute bars for US equities). Callers MUST invoke
  reset() at every session boundary, otherwise IB stays fixed for the
  lifetime of the instance.

- OpeningRange(period) -> {high, low, breakout_distance}. Same
  lock-after-N-bars semantics as IB with a shorter default period
  (6 = 30 min on 5-minute bars) and a third output that tracks
  close - or_mid (positive above the range mid, negative below).

Histogram-output Market Profile variants (Volume Profile, VPVR,
Composite Profile) are deferred because they need a new histogram
output API layer rather than fixed-arity scalars. Tick-data-only
variants (TPO Profile, Single Print, Order Flow Delta, Cumulative
Delta, Volume-Weighted Open) are out of scope because `wickra-data`
does not currently expose tick / L2 data.

All four bindings (Rust core, Python, Node, WASM) ship the new
indicators with parity tests; benches added; fuzz target extended.
Counter 71 -> 74 across 8 -> 9 families. cargo check --workspace
--all-features green.

* fix(family-16): cover cold paths in InitialBalance + ValueArea

InitialBalance::value() public getter had no test covering the post-update
Some(...) branch — extended accessors_and_metadata to call value() after one
update. ValueArea single-print bar path (c.high == c.low) was unreachable in
existing tests since the only single-print test used a uniform 100-price
window which exits early via the span == 0 guard; added a mixed-window test
that triggers the c.high <= c.low branch directly. The (None, None) arm of
the expansion match was by-construction unreachable (the loop condition
already requires at least one neighbour) and has been folded into an
if/else.

bindings/python/python/wickra/__init__.py

@@ -215,6 +215,10 @@ from ._wickra import (
     # Ichimoku & alternative charts
     Ichimoku,
     HeikinAshi,
+    # Market Profile
+    ValueArea,
+    InitialBalance,
+    OpeningRange,
 )
 
 __all__ = [
@@ -409,4 +413,8 @@ __all__ = [
     # Ichimoku & alternative charts
     "Ichimoku",
     "HeikinAshi",
+    # Market Profile
+    "ValueArea",
+    "InitialBalance",
+    "OpeningRange",
 ]

bindings/python/src/lib.rs

@@ -10816,6 +10816,244 @@ impl PySpearmanCorrelation {
     }
 }
 
+// ============================== ValueArea ==============================
+
+#[pyclass(name = "ValueArea", module = "wickra._wickra", skip_from_py_object)]
+#[derive(Clone)]
+struct PyValueArea {
+    inner: wc::ValueArea,
+}
+
+#[pymethods]
+impl PyValueArea {
+    #[new]
+    #[pyo3(signature = (period=20, bin_count=50, value_area_pct=0.70))]
+    fn new(period: usize, bin_count: usize, value_area_pct: f64) -> PyResult<Self> {
+        Ok(Self {
+            inner: wc::ValueArea::new(period, bin_count, value_area_pct).map_err(map_err)?,
+        })
+    }
+    fn update(&mut self, candle: &Bound<'_, PyAny>) -> PyResult<Option<(f64, f64, f64)>> {
+        let c = extract_candle(candle)?;
+        Ok(self.inner.update(c).map(|o| (o.poc, o.vah, o.val)))
+    }
+    /// Batch over numpy columns high, low, volume. Returns shape `(n, 3)`
+    /// with columns `[poc, vah, val]`; warmup rows are `NaN`.
+    fn batch<'py>(
+        &mut self,
+        py: Python<'py>,
+        high: PyReadonlyArray1<'py, f64>,
+        low: PyReadonlyArray1<'py, f64>,
+        volume: PyReadonlyArray1<'py, f64>,
+    ) -> PyResult<Bound<'py, PyArray2<f64>>> {
+        let h = high
+            .as_slice()
+            .map_err(|_| PyValueError::new_err(NON_CONTIGUOUS))?;
+        let l = low
+            .as_slice()
+            .map_err(|_| PyValueError::new_err(NON_CONTIGUOUS))?;
+        let v = volume
+            .as_slice()
+            .map_err(|_| PyValueError::new_err(NON_CONTIGUOUS))?;
+        if h.len() != l.len() || l.len() != v.len() {
+            return Err(PyValueError::new_err(
+                "high, low, volume must be equal length",
+            ));
+        }
+        let n = h.len();
+        let mut out = vec![f64::NAN; n * 3];
+        for i in 0..n {
+            // open / close pinned to the midpoint so the candle validates.
+            let mid = (h[i] + l[i]) / 2.0;
+            let candle = wc::Candle::new(mid, h[i], l[i], mid, v[i], 0).map_err(map_err)?;
+            if let Some(o) = self.inner.update(candle) {
+                out[i * 3] = o.poc;
+                out[i * 3 + 1] = o.vah;
+                out[i * 3 + 2] = o.val;
+            }
+        }
+        Ok(numpy::ndarray::Array2::from_shape_vec((n, 3), out)
+            .expect("shape consistent")
+            .into_pyarray(py))
+    }
+    #[getter]
+    fn params(&self) -> (usize, usize, f64) {
+        self.inner.params()
+    }
+    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 {
+        let (period, bin_count, pct) = self.inner.params();
+        format!("ValueArea(period={period}, bin_count={bin_count}, value_area_pct={pct})")
+    }
+}
+
+// ============================== InitialBalance ==============================
+
+#[pyclass(
+    name = "InitialBalance",
+    module = "wickra._wickra",
+    skip_from_py_object
+)]
+#[derive(Clone)]
+struct PyInitialBalance {
+    inner: wc::InitialBalance,
+}
+
+#[pymethods]
+impl PyInitialBalance {
+    #[new]
+    #[pyo3(signature = (period=12))]
+    fn new(period: usize) -> PyResult<Self> {
+        Ok(Self {
+            inner: wc::InitialBalance::new(period).map_err(map_err)?,
+        })
+    }
+    fn update(&mut self, candle: &Bound<'_, PyAny>) -> PyResult<Option<(f64, f64)>> {
+        let c = extract_candle(candle)?;
+        Ok(self.inner.update(c).map(|o| (o.high, o.low)))
+    }
+    /// Batch over numpy columns high, low. Returns shape `(n, 2)` with
+    /// columns `[high, low]`.
+    fn batch<'py>(
+        &mut self,
+        py: Python<'py>,
+        high: PyReadonlyArray1<'py, f64>,
+        low: PyReadonlyArray1<'py, f64>,
+    ) -> PyResult<Bound<'py, PyArray2<f64>>> {
+        let h = high
+            .as_slice()
+            .map_err(|_| PyValueError::new_err(NON_CONTIGUOUS))?;
+        let l = low
+            .as_slice()
+            .map_err(|_| PyValueError::new_err(NON_CONTIGUOUS))?;
+        if h.len() != l.len() {
+            return Err(PyValueError::new_err("high and low must be equal length"));
+        }
+        let n = h.len();
+        let mut out = vec![f64::NAN; n * 2];
+        for i in 0..n {
+            let mid = (h[i] + l[i]) / 2.0;
+            let candle = wc::Candle::new(mid, h[i], l[i], mid, 0.0, 0).map_err(map_err)?;
+            if let Some(o) = self.inner.update(candle) {
+                out[i * 2] = o.high;
+                out[i * 2 + 1] = o.low;
+            }
+        }
+        Ok(numpy::ndarray::Array2::from_shape_vec((n, 2), out)
+            .expect("shape consistent")
+            .into_pyarray(py))
+    }
+    #[getter]
+    fn period(&self) -> usize {
+        self.inner.period()
+    }
+    fn is_locked(&self) -> bool {
+        self.inner.is_locked()
+    }
+    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!("InitialBalance(period={})", self.inner.period())
+    }
+}
+
+// ============================== OpeningRange ==============================
+
+#[pyclass(name = "OpeningRange", module = "wickra._wickra", skip_from_py_object)]
+#[derive(Clone)]
+struct PyOpeningRange {
+    inner: wc::OpeningRange,
+}
+
+#[pymethods]
+impl PyOpeningRange {
+    #[new]
+    #[pyo3(signature = (period=6))]
+    fn new(period: usize) -> PyResult<Self> {
+        Ok(Self {
+            inner: wc::OpeningRange::new(period).map_err(map_err)?,
+        })
+    }
+    fn update(&mut self, candle: &Bound<'_, PyAny>) -> PyResult<Option<(f64, f64, f64)>> {
+        let c = extract_candle(candle)?;
+        Ok(self
+            .inner
+            .update(c)
+            .map(|o| (o.high, o.low, o.breakout_distance)))
+    }
+    /// Batch over numpy columns high, low, close. Returns shape `(n, 3)`
+    /// with columns `[high, low, breakout_distance]`.
+    fn batch<'py>(
+        &mut self,
+        py: Python<'py>,
+        high: PyReadonlyArray1<'py, f64>,
+        low: PyReadonlyArray1<'py, f64>,
+        close: PyReadonlyArray1<'py, f64>,
+    ) -> PyResult<Bound<'py, PyArray2<f64>>> {
+        let h = high
+            .as_slice()
+            .map_err(|_| PyValueError::new_err(NON_CONTIGUOUS))?;
+        let l = low
+            .as_slice()
+            .map_err(|_| PyValueError::new_err(NON_CONTIGUOUS))?;
+        let c = close
+            .as_slice()
+            .map_err(|_| PyValueError::new_err(NON_CONTIGUOUS))?;
+        if h.len() != l.len() || l.len() != c.len() {
+            return Err(PyValueError::new_err(
+                "high, low, close must be equal length",
+            ));
+        }
+        let n = h.len();
+        let mut out = vec![f64::NAN; n * 3];
+        for i in 0..n {
+            let candle = wc::Candle::new(c[i], h[i], l[i], c[i], 0.0, 0).map_err(map_err)?;
+            if let Some(o) = self.inner.update(candle) {
+                out[i * 3] = o.high;
+                out[i * 3 + 1] = o.low;
+                out[i * 3 + 2] = o.breakout_distance;
+            }
+        }
+        Ok(numpy::ndarray::Array2::from_shape_vec((n, 3), out)
+            .expect("shape consistent")
+            .into_pyarray(py))
+    }
+    #[getter]
+    fn period(&self) -> usize {
+        self.inner.period()
+    }
+    fn is_locked(&self) -> bool {
+        self.inner.is_locked()
+    }
+    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!("OpeningRange(period={})", self.inner.period())
+    }
+}
+
 // ============================== Module ==============================
 
 #[pymodule]
@@ -11004,5 +11242,8 @@ fn _wickra(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<PyPearsonCorrelation>()?;
     m.add_class::<PyBeta>()?;
     m.add_class::<PySpearmanCorrelation>()?;
+    m.add_class::<PyValueArea>()?;
+    m.add_class::<PyInitialBalance>()?;
+    m.add_class::<PyOpeningRange>()?;
     Ok(())
 }

bindings/python/tests/test_input_validation.py

@@ -41,6 +41,38 @@ def test_roc_and_trix_have_default_periods():
     assert ta.TRIX() is not None
 
 
+def test_value_area_rejects_zero_period():
+    with pytest.raises(ValueError):
+        ta.ValueArea(0, 50, 0.7)
+    with pytest.raises(ValueError):
+        ta.ValueArea(20, 0, 0.7)
+
+
+def test_value_area_rejects_invalid_pct():
+    with pytest.raises(ValueError):
+        ta.ValueArea(20, 50, 0.0)
+    with pytest.raises(ValueError):
+        ta.ValueArea(20, 50, 1.5)
+
+
+def test_initial_balance_rejects_zero_period():
+    with pytest.raises(ValueError):
+        ta.InitialBalance(0)
+
+
+def test_opening_range_rejects_zero_period():
+    with pytest.raises(ValueError):
+        ta.OpeningRange(0)
+
+
+def test_value_area_unequal_length_raises():
+    high = np.array([1.0, 2.0, 3.0])
+    low = np.array([0.5, 1.5])
+    volume = np.array([10.0, 10.0, 10.0])
+    with pytest.raises(ValueError):
+        ta.ValueArea(2, 10, 0.7).batch(high, low, volume)
+
+
 def test_ichimoku_rejects_zero_and_non_increasing_periods():
     with pytest.raises(ValueError):
         ta.Ichimoku(0, 26, 52, 26)

bindings/python/tests/test_known_values.py

@@ -332,6 +332,45 @@ def test_obv_cumulative_known_sequence():
     np.testing.assert_allclose(out, [0.0, 20.0, -10.0, -10.0, 0.0])
 
 
+def test_value_area_concentrated_volume_locates_poc():
+    # Bars 0..3 sit at price 100 with low volume; bar 4 dumps massive volume
+    # at price 110. POC must fall inside the high-volume bar's [low, high]
+    # range; ties resolve to the lowest-index bin, so the POC may sit on the
+    # left edge of bar 4's range rather than at its midpoint.
+    high = np.array([100.5, 100.5, 100.5, 100.5, 110.5])
+    low = np.array([99.5, 99.5, 99.5, 99.5, 109.5])
+    volume = np.array([1.0, 1.0, 1.0, 1.0, 1000.0])
+    out = ta.ValueArea(5, 50, 0.70).batch(high, low, volume)
+    poc = out[-1, 0]
+    assert 109.5 <= poc <= 110.5
+    # VAH >= POC >= VAL.
+    assert out[-1, 1] >= poc >= out[-1, 2]
+
+
+def test_initial_balance_locks_after_period():
+    # First two bars set IB = [99, 103]. Third bar (extreme) must be ignored.
+    high = np.array([102.0, 103.0, 200.0])
+    low = np.array([100.0, 99.0, 50.0])
+    out = ta.InitialBalance(2).batch(high, low)
+    # Bar 0: IB = [100, 102]; Bar 1: IB locked at [99, 103]; Bar 2: unchanged.
+    np.testing.assert_allclose(out[0], [102.0, 100.0])
+    np.testing.assert_allclose(out[1], [103.0, 99.0])
+    np.testing.assert_allclose(out[2], [103.0, 99.0])
+
+
+def test_opening_range_breakout_distance_signed():
+    # OR locks after 2 bars at high 103 / low 100; mid 101.5. Third bar
+    # closes at 105 -> breakout +3.5; fourth bar closes at 95 -> -6.5.
+    high = np.array([102.0, 103.0, 110.0, 110.0])
+    low = np.array([100.0, 101.0, 102.0, 90.0])
+    close = np.array([101.0, 102.0, 105.0, 95.0])
+    out = ta.OpeningRange(2).batch(high, low, close)
+    assert math.isclose(out[2, 0], 103.0)
+    assert math.isclose(out[2, 1], 100.0)
+    assert math.isclose(out[2, 2], 105.0 - 101.5)
+    assert math.isclose(out[3, 2], 95.0 - 101.5)
+
+
 # --- Family 10 — Ehlers / Cycle reference values ---
 
 

bindings/python/tests/test_lifecycle.py

@@ -88,6 +88,32 @@ def test_candle_tuple_input_supported():
     assert v is not None
 
 
+def test_initial_balance_reset_unlocks():
+    ib = ta.InitialBalance(2)
+    assert not ib.is_ready()
+    ib.update((101.0, 102.0, 100.0, 101.0, 0.0, 0))
+    ib.update((102.0, 103.0, 101.0, 102.0, 0.0, 1))
+    assert ib.is_ready()
+    assert ib.is_locked()
+    ib.reset()
+    assert not ib.is_ready()
+    assert not ib.is_locked()
+
+
+def test_opening_range_reset_unlocks():
+    or_ind = ta.OpeningRange(2)
+    or_ind.update((101.0, 102.0, 100.0, 101.0, 0.0, 0))
+    or_ind.update((102.0, 103.0, 101.0, 102.0, 0.0, 1))
+    assert or_ind.is_locked()
+    or_ind.reset()
+    assert not or_ind.is_locked()
+
+
+def test_value_area_warmup_equals_period():
+    assert ta.ValueArea(20, 50, 0.70).warmup_period() == 20
+    assert ta.ValueArea(10, 30, 0.80).warmup_period() == 10
+
+
 def test_ehlers_indicators_lifecycle():
     # Spot-check a few Family-10 entries beyond what test_new_indicators covers.
     series = np.linspace(1.0, 200.0, 200) + np.sin(np.arange(200) * 0.3) * 5.0

bindings/python/tests/test_new_indicators.py

@@ -581,6 +581,57 @@ def test_multi_scalar_streaming_matches_batch(name, ohlcv):
     assert _eq_nan(batch, np.array(rows, dtype=np.float64)), f"{name} mismatch"
 
 
+# --- Market Profile (multi-output with variable shapes) ------------------
+
+
+def test_value_area_shape_and_streaming(ohlcv):
+    high, low, _close, volume = ohlcv
+    batch = ta.ValueArea(20, 50, 0.70).batch(high, low, volume)
+    assert batch.shape == (high.size, 3)
+    streamer = ta.ValueArea(20, 50, 0.70)
+    rows = []
+    for i in range(high.size):
+        mid = float((high[i] + low[i]) / 2.0)
+        candle = (mid, float(high[i]), float(low[i]), mid, float(volume[i]), i)
+        v = streamer.update(candle)
+        rows.append([math.nan, math.nan, math.nan] if v is None else list(v))
+    assert _eq_nan(batch, np.array(rows, dtype=np.float64))
+
+
+def test_initial_balance_shape_and_streaming(ohlcv):
+    high, low, _close, _volume = ohlcv
+    batch = ta.InitialBalance(12).batch(high, low)
+    assert batch.shape == (high.size, 2)
+    streamer = ta.InitialBalance(12)
+    rows = []
+    for i in range(high.size):
+        mid = float((high[i] + low[i]) / 2.0)
+        candle = (mid, float(high[i]), float(low[i]), mid, 0.0, i)
+        v = streamer.update(candle)
+        rows.append([math.nan, math.nan] if v is None else list(v))
+    assert _eq_nan(batch, np.array(rows, dtype=np.float64))
+
+
+def test_opening_range_shape_and_streaming(ohlcv):
+    high, low, close, _volume = ohlcv
+    batch = ta.OpeningRange(6).batch(high, low, close)
+    assert batch.shape == (high.size, 3)
+    streamer = ta.OpeningRange(6)
+    rows = []
+    for i in range(high.size):
+        candle = (
+            float(close[i]),
+            float(high[i]),
+            float(low[i]),
+            float(close[i]),
+            0.0,
+            i,
+        )
+        v = streamer.update(candle)
+        rows.append([math.nan, math.nan, math.nan] if v is None else list(v))
+    assert _eq_nan(batch, np.array(rows, dtype=np.float64))
+
+
 # --- TD Pressure (OHLCV-input) -------------------------------------------
 
 

bindings/python/tests/test_smoke.py

@@ -57,6 +57,25 @@ def test_obv_batch_shape(ohlc_series):
     assert out.shape == close.shape
 
 
+def test_value_area_batch_shape(ohlc_series):
+    high, low, close = ohlc_series
+    volume = np.ones_like(close)
+    out = ta.ValueArea(20, 50, 0.70).batch(high, low, volume)
+    assert out.shape == (close.size, 3)
+
+
+def test_initial_balance_batch_shape(ohlc_series):
+    high, low, _close = ohlc_series
+    out = ta.InitialBalance(12).batch(high, low)
+    assert out.shape == (high.size, 2)
+
+
+def test_opening_range_batch_shape(ohlc_series):
+    high, low, close = ohlc_series
+    out = ta.OpeningRange(6).batch(high, low, close)
+    assert out.shape == (close.size, 3)
+
+
 def test_ichimoku_batch_returns_n_by_5(ohlc_series):
     high, low, close = ohlc_series
     out = ta.Ichimoku().batch(high, low, close)

bindings/python/tests/test_streaming_vs_batch.py

@@ -159,3 +159,45 @@ def test_rolling_vwap_streaming_matches_batch(ohlc_series):
     assert streamer.is_ready()
     streamer.reset()
     assert not streamer.is_ready()
+
+
+def test_value_area_streaming_matches_batch(ohlc_series):
+    high, low, close = ohlc_series
+    volume = np.linspace(100.0, 200.0, num=close.size, dtype=np.float64)
+    batch = ta.ValueArea(20, 50, 0.70).batch(high, low, volume)
+
+    streamer = ta.ValueArea(20, 50, 0.70)
+    rows = []
+    for h, l, v in zip(high, low, volume):
+        mid = float((h + l) / 2.0)
+        out = streamer.update((mid, float(h), float(l), mid, float(v), 0))
+        rows.append([math.nan, math.nan, math.nan] if out is None else list(out))
+    streamed = np.array(rows, dtype=np.float64)
+    assert _equal_with_nan(batch, streamed)
+
+
+def test_initial_balance_streaming_matches_batch(ohlc_series):
+    high, low, _close = ohlc_series
+    batch = ta.InitialBalance(12).batch(high, low)
+
+    streamer = ta.InitialBalance(12)
+    rows = []
+    for h, l in zip(high, low):
+        mid = float((h + l) / 2.0)
+        out = streamer.update((mid, float(h), float(l), mid, 0.0, 0))
+        rows.append([math.nan, math.nan] if out is None else list(out))
+    streamed = np.array(rows, dtype=np.float64)
+    assert _equal_with_nan(batch, streamed)
+
+
+def test_opening_range_streaming_matches_batch(ohlc_series):
+    high, low, close = ohlc_series
+    batch = ta.OpeningRange(6).batch(high, low, close)
+
+    streamer = ta.OpeningRange(6)
+    rows = []
+    for h, l, c in zip(high, low, close):
+        out = streamer.update((float(c), float(h), float(l), float(c), 0.0, 0))
+        rows.append([math.nan, math.nan, math.nan] if out is None else list(out))
+    streamed = np.array(rows, dtype=np.float64)
+    assert _equal_with_nan(batch, streamed)