views-frames 1.0.0__py3-none-any.whl

views_frames/__init__.py

@@ -0,0 +1,41 @@
+"""views-frames — the VIEWS platform data-contract layer (numpy only).
+
+Immutable array+identifier value objects at the root of the platform dependency
+DAG. Explicit re-exports only (no ``import *``) so the public API is statically
+analyzable (README §6).
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from views_frames.feature_frame import FeatureFrame
+from views_frames.index import SpatioTemporalIndex
+from views_frames.metadata import FrameMetadata
+from views_frames.prediction_frame import PredictionFrame
+from views_frames.protocols import (
+    Frame,
+    Persistable,
+    Sampled,
+    SpatioTemporalIndexed,
+)
+from views_frames.spatial_level import SpatialLevel
+from views_frames.target_frame import TargetFrame
+
+__all__ = [
+    "FeatureFrame",
+    "Frame",
+    "FrameMetadata",
+    "Persistable",
+    "PredictionFrame",
+    "Sampled",
+    "SpatialLevel",
+    "SpatioTemporalIndex",
+    "SpatioTemporalIndexed",
+    "TargetFrame",
+]
+
+try:
+    __version__ = version("views-frames")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0"

views_frames/_typing.py

@@ -0,0 +1,24 @@
+"""Internal type aliases for the leaf's array surface (register C-19).
+
+`NDArray[np.integer]` is a generic with an unbound parameter: under
+``mypy --strict`` (``disallow_any_generics``) it is a ``[type-arg]`` error at the
+declared numpy floor (``numpy==1.26.4``), even though newer stubs let it slide.
+Parameterising once here — ``np.integer[Any]`` — keeps every call site green at
+the floor and gives the integer identifier arrays a single, named contract.
+
+These are private (underscore module): the public surface is the frames, not the
+array aliases.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+# Integer identifier arrays (``time``, ``unit``): any width, fixed to integers.
+IntArray = NDArray[np.integer[Any]]
+
+# Float32 value arrays: the leaf's canonical value dtype (ADR-009).
+Float32Array = NDArray[np.float32]

views_frames/_validation.py

@@ -0,0 +1,114 @@
+"""Shared construction-time invariant checks (ADR-008, ADR-009).
+
+Fail loud at construction. The guarantee is **structural, not temporal**: the
+leaf validates integer dtype / length-N / completeness, but ``time`` is an opaque
+integer — epoch, range, and monotonicity are a producer concern (register C-11).
+
+This is the numpy-only replacement for the ``pd.isna`` check used today in
+``views-pipeline-core/.../data/prediction_frame.py`` (register C-17): identifiers
+are required to be **integer** dtype, which makes them complete by construction
+(integers cannot be NaN).
+"""
+
+from __future__ import annotations
+
+from typing import cast
+
+import numpy as np
+from numpy.typing import NDArray
+
+from views_frames._typing import IntArray
+
+REQUIRED_IDENTIFIERS = ("time", "unit")
+
+
+def validate_identifiers(
+    identifiers: dict[str, IntArray], n_rows: int
+) -> None:
+    """Assert identifiers are integer 1-D arrays of length ``n_rows``, complete.
+
+    Args:
+        identifiers: Mapping of identifier name to a 1-D integer array.
+        n_rows: The expected length of every identifier array.
+
+    Raises:
+        ValueError: A required identifier is missing, an array is not 1-D, or an
+            array length does not match ``n_rows``.
+        TypeError: An identifier is not a numpy array or not an integer dtype.
+    """
+    for key in REQUIRED_IDENTIFIERS:
+        if key not in identifiers:
+            raise ValueError(f"Missing required identifier: '{key}'")
+    for key, arr in identifiers.items():
+        if not isinstance(arr, np.ndarray):
+            raise TypeError(
+                f"Identifier '{key}' must be a numpy array, "
+                f"got {type(arr).__name__}"
+            )
+        if not np.issubdtype(arr.dtype, np.integer):
+            raise TypeError(
+                f"Identifier '{key}' must be an integer dtype "
+                f"(integers cannot be NaN); got {arr.dtype}"
+            )
+        if arr.ndim != 1:
+            raise ValueError(
+                f"Identifier '{key}' must be 1-D, got ndim={arr.ndim}"
+            )
+        if arr.shape[0] != n_rows:
+            raise ValueError(
+                f"Identifier '{key}' has length {arr.shape[0]} "
+                f"but expected {n_rows}"
+            )
+
+
+def coerce_values(values: object) -> NDArray[np.float32]:
+    """Coerce input to a ``float32`` array, banning object dtype (list-in-cell).
+
+    A ``float32`` input (including an ``np.memmap``) is returned **without a copy**
+    so ``mmap`` and zero-copy semantics are preserved (register C-07). A ``float64``
+    (or other numeric) input is cast to ``float32``.
+
+    Raises:
+        ValueError: the input is object dtype (the banned list-in-cell encoding).
+    """
+    # asanyarray preserves subclasses (e.g. np.memmap) so mmap loads stay zero-copy.
+    arr = np.asanyarray(values)
+    if arr.dtype == np.dtype(object):
+        raise ValueError(
+            "values must not be object dtype — list-in-cell is banned (README §7)"
+        )
+    if arr.dtype == np.float32:
+        return cast("NDArray[np.float32]", arr)
+    return np.asarray(arr, dtype=np.float32)
+
+
+def validate_values(values: NDArray[np.float32]) -> None:
+    """Assert ``values`` are a ``float32`` array with an explicit trailing axis.
+
+    The frame is responsible for coercing input to ``float32`` (accepting e.g.
+    ``float64``) and for rejecting object-dtype input before calling this; this
+    check confirms the final stored invariants.
+
+    Args:
+        values: The frame's value array (first axis = rows; last axis = samples).
+
+    Raises:
+        TypeError: ``values`` is not a numpy array or not ``float32``.
+        ValueError: ``values`` is object dtype (list-in-cell is banned) or lacks
+            an explicit trailing sample axis (``ndim < 2``).
+    """
+    if not isinstance(values, np.ndarray):
+        raise TypeError(
+            f"values must be a numpy array, got {type(values).__name__}"
+        )
+    if values.dtype == np.dtype(object):
+        raise ValueError(
+            "values must not be object dtype — list-in-cell is banned (README §7)"
+        )
+    if values.dtype != np.float32:
+        raise TypeError(f"values must be float32, got {values.dtype}")
+    if values.ndim < 2:
+        raise ValueError(
+            "values must have an explicit trailing sample axis (ndim >= 2), "
+            f"got ndim={values.ndim}"
+        )

