views-frames 1.0.0__py3-none-any.whl

views_frames-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simon Polichinel von der Maase
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

views_frames_summarize/__init__.py

@@ -0,0 +1,29 @@
+"""views_frames_summarize — posterior / sample-axis summarization over frames.
+
+A sibling package to `views_frames` (ADR-017): it operates on frames and owns the
+volatile statistics the leaf must not. Depends on `views_frames` + numpy only;
+never the reverse (enforced by ``tests/test_import_enforcement.py``).
+
+Conventions (ADR-017): point estimates (mean/median/MAP, generic ``collapse``)
+return a `(N, …, 1)` **frame**; interval estimates (HDI, quantiles) return numpy
+arrays **aligned to the input frame's index** (the caller holds the index).
+"""
+
+from __future__ import annotations
+
+from views_frames_summarize.aggregate import (
+    aggregate_distributions,
+    aggregate_distributions_arrays,
+)
+from views_frames_summarize.collapse import collapse
+from views_frames_summarize.interval import hdi, quantiles
+from views_frames_summarize.point import map_estimate
+
+__all__ = [
+    "aggregate_distributions",
+    "aggregate_distributions_arrays",
+    "collapse",
+    "hdi",
+    "map_estimate",
+    "quantiles",
+]

views_frames_summarize/_common.py

@@ -0,0 +1,68 @@
+"""Shared helpers for the summarize package.
+
+Rebuilds a frame of the same concrete type with new values, preserving the index
+and metadata — the structural plumbing every reducer needs.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import numpy as np
+from numpy.typing import NDArray
+
+from views_frames import (
+    FeatureFrame,
+    PredictionFrame,
+    SpatioTemporalIndex,
+    TargetFrame,
+)
+
+AnyFrame = PredictionFrame | FeatureFrame | TargetFrame
+
+# Default row-block size for the memory-bounded estimators. Blocking caps the peak
+# memory of an estimator at ``O(block * …)`` regardless of row count, so the
+# full-grid reduction path stays well under the #181 OOM (register C-22, C-25).
+ROW_BLOCK = 1 << 16
+
+
+def block_apply(
+    values: NDArray[np.float32],
+    block_rows: int,
+    fn: Callable[[NDArray[np.float32]], NDArray[np.float32]],
+) -> NDArray[np.float32]:
+    """Apply ``fn`` to row-blocks of ``values`` (over axis 0), concatenating results.
+
+    ``fn`` maps a ``(block, …)`` slice to a ``(block, …)`` result (same axis-0
+    length). Peak memory is bounded by one block's working set, not the whole grid.
+    Frames at or below ``block_rows`` rows take the single-shot path (no copy).
+    """
+    n = values.shape[0]
+    if n <= block_rows:
+        return fn(values)
+    parts = [
+        fn(values[start : start + block_rows]) for start in range(0, n, block_rows)
+    ]
+    return np.concatenate(parts, axis=0)
+
+
+def rebuild(
+    frame: AnyFrame,
+    values: NDArray[np.float32],
+    index: SpatioTemporalIndex | None = None,
+) -> AnyFrame:
+    """Return a frame of the same type as ``frame`` with new ``values``.
+
+    The metadata (and, for `FeatureFrame`, `feature_names`) is preserved. The index
+    defaults to the input frame's; pass ``index`` to rebuild at a different index
+    (e.g. after cross-level aggregation). The new values are validated by the
+    frame's constructor.
+    """
+    idx = frame.index if index is None else index
+    if isinstance(frame, FeatureFrame):
+        return FeatureFrame(values, idx, frame.feature_names, frame.metadata)
+    if isinstance(frame, PredictionFrame):
+        return PredictionFrame(values, idx, frame.metadata)
+    if isinstance(frame, TargetFrame):
+        return TargetFrame(values, idx, frame.metadata)
+    raise TypeError(f"unsupported frame type: {type(frame).__name__}")

views_frames_summarize/aggregate.py

@@ -0,0 +1,83 @@
+"""Conservation-correct cross-level aggregation of sample distributions (ADR-017).
+
+Sum the per-cell sample arrays across the cells of each coarser unit **preserving the
+sample index** (joint sampling), so the aggregated uncertainty is correct —
+``HDI(sum) != sum(HDI)`` (the faoapi C-70 concern). The ``(time, unit) ->
+target_unit`` mapping is **injected** by the caller (the same map the leaf's
+``cross_level_align`` takes — time-varying, register C-20); no geography is
+embedded here.
+
+The mapping may be a Python ``dict`` (``aggregate_distributions``) or parallel
+arrays (``aggregate_distributions_arrays``) — the columnar form avoids building a
+~10.5M-key dict at grid scale (register C-26).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from views_frames import SpatialLevel, SpatioTemporalIndex
+from views_frames_summarize._common import AnyFrame, rebuild
+
+
+def aggregate_distributions(
+    frame: AnyFrame,
+    mapping: Mapping[tuple[int, int], int],
+    target_level: SpatialLevel,
+) -> AnyFrame:
+    """Aggregate a frame's sample distributions up to ``target_level``.
+
+    Rows are grouped by ``(time, target_unit)`` — where ``target_unit`` comes from the
+    injected ``(time, unit) -> target_unit`` ``mapping`` via the leaf's
+    ``cross_level_align`` — and the sample arrays are summed **element-wise across the
+    constituent cells** (joint sampling). Time is preserved.
+
+    Raises:
+        ValueError: ``mapping`` is missing/empty, is not keyed by ``(time, unit)``
+            pairs, or a row's ``(time, unit)`` has no entry (inherited from
+            ``cross_level_align`` — the leaf never guesses a mapping).
+    """
+    remapped = frame.index.cross_level_align(mapping, target_level)
+    return _aggregate_to(frame, remapped, target_level)
+
+
+def aggregate_distributions_arrays(
+    frame: AnyFrame,
+    map_keys: NDArray[np.integer[Any]],
+    map_vals: NDArray[np.integer[Any]],
+    target_level: SpatialLevel,
+) -> AnyFrame:
+    """Columnar ``aggregate_distributions`` — the mapping as parallel arrays.
+
+    Identical semantics, but the mapping is injected as ``map_keys`` ``(M, 2)`` and
+    ``map_vals`` ``(M,)`` rather than a Python ``dict``, so a producer holding a
+    grid-scale time-varying mapping never materializes a giant dict (register C-26).
+    Delegates to the leaf's ``cross_level_align_arrays``.
+    """
+    remapped = frame.index.cross_level_align_arrays(map_keys, map_vals, target_level)
+    return _aggregate_to(frame, remapped, target_level)
+
+
+def _aggregate_to(
+    frame: AnyFrame, remapped: SpatioTemporalIndex, target_level: SpatialLevel
+) -> AnyFrame:
+    """Sum samples within each ``(time, target_unit)`` group of ``remapped``."""
+    keys = np.stack(
+        [remapped.time.astype(np.int64), remapped.unit.astype(np.int64)], axis=1
+    )
+    unique, inverse = np.unique(keys, axis=0, return_inverse=True)
+    inverse = np.asarray(inverse).reshape(-1)
+
+    agg = np.zeros((unique.shape[0], *frame.values.shape[1:]), dtype=np.float32)
+    np.add.at(agg, inverse, frame.values)
+
+    agg_index = SpatioTemporalIndex(
+        time=np.asarray(unique[:, 0], dtype=np.int64),
+        unit=np.asarray(unique[:, 1], dtype=np.int64),
+        level=target_level,
+    )
+    return rebuild(frame, agg, agg_index)

