views-frames 1.1.1__tar.gz → 1.2.0__tar.gz

{views_frames-1.1.1 → views_frames-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: views-frames
-Version: 1.1.1
+Version: 1.2.0
 Summary: The VIEWS platform data-contract layer: immutable array+identifier frames (numpy only, root of the dependency DAG).
 Project-URL: Homepage, https://github.com/views-platform/views-frames
 Project-URL: Repository, https://github.com/views-platform/views-frames
@@ -30,8 +30,9 @@ Description-Content-Type: text/markdown
 > containers (`FeatureFrame`, `PredictionFrame`, and their anticipated siblings)
 > that every other repo depends on and that depends on nothing internal.
 >
-> **Status:** **v1.1.1 — frozen API** (frozen since v1.0.0, ADR-018; the v1.1.0 surface
-> is purely additive — the coherent posterior summary, ADR-019; v1.1.1 is a docs patch). This README is the design
+> **Status:** **v1.2.0 — frozen API** (frozen since v1.0.0, ADR-018; the v1.1 surface is
+> purely additive — the coherent posterior summary, ADR-019; v1.2.0 rebuilds the tower
+> `outside-in` and makes it config-driven, register C-44). This README is the design
 > bible; the contract it specifies is realised in `src/views_frames/` (index, frames,
 > io, conformance suite) plus the `src/views_frames_summarize/` sibling package
 > (sample-axis summarization — `collapse`/MAP/HDI/quantiles, the coherent-tower estimators
@@ -95,14 +96,16 @@ Both are numpy-only. For the subtler cm↔pgm surface — a time-varying
 `aggregate_distributions` (`HDI(sum) ≠ sum(HDI)`) — see
 [`examples/cross_level.py`](examples/cross_level.py).
 
-**Which estimator? (two coherent paths, v1.1.0).** Each frozen estimator has a
+**Which estimator? (two coherent paths, v1.2.0).** Each frozen estimator has a
 coherent-tower sibling (ADR-019): `map_estimate` ↔ `tower_point` (an unbinned
-median-of-the-narrowest-floor point, free of `map_estimate`'s histogram tie-break bias),
-and `hdi`/`quantiles` ↔ `hdi_tower(masses=…)` (HDIs nested **by construction** and
-reproducible — a mass's interval is identical regardless of which others you request),
-with `summarize_tower` returning all three in one pass. Use the **frozen** estimators for
-parity with existing pipelines; use the **tower** path when you need coherent, reproducible
-bands plus a matching point.
+median-of-the-`tip_mass`-floor point — the "shorth", free of `map_estimate`'s histogram
+tie-break bias **and** robust to minority duplicated draws, register C-44), and
+`hdi`/`quantiles` ↔ `hdi_tower(masses=…)` (HDIs built **outside-in**, nested **by
+construction** and reproducible — a mass's interval is identical regardless of which others
+you request), with `summarize_tower` returning all three in one pass. The tower's tunables
+live in `views_frames_summarize.config` (fail-loud, no silent defaults). Use the **frozen**
+estimators for parity with existing pipelines; use the **tower** path when you need coherent,
+reproducible bands plus a matching, duplicate-robust point.
 
 **Reading the `bimodality` flag.** It is a *deliberately conservative* heuristic, **not** a
 formal multimodality test — tuned for **zero false positives** at the cost of recall on

{views_frames-1.1.1 → views_frames-1.2.0}/README.md

@@ -4,8 +4,9 @@
 > containers (`FeatureFrame`, `PredictionFrame`, and their anticipated siblings)
 > that every other repo depends on and that depends on nothing internal.
 >
-> **Status:** **v1.1.1 — frozen API** (frozen since v1.0.0, ADR-018; the v1.1.0 surface
-> is purely additive — the coherent posterior summary, ADR-019; v1.1.1 is a docs patch). This README is the design
+> **Status:** **v1.2.0 — frozen API** (frozen since v1.0.0, ADR-018; the v1.1 surface is
+> purely additive — the coherent posterior summary, ADR-019; v1.2.0 rebuilds the tower
+> `outside-in` and makes it config-driven, register C-44). This README is the design
 > bible; the contract it specifies is realised in `src/views_frames/` (index, frames,
 > io, conformance suite) plus the `src/views_frames_summarize/` sibling package
 > (sample-axis summarization — `collapse`/MAP/HDI/quantiles, the coherent-tower estimators
@@ -69,14 +70,16 @@ Both are numpy-only. For the subtler cm↔pgm surface — a time-varying
 `aggregate_distributions` (`HDI(sum) ≠ sum(HDI)`) — see
 [`examples/cross_level.py`](examples/cross_level.py).
 
-**Which estimator? (two coherent paths, v1.1.0).** Each frozen estimator has a
+**Which estimator? (two coherent paths, v1.2.0).** Each frozen estimator has a
 coherent-tower sibling (ADR-019): `map_estimate` ↔ `tower_point` (an unbinned
-median-of-the-narrowest-floor point, free of `map_estimate`'s histogram tie-break bias),
-and `hdi`/`quantiles` ↔ `hdi_tower(masses=…)` (HDIs nested **by construction** and
-reproducible — a mass's interval is identical regardless of which others you request),
-with `summarize_tower` returning all three in one pass. Use the **frozen** estimators for
-parity with existing pipelines; use the **tower** path when you need coherent, reproducible
-bands plus a matching point.
+median-of-the-`tip_mass`-floor point — the "shorth", free of `map_estimate`'s histogram
+tie-break bias **and** robust to minority duplicated draws, register C-44), and
+`hdi`/`quantiles` ↔ `hdi_tower(masses=…)` (HDIs built **outside-in**, nested **by
+construction** and reproducible — a mass's interval is identical regardless of which others
+you request), with `summarize_tower` returning all three in one pass. The tower's tunables
+live in `views_frames_summarize.config` (fail-loud, no silent defaults). Use the **frozen**
+estimators for parity with existing pipelines; use the **tower** path when you need coherent,
+reproducible bands plus a matching, duplicate-robust point.
 
 **Reading the `bimodality` flag.** It is a *deliberately conservative* heuristic, **not** a
 formal multimodality test — tuned for **zero false positives** at the cost of recall on

{views_frames-1.1.1 → views_frames-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "views-frames"
-version = "1.1.1"
+version = "1.2.0"
 description = "The VIEWS platform data-contract layer: immutable array+identifier frames (numpy only, root of the dependency DAG)."
 authors = [
     { name = "Simon Polichinel von der Maase", email = "simmaa@prio.org" },

{views_frames-1.1.1 → views_frames-1.2.0}/src/views_frames_summarize/bimodality.py

@@ -26,11 +26,10 @@ from __future__ import annotations
 import numpy as np
 from numpy.typing import NDArray
 
-from views_frames_summarize._common import ROW_BLOCK, AnyFrame, block_apply
+from views_frames_summarize import config
+from views_frames_summarize._common import AnyFrame, block_apply
 from views_frames_summarize.tower import _zero_mask
 
-_SMOOTH = 3  # moving-average window over bins; tames sparse-histogram flicker
-
 
 def _coarse_counts(flat: NDArray[np.float32], bins: int) -> NDArray[np.intp]:
     """Per-row histogram counts ``(rows, bins)`` over each row's ``[min, max]``.
@@ -49,24 +48,32 @@ def _coarse_counts(flat: NDArray[np.float32], bins: int) -> NDArray[np.intp]:
 
 
 def _bimodal_block(
-    block: NDArray[np.float32], bins: int, prominence: float, min_mass: float
+    block: NDArray[np.float32],
+    bins: int,
+    prominence: float,
+    min_mass: float,
+    smooth: int,
 ) -> NDArray[np.float32]:
-    """Flag (0/1) per row of a block: ≥ 2 separated regions each holding enough mass."""
+    """Flag (0/1) per row of a block: ≥ 2 separated regions each holding enough mass.
+
+    ``smooth`` is the moving-average window width (the 3-tap normalization; config
+    ``bimodality_smooth``). It tames sparse-histogram flicker.
+    """
     rows = block.shape[0]
     counts = _coarse_counts(block, bins).astype(np.float64)
 
-    # Light moving-average smoothing (window _SMOOTH) over the bins. Normalise each
+    # Light moving-average smoothing (window ``smooth``) over the bins. Normalise each
     # position by the number of *real* bins in its window — the two edge bins have one
     # fewer neighbour, so dividing them by the full window would deflate an edge peak
     # (e.g. the zero atom, which always lands in bin 0) and hide an atom+bump bimodal.
     pad = np.zeros((rows, 1))
     padded = np.concatenate([pad, counts, pad], axis=1)
     window_sum = padded[:, :-2] + padded[:, 1:-1] + padded[:, 2:]
-    divisor = np.full(bins, _SMOOTH, dtype=np.float64)
-    divisor[0] = divisor[-1] = _SMOOTH - 1  # edges contribute one fewer real bin
-    smooth = window_sum / divisor
+    divisor = np.full(bins, smooth, dtype=np.float64)
+    divisor[0] = divisor[-1] = smooth - 1  # edges contribute one fewer real bin
+    smoothed = window_sum / divisor
 
-    significant = smooth >= prominence * smooth.max(axis=1, keepdims=True)
+    significant = smoothed >= prominence * smoothed.max(axis=1, keepdims=True)
     prev = np.concatenate(
         [np.zeros((rows, 1), dtype=bool), significant[:, :-1]], axis=1
     )
@@ -87,27 +94,26 @@ def _bimodal_block(
     return flag
 
 
-def bimodality(
-    frame: AnyFrame,
-    *,
-    bins: int = 16,
-    prominence: float = 0.40,
-    min_mass: float = 0.15,
-    block_rows: int = ROW_BLOCK,
-) -> NDArray[np.float32]:
+def bimodality(frame: AnyFrame) -> NDArray[np.float32]:
     """Per-row bimodality flag over the sample axis → ``(N, …, 1)`` of ``0.0``/``1.0``.
 
     Conservative heuristic (see module docstring): ≥ 2 separated density regions, each
     holding ≥ ``min_mass`` of the samples, after coarse binning + light smoothing.
-    Aligned to ``frame.index``.
+    Aligned to ``frame.index``. Tunables (``bins``, ``prominence``, ``min_mass``,
+    ``smooth``, row-block) come from ``config`` — no silent defaults (ADR-009).
     """
     values = frame.values
     lead = values.shape[:-1]
     s = values.shape[-1]
+    bins = int(config.get("bimodality_bins"))
+    prominence = float(config.get("bimodality_prominence"))
+    min_mass = float(config.get("bimodality_min_mass"))
+    smooth = int(config.get("bimodality_smooth"))
+    block_rows = int(config.get("row_block"))
     flat = np.ascontiguousarray(values).reshape(-1, s)
 
     def _block(block: NDArray[np.float32]) -> NDArray[np.float32]:
-        return _bimodal_block(block, bins, prominence, min_mass)
+        return _bimodal_block(block, bins, prominence, min_mass, smooth)
 
     out = block_apply(flat, block_rows, _block)
     return np.asarray(out, dtype=np.float32).reshape(lead)[..., np.newaxis]

views_frames-1.2.0/src/views_frames_summarize/config.py

@@ -0,0 +1,89 @@
+"""Tower-family tunables (ADR-019) — a fail-loud config dict, no silent defaults.
+
+views-models style: a plain dict of tunables, validated at entry, with **no defaults
+anywhere downstream**. ADR-008 (explicit failure) + ADR-009 ("No semantic defaults may
+exist silently"): a tower-family function reads each parameter from here, and a missing
+key raises a ``ValueError`` naming it rather than falling back to a hidden literal.
+
+``masses`` is **not** here — it stays a per-call argument (it is *what* a caller asks
+for, not a tunable). The frozen estimators (``map_estimate``/``hdi``/``quantiles``,
+ADR-018) are **out of scope**; this config governs only the tower family
+(``hdi_tower``/``tower_point``/``bimodality``/``summarize_tower``).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Final
+
+import numpy as np
+from numpy.typing import NDArray
+
+# The single source of truth for every tower-family tunable. Edit values here; the
+# algorithm code carries no fallback literals (ADR-009).
+TOWER_CONFIG: Final[dict[str, Any]] = {
+    # The fixed canonical mass grid: a 5% body + a fine high-mass tail to 0.99. Built
+    # from rounded literals — never ``np.arange`` (which drifts ~1 ulp across numpy
+    # versions and would make every pinned interval non-reproducible; register C-24).
+    "canonical_floors": tuple(
+        [round(0.05 * i, 2) for i in range(1, 19)]  # 0.05 … 0.90
+        + [0.92, 0.94, 0.95, 0.96, 0.97, 0.98, 0.99]  # fine high-mass tail
+    ),
+    # The tower-tip reads the median of the floor at this mass — the "shorth". 0.5 is
+    # the maximally-robust choice: a duplicate would need ~half the draws to hijack it.
+    "tip_mass": 0.5,
+    # Raw-count zero rule: a row whose every draw is <= this collapses to 0 (the quiet
+    # cell). A *count* rule, distinct from ``map_estimate``'s zero-mass-fraction rule.
+    "zero_cutoff": 1.0,
+    # Bimodality detector (coarse histogram + light smoothing; see bimodality.py).
+    "bimodality_bins": 16,
+    "bimodality_prominence": 0.40,
+    "bimodality_min_mass": 0.15,
+    "bimodality_smooth": 3,
+    # Row-block size for the memory-bounded estimators (register C-22/C-25).
+    "row_block": 1 << 16,
+}
+
+# Every key a tower-family function may read. The completeness check is keyed off this,
+# so adding a reader without a corresponding key fails the test suite, not production.
+REQUIRED_KEYS: Final[frozenset[str]] = frozenset(
+    {
+        "canonical_floors",
+        "tip_mass",
+        "zero_cutoff",
+        "bimodality_bins",
+        "bimodality_prominence",
+        "bimodality_min_mass",
+        "bimodality_smooth",
+        "row_block",
+    }
+)
+
+
+def validate_config(cfg: dict[str, Any]) -> None:
+    """Raise ``ValueError`` listing any missing required key (ADR-009 completeness)."""
+    missing = REQUIRED_KEYS - cfg.keys()
+    if missing:
+        raise ValueError(
+            f"tower config is missing required key(s): {sorted(missing)}; "
+            "no semantic defaults may exist silently (ADR-009)"
+        )
+
+
+def get(key: str, cfg: dict[str, Any] | None = None) -> Any:
+    """Fail-loud accessor: raise naming the key rather than returning a default."""
+    cfg = TOWER_CONFIG if cfg is None else cfg
+    if key not in cfg:
+        raise ValueError(
+            f"tower config key {key!r} is not set; no silent default (ADR-008/009). "
+            f"known keys: {sorted(cfg)}"
+        )
+    return cfg[key]
+
+
+def canonical_floors(cfg: dict[str, Any] | None = None) -> NDArray[np.float64]:
+    """The fixed grid as a float64 array (rounded literals; never ``np.arange``)."""
+    return np.asarray(get("canonical_floors", cfg), dtype=np.float64)
+
+
+# Import-time guarantee: the shipped config is itself complete.
+validate_config(TOWER_CONFIG)

{views_frames-1.1.1 → views_frames-1.2.0}/src/views_frames_summarize/conformance.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import numpy as np
 
+from views_frames_summarize import config
 from views_frames_summarize._common import AnyFrame
 from views_frames_summarize.bimodality import bimodality
 from views_frames_summarize.collapse import collapse
@@ -69,10 +70,15 @@ def _assert_tower_contract(frame: AnyFrame, n: int) -> None:
         "tower uppers must be non-decreasing"
     )
 
-    # Tip-in-narrowest law: the point lies inside the narrowest requested floor.
-    lo0, hi0 = tower[..., 0, 0], tower[..., 0, 1]
-    assert (tip.values[..., 0] >= lo0 - 1e-6).all(), "tip below the narrowest floor"
-    assert (tip.values[..., 0] <= hi0 + 1e-6).all(), "tip above the narrowest floor"
+    # Tip-in-tip_mass-floor law (ADR-019, outside-in redesign): the point is the median
+    # of the configured ``tip_mass`` floor, so it lies inside that floor. (It is *not*
+    # tied to the narrowest *requested* floor any longer — a caller may request a
+    # narrower or wider band than ``tip_mass``.)
+    tip_mass = float(config.get("tip_mass"))
+    tip_floor = hdi_tower(frame, masses=(tip_mass,))
+    tlo, thi = tip_floor[..., 0, 0], tip_floor[..., 0, 1]
+    assert (tip.values[..., 0] >= tlo - 1e-6).all(), "tip below the tip_mass floor"
+    assert (tip.values[..., 0] <= thi + 1e-6).all(), "tip above the tip_mass floor"
 
     # Reproducibility law: the 50% HDI is independent of the other requested masses.
     just_50 = hdi_tower(frame, masses=(0.5,))

{views_frames-1.1.1 → views_frames-1.2.0}/src/views_frames_summarize/summarize_tower.py

@@ -4,7 +4,7 @@
 the canonical tower **once**, deriving the tower-tip point, the pinned nested HDIs, and
 the bimodality flag together. It returns exactly what the three composable functions
 (`tower_point`, `hdi_tower`, `bimodality`) return — the bundle is purely an efficiency
-collapse of the three, not a different computation.
+collapse of the three, not a different computation. All tunables come from `config`.
 """
 
 from __future__ import annotations
@@ -15,14 +15,16 @@ from typing import NamedTuple
 import numpy as np
 from numpy.typing import NDArray
 
-from views_frames_summarize._common import ROW_BLOCK, AnyFrame, rebuild
+from views_frames_summarize import config
+from views_frames_summarize._common import AnyFrame, rebuild
 from views_frames_summarize.bimodality import _bimodal_block
 from views_frames_summarize.tower import (
     _CANONICAL_FLOORS,
     _dense_tower,
     _ks,
+    _median_in,
     _pin,
-    _tip,
+    _tip_floor_index,
     _zero_mask,
 )
 
@@ -46,11 +48,6 @@ class TowerSummary(NamedTuple):
 def summarize_tower(
     frame: AnyFrame,
     masses: Sequence[float] = (0.5, 0.9, 0.99),
-    *,
-    bins: int = 16,
-    prominence: float = 0.40,
-    min_mass: float = 0.15,
-    block_rows: int = ROW_BLOCK,
 ) -> TowerSummary:
     """Point + nested HDIs + bimodality flag in one sort-once pass → `TowerSummary`."""
     values = frame.values
@@ -58,7 +55,12 @@ def summarize_tower(
     s = values.shape[-1]
     ks = _ks(s)
     pin = _pin(masses)
-    k0 = int(ks[0])
+    t = _tip_floor_index(s)
+    bins = int(config.get("bimodality_bins"))
+    prominence = float(config.get("bimodality_prominence"))
+    min_mass = float(config.get("bimodality_min_mass"))
+    smooth = int(config.get("bimodality_smooth"))
+    block_rows = int(config.get("row_block"))
     flat = np.ascontiguousarray(values).reshape(-1, s)
     rows = flat.shape[0]
 
@@ -71,14 +73,19 @@ def summarize_tower(
         srt = np.sort(block, axis=-1)
         zero = _zero_mask(block)
 
-        sel = _dense_tower(srt, ks)[:, pin, :]
+        tower = _dense_tower(srt, ks)
+        sel = tower[:, pin, :]
         sel[zero] = 0.0
-        tip = np.where(zero, np.float32(0.0), _tip(srt, k0))
+        tip = np.where(
+            zero, np.float32(0.0), _median_in(srt, tower[:, t, 0], tower[:, t, 1])
+        )
 
         stop = start + block.shape[0]
         point_flat[start:stop] = tip
         intervals_flat[start:stop] = sel
-        bimodal_flat[start:stop] = _bimodal_block(block, bins, prominence, min_mass)
+        bimodal_flat[start:stop] = _bimodal_block(
+            block, bins, prominence, min_mass, smooth
+        )
 
     point = rebuild(frame, point_flat.reshape(lead)[..., np.newaxis])
     intervals = intervals_flat.reshape(*lead, pin.shape[0], 2)

views_frames-1.2.0/src/views_frames_summarize/tower.py

@@ -0,0 +1,224 @@
+"""The constrained-nested HDI tower (ADR-019) — interval estimates over the sample axis.
+
+`hdi_tower` returns, for each requested mass, the highest-density interval read out of
+a **fixed canonical tower** built **outside-in**: the widest floor is the shortest
+interval holding its mass, then each *narrower* floor is the shortest interval
+**contained in** its wider parent. Nesting is guaranteed **by construction** (register
+C-33), and — crucially — the build is **robust to minority duplicated draws** (register
+C-44): a lonely outlier (a couple of exact zeros, a stray pair) is shed by the
+well-determined wide floors, and the containment constraint forbids any narrower floor
+from re-selecting a window that pokes outside its parent. Because the tower is always
+built on the same fixed `_CANONICAL_FLOORS` grid — requested masses are *pinned* to the
+nearest floor, never inserted — "the 50% HDI" is identical regardless of which other
+masses a caller asks for (reproducibility).
+
+The construction is vectorized over the sample axis and runs in row-blocks (register
+C-22/C-25): one sort per block, never a whole-grid sorted copy. A raw-count zero
+short-circuit (`max(row) <= zero_cutoff` → the whole summary collapses to 0) kills the
+quiet cells cheaply.
+
+All tunables (the grid, zero cutoff, row-block size) come from `config` with **no silent
+defaults** (ADR-009). The private engine (`_dense_tower`, `_median_in`, `_pin`,
+`_zero_mask`, `_CANONICAL_FLOORS`) is shared by `tower_point`, `bimodality`, and the
+single-pass `summarize_tower` bundle.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Final
+
+import numpy as np
+from numpy.typing import NDArray
+
+from views_frames_summarize import config
+from views_frames_summarize._common import AnyFrame, block_apply
+
+# The fixed canonical mass grid + the zero cutoff, sourced from the single config (no
+# silent defaults — ADR-009). Kept as module names so the engine and its siblings share
+# one source of truth.
+_CANONICAL_FLOORS: Final[NDArray[np.float64]] = config.canonical_floors()
+_ZERO_CUTOFF: Final[float] = float(config.get("zero_cutoff"))
+
+
+def _ks(sample_count: int) -> NDArray[np.intp]:
+    """The per-floor window size ``k = floor(mass * S)`` for every canonical floor."""
+    return np.asarray(np.floor(_CANONICAL_FLOORS * sample_count), dtype=np.intp)
+
+
+def _pin(masses: Sequence[float]) -> NDArray[np.intp]:
+    """Index of the nearest canonical floor for each requested mass.
+
+    Deterministic: ``argmin`` of the distance, breaking ties on the lowest index. A
+    mass at the midpoint between two floors (e.g. ``0.075`` between ``0.05`` and
+    ``0.10``) therefore pins **down** to the lower floor — unambiguous and
+    reproducible. Fails loud (ADR-008) on a mass outside ``(0, 1)`` rather than silently
+    pinning a nonsense value to the nearest floor and returning a plausible interval.
+    """
+    m = np.asarray(masses, dtype=np.float64)
+    if m.size == 0 or not np.all((m > 0.0) & (m < 1.0)):
+        raise ValueError(
+            f"masses must each be in the open interval (0, 1); got {masses!r}"
+        )
+    dist = np.abs(_CANONICAL_FLOORS[None, :] - m[:, None])
+    return np.asarray(np.argmin(dist, axis=1), dtype=np.intp)
+
+
+def _zero_mask(block: NDArray[np.float32]) -> NDArray[np.bool_]:
+    """Rows whose maximum draw is at/below the zero cutoff — the quiet cells."""
+    return np.asarray(block.max(axis=-1) <= _ZERO_CUTOFF, dtype=np.bool_)
+
+
+def _in_range_span(
+    srt: NDArray[np.float32], lo: NDArray[np.float32], hi: NDArray[np.float32]
+) -> tuple[NDArray[np.intp], NDArray[np.intp]]:
+    """``(first, count)`` of the contiguous run of samples within ``[lo, hi]`` per row.
+
+    ``lo``/``hi`` are sample values (a floor's bounds), so the in-range samples form a
+    contiguous run; at least one is always in range (the floor was built from samples).
+    """
+    inside = (srt >= lo[:, None]) & (srt <= hi[:, None])
+    first = np.argmax(inside, axis=1)  # index of the first in-range sample
+    count = inside.sum(axis=1)
+    return np.asarray(first, dtype=np.intp), np.asarray(count, dtype=np.intp)
+
+
+def _median_in(
+    srt: NDArray[np.float32], lo: NDArray[np.float32], hi: NDArray[np.float32]
+) -> NDArray[np.float32]:
+    """Per-row **median value** of the samples within ``[lo, hi]`` (averaged for an even
+    count). Used for the *tip point estimate*, which may fall between two samples.
+    """
+    first, count = _in_range_span(srt, lo, hi)
+    a = first + (count - 1) // 2
+    b = first + count // 2
+    va = np.take_along_axis(srt, a[:, None], axis=1)[:, 0]
+    vb = np.take_along_axis(srt, b[:, None], axis=1)[:, 0]
+    return np.asarray((va + vb) * 0.5, dtype=np.float32)
+
+
+def _mid_sample_in(
+    srt: NDArray[np.float32], lo: NDArray[np.float32], hi: NDArray[np.float32]
+) -> NDArray[np.float32]:
+    """Per-row **middle sample** (a real draw) of the run within ``[lo, hi]``.
+
+    Used for a ``k <= 0`` *floor*, whose bounds must be actual samples so that the next
+    narrower floor's containment (and `_median_in`) stays well-defined — an averaged
+    median could be a value no draw equals, breaking the contiguous-run assumption.
+    """
+    first, count = _in_range_span(srt, lo, hi)
+    mid = first + (count - 1) // 2
+    return np.asarray(
+        np.take_along_axis(srt, mid[:, None], axis=1)[:, 0], dtype=np.float32
+    )
+
+
+def _shortest_seed(
+    srt: NDArray[np.float32], k: int
+) -> tuple[NDArray[np.float32], NDArray[np.float32]]:
+    """The widest floor (no parent): the shortest interval holding ``k + 1`` samples.
+
+    Leftmost tie-break (``np.argmin`` returns the first). ``k <= 0`` degenerates to the
+    per-row median point; ``k >= n-1`` is the whole row (the widest floor of a small S).
+    """
+    n = srt.shape[-1]
+    if k <= 0:
+        v = srt[:, n // 2]
+        return v.copy(), v.copy()
+    if k >= n - 1:
+        return srt[:, 0].copy(), srt[:, -1].copy()
+    widths = srt[:, k:] - srt[:, : n - k]
+    i = np.argmin(widths, axis=-1)
+    lo = np.take_along_axis(srt, i[:, None], axis=-1)[:, 0]
+    hi = np.take_along_axis(srt, (i + k)[:, None], axis=-1)[:, 0]
+    return lo, hi
+
+
+def _shortest_contained_in(
+    srt: NDArray[np.float32],
+    k: int,
+    parent_lo: NDArray[np.float32],
+    parent_hi: NDArray[np.float32],
+) -> tuple[NDArray[np.float32], NDArray[np.float32]]:
+    """Shortest ``k+1``-sample window ``[lo, hi]`` with ``parent_lo <= lo`` and
+    ``hi <= parent_hi`` — the outside-in nesting step.
+
+    This is what makes the tower nested *and* robust to minority duplicates: a window
+    straddling an outlier cannot fit in a parent that already shed it. Always feasible
+    — the parent's own first ``k+1`` samples are a candidate (the parent holds at least
+    ``k+1`` samples, since floors are non-decreasing in mass and built widest-first).
+    ``k <= 0`` collapses to the in-parent median point.
+    """
+    n = srt.shape[-1]
+    if k <= 0:
+        v = _mid_sample_in(srt, parent_lo, parent_hi)
+        return v, v
+    starts = srt[:, : n - k]
+    ends = srt[:, k:]
+    inside = (starts >= parent_lo[:, None]) & (ends <= parent_hi[:, None])
+    widths = np.where(inside, ends - starts, np.inf)
+    i = np.argmin(widths, axis=-1)
+    lo = np.take_along_axis(starts, i[:, None], axis=-1)[:, 0]
+    hi = np.take_along_axis(ends, i[:, None], axis=-1)[:, 0]
+    return lo, hi
+
+
+def _dense_tower(srt: NDArray[np.float32], ks: NDArray[np.intp]) -> NDArray[np.float32]:
+    """Build the full constrained-nested tower over a sorted block → ``(rows, F, 2)``.
+
+    Built **outside-in**: the widest floor (last index) first, then each narrower floor
+    contained in its wider parent. Each floor is written at its natural ascending index,
+    so the output layout, the ``[:, pin, :]`` readout, and reproducibility are unchanged
+    from the published contract — only the *fill order* runs widest→narrowest.
+    """
+    rows = srt.shape[0]
+    f = ks.shape[0]
+    out = np.empty((rows, f, 2), dtype=np.float32)
+    plo: NDArray[np.float32] | None = None
+    phi: NDArray[np.float32] | None = None
+    for j in range(f - 1, -1, -1):  # widest → narrowest
+        k = int(ks[j])
+        if plo is None or phi is None:
+            lo, hi = _shortest_seed(srt, k)
+        else:
+            lo, hi = _shortest_contained_in(srt, k, plo, phi)
+        out[:, j, 0] = lo
+        out[:, j, 1] = hi
+        plo, phi = lo, hi
+    return out
+
+
+def _tip_floor_index(sample_count: int) -> int:
+    """The canonical-grid index whose mass is nearest ``config['tip_mass']``."""
+    tip_mass = float(config.get("tip_mass"))
+    return int(np.argmin(np.abs(_CANONICAL_FLOORS - tip_mass)))
+
+
+def hdi_tower(
+    frame: AnyFrame,
+    masses: Sequence[float] = (0.5, 0.9, 0.99),
+) -> NDArray[np.float32]:
+    """Per-row constrained-nested HDIs at the requested ``masses`` → ``(N, …, M, 2)``.
+
+    Each requested mass is pinned to the nearest fixed canonical floor; the interval is
+    read out of the full canonical tower (built once per block, outside-in). Nested by
+    construction, robust to minority duplicates, and reproducible (a mass's interval is
+    independent of the other requested masses). Quiet rows (``max <= zero_cutoff``)
+    collapse to ``(0, 0)``. Aligned to ``frame.index``. Tunables come from ``config``.
+    """
+    values = frame.values
+    lead = values.shape[:-1]
+    s = values.shape[-1]
+    ks = _ks(s)
+    pin = _pin(masses)
+    block_rows = int(config.get("row_block"))
+    flat = np.ascontiguousarray(values).reshape(-1, s)
+
+    def _block(block: NDArray[np.float32]) -> NDArray[np.float32]:
+        srt = np.sort(block, axis=-1)
+        sel = _dense_tower(srt, ks)[:, pin, :]
+        sel[_zero_mask(block)] = 0.0
+        return sel
+
+    out = block_apply(flat, block_rows, _block)
+    return np.asarray(out, dtype=np.float32).reshape(*lead, pin.shape[0], 2)

views_frames-1.2.0/src/views_frames_summarize/tower_point.py

@@ -0,0 +1,59 @@
+"""The tower-tip point estimate (ADR-019) — a `(N, …, 1)` frame.
+
+`tower_point` is the "most likely single value" we report to a consumer: the median of
+the draws inside the **`tip_mass` floor** of the nested tower (config-driven, default
+0.5 — the "shorth"), with the same raw-count zero short-circuit as the tower
+(`max(row) <= zero_cutoff` → 0).
+
+It is a *new* estimator, deliberately distinct from the frozen `map_estimate` (ADR-018):
+`map_estimate` is a binned histogram mode with a zero-*mass*-fraction rule and a
+lowest-index tie-break that is directionally biased on right-skewed, zero-inflated,
+low-sample posteriors (register C-32). The tower tip is unbinned — it reads the median
+of a mass-aware floor — so it carries no histogram tie-break **and** is robust to
+minority duplicated draws (register C-44; a lonely outlier cannot define a 50%-mass
+floor). On a genuinely multi-peaked row the tip is, like any point, ambiguous; pair it
+with `bimodality` to detect that case rather than collapse it silently.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+from views_frames_summarize import config
+from views_frames_summarize._common import AnyFrame, block_apply, rebuild
+from views_frames_summarize.tower import (
+    _dense_tower,
+    _ks,
+    _median_in,
+    _tip_floor_index,
+    _zero_mask,
+)
+
+
+def tower_point(frame: AnyFrame) -> AnyFrame:
+    """Per-row tower-tip point estimate over the sample axis → a `(N, …, 1)` frame.
+
+    The median of the ``tip_mass`` floor's samples; ``0.0`` for quiet rows (every draw
+    ``<= zero_cutoff``). Returns a frame of the same type as ``frame``. Tunables (the
+    ``tip_mass``, the grid, the zero cutoff, the row-block) come from ``config``.
+    """
+    values = frame.values
+    lead = values.shape[:-1]
+    s = values.shape[-1]
+    ks = _ks(s)
+    t = _tip_floor_index(s)
+    block_rows = int(config.get("row_block"))
+    flat = np.ascontiguousarray(values).reshape(-1, s)
+
+    def _block(block: NDArray[np.float32]) -> NDArray[np.float32]:
+        srt = np.sort(block, axis=-1)
+        tower = _dense_tower(srt, ks)
+        tip = _median_in(srt, tower[:, t, 0], tower[:, t, 1])
+        return np.asarray(
+            np.where(_zero_mask(block), np.float32(0.0), tip), dtype=np.float32
+        )
+
+    out = block_apply(flat, block_rows, _block)
+    reduced = np.asarray(out, dtype=np.float32).reshape(lead)[..., np.newaxis]
+    return rebuild(frame, reduced)

views_frames-1.1.1/src/views_frames_summarize/tower.py

@@ -1,192 +0,0 @@
-"""The constrained-nested HDI tower (ADR-019) — interval estimates over the sample axis.
-
-`hdi_tower` returns, for each requested mass, the highest-density interval read out
-of a **fixed canonical tower**: a dense set of shortest intervals built inside-out so
-each floor is the shortest interval that *contains* the next-narrower one. Nesting is
-therefore guaranteed **by construction** (no post-hoc "move to nest" patch; register
-C-33), and because the tower is always built on the same fixed `_CANONICAL_FLOORS`
-grid — with requested masses *pinned* to the nearest floor, never inserted — "the 50%
-HDI" is identical regardless of which other masses a caller asks for (reproducibility).
-
-The construction is vectorized over the sample axis and runs in row-blocks (register
-C-22/C-25): one sort per block, never a whole-grid sorted copy. A raw-count zero
-short-circuit (`max(row) <= 1.0` → the whole summary collapses to 0) kills the quiet
-cells — the overwhelming majority — cheaply.
-
-Returns numpy arrays aligned to the frame's index (the interval convention, ADR-017);
-the caller holds the index. The private engine here (`_dense_tower`, `_tip`, `_pin`,
-`_zero_mask`, `_CANONICAL_FLOORS`) is shared by `tower_point`, `bimodality`, and the
-single-pass `summarize_tower` bundle.
-"""
-
-from __future__ import annotations
-
-from collections.abc import Sequence
-from typing import Final
-
-import numpy as np
-from numpy.typing import NDArray
-
-from views_frames_summarize._common import ROW_BLOCK, AnyFrame, block_apply
-
-# The fixed canonical mass grid: a 5% body plus a fixed fine high-mass tail so a
-# requested 0.99 pins to 0.99 (not 0.95). Built from rounded literals — NOT
-# ``np.arange`` (whose float accumulation drifts ~1 ulp across numpy versions and
-# would make the grid, and therefore every pinned interval, non-reproducible).
-_CANONICAL_FLOORS: Final[NDArray[np.float64]] = np.array(
-    [round(0.05 * i, 2) for i in range(1, 19)]  # 0.05 … 0.90
-    + [0.92, 0.94, 0.95, 0.96, 0.97, 0.98, 0.99],  # fine high-mass tail (incl. 0.95)
-    dtype=np.float64,
-)
-
-# Raw-count zero rule: a row whose every draw is <= this collapses to 0 (the quiet
-# cell — no meaningful positive mass). Deliberately a *count* rule, distinct from
-# ``map_estimate``'s zero-*mass*-fraction rule, so the two estimators stay independent.
-_ZERO_CUTOFF: Final = 1.0
-
-
-def _ks(sample_count: int) -> NDArray[np.intp]:
-    """The per-floor window size ``k = floor(mass * S)`` for every canonical floor."""
-    return np.asarray(np.floor(_CANONICAL_FLOORS * sample_count), dtype=np.intp)
-
-
-def _pin(masses: Sequence[float]) -> NDArray[np.intp]:
-    """Index of the nearest canonical floor for each requested mass.
-
-    Deterministic: ``argmin`` of the distance, breaking ties on the lowest index. A
-    mass at the midpoint between two floors (e.g. ``0.075`` between ``0.05`` and
-    ``0.10``) therefore pins **down** to the lower floor — unambiguous and
-    reproducible. Fails loud (ADR-008) on a mass outside ``(0, 1)`` rather than silently
-    pinning a nonsense value to the nearest floor and returning a plausible interval.
-    """
-    m = np.asarray(masses, dtype=np.float64)
-    if m.size == 0 or not np.all((m > 0.0) & (m < 1.0)):
-        raise ValueError(
-            f"masses must each be in the open interval (0, 1); got {masses!r}"
-        )
-    dist = np.abs(_CANONICAL_FLOORS[None, :] - m[:, None])
-    return np.asarray(np.argmin(dist, axis=1), dtype=np.intp)
-
-
-def _zero_mask(block: NDArray[np.float32]) -> NDArray[np.bool_]:
-    """Rows whose maximum draw is at/below the zero cutoff — the quiet cells."""
-    return np.asarray(block.max(axis=-1) <= _ZERO_CUTOFF, dtype=np.bool_)
-
-
-def _shortest(
-    srt: NDArray[np.float32], k: int
-) -> tuple[NDArray[np.float32], NDArray[np.float32]]:
-    """Shortest interval holding ``k + 1`` samples, per row of a sorted block.
-
-    For ``k <= 0`` the floor cannot hold two samples (``S`` below the grid's 1/S
-    resolution); it degenerates to the per-row median point — the tower-tip seed.
-    """
-    n = srt.shape[-1]
-    if k <= 0:
-        v = srt[:, n // 2]
-        return v.copy(), v.copy()
-    widths = srt[:, k:] - srt[:, : n - k]
-    i = np.argmin(widths, axis=-1)
-    lo = np.take_along_axis(srt, i[:, None], axis=-1)[:, 0]
-    hi = np.take_along_axis(srt, (i + k)[:, None], axis=-1)[:, 0]
-    return lo, hi
-
-
-def _shortest_containing(
-    srt: NDArray[np.float32],
-    k: int,
-    plo: NDArray[np.float32],
-    phi: NDArray[np.float32],
-) -> tuple[NDArray[np.float32], NDArray[np.float32]]:
-    """Shortest ``k+1``-sample interval that contains the inner floor ``[plo, phi]``.
-
-    This is what makes the tower nested by construction. ``k <= 0`` inherits the inner
-    floor; ``k >= n-1`` is the whole row.
-    """
-    n = srt.shape[-1]
-    if k <= 0:
-        return plo.copy(), phi.copy()
-    if k >= n - 1:
-        return srt[:, 0].copy(), srt[:, -1].copy()
-    starts = srt[:, : n - k]
-    ends = srt[:, k:]
-    ok = (starts <= plo[:, None]) & (ends >= phi[:, None])
-    widths = np.where(ok, ends - starts, np.inf)
-    i = np.argmin(widths, axis=-1)
-    lo = np.take_along_axis(starts, i[:, None], axis=-1)[:, 0]
-    hi = np.take_along_axis(ends, i[:, None], axis=-1)[:, 0]
-    # Defensive: the construction guarantees an inner floor is itself a sample window,
-    # so a wider containing window always exists — but if that invariant is ever
-    # broken, expand minimally rather than emit a non-nested floor.
-    bad = ~np.isfinite(widths.min(axis=-1))
-    if bad.any():  # pragma: no cover - unreachable while inner ⊂ outer holds
-        lo = np.where(bad, np.minimum(srt[:, 0], plo), lo)
-        hi = np.where(bad, np.maximum(srt[:, -1], phi), hi)
-    return lo, hi
-
-
-def _dense_tower(srt: NDArray[np.float32], ks: NDArray[np.intp]) -> NDArray[np.float32]:
-    """Build the full constrained-nested tower over a sorted block → ``(rows, F, 2)``.
-
-    F is the number of canonical floors; each is nested in the next-wider one.
-    """
-    rows = srt.shape[0]
-    out = np.empty((rows, ks.shape[0], 2), dtype=np.float32)
-    plo: NDArray[np.float32] | None = None
-    phi: NDArray[np.float32] | None = None
-    for j, k in enumerate(ks):
-        if plo is None or phi is None:
-            lo, hi = _shortest(srt, int(k))
-        else:
-            lo, hi = _shortest_containing(srt, int(k), plo, phi)
-        out[:, j, 0] = lo
-        out[:, j, 1] = hi
-        plo, phi = lo, hi
-    return out
-
-
-def _tip(srt: NDArray[np.float32], k0: int) -> NDArray[np.float32]:
-    """The tower tip: the median of the narrowest floor's ``k0 + 1`` samples, per row.
-
-    For ``k0 <= 0`` the floor is the median point itself.
-    """
-    n = srt.shape[-1]
-    if k0 <= 0:
-        return np.array(srt[:, n // 2], dtype=np.float32)
-    widths = srt[:, k0:] - srt[:, : n - k0]
-    i = np.argmin(widths, axis=-1)
-    lo_mid = i + (k0 // 2)
-    hi_mid = i + ((k0 + 1) // 2)
-    a = np.take_along_axis(srt, lo_mid[:, None], axis=-1)[:, 0]
-    b = np.take_along_axis(srt, hi_mid[:, None], axis=-1)[:, 0]
-    return np.asarray((a + b) * 0.5, dtype=np.float32)
-
-
-def hdi_tower(
-    frame: AnyFrame,
-    masses: Sequence[float] = (0.5, 0.9, 0.99),
-    *,
-    block_rows: int = ROW_BLOCK,
-) -> NDArray[np.float32]:
-    """Per-row constrained-nested HDIs at the requested ``masses`` → ``(N, …, M, 2)``.
-
-    Each requested mass is pinned to the nearest fixed canonical floor; the interval is
-    read out of the full canonical tower (built once per block). Nested by construction
-    and reproducible (a mass's interval is independent of the other requested masses).
-    Quiet rows (``max <= 1``) collapse to ``(0, 0)``. Aligned to ``frame.index``.
-    """
-    values = frame.values
-    lead = values.shape[:-1]
-    s = values.shape[-1]
-    ks = _ks(s)
-    pin = _pin(masses)
-    flat = np.ascontiguousarray(values).reshape(-1, s)
-
-    def _block(block: NDArray[np.float32]) -> NDArray[np.float32]:
-        srt = np.sort(block, axis=-1)
-        sel = _dense_tower(srt, ks)[:, pin, :]
-        sel[_zero_mask(block)] = 0.0
-        return sel
-
-    out = block_apply(flat, block_rows, _block)
-    return np.asarray(out, dtype=np.float32).reshape(*lead, pin.shape[0], 2)

views_frames-1.1.1/src/views_frames_summarize/tower_point.py

@@ -1,46 +0,0 @@
-"""The tower-tip point estimate (ADR-019) — a `(N, …, 1)` frame.
-
-`tower_point` is the "most likely single value" we report to a consumer: the median of
-the draws inside the **narrowest canonical floor** of the constrained-nested tower (the
-tip), with the same raw-count zero short-circuit as the tower (`max(row) <= 1` → 0).
-
-It is a *new* estimator, deliberately distinct from the frozen `map_estimate` (ADR-018):
-`map_estimate` is a binned histogram mode with a zero-*mass*-fraction rule and a
-lowest-index tie-break that is directionally biased on right-skewed, zero-inflated,
-low-sample posteriors (register C-32). The tower tip is unbinned — it reads the median
-of an actual shortest-interval window — so it carries no histogram tie-break. On a
-genuinely multi-peaked row the tip is, like any single point, ambiguous; pair it with
-`bimodality` to detect that case rather than collapse it silently.
-"""
-
-from __future__ import annotations
-
-import numpy as np
-from numpy.typing import NDArray
-
-from views_frames_summarize._common import ROW_BLOCK, AnyFrame, block_apply, rebuild
-from views_frames_summarize.tower import _CANONICAL_FLOORS, _tip, _zero_mask
-
-
-def tower_point(frame: AnyFrame, *, block_rows: int = ROW_BLOCK) -> AnyFrame:
-    """Per-row tower-tip point estimate over the sample axis → a `(N, …, 1)` frame.
-
-    The median of the narrowest canonical floor's samples; ``0.0`` for quiet rows
-    (every draw ``<= 1``). Returns a frame of the same type as ``frame``.
-    """
-    values = frame.values
-    lead = values.shape[:-1]
-    s = values.shape[-1]
-    k0 = int(np.floor(_CANONICAL_FLOORS[0] * s))
-    flat = np.ascontiguousarray(values).reshape(-1, s)
-
-    def _block(block: NDArray[np.float32]) -> NDArray[np.float32]:
-        srt = np.sort(block, axis=-1)
-        tip = _tip(srt, k0)
-        return np.asarray(
-            np.where(_zero_mask(block), np.float32(0.0), tip), dtype=np.float32
-        )
-
-    out = block_apply(flat, block_rows, _block)
-    reduced = np.asarray(out, dtype=np.float32).reshape(lead)[..., np.newaxis]
-    return rebuild(frame, reduced)