views-frames 1.0.0__py3-none-any.whl

views_frames/index.py

@@ -0,0 +1,309 @@
+"""`SpatioTemporalIndex` — the genuinely-reused alignment primitive.
+
+`{time, unit, level}` integer arrays plus **same-level** pure-numpy alignment
+(intersect / reindex / is_superset_of / argsort / searchsorted). Cross-level
+(cm↔pgm) alignment is exposed via `cross_level_align`, whose mapping is
+**injected by the consumer** and never embedded or fetched here (ADR-014,
+register C-14).
+
+The same-level join is the pure-numpy unwrap of the proven
+`pd.Index.get_indexer` pattern in `views-faoapi/.../data/handlers.py`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+import numpy as np
+from numpy.typing import NDArray
+
+from views_frames._typing import IntArray
+from views_frames._validation import validate_identifiers
+from views_frames.spatial_level import SpatialLevel
+
+
+class SpatioTemporalIndex:
+    """An immutable ``{time, unit, level}`` row index with same-level alignment.
+
+    **Row-uniqueness stance (register C-21).** A frame *may* contain duplicate
+    ``(time, unit)`` rows — ``cross_level_align`` deliberately produces them (many
+    pgm cells map to one country, to be summed by ``aggregate_distributions``), so
+    uniqueness is **not** a global invariant and is **not** validated at
+    construction. The **same-level joins** (``searchsorted``/``reindex``/
+    ``intersect``/``is_superset_of``), however, assume one row per ``(time, unit)``
+    and give undefined results on duplicates. A consumer that needs that guarantee
+    should check :meth:`has_unique_rows` before joining; the default path stays
+    allocation-free.
+    """
+
+    def __init__(
+        self,
+        time: IntArray,
+        unit: IntArray,
+        level: SpatialLevel,
+    ) -> None:
+        if not isinstance(level, SpatialLevel):
+            raise TypeError(
+                f"level must be a SpatialLevel, got {type(level).__name__}"
+            )
+        is_array = isinstance(time, np.ndarray) and time.ndim >= 1
+        n = int(time.shape[0]) if is_array else -1
+        validate_identifiers({"time": time, "unit": unit}, n_rows=n)
+        # store as read-only views so the value object cannot be mutated in place
+        self._time = np.ascontiguousarray(time)
+        self._unit = np.ascontiguousarray(unit)
+        self._time.setflags(write=False)
+        self._unit.setflags(write=False)
+        self._level = level
+
+    # ---- core surface -------------------------------------------------------
+
+    @property
+    def time(self) -> IntArray:
+        """The time identifier array (read-only)."""
+        return self._time
+
+    @property
+    def unit(self) -> IntArray:
+        """The unit identifier array (read-only)."""
+        return self._unit
+
+    @property
+    def level(self) -> SpatialLevel:
+        """The spatial level (cm/pgm) of these rows."""
+        return self._level
+
+    @property
+    def n_rows(self) -> int:
+        """Number of rows (the first axis length)."""
+        return int(self._time.shape[0])
+
+    @property
+    def identifiers(self) -> dict[str, IntArray]:
+        """The integer identifier arrays, keyed by name."""
+        return {"time": self._time, "unit": self._unit}
+
+    def __len__(self) -> int:
+        return self.n_rows
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, SpatioTemporalIndex):
+            return NotImplemented
+        return (
+            self._level == other._level
+            and np.array_equal(self._time, other._time)
+            and np.array_equal(self._unit, other._unit)
+        )
+
+    def __hash__(self) -> int:  # value objects are immutable; hash by identity surface
+        return hash((self._level, self._time.tobytes(), self._unit.tobytes()))
+
+    # ---- internal key representation ---------------------------------------
+
+    def _keys(self) -> NDArray[np.int64]:
+        """A contiguous ``(N, 2)`` int64 ``(time, unit)`` key array."""
+        return np.ascontiguousarray(
+            np.stack([self._time.astype(np.int64), self._unit.astype(np.int64)], axis=1)
+        )
+
+    @staticmethod
+    def _row_view(keys: NDArray[np.int64]) -> NDArray[np.void]:
+        """View each ``(time, unit)`` row as a single void scalar for set ops."""
+        return np.ascontiguousarray(keys).view(
+            np.dtype((np.void, keys.dtype.itemsize * keys.shape[1]))
+        ).reshape(-1)
+
+    def _require_same_level(self, other: SpatioTemporalIndex) -> None:
+        if self._level != other._level:
+            raise ValueError(
+                "same-level operation requires equal SpatialLevel; "
+                f"got {self._level} and {other._level}. Use cross_level_align."
+            )
+
+    # ---- same-level alignment ----------------------------------------------
+
+    def argsort(self) -> NDArray[np.intp]:
+        """Positions that sort the rows by ``(time, unit)`` (time-major)."""
+        return np.asarray(np.lexsort((self._unit, self._time)), dtype=np.intp)
+
+    def searchsorted(self, other: SpatioTemporalIndex) -> NDArray[np.intp]:
+        """For each row of ``other``, its position in ``self`` (-1 if absent).
+
+        The pure-numpy analogue of ``pd.Index.get_indexer``: a same-level join.
+        """
+        self._require_same_level(other)
+        self_rows = self._row_view(self._keys())
+        other_rows = self._row_view(other._keys())
+        order = np.argsort(self_rows, kind="stable")
+        sorted_rows = self_rows[order]
+        pos = np.searchsorted(sorted_rows, other_rows)
+        pos = np.clip(pos, 0, len(sorted_rows) - 1)
+        found = sorted_rows[pos] == other_rows
+        result = np.where(found, order[pos], -1)
+        return result.astype(np.intp)
+
+    def reindex(self, other: SpatioTemporalIndex) -> NDArray[np.intp]:
+        """Alias of :meth:`searchsorted` — positions to align ``self`` to ``other``."""
+        return self.searchsorted(other)
+
+    def is_superset_of(self, other: SpatioTemporalIndex) -> bool:
+        """True iff every row of ``other`` is present in ``self`` (same level)."""
+        self._require_same_level(other)
+        self_rows = self._row_view(self._keys())
+        other_rows = self._row_view(other._keys())
+        return bool(np.isin(other_rows, self_rows).all())
+
+    def intersect(self, other: SpatioTemporalIndex) -> SpatioTemporalIndex:
+        """A new index of the rows present in **both** ``self`` and ``other``."""
+        self._require_same_level(other)
+        common = np.intersect1d(
+            self._row_view(self._keys()), self._row_view(other._keys())
+        )
+        keys = common.view(np.int64).reshape(-1, 2)
+        return SpatioTemporalIndex(
+            time=keys[:, 0].copy(), unit=keys[:, 1].copy(), level=self._level
+        )
+
+    def has_unique_rows(self) -> bool:
+        """True iff every ``(time, unit)`` row is unique (register C-21).
+
+        Duplicates are **allowed** in a frame, but the same-level joins
+        (``searchsorted``/``reindex``/``intersect``/``is_superset_of``) assume
+        uniqueness. Call this before joining if the caller cannot otherwise
+        guarantee it. ``O(n log n)``; not run by default.
+        """
+        rows = self._row_view(self._keys())
+        return bool(len(np.unique(rows)) == rows.shape[0])
+
+    def select(
+        self, indexer: IntArray | NDArray[np.bool_]
+    ) -> SpatioTemporalIndex:
+        """A new index of the rows at integer positions **or** a boolean mask.
+
+        The row-selection primitive the frame-level ``select``/``reindex`` build on:
+        ``indexer`` is applied to ``time`` and ``unit`` by numpy fancy indexing
+        (so an integer position array reorders/repeats, a boolean mask filters).
+        """
+        return SpatioTemporalIndex(
+            time=self._time[indexer], unit=self._unit[indexer], level=self._level
+        )
+
+    # ---- cross-level alignment (ADR-014) -----------------------------------
+
+    def cross_level_align(
+        self,
+        mapping: Mapping[tuple[int, int], int],
+        target_level: SpatialLevel,
+    ) -> SpatioTemporalIndex:
+        """Remap each row's ``unit`` to ``target_level`` using an injected mapping.
+
+        The cross-level (cm↔pgm) join needs an external, **time-varying**
+        ``(time, unit) -> target_unit`` mapping (e.g. ``(month_id, priogrid_id) ->
+        country_id``): a cell's country assignment changes by month, so the key is
+        ``(time, unit)``, not ``unit`` alone (ADR-014; register C-20). The leaf owns
+        this **operation**; the **mapping is supplied by the caller** and is never
+        embedded or fetched here. Time is preserved.
+
+        The remap is vectorized — ``(time, unit)`` keys are viewed as void scalars
+        and matched with a single ``searchsorted`` against the sorted mapping keys —
+        so it scales to the full grid (no per-row Python loop; register C-22).
+
+        Args:
+            mapping: A ``{(time, unit): target_unit}`` mapping injected by the
+                consumer, keyed by the ``(time, unit)`` pair.
+            target_level: The ``SpatialLevel`` of the produced index.
+
+        Raises:
+            ValueError: ``mapping`` is missing/empty, is not keyed by ``(time,
+                unit)`` pairs, or a row's ``(time, unit)`` has no entry in
+                ``mapping`` (the leaf never guesses a mapping).
+            TypeError: ``target_level`` is not a ``SpatialLevel``.
+        """
+        if not isinstance(target_level, SpatialLevel):
+            got = type(target_level).__name__
+            raise TypeError(f"target_level must be a SpatialLevel, got {got}")
+        if mapping is None or len(mapping) == 0:
+            raise ValueError(
+                "cross_level_align requires an injected (time, unit)->target_unit "
+                "mapping; the leaf never embeds or fetches it (ADR-014)."
+            )
+        map_keys = np.array(list(mapping.keys()), dtype=np.int64)
+        if map_keys.ndim != 2 or map_keys.shape[1] != 2:
+            raise ValueError(
+                "cross_level_align mapping must be keyed by (time, unit) pairs "
+                "(register C-20); got keys that are not 2-tuples."
+            )
+        map_vals = np.array(list(mapping.values()), dtype=self._unit.dtype)
+        return self._remap(map_keys, map_vals, target_level)
+
+    def cross_level_align_arrays(
+        self,
+        map_keys: IntArray,
+        map_vals: IntArray,
+        target_level: SpatialLevel,
+    ) -> SpatioTemporalIndex:
+        """Columnar form of :meth:`cross_level_align` for grid-scale mappings.
+
+        Identical semantics, but the ``(time, unit) -> target_unit`` mapping is
+        injected as **parallel arrays** — ``map_keys`` of shape ``(M, 2)`` and
+        ``map_vals`` of shape ``(M,)`` — rather than a Python ``dict``. At full-grid
+        scale building and materializing a ~10.5M-key dict is the dominant cost
+        (~30× slower, ~10× the memory of the columnar form; register C-26); a
+        producer that already holds the mapping columnar passes it straight through.
+
+        Raises:
+            ValueError: ``map_keys`` is not ``(M, 2)``, ``map_vals`` is not length
+                ``M``, the mapping is empty, or a row's ``(time, unit)`` is absent.
+            TypeError: ``target_level`` is not a ``SpatialLevel``.
+        """
+        if not isinstance(target_level, SpatialLevel):
+            got = type(target_level).__name__
+            raise TypeError(f"target_level must be a SpatialLevel, got {got}")
+        keys = np.ascontiguousarray(map_keys, dtype=np.int64)
+        vals = np.asarray(map_vals)
+        if keys.ndim != 2 or keys.shape[1] != 2:
+            raise ValueError(
+                "cross_level_align_arrays map_keys must be an (M, 2) array of "
+                "(time, unit) rows (register C-20/C-26)."
+            )
+        if vals.shape != (keys.shape[0],):
+            raise ValueError(
+                "cross_level_align_arrays map_vals must be a length-M array "
+                "aligned to map_keys."
+            )
+        if keys.shape[0] == 0:
+            raise ValueError(
+                "cross_level_align_arrays requires a non-empty mapping; the leaf "
+                "never embeds or fetches it (ADR-014)."
+            )
+        return self._remap(keys, vals, target_level)
+
+    def _remap(
+        self, map_keys: IntArray, map_vals: IntArray, target_level: SpatialLevel
+    ) -> SpatioTemporalIndex:
+        """The vectorized ``(time, unit) -> target`` remap shared by both entries.
+
+        ``map_keys`` is coerced to a contiguous int64 ``(M, 2)`` so the void-view
+        keys match ``self``'s; a single ``searchsorted`` does the lookup; a missing
+        ``(time, unit)`` fails loud.
+        """
+        keys = np.ascontiguousarray(map_keys, dtype=np.int64)
+        map_rows = self._row_view(keys)
+        order = np.argsort(map_rows, kind="stable")
+        sorted_rows = map_rows[order]
+
+        self_rows = self._row_view(self._keys())
+        pos = np.clip(
+            np.searchsorted(sorted_rows, self_rows), 0, len(sorted_rows) - 1
+        )
+        found = sorted_rows[pos] == self_rows
+        if not bool(found.all()):
+            miss = int(np.argmax(~found))
+            t, u = int(self._time[miss]), int(self._unit[miss])
+            raise ValueError(
+                f"(time, unit) ({t}, {u}) has no entry in the injected mapping"
+            )
+        mapped = np.asarray(map_vals[order[pos]], dtype=self._unit.dtype)
+        return SpatioTemporalIndex(
+            time=self._time.copy(), unit=mapped, level=target_level
+        )

views_frames/io/__init__.py

@@ -0,0 +1,13 @@
+"""Serialization adapters — frame ↔ bytes *format*, never *transport* (ADR-009).
+
+Two scalable formats; list-in-cell object-dtype is banned (README §7):
+
+- `npz` — native ``values.npy`` + ``identifiers.npz`` (mmap-capable).
+- `arrow` — flat-columnar parquet (the scalable interchange format).
+
+`pyarrow` is imported only inside this subpackage, never in the core frames.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

