spatialsample 0.1.0__py3-none-any.whl

spatialsample/estimators.py

@@ -0,0 +1,222 @@
+"""Design-based estimators: Horvitz-Thompson totals and means, with variance
+estimators for independent (SRS-like) and spatially balanced designs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from statistics import NormalDist
+from typing import Any, Optional
+
+import numpy as np
+
+from .probabilities import knn_indices
+from .sample import Sample
+
+__all__ = [
+    "ht_total",
+    "ht_mean",
+    "srs_variance",
+    "local_variance",
+    "local_weights",
+    "estimate",
+    "Estimate",
+]
+
+
+def _check(y: Any, pi: Any) -> tuple:
+    yy = np.asarray(y, dtype=float).ravel()
+    pp = np.asarray(pi, dtype=float).ravel()
+    if yy.shape != pp.shape:
+        raise ValueError("y and pi must have the same length")
+    if np.any(pp <= 0):
+        raise ValueError("inclusion probabilities/densities must be positive")
+    return yy, pp
+
+
+def ht_total(y: Any, pi: Any) -> float:
+    """Horvitz-Thompson estimator of a population total, ``sum(y / pi)``.
+
+    For continuous designs (``pi`` an inclusion density) this estimates the
+    integral of ``y`` over the domain (Cordy 1993).
+    """
+    yy, pp = _check(y, pi)
+    return float(np.sum(yy / pp))
+
+
+def ht_mean(y: Any, pi: Any, size: Optional[float] = None) -> float:
+    """Mean per unit (or per unit area).
+
+    With ``size`` (population size ``N`` or domain area) this is the
+    Horvitz-Thompson mean ``ht_total / size``; without it, the Hajek ratio
+    ``sum(y/pi) / sum(1/pi)``.
+    """
+    yy, pp = _check(y, pi)
+    if size is not None:
+        return float(np.sum(yy / pp) / size)
+    return float(np.sum(yy / pp) / np.sum(1.0 / pp))
+
+
+def srs_variance(y: Any, pi: Any) -> float:
+    """Variance of the HT total under the with-replacement approximation.
+
+    ``n / (n - 1) * sum((y_i/pi_i - T/n)^2)``. This is (approximately)
+    unbiased for simple random sampling and conservative for spatially
+    balanced designs, whose real variance is usually much smaller.
+    """
+    yy, pp = _check(y, pi)
+    n = len(yy)
+    if n < 2:
+        raise ValueError("need at least two observations")
+    z = yy / pp
+    return float(n / (n - 1) * np.sum((z - z.mean()) ** 2))
+
+
+def local_weights(xy: Any, pi: Any, k: int = 4, iters: int = 500, tol: float = 1e-6) -> tuple:
+    """Neighbourhood weights for the local variance estimator.
+
+    Each site's neighbourhood holds the site and its ``k - 1`` nearest sample
+    neighbours. Initial weights are proportional to ``1/pi_j`` and are then
+    balanced by iterative proportional fitting so that every row and every
+    column of the weight matrix sums to one (Stevens & Olsen 2003); rows are
+    exact, columns converge to one within a small tolerance.
+
+    Returns ``(neighbours, weights)``, both of shape ``(n, k)``.
+    """
+    pts = np.asarray(xy, dtype=float).reshape(-1, 2)
+    pp = np.asarray(pi, dtype=float).ravel()
+    nb = knn_indices(pts, k)
+    w = 1.0 / pp[nb]
+    flat = nb.ravel()
+    for _ in range(iters):
+        w = w / w.sum(axis=1, keepdims=True)
+        col = np.bincount(flat, weights=w.ravel(), minlength=len(pts))
+        if np.max(np.abs(col - 1.0)) < tol:
+            break
+        w = w / col[nb]
+    w = w / w.sum(axis=1, keepdims=True)
+    return nb, w
+
+
+def local_variance(y: Any, xy: Any, pi: Any, k: int = 4, correction: bool = True) -> float:
+    """Local neighbourhood variance estimator for spatially balanced samples.
+
+    Implements the neighbourhood estimator of Stevens & Olsen (2003):
+
+    ``V = sum_i sum_{j in D(i)} w_ij (y_j/pi_j - zbar_i)^2``,
+    ``zbar_i = sum_{j in D(i)} w_ij y_j/pi_j``
+
+    where ``D(i)`` is the site and its ``k - 1`` nearest sample neighbours and
+    the weights are doubly stochastic (:func:`local_weights`). Because nearby
+    sites are compared, smooth spatial trends do not inflate the estimate,
+    unlike :func:`srs_variance`.
+
+    With ``correction=True`` (default) each neighbourhood term is divided by
+    ``1 - sum_j w_ij^2``, the usual small-sample correction for a weighted
+    variance, which makes the estimator unbiased when the population has no
+    spatial structure; with ``correction=False`` the uncorrected form is
+    returned (smaller by about ``(k - 1) / k``).
+    """
+    yy, pp = _check(y, pi)
+    if len(yy) < 3:
+        raise ValueError("need at least three observations")
+    nb, w = local_weights(xy, pp, k)
+    z = yy / pp
+    zn = z[nb]
+    zbar = np.sum(w * zn, axis=1, keepdims=True)
+    terms = np.sum(w * (zn - zbar) ** 2, axis=1)
+    if correction:
+        terms = terms / np.maximum(1.0 - np.sum(w**2, axis=1), 1e-12)
+    return float(np.sum(terms))
+
+
+@dataclass
+class Estimate:
+    """Result of :func:`estimate`."""
+
+    total: float
+    total_se: float
+    mean: float
+    mean_se: float
+    ci_low: float
+    ci_high: float
+    n: int
+    variance: str
+    conf: float
+
+    def as_dict(self) -> dict:
+        return dict(self.__dict__)
+
+
+def estimate(
+    sample: Sample,
+    y: Any,
+    variance: str = "auto",
+    conf: float = 0.95,
+    size: Optional[float] = None,
+    k: int = 4,
+    mean_type: str = "ratio",
+) -> Estimate:
+    """Horvitz-Thompson total and mean of ``y`` with a standard error and CI.
+
+    Parameters
+    ----------
+    sample:
+        A :class:`~spatialsample.Sample`; only base sites should be passed
+        (use ``sample.base()``) unless the weights were adjusted.
+    y:
+        Observed values at the sample sites.
+    variance:
+        ``"srs"``, ``"local"`` or ``"auto"`` (local for GRTS, BAS, LPM and
+        systematic designs, SRS otherwise).
+    size:
+        Population size or domain area used by ``mean_type="ht"``; defaults
+        to ``meta["population_size"]`` or ``meta["area"]``.
+    mean_type:
+        ``"ratio"`` (default): the Hajek mean ``sum(y/pi) / sum(1/pi)`` with a
+        linearised standard error, which removes the extra variance of
+        random-size designs (systematic grids, clusters). ``"ht"``: the
+        Horvitz-Thompson total divided by ``size``.
+
+    The confidence interval (``ci_low``, ``ci_high``) is for the total.
+    """
+    yy = np.asarray(y, dtype=float).ravel()
+    if len(yy) != len(sample):
+        raise ValueError("y must have one value per sample site")
+    if variance == "auto":
+        balanced = sample.design.startswith(("grts", "bas", "lpm", "systematic"))
+        variance = "local" if balanced and len(yy) >= 3 else "srs"
+    if variance == "local":
+        var = local_variance(yy, sample.xy, sample.pi, k=k)
+    elif variance == "srs":
+        var = srs_variance(yy, sample.pi)
+    else:
+        raise ValueError("variance must be 'srs', 'local' or 'auto'")
+    total = ht_total(yy, sample.pi)
+    se = float(np.sqrt(max(var, 0.0)))
+    if size is None:
+        size = sample.meta.get("population_size", sample.meta.get("area"))
+    zq = NormalDist().inv_cdf(0.5 + conf / 2)
+    if mean_type not in ("ratio", "ht"):
+        raise ValueError("mean_type must be 'ratio' or 'ht'")
+    if mean_type == "ht" and size:
+        mean, mean_se = total / size, se / size
+    else:
+        # Hajek ratio mean with a linearised (residual) variance.
+        mean = ht_mean(yy, sample.pi)
+        resid = yy - mean
+        if variance == "local":
+            rvar = local_variance(resid, sample.xy, sample.pi, k=k)
+        else:
+            rvar = srs_variance(resid, sample.pi)
+        mean_se = float(np.sqrt(max(rvar, 0.0)) / np.sum(1.0 / sample.pi))
+    return Estimate(
+        total=total,
+        total_se=se,
+        mean=mean,
+        mean_se=mean_se,
+        ci_low=total - zq * se,
+        ci_high=total + zq * se,
+        n=len(yy),
+        variance=variance,
+        conf=conf,
+    )

spatialsample/geometry.py

@@ -0,0 +1,253 @@
+"""Planar polygon regions with holes and multiple parts, implemented in pure NumPy.
+
+A :class:`Region` is the sampling domain for every continuous design. It is
+built from GeoJSON (``Polygon``, ``MultiPolygon``, ``Feature``,
+``FeatureCollection`` or ``GeometryCollection``), from any object that exposes
+``__geo_interface__`` (Shapely geometries, GeoPandas objects) or directly from
+coordinate arrays.
+
+Coordinates are treated as planar. Distance-based designs (systematic grids,
+Poisson-disk, GRTS, LPM, the local variance estimator and the spatial balance
+metric) assume a projected coordinate reference system in metres or another
+linear unit; reproject longitude/latitude data before sampling.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, Iterator, List, Mapping, Optional, Sequence, Tuple
+
+import numpy as np
+
+from ._types import FloatArray, SeedLike, as_rng
+
+__all__ = ["Polygon", "Region", "ring_area", "points_in_ring"]
+
+
+def _as_ring(coords: Any) -> FloatArray:
+    ring = np.asarray(coords, dtype=float)
+    if ring.ndim != 2 or ring.shape[1] < 2:
+        raise ValueError("a ring must be an (m, 2) sequence of coordinates")
+    ring = ring[:, :2]
+    if len(ring) > 1 and np.allclose(ring[0], ring[-1]):
+        ring = ring[:-1]
+    if len(ring) < 3:
+        raise ValueError("a ring needs at least three distinct vertices")
+    if not np.all(np.isfinite(ring)):
+        raise ValueError("ring coordinates must be finite")
+    return ring
+
+
+def ring_area(ring: FloatArray) -> float:
+    """Signed shoelace area of an open ring (positive when counter-clockwise)."""
+    x = ring[:, 0]
+    y = ring[:, 1]
+    return 0.5 * float(np.sum(x * np.roll(y, -1) - np.roll(x, -1) * y))
+
+
+def points_in_ring(xy: FloatArray, ring: FloatArray) -> np.ndarray:
+    """Even-odd (crossing number) test of many points against one ring."""
+    px = xy[:, 0]
+    py = xy[:, 1]
+    inside = np.zeros(len(xy), dtype=bool)
+    x0 = ring[:, 0]
+    y0 = ring[:, 1]
+    x1 = np.roll(x0, -1)
+    y1 = np.roll(y0, -1)
+    for k in range(len(ring)):
+        ya, yb = y0[k], y1[k]
+        if ya == yb:
+            continue
+        cond = (ya > py) != (yb > py)
+        if not cond.any():
+            continue
+        xa, xb = x0[k], x1[k]
+        xint = xa + (py - ya) * (xb - xa) / (yb - ya)
+        inside ^= cond & (px < xint)
+    return inside
+
+
+class Polygon:
+    """A single polygon: one exterior ring and any number of holes."""
+
+    def __init__(self, exterior: Any, holes: Optional[Iterable[Any]] = None) -> None:
+        self.exterior: FloatArray = _as_ring(exterior)
+        self.holes: List[FloatArray] = [_as_ring(h) for h in (holes or [])]
+        rings = [self.exterior, *self.holes]
+        allpts = np.vstack(rings)
+        self.bounds: Tuple[float, float, float, float] = (
+            float(allpts[:, 0].min()),
+            float(allpts[:, 1].min()),
+            float(allpts[:, 0].max()),
+            float(allpts[:, 1].max()),
+        )
+
+    @property
+    def area(self) -> float:
+        a = abs(ring_area(self.exterior))
+        for h in self.holes:
+            a -= abs(ring_area(h))
+        return a
+
+    def contains(self, xy: Any) -> np.ndarray:
+        pts = np.atleast_2d(np.asarray(xy, dtype=float))
+        x0, y0, x1, y1 = self.bounds
+        out = np.zeros(len(pts), dtype=bool)
+        box = (pts[:, 0] >= x0) & (pts[:, 0] <= x1) & (pts[:, 1] >= y0) & (pts[:, 1] <= y1)
+        if not box.any():
+            return out
+        sub = pts[box]
+        inside = points_in_ring(sub, self.exterior)
+        for h in self.holes:
+            inside &= ~points_in_ring(sub, h)
+        out[box] = inside
+        return out
+
+    def to_coordinates(self) -> List[List[List[float]]]:
+        rings = []
+        for k, r in enumerate([self.exterior, *self.holes]):
+            ccw = ring_area(r) > 0
+            # RFC 7946: exterior counter-clockwise, holes clockwise.
+            if (k == 0) != ccw:
+                r = r[::-1]
+            closed = np.vstack([r, r[:1]])
+            rings.append(closed.tolist())
+        return rings
+
+
+class Region:
+    """A planar sampling domain made of one or more non-overlapping polygons.
+
+    Parts are combined by union for point-in-region tests; the area is the sum
+    of part areas, so parts should not overlap.
+    """
+
+    def __init__(self, polygons: Sequence[Polygon]) -> None:
+        if len(polygons) == 0:
+            raise ValueError("a Region needs at least one polygon")
+        self.polygons: List[Polygon] = list(polygons)
+        b = np.array([p.bounds for p in self.polygons])
+        self.bounds: Tuple[float, float, float, float] = (
+            float(b[:, 0].min()),
+            float(b[:, 1].min()),
+            float(b[:, 2].max()),
+            float(b[:, 3].max()),
+        )
+        self._area = float(sum(p.area for p in self.polygons))
+        if self._area <= 0:
+            raise ValueError("region has zero or negative area")
+
+    # ------------------------------------------------------------------ constructors
+    @classmethod
+    def box(cls, xmin: float, ymin: float, xmax: float, ymax: float) -> Region:
+        """Axis-aligned rectangle."""
+        if xmax <= xmin or ymax <= ymin:
+            raise ValueError("box needs xmax > xmin and ymax > ymin")
+        ring = [(xmin, ymin), (xmax, ymin), (xmax, ymax), (xmin, ymax)]
+        return cls([Polygon(ring)])
+
+    @classmethod
+    def from_coords(cls, exterior: Any, holes: Optional[Iterable[Any]] = None) -> Region:
+        """Single polygon from an exterior ring and optional hole rings."""
+        return cls([Polygon(exterior, holes)])
+
+    @classmethod
+    def from_geojson(cls, obj: Mapping[str, Any]) -> Region:
+        """Build from a GeoJSON geometry, Feature, FeatureCollection or GeometryCollection.
+
+        Non-areal geometries (points, lines) inside collections are ignored.
+        """
+        polys = list(_iter_polygons(obj))
+        if not polys:
+            raise ValueError("no Polygon or MultiPolygon geometry found")
+        return cls(polys)
+
+    @classmethod
+    def from_shapely(cls, geom: Any) -> Region:
+        """Build from any object exposing ``__geo_interface__`` (Shapely, GeoPandas)."""
+        gi = getattr(geom, "__geo_interface__", None)
+        if gi is None:
+            raise TypeError("object does not expose __geo_interface__")
+        return cls.from_geojson(gi)
+
+    # ------------------------------------------------------------------ properties
+    @property
+    def area(self) -> float:
+        return self._area
+
+    def contains(self, xy: Any) -> np.ndarray:
+        """Boolean mask of points that fall inside the region (holes excluded)."""
+        pts = np.atleast_2d(np.asarray(xy, dtype=float))
+        out = np.zeros(len(pts), dtype=bool)
+        for p in self.polygons:
+            todo = ~out
+            if todo.any():
+                out[todo] = p.contains(pts[todo])
+        return out
+
+    # ------------------------------------------------------------------ point generators
+    def random_points(self, n: int, seed: SeedLike = None) -> FloatArray:
+        """``n`` independent uniform points inside the region (rejection sampling)."""
+        return _rejection_points(self, n, as_rng(seed))
+
+    def to_geojson(self) -> dict:
+        """GeoJSON geometry (``Polygon`` or ``MultiPolygon``)."""
+        if len(self.polygons) == 1:
+            return {"type": "Polygon", "coordinates": self.polygons[0].to_coordinates()}
+        return {
+            "type": "MultiPolygon",
+            "coordinates": [p.to_coordinates() for p in self.polygons],
+        }
+
+    @property
+    def __geo_interface__(self) -> dict:
+        return self.to_geojson()
+
+    def __repr__(self) -> str:
+        nh = sum(len(p.holes) for p in self.polygons)
+        return f"Region(parts={len(self.polygons)}, holes={nh}, area={self.area:.6g})"
+
+
+def _iter_polygons(obj: Mapping[str, Any]) -> Iterator[Polygon]:
+    if hasattr(obj, "__geo_interface__") and not isinstance(obj, Mapping):
+        obj = obj.__geo_interface__
+    t = obj.get("type")
+    if t == "FeatureCollection":
+        for f in obj.get("features", []):
+            yield from _iter_polygons(f)
+    elif t == "Feature":
+        g = obj.get("geometry")
+        if g:
+            yield from _iter_polygons(g)
+    elif t == "GeometryCollection":
+        for g in obj.get("geometries", []):
+            yield from _iter_polygons(g)
+    elif t == "Polygon":
+        rings = obj["coordinates"]
+        if rings:
+            yield Polygon(rings[0], rings[1:])
+    elif t == "MultiPolygon":
+        for rings in obj["coordinates"]:
+            if rings:
+                yield Polygon(rings[0], rings[1:])
+
+
+def _rejection_points(domain: Any, n: int, rng: np.random.Generator) -> FloatArray:
+    if n < 0:
+        raise ValueError("n must be non-negative")
+    if n == 0:
+        return np.empty((0, 2))
+    x0, y0, x1, y1 = domain.bounds
+    frac = max(domain.area / max((x1 - x0) * (y1 - y0), 1e-300), 1e-6)
+    out: List[FloatArray] = []
+    have = 0
+    for _ in range(10000):
+        m = int(min(max(64, 1.3 * (n - have) / frac), 5_000_000))
+        cand = np.column_stack([rng.uniform(x0, x1, m), rng.uniform(y0, y1, m)])
+        cand = cand[domain.contains(cand)]
+        out.append(cand)
+        have += len(cand)
+        if have >= n:
+            break
+    else:  # pragma: no cover - only for pathological slivers
+        raise RuntimeError("rejection sampling failed; is the domain degenerate?")
+    return np.vstack(out)[:n]