views_frames_summarize/collapse.py

@@ -0,0 +1,37 @@
+"""`collapse` — the generic sample-axis fold (a point estimate over the samples).
+
+The statistic is **injected** by the caller (e.g. ``np.mean``, ``np.median``); this
+package owns the *mechanism* (reduce the trailing axis, rebuild a valid frame), not
+a menu of statistics. This is the operation that was removed from the leaf (ADR-017).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import numpy as np
+
+from views_frames_summarize._common import AnyFrame, rebuild
+
+# A reducer is applied as ``reducer(values, axis=-1)`` and reduces the sample axis.
+Reducer = Callable[..., Any]
+
+
+def collapse(frame: AnyFrame, reducer: Reducer) -> AnyFrame:
+    """Reduce the trailing sample axis with ``reducer``, returning a new frame.
+
+    ``reducer`` is called as ``reducer(frame.values, axis=-1)`` — any numpy-style
+    reduction works (``np.mean``, ``np.median``, ``np.max`` …). The result is a
+    point estimate with an explicit trailing axis of size 1 (e.g. `(N, S) → (N, 1)`,
+    `(N, F, S) → (N, F, 1)`).
+
+    Args:
+        frame: A frame with a trailing sample axis.
+        reducer: A callable taking ``(values, axis=-1)`` and reducing that axis.
+
+    Returns:
+        A new frame of the same type with the sample axis collapsed to size 1.
+    """
+    reduced = np.asarray(reducer(frame.values, axis=-1), dtype=np.float32)
+    return rebuild(frame, reduced[..., np.newaxis])

views_frames_summarize/conformance.py

@@ -0,0 +1,40 @@
+"""Conformance checks for the summarize package (ADR-016/017).
+
+A consumer can re-run these against its own frame factories to confirm the
+summarizers behave: point estimates return same-type `(N, …, 1)` frames; interval
+estimates return arrays aligned to the input frame's rows.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from views_frames_summarize._common import AnyFrame
+from views_frames_summarize.collapse import collapse
+from views_frames_summarize.interval import hdi, quantiles
+from views_frames_summarize.point import map_estimate
+
+
+def assert_summarizer_contract(frame: AnyFrame) -> None:
+    """Assert the summarizers behave on ``frame``.
+
+    Raises:
+        AssertionError: a summarizer violates its output contract.
+    """
+    n = frame.n_rows
+
+    point = collapse(frame, np.mean)
+    assert type(point) is type(frame), "collapse must return the same frame type"
+    assert point.values.shape[-1] == 1, "collapse must reduce the sample axis to 1"
+    assert point.n_rows == n, "collapse must preserve rows"
+
+    mode = map_estimate(frame)
+    assert mode.values.shape[-1] == 1 and mode.n_rows == n, "map_estimate → (N,…,1)"
+
+    lo_hi = hdi(frame, mass=0.9)
+    assert lo_hi.shape[0] == n, "hdi must be aligned to the frame's rows"
+    assert lo_hi.shape[-1] == 2, "hdi must produce (lower, upper)"
+
+    qs = quantiles(frame, [0.1, 0.5, 0.9])
+    assert qs.shape[0] == n, "quantiles must be aligned to the frame's rows"
+    assert qs.shape[-1] == 3, "quantiles must produce one column per quantile"

