spatialsample 0.1.0__py3-none-any.whl

spatialsample/__init__.py

@@ -0,0 +1,89 @@
+"""spatialsample: design-based spatial sampling in pure NumPy.
+
+Spatially balanced designs (GRTS, BAS, LPM), classical designs (simple
+random, systematic, stratified, cluster, two-stage, transects, Poisson-disk),
+inclusion probabilities and design weights, Horvitz-Thompson estimation with
+local-neighbourhood variance, the Voronoi spatial-balance metric and map
+accuracy assessment following Olofsson et al. (2014).
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .accuracy import AccuracyAssessment, allocate_accuracy_sample, olofsson, sample_size
+from .balance import BalanceResult, compare_designs, spatial_balance, voronoi_balance
+from .bas import bas, halton
+from .designs import (
+    cluster,
+    points_along_lines,
+    poisson_disk,
+    random_transects,
+    srs,
+    stratified,
+    stratified_pixels,
+    systematic,
+    two_stage,
+)
+from .estimators import (
+    Estimate,
+    estimate,
+    ht_mean,
+    ht_total,
+    local_variance,
+    local_weights,
+    srs_variance,
+)
+from .geometry import Polygon, Region
+from .grts import grts, grts_order, reverse_hierarchical_order
+from .io import read_lines, read_matrix_csv, read_points, read_region, read_strata
+from .lpm import lpm, lpm2_select
+from .probabilities import allocate, inclusion_probabilities
+from .raster import RasterMask
+from .sample import Sample
+
+__all__ = [
+    "__version__",
+    "AccuracyAssessment",
+    "BalanceResult",
+    "Estimate",
+    "Polygon",
+    "RasterMask",
+    "Region",
+    "Sample",
+    "allocate",
+    "allocate_accuracy_sample",
+    "bas",
+    "cluster",
+    "compare_designs",
+    "estimate",
+    "grts",
+    "grts_order",
+    "halton",
+    "ht_mean",
+    "ht_total",
+    "inclusion_probabilities",
+    "local_variance",
+    "local_weights",
+    "lpm",
+    "lpm2_select",
+    "olofsson",
+    "points_along_lines",
+    "poisson_disk",
+    "random_transects",
+    "read_lines",
+    "read_matrix_csv",
+    "read_points",
+    "read_region",
+    "read_strata",
+    "reverse_hierarchical_order",
+    "sample_size",
+    "spatial_balance",
+    "srs",
+    "srs_variance",
+    "stratified",
+    "stratified_pixels",
+    "systematic",
+    "two_stage",
+    "voronoi_balance",
+]

spatialsample/_frame.py

@@ -0,0 +1,91 @@
+"""Internal helpers: resolve inputs into a domain or a finite frame, build grid frames."""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Callable, Mapping, Optional, Tuple, Union
+
+import numpy as np
+
+from ._types import Domain, FloatArray
+from .geometry import Region
+from .raster import RasterMask
+
+FrameInput = Union[Domain, FloatArray, Mapping[str, Any]]
+ProbLike = Optional[Union[FloatArray, Callable[[FloatArray], Any]]]
+
+
+def as_domain(obj: Any) -> Domain:
+    """Coerce a Region, RasterMask, GeoJSON mapping or ``__geo_interface__`` object."""
+    if isinstance(obj, (Region, RasterMask)):
+        return obj
+    if isinstance(obj, Mapping) or hasattr(obj, "__geo_interface__"):
+        return Region.from_geojson(obj)
+    if all(hasattr(obj, a) for a in ("area", "bounds", "contains", "random_points")):
+        return obj  # duck-typed custom domain
+    raise TypeError(
+        "expected a Region, RasterMask, GeoJSON mapping or object with __geo_interface__"
+    )
+
+
+def resolve(obj: Any) -> Tuple[Optional[Domain], Optional[FloatArray]]:
+    """Return ``(domain, None)`` for areal input or ``(None, points)`` for a finite frame."""
+    if isinstance(obj, (Region, RasterMask, Mapping)) or hasattr(obj, "__geo_interface__"):
+        return as_domain(obj), None
+    if all(hasattr(obj, a) for a in ("area", "bounds", "contains", "random_points")):
+        return obj, None
+    pts = np.asarray(obj, dtype=float)
+    if pts.ndim != 2 or pts.shape[1] < 2:
+        raise ValueError("a finite frame must be an (N, 2) array of coordinates")
+    return None, pts[:, :2]
+
+
+def grid_frame(
+    domain: Domain, size: int, rng: np.random.Generator, min_points: int = 1
+) -> Tuple[FloatArray, float]:
+    """Square-grid frame of roughly ``size`` cell centres inside ``domain``.
+
+    The grid has a uniformly random offset, so every location in the domain is
+    equally likely to lie in any cell. Returns ``(points, spacing)``.
+    """
+    h = math.sqrt(domain.area / max(size, 1))
+    x0, y0, x1, y1 = domain.bounds
+    for _ in range(12):
+        off = rng.uniform(0.0, h, 2)
+        xs = x0 - off[0] + h * (np.arange(int(math.ceil((x1 - x0) / h)) + 2) + 0.5) - h
+        ys = y0 - off[1] + h * (np.arange(int(math.ceil((y1 - y0) / h)) + 2) + 0.5) - h
+        gx, gy = np.meshgrid(xs, ys)
+        pts = np.column_stack([gx.ravel(), gy.ravel()])
+        pts = pts[domain.contains(pts)]
+        if len(pts) >= max(min_points, size // 2):
+            return pts, h
+        h /= math.sqrt(2.0)
+    raise ValueError("could not build a grid frame; the domain may be too thin")
+
+
+def jitter_in_cells(
+    centres: FloatArray, h: float, domain: Domain, rng: np.random.Generator, tries: int = 50
+) -> FloatArray:
+    """Move each grid centre to a uniform location in its cell that lies in the domain."""
+    out = centres.copy()
+    todo = np.arange(len(centres))
+    for _ in range(tries):
+        if len(todo) == 0:
+            break
+        cand = centres[todo] + rng.uniform(-h / 2, h / 2, (len(todo), 2))
+        ok = domain.contains(cand)
+        out[todo[ok]] = cand[ok]
+        todo = todo[~ok]
+    return out
+
+
+def frame_sizes(prob: ProbLike, xy: FloatArray) -> FloatArray:
+    if prob is None:
+        return np.ones(len(xy))
+    if callable(prob):
+        sizes = np.asarray(prob(xy), dtype=float).ravel()
+    else:
+        sizes = np.asarray(prob, dtype=float).ravel()
+    if len(sizes) != len(xy):
+        raise ValueError("prob must give one value per frame unit")
+    return sizes

spatialsample/_types.py

@@ -0,0 +1,36 @@
+"""Shared type aliases and small helpers."""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Tuple, Union
+
+import numpy as np
+
+try:  # Protocol is in typing from 3.8
+    from typing import Protocol
+except ImportError:  # pragma: no cover
+    from typing_extensions import Protocol  # type: ignore[assignment]
+
+FloatArray = np.ndarray
+SeedLike = Optional[Union[int, np.random.Generator, np.random.SeedSequence]]
+
+
+def as_rng(seed: SeedLike) -> np.random.Generator:
+    """Return a NumPy ``Generator`` from an int, a generator or ``None``."""
+    if isinstance(seed, np.random.Generator):
+        return seed
+    return np.random.default_rng(seed)
+
+
+class Domain(Protocol):
+    """Anything that can be sampled continuously: a polygon region or a raster mask."""
+
+    @property
+    def area(self) -> float: ...
+
+    @property
+    def bounds(self) -> Tuple[float, float, float, float]: ...
+
+    def contains(self, xy: Any) -> np.ndarray: ...
+
+    def random_points(self, n: int, seed: SeedLike = None) -> FloatArray: ...

spatialsample/accuracy.py

@@ -0,0 +1,232 @@
+"""Map accuracy assessment and area estimation, Olofsson et al. (2014).
+
+Good-practice estimators for a stratified random sample in which the strata
+are the map classes. Given the error matrix of *sample counts* (rows = map
+class, columns = reference class) and the mapped area of each class, the
+functions return unbiased (stratified) estimates of overall, user's and
+producer's accuracy and of the area of each reference class, all with
+standard errors and confidence intervals. :func:`sample_size` implements
+equation 13 of the paper (Cochran 1977, eq. 5.25) for a target standard error
+of overall accuracy.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from statistics import NormalDist
+from typing import Any, Dict, List, Optional, Sequence
+
+import numpy as np
+
+from .probabilities import allocate
+
+__all__ = ["olofsson", "AccuracyAssessment", "sample_size", "allocate_accuracy_sample"]
+
+
+@dataclass
+class AccuracyAssessment:
+    """Stratified estimates from an error matrix (Olofsson et al. 2014)."""
+
+    labels: List[str]
+    counts: np.ndarray
+    mapped_area: np.ndarray
+    proportions: np.ndarray
+    overall: float
+    overall_se: float
+    users: np.ndarray
+    users_se: np.ndarray
+    producers: np.ndarray
+    producers_se: np.ndarray
+    area_proportion: np.ndarray
+    area_proportion_se: np.ndarray
+    area: np.ndarray
+    area_se: np.ndarray
+    conf: float = 0.95
+    z: float = field(default=1.959963984540054)
+
+    @property
+    def area_ci(self) -> np.ndarray:
+        """Half-width of the confidence interval for each class area."""
+        return self.z * self.area_se
+
+    def ci(self, se: Any) -> Any:
+        return self.z * np.asarray(se)
+
+    def table(self) -> List[Dict[str, Any]]:
+        """One row per class with all estimates and CI half-widths."""
+        rows = []
+        for i, lab in enumerate(self.labels):
+            rows.append(
+                {
+                    "class": lab,
+                    "mapped_area": float(self.mapped_area[i]),
+                    "area": float(self.area[i]),
+                    "area_se": float(self.area_se[i]),
+                    "area_ci": float(self.z * self.area_se[i]),
+                    "users": float(self.users[i]),
+                    "users_ci": float(self.z * self.users_se[i]),
+                    "producers": float(self.producers[i]),
+                    "producers_ci": float(self.z * self.producers_se[i]),
+                }
+            )
+        return rows
+
+    def summary(self, digits: int = 3) -> str:
+        """Plain-text report."""
+        pct = int(round(self.conf * 100))
+        head = (
+            f"{'class':<20}{'mapped area':>14}{'est. area':>14}{'+/- ' + str(pct) + '% CI':>14}"
+            f"{'user':>9}{'+/-':>8}{'producer':>10}{'+/-':>8}"
+        )
+        lines = [head, "-" * len(head)]
+        for r in self.table():
+            lines.append(
+                f"{str(r['class']):<20}{r['mapped_area']:>14,.{0}f}{r['area']:>14,.{0}f}"
+                f"{r['area_ci']:>14,.{0}f}{r['users']:>9.{digits}f}{r['users_ci']:>8.{digits}f}"
+                f"{r['producers']:>10.{digits}f}{r['producers_ci']:>8.{digits}f}"
+            )
+        lines.append(
+            f"overall accuracy {self.overall:.{digits}f} +/- {self.z * self.overall_se:.{digits}f}"
+            f" ({pct}% CI), n = {int(self.counts.sum())}"
+        )
+        return "\n".join(lines)
+
+    def as_dict(self) -> Dict[str, Any]:
+        return {
+            "labels": list(self.labels),
+            "conf": self.conf,
+            "overall": self.overall,
+            "overall_se": self.overall_se,
+            "classes": self.table(),
+            "proportions": self.proportions.tolist(),
+        }
+
+
+def olofsson(
+    matrix: Any,
+    mapped_area: Sequence[float],
+    labels: Optional[Sequence[str]] = None,
+    conf: float = 0.95,
+) -> AccuracyAssessment:
+    """Accuracy and area estimates from an error matrix of sample counts.
+
+    Parameters
+    ----------
+    matrix:
+        ``(q, q)`` sample counts ``n_ij``: rows are map classes (strata),
+        columns are reference classes, in the same class order.
+    mapped_area:
+        Mapped area (or pixel count) of each map class; estimated areas are
+        returned in the same unit.
+    labels:
+        Class names (default ``"1"`` ... ``"q"``).
+    conf:
+        Confidence level for intervals (default 0.95, ``z = 1.96``).
+    """
+    n = np.asarray(matrix, dtype=float)
+    if n.ndim != 2 or n.shape[0] != n.shape[1]:
+        raise ValueError("the error matrix must be square")
+    q = n.shape[0]
+    am = np.asarray(mapped_area, dtype=float).ravel()
+    if len(am) != q:
+        raise ValueError("need one mapped area per map class")
+    if np.any(n < 0) or np.any(am < 0):
+        raise ValueError("counts and areas must be non-negative")
+    ni = n.sum(axis=1)
+    if np.any(ni < 2):
+        raise ValueError("every map class needs at least two sample units")
+    a_tot = am.sum()
+    w = am / a_tot
+    frac = n / ni[:, None]  # n_ij / n_i.
+    p = w[:, None] * frac  # estimated cell proportions
+    diag = np.diag(p)
+    overall = float(diag.sum())
+    users = np.diag(frac)
+    users_var = users * (1 - users) / (ni - 1)
+    overall_var = float(np.sum(w**2 * users_var))
+    p_col = p.sum(axis=0)
+    with np.errstate(divide="ignore", invalid="ignore"):
+        producers = np.where(p_col > 0, diag / p_col, np.nan)
+    # Producer's accuracy variance (Olofsson et al. 2014, eq. 7; Card 1982)
+    n_col_hat = (am[:, None] / ni[:, None] * n).sum(axis=0)  # estimated reference totals
+    cell_var = frac * (1 - frac) / (ni[:, None] - 1)
+    prod_var = np.full(q, np.nan)
+    for j in range(q):
+        if n_col_hat[j] <= 0:
+            continue
+        other = sum(am[i] ** 2 * cell_var[i, j] for i in range(q) if i != j)
+        term = am[j] ** 2 * (1 - producers[j]) ** 2 * users_var[j] + producers[j] ** 2 * other
+        prod_var[j] = term / n_col_hat[j] ** 2
+    area_prop = p_col
+    area_prop_var = np.sum(w[:, None] ** 2 * cell_var, axis=0)  # eq. 10
+    z = NormalDist().inv_cdf(0.5 + conf / 2)
+    return AccuracyAssessment(
+        labels=[str(s) for s in (labels or [str(i + 1) for i in range(q)])],
+        counts=n,
+        mapped_area=am,
+        proportions=p,
+        overall=overall,
+        overall_se=math.sqrt(overall_var),
+        users=users,
+        users_se=np.sqrt(users_var),
+        producers=producers,
+        producers_se=np.sqrt(prod_var),
+        area_proportion=area_prop,
+        area_proportion_se=np.sqrt(area_prop_var),
+        area=area_prop * a_tot,
+        area_se=np.sqrt(area_prop_var) * a_tot,
+        conf=conf,
+        z=z,
+    )
+
+
+def sample_size(
+    mapped_area: Sequence[float], expected_users: Sequence[float], target_se: float = 0.01
+) -> int:
+    """Total sample size for a target standard error of overall accuracy.
+
+    ``n = (sum_i W_i S_i / S(O))^2`` with ``S_i = sqrt(U_i (1 - U_i))``, where
+    ``W_i`` are mapped area proportions and ``U_i`` conjectured user's
+    accuracies (Olofsson et al. 2014, eq. 13). Rounded up.
+    """
+    am = np.asarray(mapped_area, dtype=float)
+    u = np.asarray(expected_users, dtype=float)
+    if am.shape != u.shape:
+        raise ValueError("need one expected user's accuracy per class")
+    if target_se <= 0:
+        raise ValueError("target_se must be positive")
+    w = am / am.sum()
+    s = np.sqrt(u * (1 - u))
+    return int(math.ceil((np.sum(w * s) / target_se) ** 2 - 1e-9))
+
+
+def allocate_accuracy_sample(
+    n: int,
+    mapped_area: Sequence[float],
+    method: str = "proportional",
+    min_per_class: int = 0,
+    rare: Optional[Dict[int, int]] = None,
+) -> List[int]:
+    """Allocate ``n`` among map classes.
+
+    ``method`` is ``"proportional"`` or ``"equal"``. ``rare`` fixes the size of
+    selected classes (index -> n), as Olofsson et al. (2014) recommend for
+    small change classes (e.g. 50-100 units each), and the remainder is
+    allocated proportionally among the other classes.
+    """
+    am = [float(a) for a in mapped_area]
+    if not rare:
+        return list(allocate(n, am, method, min_per_stratum=min_per_class))
+    fixed = {int(k): int(v) for k, v in rare.items()}
+    rest_idx = [i for i in range(len(am)) if i not in fixed]
+    left = n - sum(fixed.values())
+    if left < 0:
+        raise ValueError("fixed class sizes exceed n")
+    rest = allocate(left, [am[i] for i in rest_idx], method, min_per_stratum=min_per_class)
+    out = [0] * len(am)
+    for i, v in fixed.items():
+        out[i] = v
+    for i, v in zip(rest_idx, rest):
+        out[i] = int(v)
+    return out