views_frames/io/arrow.py

@@ -0,0 +1,103 @@
+"""Flat-columnar (parquet) serialization — the scalable interchange format.
+
+One scalar cell per ``(time, unit, sample)`` (features become columns for a 3-D
+feature frame); the scalable replacement for the banned list-in-cell encoding
+(README §7). This is the **only** module permitted to import ``pyarrow`` (the
+optional ``[arrow]`` extra). Operates on a frame's state dict (register C-09).
+
+The reconstruction shape (``n_features`` / ``n_samples``) and the header (level,
+metadata, feature_names) ride in the parquet schema key-value metadata so the
+round-trip is exact.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import pyarrow as pa
+import pyarrow.parquet as pq
+from numpy.typing import NDArray
+
+from views_frames._typing import IntArray
+
+
+def save(
+    path: Path | str,
+    *,
+    values: NDArray[np.float32],
+    time: IntArray,
+    unit: IntArray,
+    level: str,
+    metadata: dict[str, Any],
+    feature_names: list[str] | None = None,
+) -> None:
+    """Write a frame's state as flat-columnar parquet (one scalar cell per row)."""
+    if values.ndim == 2:
+        n, s = values.shape
+        n_features = 0
+    elif values.ndim == 3:
+        n, n_features, s = values.shape
+    else:
+        raise ValueError(f"unsupported values.ndim={values.ndim}")
+
+    time_col = np.repeat(time, s)
+    unit_col = np.repeat(unit, s)
+    sample_col = np.tile(np.arange(s, dtype=np.int32), n)
+    columns: dict[str, NDArray[Any]] = {
+        "time": time_col,
+        "unit": unit_col,
+        "sample": sample_col,
+    }
+    if values.ndim == 2:
+        columns["value"] = values.reshape(n * s)
+    else:
+        for f in range(n_features):
+            columns[f"f{f}"] = np.ascontiguousarray(values[:, f, :]).reshape(n * s)
+
+    header = {
+        "level": level,
+        "metadata": metadata,
+        "feature_names": feature_names,
+        "n_features": n_features,
+        "n_samples": s,
+        "ndim": int(values.ndim),
+    }
+    table = pa.table(columns)
+    table = table.replace_schema_metadata({"views_frames": json.dumps(header)})
+    pq.write_table(table, str(path))
+
+
+def load(path: Path | str) -> dict[str, Any]:
+    """Read a flat-columnar parquet frame state written by :func:`save`."""
+    table = pq.read_table(str(path))
+    raw = table.schema.metadata or {}
+    header = json.loads(raw[b"views_frames"].decode())
+    s = int(header["n_samples"])
+    ndim = int(header["ndim"])
+
+    time_col = table.column("time").to_numpy()
+    unit_col = table.column("unit").to_numpy()
+    n = time_col.shape[0] // s
+    time = time_col.reshape(n, s)[:, 0]
+    unit = unit_col.reshape(n, s)[:, 0]
+
+    if ndim == 2:
+        values = table.column("value").to_numpy().reshape(n, s).astype(np.float32)
+    else:
+        n_features = int(header["n_features"])
+        stacked = [
+            table.column(f"f{f}").to_numpy().reshape(n, s) for f in range(n_features)
+        ]
+        values = np.stack(stacked, axis=1).astype(np.float32)
+
+    return {
+        "values": values,
+        "time": np.ascontiguousarray(time),
+        "unit": np.ascontiguousarray(unit),
+        "level": header["level"],
+        "metadata": header.get("metadata", {}),
+        "feature_names": header.get("feature_names"),
+    }

