views-frames 1.8.1__tar.gz → 1.9.0__tar.gz

{views_frames-1.8.1 → views_frames-1.9.0}/.gitignore

@@ -44,3 +44,6 @@ research/**/.cache/
 research/**/results.tsv
 research/**/run.log
 research/**/audit_plots/
+
+# generated figures (research/figures/ generators; deliverable copies travel with the deliverable)
+reports/plots/

{views_frames-1.8.1 → views_frames-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: views-frames
-Version: 1.8.1
+Version: 1.9.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
@@ -36,7 +36,7 @@ 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.8.0 — frozen API, published to PyPI** (frozen since v1.0.0, ADR-018; the
+> **Status:** **v1.9.0 — frozen API, published to PyPI** (frozen since v1.0.0, ADR-018; the
 > v1.1 surface is
 > purely additive — the coherent posterior summary, ADR-019; v1.2.0 rebuilt the tower
 > `outside-in`, C-44; v1.3.0 makes the tower summary distribution-agnostic — no magnitude
@@ -47,7 +47,10 @@ Description-Content-Type: text/markdown
 > sibling package **`views_frames_reconcile`** — forecast reconciliation, ADR-023; v1.8.0
 > adds the native point-country broadcast + the self-describing reconciliation mode,
 > the three showcase notebooks, and the frames-family hardening pass — Reconcile.md CIC,
-> ADR-025 immutability-by-convention, the adversarial red-test batch). This
+> ADR-025 immutability-by-convention, the adversarial red-test batch; v1.9.0 moves the
+> tower-tip MAP to the **top floor** of the published tower — `tip_mass` 0.25 with the
+> **MAP-containment law** in the conformance suite, ADR-019 Amendment 3 — and adds the
+> `research/figures/` tower-figure toolkit). 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

{views_frames-1.8.1 → views_frames-1.9.0}/README.md

@@ -4,7 +4,7 @@
 > containers (`FeatureFrame`, `PredictionFrame`, and their anticipated siblings)
 > that every other repo depends on and that depends on nothing internal.
 >
-> **Status:** **v1.8.0 — frozen API, published to PyPI** (frozen since v1.0.0, ADR-018; the
+> **Status:** **v1.9.0 — frozen API, published to PyPI** (frozen since v1.0.0, ADR-018; the
 > v1.1 surface is
 > purely additive — the coherent posterior summary, ADR-019; v1.2.0 rebuilt the tower
 > `outside-in`, C-44; v1.3.0 makes the tower summary distribution-agnostic — no magnitude
@@ -15,7 +15,10 @@
 > sibling package **`views_frames_reconcile`** — forecast reconciliation, ADR-023; v1.8.0
 > adds the native point-country broadcast + the self-describing reconciliation mode,
 > the three showcase notebooks, and the frames-family hardening pass — Reconcile.md CIC,
-> ADR-025 immutability-by-convention, the adversarial red-test batch). This
+> ADR-025 immutability-by-convention, the adversarial red-test batch; v1.9.0 moves the
+> tower-tip MAP to the **top floor** of the published tower — `tip_mass` 0.25 with the
+> **MAP-containment law** in the conformance suite, ADR-019 Amendment 3 — and adds the
+> `research/figures/` tower-figure toolkit). 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

{views_frames-1.8.1 → views_frames-1.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "views-frames"
-version = "1.8.1"
+version = "1.9.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.8.1 → views_frames-1.9.0}/src/views_frames_summarize/config.py

@@ -28,9 +28,15 @@ TOWER_CONFIG: Final[dict[str, Any]] = {
         [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,
+    # The tower-tip reads the median of the floor at this mass — the top floor of the
+    # published tower. 0.25 (the top-quartile floor; ADR-019 amendment 2026-07-24,
+    # evidence in research/map_hdi/tip_mass_study.py): lower bias than the 0.5 shorth
+    # everywhere, RMSE-superior at pooled S, exact on zero-inflated cells, and it
+    # passes the real-cell C-44 gate with margin — the tip floor's median is safe as
+    # long as a duplicate stack is under half the floor (k > 2·duplicates; at S=32,
+    # k=8 tolerates the observed 2-3-zero stacks). Containment law: every HDI of mass
+    # > tip_mass/2 provably contains the tip (asserted in conformance.py).
+    "tip_mass": 0.25,
     # Optional magnitude zero rule, OFF by default (``None``). When set to a float, a
     # row whose every draw is <= it collapses to 0 — a *count* opt-in (sub-1 ⇒ 0).
     # Left ``None`` for any non-count target: zero-inflation is otherwise handled by the

{views_frames-1.8.1 → views_frames-1.9.0}/src/views_frames_summarize/conformance.py

@@ -126,6 +126,32 @@ def _assert_tower_contract(frame: AnyFrame, n: int) -> None:
     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"
 
+    # MAP-containment law (ADR-019 amendment 2026-07-24). Wider-than-tip_mass floors
+    # contain the tip by nesting. Below tip_mass, a nested floor still contains it
+    # whenever it holds MORE THAN HALF the tip floor's draws: a contiguous sub-window
+    # longer than half the parent cannot trim away the parent's middle draw(s), and
+    # the tip is their median/average. A floor of mass m spans floor(m·S)+1 draws
+    # (the `_ks` value counts inter-draw steps), so the exact condition is
+    # 2·(floor(m·S)+1) > floor(tip_mass·S)+1 — asymptotically mass > tip_mass/2.
+    # Floors below it carry NO guarantee and are below platform sample resolution
+    # (see tower_point.py / research/map_hdi/tip_mass_study.py).
+    s_count = int(frame.values.shape[-1])
+    n_tip = int(np.floor(tip_mass * s_count)) + 1
+    guaranteed = tuple(
+        float(m)
+        for m in config.canonical_floors()
+        if 2 * (int(np.floor(float(m) * s_count)) + 1) > n_tip
+    )
+    law_tower = hdi_tower(frame, masses=guaranteed)
+    for j, m in enumerate(guaranteed):
+        glo, ghi = law_tower[..., j, 0], law_tower[..., j, 1]
+        assert (tip.values[..., 0] >= glo - 1e-6).all(), (
+            f"MAP-containment violated: tip below the {m:.2f} floor"
+        )
+        assert (tip.values[..., 0] <= ghi + 1e-6).all(), (
+            f"MAP-containment violated: tip above the {m:.2f} floor"
+        )
+
     # Reproducibility law: the 50% HDI is independent of the other requested masses.
     just_50 = hdi_tower(frame, masses=(0.5,))
     assert np.array_equal(just_50[..., 0, :], tower[..., 0, :]), (

{views_frames-1.8.1 → views_frames-1.9.0}/src/views_frames_summarize/tower_point.py

@@ -2,15 +2,21 @@
 
 `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"). Zero-inflation is handled by that floor's density (a zero-majority
-row reads 0); the optional, off-by-default magnitude cutoff applies too if set (C-45).
+0.25 — the top-quartile floor, i.e. the top floor of the published tower; ADR-019
+amendment 2026-07-24, evidence in `research/map_hdi/tip_mass_study.py`). Zero-inflation
+is handled by that floor's density (a zero-majority row reads 0); the optional,
+off-by-default magnitude cutoff applies too if set (C-45). Containment law: every HDI
+whose floor holds more than half the tip floor's draws provably contains the tip
+(asymptotically, mass > `tip_mass`/2 — a nested contiguous window longer than half
+the parent cannot trim away the parent's median); narrower floors carry no guarantee
+and are below platform sample resolution. Asserted in ``conformance.py``.
 
 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
+minority duplicated draws (register C-44; a lonely outlier cannot define a 25%-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.
 """