spatialsample/balance.py

@@ -0,0 +1,144 @@
+"""Voronoi spatial-balance metric of Stevens & Olsen (2004).
+
+For each sample site ``i`` let ``v_i`` be the total inclusion probability of
+the frame units in the site's Voronoi polygon (the units nearer to ``i`` than
+to any other site). In a perfectly balanced sample every ``v_i`` equals one.
+The metric is the variance ``mean((v_i - 1)^2)``; smaller is better. Simple
+random samples typically score around 0.3; GRTS, BAS and LPM designs are
+markedly lower.
+
+Voronoi polygons are evaluated on a dense frame (a fine grid for continuous
+domains), so no polygon clipping is required.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Mapping, Optional
+
+import numpy as np
+
+from ._frame import as_domain, grid_frame
+from ._types import SeedLike, as_rng
+from .probabilities import nearest_index
+from .sample import Sample
+
+__all__ = ["voronoi_balance", "spatial_balance", "BalanceResult", "compare_designs"]
+
+
+@dataclass
+class BalanceResult:
+    """Voronoi balance of a sample."""
+
+    value: float
+    v: np.ndarray
+    n: int
+
+    @property
+    def max_deviation(self) -> float:
+        return float(np.max(np.abs(self.v - 1.0))) if self.n else float("nan")
+
+
+def voronoi_balance(sample_xy: Any, frame_xy: Any, frame_pi: Optional[Any] = None) -> BalanceResult:
+    """Voronoi balance of sites ``sample_xy`` against a finite frame.
+
+    ``frame_pi`` are the frame units' inclusion probabilities; by default they
+    are equal and sum to the sample size.
+    """
+    s = np.asarray(sample_xy, dtype=float).reshape(-1, 2)
+    f = np.asarray(frame_xy, dtype=float).reshape(-1, 2)
+    n = len(s)
+    if n == 0:
+        raise ValueError("empty sample")
+    if frame_pi is None:
+        pi = np.full(len(f), n / len(f))
+    else:
+        pi = np.asarray(frame_pi, dtype=float).ravel()
+        if len(pi) != len(f):
+            raise ValueError("frame_pi must have one value per frame point")
+        pi = pi * (n / pi.sum())
+    owner = nearest_index(f, s)
+    v = np.bincount(owner, weights=pi, minlength=n)
+    return BalanceResult(value=float(np.mean((v - 1.0) ** 2)), v=v, n=n)
+
+
+def spatial_balance(
+    sample: Any,
+    domain: Any = None,
+    frame_xy: Any = None,
+    frame_pi: Any = None,
+    frame_size: int = 20000,
+    base_only: bool = True,
+    seed: SeedLike = 0,
+) -> BalanceResult:
+    """Voronoi balance of a :class:`Sample` (or ``(n, 2)`` array).
+
+    Give either a finite frame (``frame_xy``, optional ``frame_pi``) or a
+    ``domain``, which is discretised into about ``frame_size`` grid points
+    with equal inclusion probability.
+    """
+    if isinstance(sample, Sample):
+        smp = sample.base() if base_only else sample
+        xy = smp.xy
+    else:
+        xy = np.asarray(sample, dtype=float).reshape(-1, 2)
+    if frame_xy is None:
+        if domain is None:
+            raise ValueError("give a domain or frame_xy")
+        frame_xy, _ = grid_frame(as_domain(domain), frame_size, as_rng(seed))
+    return voronoi_balance(xy, frame_xy, frame_pi)
+
+
+def compare_designs(
+    domain: Any,
+    n: int,
+    reps: int = 20,
+    designs: Optional[Mapping[str, Any]] = None,
+    frame_size: int = 20000,
+    seed: SeedLike = 0,
+) -> Dict[str, Dict[str, float]]:
+    """Mean and standard deviation of Voronoi balance over repeated draws.
+
+    ``designs`` maps a label to a callable ``f(domain, n, seed) -> Sample``;
+    by default SRS, square and hex systematic grids, BAS, GRTS, LPM and
+    Poisson-disk are compared.
+    """
+    from .bas import bas
+    from .designs import poisson_disk, srs, systematic
+    from .grts import grts
+    from .lpm import lpm
+
+    dom = as_domain(domain)
+    rng = as_rng(seed)
+    if designs is None:
+        designs = {
+            "srs": srs,
+            "systematic-square": lambda d, k, seed: systematic(d, k, rotation="random", seed=seed),
+            "systematic-hex": lambda d, k, seed: systematic(
+                d, k, shape="hex", rotation="random", seed=seed
+            ),
+            "poisson-disk": poisson_disk,
+            "bas": bas,
+            "grts": grts,
+            "lpm": lpm,
+        }
+    frame, _ = grid_frame(dom, frame_size, rng)
+    out: Dict[str, Dict[str, float]] = {}
+    for name, fn in designs.items():
+        vals = []
+        sizes = []
+        for _ in range(reps):
+            smp = fn(dom, n, seed=rng)
+            if isinstance(smp, Sample):
+                smp = smp.base()
+                xy = smp.xy
+            else:  # pragma: no cover - custom callables
+                xy = np.asarray(smp)
+            sizes.append(len(xy))
+            vals.append(voronoi_balance(xy, frame).value)
+        out[name] = {
+            "mean": float(np.mean(vals)),
+            "sd": float(np.std(vals, ddof=1)) if reps > 1 else 0.0,
+            "mean_n": float(np.mean(sizes)),
+        }
+    return out

spatialsample/bas.py

@@ -0,0 +1,96 @@
+"""Balanced Acceptance Sampling (BAS), Robertson et al. (2013).
+
+BAS draws points from a random-start Halton sequence (bases 2 and 3) over the
+bounding box of the domain and keeps those that fall inside it. Because the
+Halton sequence is a low-discrepancy sequence, consecutive accepted points are
+spread evenly, and the design is an equal-probability design in which each
+location has the same inclusion density ``n / area``. The points after the
+first ``n`` form a natural, still well spread, oversample.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List
+
+import numpy as np
+
+from ._frame import as_domain
+from ._types import FloatArray, SeedLike, as_rng
+from .sample import Sample
+
+__all__ = ["bas", "halton"]
+
+_MAX_START = 10_000_000
+
+
+def halton(index: Any, base: int) -> FloatArray:
+    """Radical-inverse (van der Corput) values of non-negative integers in ``base``."""
+    i = np.asarray(index, dtype=np.int64).copy()
+    if np.any(i < 0):
+        raise ValueError("Halton indices must be non-negative")
+    out = np.zeros(i.shape, dtype=float)
+    f = 1.0
+    while np.any(i > 0):
+        f /= base
+        out += f * (i % base)
+        i //= base
+    return out
+
+
+def bas(
+    domain: Any,
+    n: int,
+    n_over: int = 0,
+    seed: SeedLike = None,
+) -> Sample:
+    """Draw a Balanced Acceptance Sample of ``n`` sites (plus ``n_over`` oversample sites).
+
+    Parameters
+    ----------
+    domain:
+        Polygon :class:`~spatialsample.Region`, :class:`~spatialsample.RasterMask`
+        or GeoJSON mapping.
+    n, n_over:
+        Base and oversample sizes; oversample sites continue the Halton sequence.
+    seed:
+        Seed for the random start ``(k1, k2)`` of the Halton sequence.
+    """
+    rng = as_rng(seed)
+    dom = as_domain(domain)
+    if n < 1 or n_over < 0:
+        raise ValueError("n must be >= 1 and n_over >= 0")
+    m = n + n_over
+    x0, y0, x1, y1 = dom.bounds
+    k1, k2 = (int(v) for v in rng.integers(0, _MAX_START, 2))
+    frac = max(dom.area / ((x1 - x0) * (y1 - y0)), 1e-6)
+    got: List[FloatArray] = []
+    seq: List[np.ndarray] = []
+    have = 0
+    start = 0
+    for _ in range(100000):
+        batch = int(max(64, 1.3 * (m - have) / frac))
+        j = np.arange(start, start + batch, dtype=np.int64)
+        start += batch
+        pts = np.column_stack(
+            [x0 + (x1 - x0) * halton(k1 + j, 2), y0 + (y1 - y0) * halton(k2 + j, 3)]
+        )
+        ok = dom.contains(pts)
+        got.append(pts[ok])
+        seq.append(j[ok])
+        have += int(ok.sum())
+        if have >= m:
+            break
+    xy = np.vstack(got)[:m]
+    index = np.concatenate(seq)[:m]
+    density = n / dom.area
+    return Sample(
+        xy=xy,
+        pi=np.full(m, density),
+        weight=np.full(m, 1.0 / density),
+        design="bas",
+        kind="continuous",
+        site_type=np.array(["base"] * n + ["over"] * n_over, dtype=object),
+        order=np.arange(m),
+        attrs={"halton_index": index},
+        meta={"n": n, "n_over": n_over, "area": dom.area, "halton_start": (k1, k2)},
+    )