views_frames/io/npz.py

@@ -0,0 +1,59 @@
+"""Native serialization: ``values.npy`` + ``identifiers.npz`` (+ JSON header).
+
+Operates on a frame's **state dict** — it carries no per-frame schema (register
+C-09); each frame maps its fields to/from the state. The ``mmap`` path returns a
+read-only memmap and preserves the subclass so peak RAM stays the working set
+(register C-07, README §7) — the proven ``PredictionFrame`` idiom.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Literal
+
+import numpy as np
+from numpy.typing import NDArray
+
+from views_frames._typing import IntArray
+
+
+def save(
+    directory: Path | str,
+    *,
+    values: NDArray[np.float32],
+    time: IntArray,
+    unit: IntArray,
+    level: str,
+    metadata: dict[str, Any],
+    feature_names: list[str] | None = None,
+) -> None:
+    """Write a frame's state (npy values + npz identifiers + json header)."""
+    directory = Path(directory)
+    directory.mkdir(parents=True, exist_ok=True)
+    np.save(directory / "values.npy", values)
+    np.savez(directory / "identifiers.npz", time=time, unit=unit)
+    header: dict[str, Any] = {"level": level, "metadata": metadata}
+    if feature_names is not None:
+        header["feature_names"] = feature_names
+    payload = json.dumps(header, sort_keys=True, default=str)
+    (directory / "header.json").write_text(payload)
+
+
+def load(directory: Path | str, *, mmap: bool = False) -> dict[str, Any]:
+    """Read a frame's state; ``mmap=True`` returns ``values`` as a read-only memmap."""
+    directory = Path(directory)
+    mmap_mode: Literal["r"] | None = "r" if mmap else None
+    values = np.load(directory / "values.npy", mmap_mode=mmap_mode)
+    with np.load(directory / "identifiers.npz") as npz:
+        time = npz["time"]
+        unit = npz["unit"]
+    header = json.loads((directory / "header.json").read_text())
+    return {
+        "values": values,
+        "time": time,
+        "unit": unit,
+        "level": header["level"],
+        "metadata": header.get("metadata", {}),
+        "feature_names": header.get("feature_names"),
+    }