spatialsample/grts.py

@@ -0,0 +1,175 @@
+"""Generalized Random Tessellation Stratified (GRTS) sampling.
+
+Implements the design of Stevens & Olsen (2004):
+
+1. The frame is covered by a randomly shifted square that is split
+   recursively into quadrants. At every level the four quadrant labels of each
+   parent cell are randomly permuted (*hierarchical address randomisation*),
+   and splitting stops once no cell holds more than one unit of inclusion
+   probability.
+2. Units are ordered by their randomised base-4 address, which maps the plane
+   onto a line while preserving proximity.
+3. A systematic sample with a random start is taken along that line, with
+   step one in cumulative inclusion probability, so each unit is selected with
+   exactly its prescribed probability.
+4. The selected sites are put in *reverse hierarchical order* (base-4 digit
+   reversal of their rank), so that any leading subset of the list is itself
+   spatially balanced. This is what makes oversample (replacement) sites
+   usable: visit base sites, then take replacements in order.
+
+Continuous areas are handled, as in recent versions of the R package
+spsurvey, through a dense finite approximation: a randomly offset grid of
+cell centres is sampled with GRTS and each selected centre is then moved to a
+uniform random location inside its cell.
+"""
+
+from __future__ import annotations
+
+import math
+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, systematic_pps
+from .sample import Sample
+
+__all__ = ["grts", "grts_order", "reverse_hierarchical_order"]
+
+
+def grts_order(
+    xy: FloatArray, pi: FloatArray, rng: np.random.Generator, max_level: int = 30
+) -> np.ndarray:
+    """Randomised hierarchical (quadrant-recursive) ordering of frame units.
+
+    Returns the permutation that sorts units by their randomised base-4
+    address; units that share a finest-level cell are ordered randomly.
+    """
+    p = np.asarray(xy, dtype=float)
+    n_units = len(p)
+    if n_units == 0:
+        return np.empty(0, dtype=np.int64)
+    lo = p.min(axis=0)
+    span = float(np.max(p.max(axis=0) - lo))
+    span = span if span > 0 else 1.0
+    side = 2.0 * span * (1.0 + 1e-9)
+    # Random placement of the bounding square: every unit falls inside.
+    origin = lo - rng.uniform(0.0, span, 2)
+    u = (p - origin) / side
+    address = np.zeros(n_units, dtype=np.int64)
+    weights = np.asarray(pi, dtype=float)
+    for level in range(1, min(max_level, 30) + 1):
+        k = 1 << level
+        ix = np.minimum((u[:, 0] * k).astype(np.int64), k - 1)
+        iy = np.minimum((u[:, 1] * k).astype(np.int64), k - 1)
+        quad = (ix & 1) + 2 * (iy & 1)
+        parents, inv = np.unique(address, return_inverse=True)
+        inv = inv.ravel()
+        perms = np.argsort(rng.random((len(parents), 4)), axis=1)
+        address = address * 4 + perms[inv, quad]
+        _, cell = np.unique(address, return_inverse=True)
+        cell_mass = np.bincount(cell.ravel(), weights=weights)
+        if float(np.max(cell_mass)) <= 1.0 + 1e-12:
+            break
+    tie = rng.random(n_units)
+    return np.lexsort((tie, address))
+
+
+def reverse_hierarchical_order(m: int) -> np.ndarray:
+    """Permutation of ``range(m)`` by base-4 digit reversal of the rank."""
+    if m <= 1:
+        return np.arange(m)
+    digits = max(1, int(math.ceil(math.log(m, 4) - 1e-12)))
+    k = np.arange(m)
+    key = np.zeros(m, dtype=np.int64)
+    rest = k.copy()
+    for _ in range(digits):
+        key = key * 4 + (rest % 4)
+        rest //= 4
+    return np.argsort(key, kind="stable")
+
+
+def _grts_select(sizes: FloatArray, n: int, n_over: int, xy: FloatArray, rng: np.random.Generator):
+    m = n + n_over
+    pi_base = inclusion_probabilities(sizes, n)
+    pi_all = inclusion_probabilities(sizes, m) if n_over else pi_base
+    order = grts_order(xy, pi_all, rng)
+    pos = systematic_pps(pi_all[order], rng)
+    chosen = order[pos]  # in hierarchical order
+    chosen = chosen[reverse_hierarchical_order(len(chosen))]
+    site_type = np.array(["base"] * n + ["over"] * n_over, dtype=object)
+    return chosen, pi_base, site_type
+
+
+def grts(
+    frame: Any,
+    n: int,
+    n_over: int = 0,
+    prob: ProbLike = None,
+    frame_size: Optional[int] = None,
+    seed: SeedLike = None,
+) -> Sample:
+    """Draw a GRTS sample.
+
+    Parameters
+    ----------
+    frame:
+        A :class:`~spatialsample.Region`, :class:`~spatialsample.RasterMask`,
+        GeoJSON polygon mapping (continuous design) or an ``(N, 2)`` array of
+        candidate sites (finite design).
+    n:
+        Base sample size.
+    n_over:
+        Number of oversample / replacement sites, returned after the base
+        sites in reverse hierarchical order.
+    prob:
+        Size measure for unequal-probability sampling: an array with one value
+        per frame point, or (continuous designs) a callable evaluated at grid
+        cell centres. Inclusion probabilities are proportional to it.
+    frame_size:
+        Number of grid cells used to approximate a continuous domain
+        (default ``max(4000, 100 * (n + n_over))``).
+    seed:
+        Seed or ``numpy.random.Generator`` for reproducibility.
+    """
+    rng = as_rng(seed)
+    if n < 1 or n_over < 0:
+        raise ValueError("n must be >= 1 and n_over >= 0")
+    domain, pts = resolve(frame)
+    m = n + n_over
+    if pts is not None:
+        sizes = frame_sizes(prob, pts)
+        chosen, pi_base, site_type = _grts_select(sizes, n, n_over, pts, rng)
+        pi = pi_base[chosen]
+        return Sample(
+            xy=pts[chosen],
+            pi=pi,
+            weight=1.0 / pi,
+            design="grts",
+            kind="finite",
+            site_type=site_type,
+            order=np.arange(m),
+            index=chosen,
+            meta={"n": n, "n_over": n_over, "population_size": len(pts)},
+        )
+    assert domain is not None
+    size = frame_size or max(4000, 100 * m)
+    cells, h = grid_frame(domain, size, rng, min_points=2 * m)
+    sizes = frame_sizes(prob, cells)
+    chosen, pi_base, site_type = _grts_select(sizes, n, n_over, cells, rng)
+    xy = jitter_in_cells(cells[chosen], h, domain, rng)
+    if prob is None:
+        density = np.full(m, n / domain.area)
+    else:
+        density = pi_base[chosen] / (h * h)
+    return Sample(
+        xy=xy,
+        pi=density,
+        weight=1.0 / density,
+        design="grts",
+        kind="continuous",
+        site_type=site_type,
+        order=np.arange(m),
+        meta={"n": n, "n_over": n_over, "area": domain.area, "frame_size": len(cells)},
+    )