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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: views-frames
-Version: 1.1.0
+Version: 1.1.1
 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,8 @@ 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.0 — frozen API** (frozen since v1.0.0, ADR-018; the v1.1.0 surface
-> is purely additive — the coherent posterior summary, ADR-019). This README is the design
+> **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
 > 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,6 +95,21 @@ 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
+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.
+
+**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
+overlapping / unequal mixtures. A `1` means "clearly-separated modes detected"; a `0` means
+**"no clear bimodality detected," not "proven unimodal."** (Full caveat: the `bimodality`
+module docstring; register C-34.)
+
 ---
 
 ## 1. Why this package exists (the problems it kills)

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

@@ -4,8 +4,8 @@
 > containers (`FeatureFrame`, `PredictionFrame`, and their anticipated siblings)
 > that every other repo depends on and that depends on nothing internal.
 >
-> **Status:** **v1.1.0 — frozen API** (frozen since v1.0.0, ADR-018; the v1.1.0 surface
-> is purely additive — the coherent posterior summary, ADR-019). This README is the design
+> **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
 > 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,6 +69,21 @@ 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
+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.
+
+**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
+overlapping / unequal mixtures. A `1` means "clearly-separated modes detected"; a `0` means
+**"no clear bimodality detected," not "proven unimodal."** (Full caveat: the `bimodality`
+module docstring; register C-34.)
+
 ---
 
 ## 1. Why this package exists (the problems it kills)

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "views-frames"
-version = "1.1.0"
+version = "1.1.1"
 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.0 → views_frames-1.1.1}/src/views_frames_summarize/tower.py

@@ -53,10 +53,11 @@ def _ks(sample_count: int) -> NDArray[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); the fixed grid produces no exact
-    distance ties, so the choice is 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-looking interval.
+    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)):