views_frames/conformance/__init__.py

@@ -0,0 +1,123 @@
+"""The published conformance suite (ADR-016).
+
+A consumer re-runs these contract checks in CI against **its own** frame factories,
+at a single governed **conformance-floor** version, so every consumer tests the same
+contract (closes the cross-repo gap; register C-10). The checks are plain assertion
+functions (no pytest dependency) so they run anywhere.
+
+Usage in a consumer's test::
+
+    from views_frames.conformance import assert_frame_contract
+    assert_frame_contract(my_adapter_output())
+
+The floor is governed in ``GOVERNANCE.md``; ``CONFORMANCE_FLOOR`` records the version
+this suite belongs to.
+"""
+
+from __future__ import annotations
+
+import tempfile
+from typing import Any
+
+import numpy as np
+
+CONFORMANCE_FLOOR = "1.0.0"
+
+__all__ = [
+    "CONFORMANCE_FLOOR",
+    "assert_cross_level_alignment_law",
+    "assert_frame_contract",
+    "assert_index_alignment_laws",
+]
+
+
+def assert_frame_contract(frame: Any) -> None:
+    """Assert ``frame`` satisfies the views-frames data contract.
+
+    Checks the structural invariants (float32 values, no object dtype, an explicit
+    trailing axis, complete integer identifiers of length ``n_rows``) and the
+    save/load round-trip. (Sample-axis reduction is the ``views_frames_summarize``
+    package's concern, not the contract's — ADR-017.)
+
+    Raises:
+        AssertionError: any part of the contract is violated.
+    """
+    values = frame.values
+    assert isinstance(values, np.ndarray), "values must be a numpy array"
+    assert values.dtype == np.float32, f"values must be float32, got {values.dtype}"
+    assert values.dtype != np.dtype(object), "object dtype is banned (list-in-cell)"
+    assert values.ndim >= 2, "values must have an explicit trailing sample axis"
+    assert values.shape[0] == frame.n_rows, "values rows must equal n_rows"
+
+    ids = frame.identifiers
+    for key in ("time", "unit"):
+        assert key in ids, f"missing required identifier '{key}'"
+        arr = ids[key]
+        assert np.issubdtype(arr.dtype, np.integer), f"'{key}' must be integer"
+        assert arr.shape == (frame.n_rows,), f"'{key}' must be length n_rows"
+
+    _assert_roundtrip(frame)
+
+
+def _assert_roundtrip(frame: Any) -> None:
+    with tempfile.TemporaryDirectory() as directory:
+        frame.save(directory)
+        loaded = type(frame).load(directory)
+        assert np.array_equal(loaded.values, frame.values), "save/load changed values"
+        for key, arr in frame.identifiers.items():
+            assert np.array_equal(loaded.identifiers[key], arr), (
+                f"save/load changed identifier '{key}'"
+            )
+
+
+def assert_index_alignment_laws(index_a: Any, index_b: Any) -> None:
+    """Assert the same-level alignment laws hold for two indices at the same level.
+
+    - intersection is commutative;
+    - an index is a superset of itself (reflexive);
+    - ``searchsorted`` against itself is an identity round-trip.
+
+    Raises:
+        AssertionError: a law is violated.
+    """
+    assert index_a.intersect(index_b) == index_b.intersect(index_a), (
+        "intersect must be commutative"
+    )
+    assert index_a.is_superset_of(index_a) is True, "is_superset_of must be reflexive"
+    pos = index_a.searchsorted(index_a)
+    assert np.array_equal(index_a.time[pos], index_a.time), "searchsorted self-identity"
+    assert np.array_equal(index_a.unit[pos], index_a.unit), "searchsorted self-identity"
+
+
+def assert_cross_level_alignment_law(
+    index: Any, mapping: Any, target_level: Any
+) -> None:
+    """Assert ``cross_level_align`` honours the **time-varying** injected mapping.
+
+    The mapping is keyed by ``(time, unit)`` (register C-20), so the same unit may
+    map to different target units in different time steps. The law:
+
+    - every row's target unit equals ``mapping[(time, unit)]`` (time-varying remap);
+    - ``time`` is preserved row-for-row;
+    - the produced index carries ``target_level``.
+
+    Args:
+        index: a ``SpatioTemporalIndex`` to remap.
+        mapping: a ``{(time, unit): target_unit}`` mapping covering every row.
+        target_level: the ``SpatialLevel`` to remap to.
+
+    Raises:
+        AssertionError: the remap disagrees with the mapping, drops time, or
+            produces the wrong level.
+    """
+    aligned = index.cross_level_align(mapping, target_level)
+    assert aligned.level is target_level, "cross_level_align must carry target_level"
+    assert np.array_equal(aligned.time, index.time), "cross_level_align must keep time"
+    pairs = zip(index.time, index.unit, strict=True)
+    expected = np.array(
+        [mapping[(int(t), int(u))] for t, u in pairs],
+        dtype=aligned.unit.dtype,
+    )
+    assert np.array_equal(aligned.unit, expected), (
+        "cross_level_align must honour the (time, unit)-keyed mapping per row"
+    )