views_frames/metadata.py

@@ -0,0 +1,36 @@
+"""`FrameMetadata` — the typed, optional-extensible provenance header (ADR-013).
+
+Not a free-form dict: a frozen dataclass with all-optional, validated fields, so
+adding a field is a MINOR change and consumers cannot diverge on key names (the
+store-side cause of reporting's C-48). It is the typed home for run/eval identity.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, fields
+from typing import Any
+
+
+@dataclass(frozen=True)
+class FrameMetadata:
+    """Optional provenance carried by a frame. All fields default to ``None``."""
+
+    model: str | None = None
+    run_type: str | None = None
+    timestamp: int | None = None
+    seed: int | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to a plain dict, omitting unset (``None``) fields."""
+        return {
+            f.name: getattr(self, f.name)
+            for f in fields(self)
+            if getattr(self, f.name) is not None
+        }
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> FrameMetadata:
+        """Reconstruct from a dict, ignoring unknown keys (forward-compatible)."""
+        known = {f.name for f in fields(cls)}
+        return cls(**{k: v for k, v in data.items() if k in known})

views_frames/prediction_frame.py

@@ -0,0 +1,143 @@
+"""`PredictionFrame` — model outputs (ŷ samples): ``y_pred (N, S)`` float32.
+
+A sibling frame (no shared base; ADR-011 Option C). Relocated from
+views-pipeline-core and rewritten **numpy-only** — the original imports pandas
+(``pd.isna``); here identifier validation is the integer-dtype check in
+``_validation`` (register C-17). The sample axis is always explicit (`S >= 1`;
+ADR-012).
+"""
+
+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 PredictionFrame:
+    """Immutable model-output frame: ``(N, S)`` float32 + a spatiotemporal index."""
+
+    def __init__(
+        self,
+        y_pred: object,
+        index: SpatioTemporalIndex,
+        metadata: FrameMetadata | None = None,
+    ) -> None:
+        values = coerce_values(y_pred)
+        validate_values(values)
+        if values.ndim != 2:
+            raise ValueError(
+                f"PredictionFrame y_pred must be 2D (N, S), got ndim={values.ndim}"
+            )
+        if values.shape[0] != index.n_rows:
+            raise ValueError(
+                f"y_pred has {values.shape[0]} rows but index has {index.n_rows}"
+            )
+        self._values = values
+        self._index = index
+        self._metadata = metadata if metadata is not None else FrameMetadata()
+
+    # ---- core surface -------------------------------------------------------
+
+    @property
+    def values(self) -> NDArray[np.float32]:
+        """The ``(N, S)`` float32 value array."""
+        return self._values
+
+    @property
+    def index(self) -> SpatioTemporalIndex:
+        """The spatiotemporal row index."""
+        return self._index
+
+    @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 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) -> PredictionFrame:
+        """Return a new frame with replaced metadata, **sharing** the values buffer."""
+        new = PredictionFrame.__new__(PredictionFrame)
+        new._values = self._values
+        new._index = self._index
+        new._metadata = metadata
+        return new
+
+    def select(self, indexer: IntArray | NDArray[np.bool_]) -> PredictionFrame:
+        """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. Metadata is preserved; the selection
+        **copies** (the result does not share the buffer). An empty selection
+        yields an empty frame.
+        """
+        return PredictionFrame(
+            self._values[indexer], self._index.select(indexer), self._metadata
+        )
+
+    def reindex(self, other: SpatioTemporalIndex) -> PredictionFrame:
+        """Align this frame to ``other``'s rows, returning a new frame.
+
+        Fails loud unless this frame's index is a **superset** of ``other`` (so
+        every target row is present). The frame-level companion to the index's
+        ``reindex``/``searchsorted``, which return positions rather than a frame.
+        """
+        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`` (npy + npz + 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(),
+        )
+
+    @classmethod
+    def load(cls, directory: Path | str, mmap: bool = False) -> PredictionFrame:
+        """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"]),
+        )
+        return cls(state["values"], index, FrameMetadata.from_dict(state["metadata"]))