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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: views-frames
-Version: 1.2.0
+Version: 1.3.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,9 +30,10 @@ 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.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
+> **Status:** **v1.3.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 rebuilt the tower
+> `outside-in`, C-44; v1.3.0 makes the tower summary distribution-agnostic — no magnitude
+> zeroing by default, register C-45). 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
@@ -96,16 +97,20 @@ 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.2.0).** Each frozen estimator has a
+**Which estimator? (two coherent paths, v1.3.0).** Each frozen estimator has a
 coherent-tower sibling (ADR-019): `map_estimate` ↔ `tower_point` (an unbinned
 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.
+you request), with `summarize_tower` returning all three in one pass. The tower path is
+**distribution-agnostic** — it works for counts, continuous, normal, and `[0,1]`
+(rate/probability) targets, with **no magnitude zeroing by default** (zero-inflation is read
+off the floor's density, register C-45); a count consumer that wants "sub-1 ⇒ 0" opts in via
+`config['zero_cutoff']`. 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.2.0 → views_frames-1.3.0}/README.md

@@ -4,9 +4,10 @@
 > containers (`FeatureFrame`, `PredictionFrame`, and their anticipated siblings)
 > that every other repo depends on and that depends on nothing internal.
 >
-> **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
+> **Status:** **v1.3.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 rebuilt the tower
+> `outside-in`, C-44; v1.3.0 makes the tower summary distribution-agnostic — no magnitude
+> zeroing by default, register C-45). 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
@@ -70,16 +71,20 @@ 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.2.0).** Each frozen estimator has a
+**Which estimator? (two coherent paths, v1.3.0).** Each frozen estimator has a
 coherent-tower sibling (ADR-019): `map_estimate` ↔ `tower_point` (an unbinned
 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.
+you request), with `summarize_tower` returning all three in one pass. The tower path is
+**distribution-agnostic** — it works for counts, continuous, normal, and `[0,1]`
+(rate/probability) targets, with **no magnitude zeroing by default** (zero-inflation is read
+off the floor's density, register C-45); a count consumer that wants "sub-1 ⇒ 0" opts in via
+`config['zero_cutoff']`. 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.2.0 → views_frames-1.3.0}/pyproject.toml

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

@@ -31,9 +31,12 @@ TOWER_CONFIG: Final[dict[str, Any]] = {
     # 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,
+    # 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
+    # density of the ``tip_mass`` floor, not by magnitude (register C-45). The leaf
+    # imposes no magnitude assumption by default; a consumer that wants it sets this.
+    "zero_cutoff": None,
     # Bimodality detector (coarse histogram + light smoothing; see bimodality.py).
     "bimodality_bins": 16,
     "bimodality_prominence": 0.40,

{views_frames-1.2.0 → views_frames-1.3.0}/src/views_frames_summarize/tower.py

@@ -13,9 +13,10 @@ nearest floor, never inserted — "the 50% HDI" is identical regardless of which
 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.
+C-22/C-25): one sort per block, never a whole-grid sorted copy. Zero-inflation is read
+off the *density* of the `tip_mass` floor (a zero-majority row reads 0); an
+**optional, off-by-default** magnitude cutoff (`config['zero_cutoff']`, a count-domain
+opt-in) can additionally force `max(row) <= cutoff` rows to 0 (C-45).
 
 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`,
@@ -34,11 +35,10 @@ 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.
+# The fixed canonical mass grid, sourced from the single config (no silent defaults —
+# ADR-009). The grid is reproducibility-fixed by design (ADR-019), so it is snapshotted
+# here; the *tunable* knobs (``zero_cutoff``, ``tip_mass``) are read live at call time.
 _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]:
@@ -65,8 +65,18 @@ def _pin(masses: Sequence[float]) -> NDArray[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_)
+    """Rows the optional magnitude cutoff zeroes — ``max(draws) <= zero_cutoff``.
+
+    **Off by default** (``zero_cutoff is None`` ⇒ no row is masked). A consumer that
+    wants magnitude zeroing (a count target where a sub-1 posterior should read 0) sets
+    ``zero_cutoff`` to a float in ``config`` — read **live** here, so the knob takes
+    effect at runtime. By default the leaf imposes **no** magnitude assumption; zero-
+    inflation is handled by the density of the ``tip_mass`` floor instead (C-45).
+    """
+    cutoff = config.get("zero_cutoff")
+    if cutoff is None:
+        return np.zeros(block.shape[0], dtype=np.bool_)
+    return np.asarray(block.max(axis=-1) <= cutoff, dtype=np.bool_)
 
 
 def _in_range_span(
@@ -203,8 +213,9 @@ def hdi_tower(
     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``.
+    independent of the other requested masses). If the optional ``zero_cutoff`` is set,
+    ``max <= cutoff`` rows collapse to ``(0, 0)`` (off by default — C-45). Aligned to
+    ``frame.index``. Tunables come from ``config``.
     """
     values = frame.values
     lead = values.shape[:-1]

{views_frames-1.2.0 → views_frames-1.3.0}/src/views_frames_summarize/tower_point.py

@@ -2,8 +2,8 @@
 
 `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).
+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).
 
 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
@@ -34,9 +34,10 @@ from views_frames_summarize.tower import (
 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``.
+    The median of the ``tip_mass`` floor's samples (``0`` when the zero atom dominates,
+    by density); if the optional ``zero_cutoff`` is set, ``max <= cutoff`` rows are
+    forced to ``0`` (off by default — C-45). Returns the same frame type as ``frame``.
+    Tunables (``tip_mass``, grid, ``zero_cutoff``, row-block) come from ``config``.
     """
     values = frame.values
     lead = values.shape[:-1]