views_frames/feature_frame.py

@@ -0,0 +1,188 @@
+"""`FeatureFrame` — model inputs (X): ``y_features (N, F, S)`` float32.
+
+A sibling frame (no shared base; ADR-011 Option C). Relocated from
+views-datafactory. The sample axis is **always explicit** (ADR-012): legacy 2D
+``(N, F)`` arrays are lifted to ``(N, F, 1)`` only through the explicit
+:meth:`from_2d` shim. Carries ``feature_names`` and a typed metadata header
+(ADR-013). ``from_grid`` is **not** here — it stays in views-datafactory.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+from numpy.typing import NDArray
+
+from views_frames._typing import IntArray
+from views_frames._validation import coerce_values, validate_values
+from views_frames.index import SpatioTemporalIndex
+from views_frames.io import npz
+from views_frames.metadata import FrameMetadata
+from views_frames.spatial_level import SpatialLevel
+
+
+class FeatureFrame:
+    """Immutable model-input frame: ``(N, F, S)`` float32 + index + feature names."""
+
+    def __init__(
+        self,
+        y_features: object,
+        index: SpatioTemporalIndex,
+        feature_names: list[str],
+        metadata: FrameMetadata | None = None,
+    ) -> None:
+        values = coerce_values(y_features)
+        validate_values(values)
+        if values.ndim != 3:
+            raise ValueError(
+                "FeatureFrame y_features must be 3D (N, F, S) with an explicit "
+                f"trailing sample axis (ADR-012), got ndim={values.ndim}. "
+                "Use FeatureFrame.from_2d to lift a legacy (N, F) array."
+            )
+        if values.shape[0] != index.n_rows:
+            raise ValueError(
+                f"y_features has {values.shape[0]} rows but index has {index.n_rows}"
+            )
+        if len(feature_names) != values.shape[1]:
+            raise ValueError(
+                f"feature_names length ({len(feature_names)}) must match the "
+                f"feature axis ({values.shape[1]})"
+            )
+        self._values = values
+        self._index = index
+        self._feature_names = list(feature_names)
+        self._metadata = metadata if metadata is not None else FrameMetadata()
+
+    @classmethod
+    def from_2d(
+        cls,
+        y_features_2d: object,
+        index: SpatioTemporalIndex,
+        feature_names: list[str],
+        metadata: FrameMetadata | None = None,
+    ) -> FeatureFrame:
+        """Lift a legacy 2D ``(N, F)`` array to ``(N, F, 1)`` (deprecated shim)."""
+        arr = coerce_values(y_features_2d)
+        if arr.ndim != 2:
+            raise ValueError(f"from_2d expects a 2D (N, F) array, got ndim={arr.ndim}")
+        return cls(arr[:, :, np.newaxis], index, feature_names, metadata)
+
+    # ---- core surface -------------------------------------------------------
+
+    @property
+    def values(self) -> NDArray[np.float32]:
+        """The ``(N, F, S)`` float32 value array."""
+        return self._values
+
+    @property
+    def index(self) -> SpatioTemporalIndex:
+        """The spatiotemporal row index."""
+        return self._index
+
+    @property
+    def feature_names(self) -> list[str]:
+        """The feature/channel names (length ``F``)."""
+        return list(self._feature_names)
+
+    @property
+    def metadata(self) -> FrameMetadata:
+        """The typed provenance header."""
+        return self._metadata
+
+    @property
+    def n_rows(self) -> int:
+        """Number of rows ``N``."""
+        return int(self._values.shape[0])
+
+    @property
+    def n_features(self) -> int:
+        """Number of features ``F``."""
+        return int(self._values.shape[1])
+
+    @property
+    def identifiers(self) -> dict[str, IntArray]:
+        """The integer identifier arrays from the index."""
+        return self._index.identifiers
+
+    @property
+    def sample_count(self) -> int:
+        """Size of the trailing sample axis ``S``."""
+        return int(self._values.shape[-1])
+
+    @property
+    def is_sample(self) -> bool:
+        """True iff ``sample_count > 1``."""
+        return self.sample_count > 1
+
+    # ---- operations ---------------------------------------------------------
+
+    def with_metadata(self, metadata: FrameMetadata) -> FeatureFrame:
+        """Return a new frame with replaced metadata, **sharing** the values buffer."""
+        new = FeatureFrame.__new__(FeatureFrame)
+        new._values = self._values
+        new._index = self._index
+        new._feature_names = self._feature_names
+        new._metadata = metadata
+        return new
+
+    def select(self, indexer: IntArray | NDArray[np.bool_]) -> FeatureFrame:
+        """A new frame of the rows at integer positions **or** a boolean mask.
+
+        Rows are selected by numpy fancy indexing — an integer array reorders or
+        repeats, a boolean mask filters. ``feature_names`` and metadata are
+        preserved; the selection **copies**. An empty selection yields an empty
+        frame.
+        """
+        return FeatureFrame(
+            self._values[indexer],
+            self._index.select(indexer),
+            self._feature_names,
+            self._metadata,
+        )
+
+    def reindex(self, other: SpatioTemporalIndex) -> FeatureFrame:
+        """Align this frame to ``other``'s rows, returning a new frame.
+
+        Fails loud unless this frame's index is a **superset** of ``other``. The
+        frame-level companion to the index's ``reindex``/``searchsorted``.
+        """
+        if not self._index.is_superset_of(other):
+            raise ValueError(
+                "reindex requires this frame's index to be a superset of `other`; "
+                "some target rows are absent"
+            )
+        return self.select(self._index.searchsorted(other))
+
+    # ---- persistence --------------------------------------------------------
+
+    def save(self, directory: Path | str) -> None:
+        """Serialize to ``directory`` (incl. ``feature_names`` + metadata header)."""
+        npz.save(
+            directory,
+            values=self._values,
+            time=self._index.time,
+            unit=self._index.unit,
+            level=self._index.level.value,
+            metadata=self._metadata.to_dict(),
+            feature_names=self._feature_names,
+        )
+
+    @classmethod
+    def load(cls, directory: Path | str, mmap: bool = False) -> FeatureFrame:
+        """Deserialize a frame from ``directory``; ``mmap`` propagates."""
+        state = npz.load(directory, mmap=mmap)
+        index = SpatioTemporalIndex(
+            time=state["time"],
+            unit=state["unit"],
+            level=SpatialLevel(state["level"]),
+        )
+        feature_names = state["feature_names"]
+        if feature_names is None:
+            raise ValueError("saved FeatureFrame is missing feature_names")
+        return cls(
+            state["values"],
+            index,
+            feature_names,
+            FrameMetadata.from_dict(state["metadata"]),
+        )