spatialsample 0.1.0__py3-none-any.whl

spatialsample/io.py

@@ -0,0 +1,161 @@
+"""Reading sampling frames and sites from GeoJSON, CSV or (optionally) GeoPandas."""
+
+from __future__ import annotations
+
+import csv
+import json
+import os
+from typing import Any, Dict, Hashable, List, Optional, Tuple, Union
+
+import numpy as np
+
+from .geometry import Region, _iter_polygons
+
+__all__ = [
+    "read_geojson",
+    "read_region",
+    "read_strata",
+    "read_points",
+    "read_lines",
+    "read_matrix_csv",
+]
+
+PathLike = Union[str, "os.PathLike[str]"]
+
+
+def read_geojson(path: PathLike) -> Dict[str, Any]:
+    """Load a GeoJSON file as a Python mapping."""
+    with open(path, encoding="utf-8") as fh:
+        data = json.load(fh)
+    if not isinstance(data, dict) or "type" not in data:
+        raise ValueError(f"{path} is not a GeoJSON object")
+    return data
+
+
+def _load(src: Any) -> Dict[str, Any]:
+    if isinstance(src, dict):
+        return src
+    if hasattr(src, "__geo_interface__"):
+        return dict(src.__geo_interface__)
+    path = os.fspath(src)
+    if path.lower().endswith((".geojson", ".json")):
+        return read_geojson(path)
+    if not os.path.exists(path):
+        raise FileNotFoundError(path)
+    try:  # other vector formats through GeoPandas, when installed
+        import geopandas as gpd
+    except ImportError as exc:
+        raise ValueError(
+            f"cannot read {path!r}: only GeoJSON is supported without geopandas "
+            "(pip install 'spatialsample[geo]')"
+        ) from exc
+    return dict(gpd.read_file(path).__geo_interface__)  # pragma: no cover
+
+
+def read_region(src: Any) -> Region:
+    """All polygons of a GeoJSON file/mapping (or GeoPandas object) as one Region."""
+    return Region.from_geojson(_load(src))
+
+
+def read_strata(src: Any, field: str) -> Dict[Hashable, Region]:
+    """Polygon features grouped by the value of property ``field``."""
+    data = _load(src)
+    feats = data.get("features") if data.get("type") == "FeatureCollection" else [data]
+    groups: Dict[Hashable, List[Any]] = {}
+    for f in feats or []:
+        props = f.get("properties") or {}
+        if field not in props:
+            raise KeyError(f"feature without property {field!r}")
+        polys = list(_iter_polygons(f))
+        if polys:
+            groups.setdefault(props[field], []).extend(polys)
+    if not groups:
+        raise ValueError("no polygon features found")
+    return {k: Region(v) for k, v in groups.items()}
+
+
+def read_points(src: Any) -> Tuple[np.ndarray, List[Dict[str, Any]]]:
+    """Point coordinates and properties from GeoJSON (Point/MultiPoint) or CSV.
+
+    CSV files need ``x`` and ``y`` columns (``lon``/``lat`` also accepted).
+    """
+    if not isinstance(src, dict) and os.fspath(src).lower().endswith(".csv"):
+        return _read_points_csv(os.fspath(src))
+    data = _load(src)
+    xy: List[List[float]] = []
+    props: List[Dict[str, Any]] = []
+
+    def visit(obj: Dict[str, Any], p: Dict[str, Any]) -> None:
+        t = obj.get("type")
+        if t == "FeatureCollection":
+            for f in obj.get("features", []):
+                visit(f, {})
+        elif t == "Feature" and obj.get("geometry"):
+            visit(obj["geometry"], obj.get("properties") or {})
+        elif t == "Point":
+            xy.append(list(obj["coordinates"][:2]))
+            props.append(p)
+        elif t == "MultiPoint":
+            for c in obj["coordinates"]:
+                xy.append(list(c[:2]))
+                props.append(p)
+
+    visit(data, {})
+    if not xy:
+        raise ValueError("no point geometries found")
+    return np.asarray(xy, dtype=float), props
+
+
+def _read_points_csv(path: str) -> Tuple[np.ndarray, List[Dict[str, Any]]]:
+    with open(path, newline="", encoding="utf-8") as fh:
+        rows = list(csv.DictReader(fh))
+    if not rows:
+        raise ValueError("empty CSV")
+    keys = {k.lower(): k for k in rows[0]}
+    xk = keys.get("x") or keys.get("lon") or keys.get("longitude")
+    yk = keys.get("y") or keys.get("lat") or keys.get("latitude")
+    if xk is None or yk is None:
+        raise ValueError("CSV needs x/y (or lon/lat) columns")
+    xy = np.array([[float(r[xk]), float(r[yk])] for r in rows])
+    return xy, [dict(r) for r in rows]
+
+
+def read_lines(src: Any) -> List[np.ndarray]:
+    """LineString / MultiLineString coordinates from GeoJSON."""
+    from .designs import _as_lines
+
+    return _as_lines(_load(src))
+
+
+def read_matrix_csv(path: PathLike) -> Tuple[np.ndarray, Optional[List[str]]]:
+    """Read a square error matrix from CSV.
+
+    A header row and/or a first label column are detected automatically
+    (rows = map classes, columns = reference classes).
+    """
+    with open(path, newline="", encoding="utf-8") as fh:
+        rows = [r for r in csv.reader(fh) if any(c.strip() for c in r)]
+    if not rows:
+        raise ValueError("empty matrix file")
+
+    def numeric(s: str) -> bool:
+        try:
+            float(s)
+            return True
+        except ValueError:
+            return False
+
+    labels: Optional[List[str]] = None
+    if not all(numeric(c) for c in rows[0] if c.strip()):
+        header = rows[0]
+        rows = rows[1:]
+        labels = [c.strip() for c in header]
+    first_col_labels = any(not numeric(r[0]) for r in rows)
+    if first_col_labels:
+        row_labels = [r[0].strip() for r in rows]
+        rows = [r[1:] for r in rows]
+        labels = row_labels
+    mat = np.array([[float(c) for c in r if c.strip() != ""] for r in rows])
+    if labels is not None and len(labels) != mat.shape[0]:
+        labels = labels[-mat.shape[0] :] if len(labels) > mat.shape[0] else None
+    return mat, labels