views_frames_summarize/interval.py

@@ -0,0 +1,62 @@
+"""Interval estimates over the sample axis (ADR-017).
+
+Return numpy arrays **aligned to the input frame's index** (the caller holds the
+index): `hdi` → `(N, …, 2)` lower/upper; `quantiles` → `(N, …, len(qs))`.
+
+Both reduce the **trailing** sample axis and are vectorized (no per-row Python
+loop). They run in **row-blocks** (`block_rows`) so peak memory is bounded by one
+block's working set rather than a full-grid sorted copy — the same discipline as
+`map_estimate`, so the whole reduction family stays under the #181 OOM (register
+C-25).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import numpy as np
+from numpy.typing import NDArray
+
+from views_frames_summarize._common import ROW_BLOCK, AnyFrame, block_apply
+
+
+def hdi(
+    frame: AnyFrame, mass: float = 0.9, *, block_rows: int = ROW_BLOCK
+) -> NDArray[np.float32]:
+    """Per-row highest-density interval over the sample axis → `(N, …, 2)`.
+
+    The shortest interval containing ``floor(mass * S)`` samples (empirical HDI),
+    computed vectorized over the trailing axis, in row-blocks of ``block_rows``.
+    """
+    s = frame.values.shape[-1]
+    k = int(np.floor(mass * s))
+
+    def _hdi_block(vals: NDArray[np.float32]) -> NDArray[np.float32]:
+        srt = np.sort(vals, axis=-1)
+        if k < 1:
+            lower = srt[..., 0]
+            return np.stack([lower, lower], axis=-1)
+        # widest-to-narrowest: for each candidate start i, width = srt[i+k] - srt[i];
+        # the narrowest window is the HDI. argmin returns the first minimum.
+        widths = srt[..., k:] - srt[..., : s - k]
+        i = np.argmin(widths, axis=-1)
+        lower = np.take_along_axis(srt, i[..., np.newaxis], axis=-1)[..., 0]
+        upper = np.take_along_axis(srt, (i + k)[..., np.newaxis], axis=-1)[..., 0]
+        return np.stack([lower, upper], axis=-1)
+
+    out = block_apply(frame.values, block_rows, _hdi_block)
+    return np.asarray(out, dtype=np.float32)
+
+
+def quantiles(
+    frame: AnyFrame, qs: Sequence[float], *, block_rows: int = ROW_BLOCK
+) -> NDArray[np.float32]:
+    """Per-row quantiles over the sample axis → `(N, …, len(qs))`, index-aligned."""
+    q_levels = np.asarray(qs, dtype=np.float64)
+
+    def _q_block(vals: NDArray[np.float32]) -> NDArray[np.float32]:
+        q = np.quantile(vals, q_levels, axis=-1)
+        return np.moveaxis(np.asarray(q, dtype=np.float32), 0, -1)
+
+    out = block_apply(frame.values, block_rows, _q_block)
+    return np.asarray(out, dtype=np.float32)

views_frames_summarize/point.py

@@ -0,0 +1,104 @@
+"""Point estimates over the sample axis (ADR-017) — return a `(N, …, 1)` frame.
+
+`map_estimate` is the maximum-a-posteriori estimate as faoapi/reporting compute it:
+the empirical density peak (histogram), with a zero-mass→0 rule for the
+zero-inflated conflict distributions. The mechanism reduces the **trailing** axis;
+the leaf guarantees that axis is the sample axis (ADR-012).
+
+The histogram is computed **batched in row-blocks** (no per-row Python loop) so
+it scales to the full grid (register C-22). Blocking caps peak memory at
+``O(block * bins)`` regardless of row count — a whole-grid batch would allocate a
+``rows × bins`` counts matrix and re-introduce the #181 OOM. The batched binning
+reproduces ``numpy.histogram``'s uniform-bin **counts** and breaks ties on the
+integer counts (lowest-index), so the selected bin is **deterministic and
+identical on every numpy version** (register C-24); the bin centre matches the
+per-row reference to float32 precision (proven by `test_summarize_scale.py`).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+from views_frames_summarize._common import ROW_BLOCK, AnyFrame, rebuild
+
+
+def map_estimate(
+    frame: AnyFrame,
+    *,
+    bins: int = 100,
+    zero_mass_threshold: float = 0.3,
+    block_rows: int = ROW_BLOCK,
+) -> AnyFrame:
+    """Per-row MAP estimate over the sample axis → a `(N, …, 1)` frame.
+
+    For each row: if a fraction ``>= zero_mass_threshold`` of the samples is ~0 the
+    MAP is ``0.0``; otherwise it is the centre of the densest histogram bin. The
+    work runs in row-blocks of ``block_rows`` to bound peak memory (register C-22).
+    """
+    values = frame.values
+    lead = values.shape[:-1]
+    s = values.shape[-1]
+    # Bin in the input dtype, exactly as the v0.2.0 per-row np.histogram did —
+    # upcasting to float64 would shift the bin edges and pick a different mode.
+    flat = np.ascontiguousarray(values).reshape(-1, s)
+
+    result = np.empty(flat.shape[0], dtype=np.float32)
+    for start in range(0, flat.shape[0], block_rows):
+        block = flat[start : start + block_rows]
+        centers = _batched_map(block, bins)
+        mass_at_zero = np.mean(np.isclose(block, 0.0, atol=1e-8), axis=1)
+        result[start : start + block_rows] = np.where(
+            mass_at_zero >= zero_mass_threshold, 0.0, centers
+        )
+
+    reduced = result.reshape(lead)[..., np.newaxis]
+    return rebuild(frame, reduced)
+
+
+def _batched_map(flat: NDArray[np.float32], bins: int) -> NDArray[np.float32]:
+    """Centre of the densest histogram bin for each row of a row-block ``(M, S)``.
+
+    Reproduces ``numpy.histogram``'s uniform-bin path row-by-row but vectorized:
+    same dtype, same edges (``linspace``), same float-rounding correction, so the
+    per-row bin counts — and therefore the argmax and bin centre — are identical.
+    """
+    m = flat.shape[0]
+    dtype = flat.dtype
+    first = flat.min(axis=1)
+    last = flat.max(axis=1)
+    # all-equal rows: numpy widens the range to (v - 0.5, v + 0.5).
+    degenerate = first == last
+    half = np.array(0.5, dtype=dtype)
+    first = np.where(degenerate, first - half, first)
+    last = np.where(degenerate, last + half, last)
+    span = last - first
+
+    # Per-row bin edges — numpy.histogram builds these with linspace at bin dtype.
+    edges = np.linspace(first, last, bins + 1, axis=1).astype(dtype)  # (M, bins + 1)
+
+    # numpy's uniform-bin index: ((a - first) / span) * bins, then the exact
+    # float-rounding correction against the gathered edges.
+    f_idx = ((flat - first[:, None]) / span[:, None]) * bins
+    idx = f_idx.astype(np.intp)
+    idx[idx == bins] = bins - 1
+    left = np.take_along_axis(edges, idx, axis=1)
+    idx[flat < left] -= 1
+    right = np.take_along_axis(edges, idx + 1, axis=1)
+    idx[(flat >= right) & (idx != bins - 1)] += 1
+
+    # Batched bincount: offset each row into its own length-``bins`` block.
+    offsets = idx + (np.arange(m)[:, None] * bins)
+    counts = np.bincount(offsets.ravel(), minlength=m * bins).reshape(m, bins)
+
+    # The densest bin = the one with the most samples. Tie-break on the **integer
+    # counts** (lowest-index wins), not on ``counts / width`` density: the bins are
+    # uniform so density and counts agree on the winner — *except* on ties, where
+    # the float64 bin widths differ by ~1 ulp across numpy versions and flip the
+    # argmax (register C-24). Integer ``argmax`` is deterministic and identical on
+    # every numpy build, so ``map_estimate`` is portable and reproducible.
+    densest = np.argmax(counts, axis=1)
+
+    lo = np.take_along_axis(edges, densest[:, None], axis=1)[:, 0]
+    hi = np.take_along_axis(edges, (densest + 1)[:, None], axis=1)[:, 0]
+    return np.asarray((lo + hi) / 2.0, dtype=np.float32)