spatialsample/lpm.py

@@ -0,0 +1,133 @@
+"""Local Pivotal Method (LPM2), Grafström, Lundström & Schelin (2012).
+
+The pivotal method repeatedly picks two undecided units and moves inclusion
+probability between them so that at least one of the two is decided (its
+probability becomes 0 or 1), while the expected value of each unit's
+probability stays the same. Choosing the pair as a randomly drawn unit and its
+*nearest* undecided neighbour (LPM2) makes nearby units unlikely to be
+selected together, which spreads the sample in space. Each unit is included
+with exactly its prescribed first-order inclusion probability.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import numpy as np
+
+from ._frame import ProbLike, frame_sizes, grid_frame, jitter_in_cells, resolve
+from ._types import FloatArray, SeedLike, as_rng
+from .probabilities import inclusion_probabilities
+from .sample import Sample
+
+__all__ = ["lpm", "lpm2_select"]
+
+_EPS = 1e-10
+
+
+def lpm2_select(xy: FloatArray, pi: FloatArray, seed: SeedLike = None) -> np.ndarray:
+    """Run LPM2 and return the indices of the selected units.
+
+    ``pi`` are the target inclusion probabilities (they should sum to an
+    integer). Runs in ``O(N^2)`` time; frames up to a few tens of thousands of
+    units are practical.
+    """
+    rng = as_rng(seed)
+    p = np.asarray(pi, dtype=float).copy()
+    pts = np.asarray(xy, dtype=float)
+    if len(p) != len(pts):
+        raise ValueError("xy and pi must have the same length")
+    if np.any(p < -_EPS) or np.any(p > 1 + _EPS):
+        raise ValueError("inclusion probabilities must lie in [0, 1]")
+    active = np.flatnonzero((p > _EPS) & (p < 1 - _EPS))
+    ax = pts[active].copy()
+    na = len(active)
+    while na > 1:
+        a = int(rng.integers(na))
+        d = (ax[:na, 0] - ax[a, 0]) ** 2 + (ax[:na, 1] - ax[a, 1]) ** 2
+        d[a] = np.inf
+        dmin = d.min()
+        ties = np.flatnonzero(d == dmin)
+        b = int(ties[rng.integers(len(ties))]) if len(ties) > 1 else int(ties[0])
+        i, j = active[a], active[b]
+        pi_i, pi_j = p[i], p[j]
+        s = pi_i + pi_j
+        u = rng.random()
+        if s < 1.0:
+            if u * s < pi_j:
+                p[i], p[j] = 0.0, s
+            else:
+                p[i], p[j] = s, 0.0
+        else:
+            if u * (2.0 - s) < 1.0 - pi_j:
+                p[i], p[j] = 1.0, s - 1.0
+            else:
+                p[i], p[j] = s - 1.0, 1.0
+        # drop decided units from the active set (swap with the last active one)
+        for pos in sorted((a, b), reverse=True):
+            q = p[active[pos]]
+            if q <= _EPS or q >= 1 - _EPS:
+                na -= 1
+                active[pos], active[na] = active[na], active[pos]
+                ax[[pos, na]] = ax[[na, pos]]
+    if na == 1:  # numerical leftover
+        k = active[0]
+        p[k] = 1.0 if rng.random() < p[k] else 0.0
+    return np.flatnonzero(p >= 0.5)
+
+
+def lpm(
+    frame: Any,
+    n: int,
+    prob: ProbLike = None,
+    frame_size: Optional[int] = None,
+    seed: SeedLike = None,
+) -> Sample:
+    """Draw a spatially balanced sample with the local pivotal method (LPM2).
+
+    Parameters
+    ----------
+    frame:
+        Polygon/raster domain (continuous design over a dense grid frame) or an
+        ``(N, 2)`` array of candidate sites (finite design).
+    n:
+        Sample size.
+    prob:
+        Optional size measure; inclusion probabilities are proportional to it
+        (units that would exceed 1 are taken with certainty).
+    frame_size:
+        Grid cells used for a continuous domain (default ``max(2000, 40 * n)``).
+    seed:
+        Seed or generator.
+    """
+    rng = as_rng(seed)
+    if n < 1:
+        raise ValueError("n must be >= 1")
+    domain, pts = resolve(frame)
+    if pts is not None:
+        pi = inclusion_probabilities(frame_sizes(prob, pts), n)
+        sel = lpm2_select(pts, pi, rng)
+        return Sample(
+            xy=pts[sel],
+            pi=pi[sel],
+            weight=1.0 / pi[sel],
+            design="lpm",
+            kind="finite",
+            index=sel,
+            meta={"n": n, "population_size": len(pts)},
+        )
+    assert domain is not None
+    size = frame_size or max(2000, 40 * n)
+    cells, h = grid_frame(domain, size, rng, min_points=2 * n)
+    pi = inclusion_probabilities(frame_sizes(prob, cells), n)
+    sel = lpm2_select(cells, pi, rng)
+    xy = jitter_in_cells(cells[sel], h, domain, rng)
+    density = np.full(len(sel), n / domain.area) if prob is None else pi[sel] / (h * h)
+    return Sample(
+        xy=xy,
+        pi=density,
+        weight=1.0 / density,
+        design="lpm",
+        kind="continuous",
+        meta={"n": n, "area": domain.area, "frame_size": len(cells)},
+    )

spatialsample/probabilities.py

@@ -0,0 +1,202 @@
+"""Inclusion probabilities, sample allocation and nearest-neighbour helpers."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Hashable, List, Mapping, Optional, Sequence, Union
+
+import numpy as np
+
+from ._types import FloatArray
+
+__all__ = [
+    "inclusion_probabilities",
+    "allocate",
+    "systematic_pps",
+    "nearest_index",
+]
+
+
+def inclusion_probabilities(size: Any, n: float) -> FloatArray:
+    """Inclusion probabilities proportional to ``size`` that sum to ``n``.
+
+    Units whose scaled value would exceed one are taken with certainty
+    (probability 1) and the remainder is rescaled, iteratively, exactly as in
+    the classic ``inclusionprobabilities`` routine of Tillé.
+    """
+    a = np.asarray(size, dtype=float).ravel()
+    if np.any(a < 0) or not np.all(np.isfinite(a)):
+        raise ValueError("size measures must be finite and non-negative")
+    if n < 0 or n > np.count_nonzero(a):
+        raise ValueError(f"n={n} must be between 0 and the number of positive sizes")
+    pi = np.zeros_like(a)
+    if n == 0:
+        return pi
+    cert = np.zeros(len(a), dtype=bool)
+    for _ in range(len(a) + 1):
+        rest = ~cert & (a > 0)
+        left = n - cert.sum()
+        pi[cert] = 1.0
+        tot = a[rest].sum()
+        pi[rest] = left * a[rest] / tot if tot > 0 else 0.0
+        over = rest & (pi >= 1.0)
+        if not over.any():
+            break
+        cert |= over
+    return np.minimum(pi, 1.0)
+
+
+def systematic_pps(pi: FloatArray, rng: np.random.Generator) -> np.ndarray:
+    """Systematic selection along the given order with probabilities ``pi``.
+
+    ``pi`` must sum to an integer ``n``; returns the selected positions
+    (exactly ``n``), each unit chosen with probability ``pi_i``.
+    """
+    cum = np.cumsum(pi)
+    n = int(round(float(cum[-1]))) if len(cum) else 0
+    if n == 0:
+        return np.empty(0, dtype=np.int64)
+    cum = cum * (n / cum[-1])
+    targets = rng.uniform() + np.arange(n)
+    pos = np.searchsorted(cum, targets, side="right")
+    return np.minimum(pos, len(pi) - 1)
+
+
+def _largest_remainder(
+    n: int, share: FloatArray, minimum: FloatArray, cap: FloatArray
+) -> np.ndarray:
+    k = len(share)
+    alloc = np.minimum(minimum.astype(np.int64), cap.astype(np.int64))
+    for _ in range(4 * k + 10):
+        left = n - alloc.sum()
+        if left <= 0:
+            break
+        open_ = alloc < cap
+        if not open_.any():
+            break
+        s = np.where(open_, share, 0.0)
+        if s.sum() <= 0:
+            s = open_.astype(float)
+        ideal = left * s / s.sum()
+        add = np.minimum(np.floor(ideal).astype(np.int64), (cap - alloc).astype(np.int64))
+        if add.sum() == 0:
+            rem = np.where(open_, ideal - np.floor(ideal) + 1e-12 * s, -np.inf)
+            j = int(np.argmax(rem))
+            add = np.zeros(k, dtype=np.int64)
+            add[j] = 1
+        alloc = alloc + add
+    return alloc
+
+
+def allocate(
+    n: int,
+    sizes: Union[Mapping[Hashable, float], Sequence[float]],
+    method: str = "proportional",
+    sd: Optional[Union[Mapping[Hashable, float], Sequence[float]]] = None,
+    min_per_stratum: int = 0,
+    caps: Optional[Union[Mapping[Hashable, float], Sequence[float]]] = None,
+) -> Any:
+    """Split a total sample size ``n`` among strata.
+
+    Parameters
+    ----------
+    n:
+        Total sample size.
+    sizes:
+        Stratum sizes (areas or unit counts), as a mapping or a sequence.
+    method:
+        ``"proportional"`` (n_h proportional to size), ``"equal"`` or
+        ``"neyman"`` (n_h proportional to size times standard deviation).
+    sd:
+        Stratum standard deviations, required for Neyman allocation.
+    min_per_stratum:
+        Lower bound for every stratum (useful for rare map classes).
+    caps:
+        Optional upper bounds (for finite strata: the number of units).
+
+    Returns
+    -------
+    A mapping when ``sizes`` is a mapping, otherwise a list of ints. Rounding
+    uses the largest-remainder method so the result sums to ``n``.
+    """
+    keys: List[Hashable]
+    if isinstance(sizes, Mapping):
+        keys = list(sizes)
+        sz = np.array([float(sizes[k]) for k in keys])
+    else:
+        keys = list(range(len(sizes)))
+        sz = np.asarray(sizes, dtype=float)
+
+    def _vec(v: Any) -> FloatArray:
+        if isinstance(v, Mapping):
+            return np.array([float(v[k]) for k in keys])
+        return np.asarray(v, dtype=float)
+
+    if np.any(sz < 0):
+        raise ValueError("stratum sizes must be non-negative")
+    method = method.lower()
+    if method == "proportional":
+        share = sz
+    elif method == "equal":
+        share = (sz > 0).astype(float)
+    elif method == "neyman":
+        if sd is None:
+            raise ValueError("Neyman allocation needs per-stratum standard deviations (sd=)")
+        share = sz * _vec(sd)
+    else:
+        raise ValueError("method must be 'proportional', 'equal' or 'neyman'")
+    cap = _vec(caps) if caps is not None else np.full(len(sz), float(n))
+    cap = np.floor(cap)
+    if n > cap.sum():
+        raise ValueError("n exceeds the total capacity of the strata")
+    minimum = np.full(len(sz), float(min_per_stratum))
+    if np.minimum(minimum, cap).sum() > n:
+        raise ValueError("min_per_stratum * number of strata exceeds n")
+    alloc = _largest_remainder(int(n), share.astype(float), minimum, cap)
+    if isinstance(sizes, Mapping):
+        return {k: int(a) for k, a in zip(keys, alloc)}
+    return [int(a) for a in alloc]
+
+
+def nearest_index(query: FloatArray, ref: FloatArray) -> np.ndarray:
+    """Index of the nearest ``ref`` point for each ``query`` point.
+
+    Uses ``scipy.spatial.cKDTree`` when SciPy is installed, otherwise a chunked
+    NumPy brute-force search.
+    """
+    q = np.asarray(query, dtype=float).reshape(-1, 2)
+    r = np.asarray(ref, dtype=float).reshape(-1, 2)
+    if len(r) == 0:
+        raise ValueError("reference set is empty")
+    try:
+        from scipy.spatial import cKDTree
+    except ImportError:  # pragma: no cover - depends on environment
+        cKDTree = None
+    if cKDTree is not None:
+        _, idx = cKDTree(r).query(q)
+        return np.asarray(idx, dtype=np.int64)
+    return _brute_nearest(q, r)
+
+
+def _brute_nearest(q: FloatArray, r: FloatArray) -> np.ndarray:
+    out = np.empty(len(q), dtype=np.int64)
+    step = max(1, int(4_000_000 // max(len(r), 1)))
+    for s in range(0, len(q), step):
+        blk = q[s : s + step]
+        d = (blk[:, None, 0] - r[None, :, 0]) ** 2 + (blk[:, None, 1] - r[None, :, 1]) ** 2
+        out[s : s + step] = np.argmin(d, axis=1)
+    return out
+
+
+def knn_indices(xy: FloatArray, k: int) -> np.ndarray:
+    """``(n, k)`` indices of each point's ``k`` nearest points, itself first."""
+    p = np.asarray(xy, dtype=float).reshape(-1, 2)
+    k = min(k, len(p))
+    d = ((p[:, None, :] - p[None, :, :]) ** 2).sum(-1)
+    np.fill_diagonal(d, -1.0)
+    return np.argsort(d, axis=1, kind="stable")[:, :k]
+
+
+def as_label_dict(values: Any, keys: Sequence[Hashable]) -> Dict[Hashable, float]:
+    if isinstance(values, Mapping):
+        return {k: float(values[k]) for k in keys}
+    return {k: float(v) for k, v in zip(keys, values)}

spatialsample/raster.py

@@ -0,0 +1,170 @@
+"""Raster masks and classified rasters as sampling domains.
+
+A :class:`RasterMask` wraps a 2D array (for example a land-cover map) together
+with a north-up geotransform. It behaves like a polygon :class:`~spatialsample.Region`
+(``area``, ``bounds``, ``contains``, ``random_points``) so every continuous design
+works on it, and it can also expose its cells as a finite population of pixels
+for pixel-based designs such as :func:`spatialsample.stratified_pixels`.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Iterable, Optional, Sequence, Tuple, Union
+
+import numpy as np
+
+from ._types import FloatArray, SeedLike, as_rng
+
+__all__ = ["RasterMask"]
+
+
+class RasterMask:
+    """A north-up raster whose valid cells form the sampling domain.
+
+    Parameters
+    ----------
+    data:
+        2D array of cell values (class codes or a 0/1 mask).
+    origin:
+        ``(x_min, y_max)`` of the upper-left corner of the raster.
+    cell_size:
+        Cell width, or ``(width, height)``; both positive.
+    nodata:
+        Value marking cells outside the domain. NaN cells are always excluded.
+    classes:
+        Optional subset of values that count as part of the domain. When the
+        array is boolean and ``classes`` is ``None``, only ``True`` cells count.
+    """
+
+    def __init__(
+        self,
+        data: Any,
+        origin: Tuple[float, float] = (0.0, 0.0),
+        cell_size: Union[float, Tuple[float, float]] = 1.0,
+        nodata: Optional[float] = None,
+        classes: Optional[Iterable[Any]] = None,
+    ) -> None:
+        arr = np.asarray(data)
+        if arr.ndim != 2:
+            raise ValueError("raster data must be 2D")
+        cs = np.atleast_1d(np.asarray(cell_size, dtype=float))
+        cw = float(cs[0])
+        ch = float(cs[-1])
+        if cw <= 0 or ch <= 0:
+            raise ValueError("cell_size must be positive")
+        self.data = arr
+        self.origin = (float(origin[0]), float(origin[1]))
+        self.cell_size = (cw, ch)
+        self.nodata = nodata
+        valid = np.ones(arr.shape, dtype=bool)
+        if arr.dtype == bool and classes is None:
+            valid &= arr
+        if np.issubdtype(arr.dtype, np.floating):
+            valid &= np.isfinite(arr)
+        if nodata is not None:
+            valid &= arr != nodata
+        self.classes: Optional[Tuple[Any, ...]] = None
+        if classes is not None:
+            self.classes = tuple(classes)
+            valid &= np.isin(arr, np.asarray(self.classes))
+        self.valid = valid
+        self._flat = np.flatnonzero(valid.ravel())
+        if len(self._flat) == 0:
+            raise ValueError("raster mask has no valid cells")
+        rows, cols = np.divmod(self._flat, arr.shape[1])
+        x0 = self.origin[0] + cols.min() * cw
+        x1 = self.origin[0] + (cols.max() + 1) * cw
+        y1 = self.origin[1] - rows.min() * ch
+        y0 = self.origin[1] - (rows.max() + 1) * ch
+        self.bounds: Tuple[float, float, float, float] = (
+            float(x0),
+            float(y0),
+            float(x1),
+            float(y1),
+        )
+
+    @classmethod
+    def from_affine(cls, data: Any, transform: Sequence[float], **kwargs: Any) -> RasterMask:
+        """Build from a rasterio/GDAL-style affine ``(a, b, c, d, e, f)``.
+
+        Only north-up transforms (``b == d == 0``, ``e < 0``) are supported.
+        """
+        a, b, c, d, e, f = (float(v) for v in list(transform)[:6])
+        if b != 0 or d != 0 or e >= 0:
+            raise ValueError("only north-up rasters (no rotation, negative e) are supported")
+        return cls(data, origin=(c, f), cell_size=(a, -e), **kwargs)
+
+    # ------------------------------------------------------------------ properties
+    @property
+    def cell_area(self) -> float:
+        return self.cell_size[0] * self.cell_size[1]
+
+    @property
+    def n_cells(self) -> int:
+        return int(len(self._flat))
+
+    @property
+    def area(self) -> float:
+        return self.n_cells * self.cell_area
+
+    def select(self, classes: Iterable[Any]) -> RasterMask:
+        """A new mask restricted to the given class values."""
+        return RasterMask(
+            self.data, self.origin, self.cell_size, nodata=self.nodata, classes=classes
+        )
+
+    def class_areas(self) -> Dict[Any, float]:
+        """Area of every distinct value among the valid cells."""
+        vals, counts = np.unique(self.data.ravel()[self._flat], return_counts=True)
+        return {_py(v): float(c) * self.cell_area for v, c in zip(vals, counts)}
+
+    def class_counts(self) -> Dict[Any, int]:
+        vals, counts = np.unique(self.data.ravel()[self._flat], return_counts=True)
+        return {_py(v): int(c) for v, c in zip(vals, counts)}
+
+    # ------------------------------------------------------------------ geometry
+    def rowcol(self, xy: Any) -> Tuple[np.ndarray, np.ndarray]:
+        pts = np.atleast_2d(np.asarray(xy, dtype=float))
+        col = np.floor((pts[:, 0] - self.origin[0]) / self.cell_size[0]).astype(np.int64)
+        row = np.floor((self.origin[1] - pts[:, 1]) / self.cell_size[1]).astype(np.int64)
+        return row, col
+
+    def contains(self, xy: Any) -> np.ndarray:
+        row, col = self.rowcol(xy)
+        h, w = self.data.shape
+        ok = (row >= 0) & (row < h) & (col >= 0) & (col < w)
+        out = np.zeros(len(row), dtype=bool)
+        out[ok] = self.valid[row[ok], col[ok]]
+        return out
+
+    def values_at(self, xy: Any) -> np.ndarray:
+        """Cell values at points (points must fall inside the raster extent)."""
+        row, col = self.rowcol(xy)
+        return self.data[row, col]
+
+    def cell_centers(self) -> Tuple[FloatArray, np.ndarray, np.ndarray]:
+        """``(xy, row, col)`` of every valid cell centre."""
+        h, w = self.data.shape
+        row, col = np.divmod(self._flat, w)
+        x = self.origin[0] + (col + 0.5) * self.cell_size[0]
+        y = self.origin[1] - (row + 0.5) * self.cell_size[1]
+        return np.column_stack([x, y]), row, col
+
+    def random_points(self, n: int, seed: SeedLike = None) -> FloatArray:
+        """``n`` independent points uniform over the valid cells."""
+        rng = as_rng(seed)
+        if n < 0:
+            raise ValueError("n must be non-negative")
+        pick = self._flat[rng.integers(0, len(self._flat), n)]
+        w = self.data.shape[1]
+        row, col = np.divmod(pick, w)
+        x = self.origin[0] + (col + rng.random(n)) * self.cell_size[0]
+        y = self.origin[1] - (row + rng.random(n)) * self.cell_size[1]
+        return np.column_stack([x, y])
+
+    def __repr__(self) -> str:
+        return f"RasterMask(shape={self.data.shape}, cells={self.n_cells}, area={self.area:.6g})"
+
+
+def _py(v: Any) -> Any:
+    return v.item() if hasattr(v, "item") else v