geomask 0.2.0__py3-none-any.whl

geomask/__init__.py

@@ -0,0 +1,103 @@
+"""geomask - geographic masking of confidential point data.
+
+Masks (random perturbation, Gaussian displacement, donut and
+population-adaptive donut masking, grid / hexagon / Voronoi aggregation with
+small-cell suppression, location swapping, adaptive areal elimination) plus
+privacy metrics (spatial k-anonymity, re-identification risk) and utility
+metrics (Ripley's L, kernel-density correlation, Moran's I) to document the
+trade-off between them.
+
+All masks work on projected coordinates in metres; see
+:mod:`geomask.projection` for lon/lat helpers. Masking is not anonymisation
+on its own - see the README's ethics section.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"
+
+from ._spatial import get_backend, set_backend
+from .aae import AAEResult, adaptive_areal_elimination
+from .aggregation import (
+    AggregationResult,
+    aggregate_by_label,
+    aggregate_to_grid,
+    aggregate_to_voronoi,
+)
+from .evaluate import EvaluationResult, compare, evaluate, report
+from .masking import (
+    DonutResult,
+    donut_mask,
+    gaussian_displacement,
+    location_swap,
+    random_perturbation,
+    snap_to_grid,
+    snap_to_hex,
+)
+from .privacy import (
+    DisplacementStats,
+    displacement,
+    displacement_stats,
+    expected_reidentification_risk,
+    nearest_neighbour_reidentification_rate,
+    spatial_k_anonymity,
+)
+from .projection import UTM, LocalEquirectangular, make_projection, utm_zone
+from .synthetic import SyntheticCity, synthetic_city
+from .utility import (
+    ClusterPreservation,
+    RipleyComparison,
+    cluster_preservation,
+    kde_correlation,
+    kernel_density,
+    mean_displacement,
+    morans_i,
+    ripley_k,
+    ripley_l,
+    ripley_l_difference,
+)
+
+__all__ = [
+    "AAEResult",
+    "AggregationResult",
+    "ClusterPreservation",
+    "DisplacementStats",
+    "DonutResult",
+    "EvaluationResult",
+    "LocalEquirectangular",
+    "RipleyComparison",
+    "SyntheticCity",
+    "UTM",
+    "__version__",
+    "adaptive_areal_elimination",
+    "aggregate_by_label",
+    "aggregate_to_grid",
+    "aggregate_to_voronoi",
+    "cluster_preservation",
+    "compare",
+    "displacement",
+    "displacement_stats",
+    "donut_mask",
+    "evaluate",
+    "expected_reidentification_risk",
+    "gaussian_displacement",
+    "get_backend",
+    "kde_correlation",
+    "kernel_density",
+    "location_swap",
+    "make_projection",
+    "mean_displacement",
+    "morans_i",
+    "nearest_neighbour_reidentification_rate",
+    "random_perturbation",
+    "report",
+    "ripley_k",
+    "ripley_l",
+    "ripley_l_difference",
+    "set_backend",
+    "snap_to_grid",
+    "snap_to_hex",
+    "spatial_k_anonymity",
+    "synthetic_city",
+    "utm_zone",
+]

geomask/_spatial.py

@@ -0,0 +1,178 @@
+"""Neighbour queries with an optional SciPy KD-tree and a pure-NumPy fallback.
+
+Every function here gives identical results with either backend; SciPy only
+makes them faster on large inputs. The backend can be forced with
+:func:`set_backend` (useful for testing) or the ``GEOMASK_NO_SCIPY``
+environment variable.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import numpy as np
+
+try:  # pragma: no cover - exercised implicitly depending on the environment
+    from scipy.spatial import cKDTree as _KDTree
+
+    _HAVE_SCIPY = True
+except Exception:  # pragma: no cover
+    _KDTree = None
+    _HAVE_SCIPY = False
+
+_use_scipy = _HAVE_SCIPY and not os.environ.get("GEOMASK_NO_SCIPY")
+
+#: Upper bound on the number of pairwise distances held in memory at once by
+#: the NumPy fallback.
+_CHUNK_ELEMENTS = 2_000_000
+
+
+def set_backend(name: str) -> str:
+    """Select the neighbour-search backend: ``"scipy"``, ``"numpy"`` or ``"auto"``.
+
+    Returns the backend actually in use. Asking for ``"scipy"`` when SciPy is
+    not installed raises :class:`ImportError`.
+    """
+    global _use_scipy
+    if name == "auto":
+        _use_scipy = _HAVE_SCIPY
+    elif name == "scipy":
+        if not _HAVE_SCIPY:
+            raise ImportError("SciPy is not installed; pip install 'geomask[fast]'")
+        _use_scipy = True
+    elif name == "numpy":
+        _use_scipy = False
+    else:
+        raise ValueError(f"unknown backend {name!r}; use 'scipy', 'numpy' or 'auto'")
+    return get_backend()
+
+
+def get_backend() -> str:
+    """Return the name of the active backend (``"scipy"`` or ``"numpy"``)."""
+    return "scipy" if _use_scipy else "numpy"
+
+
+def _step(n_ref: int) -> int:
+    return max(1, _CHUNK_ELEMENTS // max(1, n_ref))
+
+
+def _dist_block(query: np.ndarray, ref: np.ndarray) -> np.ndarray:
+    diff = query[:, None, :] - ref[None, :, :]
+    return np.sqrt(np.einsum("ijk,ijk->ij", diff, diff))
+
+
+def _tree(ref: np.ndarray) -> Any:
+    assert _KDTree is not None
+    return _KDTree(ref)
+
+
+def count_closer(ref: np.ndarray, centers: np.ndarray, radii: np.ndarray) -> np.ndarray:
+    """Count reference points *strictly* closer than ``radii[i]`` to ``centers[i]``."""
+    n = len(centers)
+    out = np.zeros(n, dtype=np.int64)
+    if n == 0 or len(ref) == 0:
+        return out
+    radii = np.asarray(radii, dtype=float)
+    if _use_scipy:
+        # query_ball_point uses a closed ball; shrink by one ulp for a strict test.
+        r = np.nextafter(radii, -np.inf)
+        r = np.where(radii > 0, r, -1.0)
+        pos = r >= 0
+        if np.any(pos):
+            lens = _tree(ref).query_ball_point(centers[pos], r[pos], return_length=True)
+            out[pos] = np.asarray(lens, dtype=np.int64)
+        return out
+    step = _step(len(ref))
+    for s in range(0, n, step):
+        d = _dist_block(centers[s : s + step], ref)
+        out[s : s + step] = np.sum(d < radii[s : s + step, None], axis=1)
+    return out
+
+
+def kth_nearest_distance(ref: np.ndarray, query: np.ndarray, k: int) -> np.ndarray:
+    """Distance from each query point to its ``k``-th nearest reference point (1-based).
+
+    Reference points at distance zero (e.g. the query location itself) count.
+    Returns ``inf`` where fewer than ``k`` reference points exist.
+    """
+    if k < 1:
+        raise ValueError("k must be >= 1")
+    n = len(query)
+    if len(ref) < k:
+        return np.full(n, np.inf)
+    if _use_scipy:
+        d, _ = _tree(ref).query(query, k=[k])
+        return np.asarray(d, dtype=float).reshape(n)
+    out = np.empty(n)
+    step = _step(len(ref))
+    for s in range(0, n, step):
+        d = _dist_block(query[s : s + step], ref)
+        out[s : s + step] = np.partition(d, k - 1, axis=1)[:, k - 1]
+    return out
+
+
+def nearest(ref: np.ndarray, query: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """Distance to and index of the nearest reference point for each query point."""
+    n = len(query)
+    if len(ref) == 0:
+        raise ValueError("reference set is empty")
+    if _use_scipy:
+        d, i = _tree(ref).query(query, k=1)
+        return np.asarray(d, dtype=float).reshape(n), np.asarray(i, dtype=np.int64).reshape(n)
+    dist = np.empty(n)
+    idx = np.empty(n, dtype=np.int64)
+    step = _step(len(ref))
+    for s in range(0, n, step):
+        d = _dist_block(query[s : s + step], ref)
+        j = np.argmin(d, axis=1)
+        idx[s : s + step] = j
+        dist[s : s + step] = d[np.arange(len(j)), j]
+    return dist, idx
+
+
+def within_annulus(
+    ref: np.ndarray, query: np.ndarray, r_min: float, r_max: float
+) -> list[np.ndarray]:
+    """Indices of reference points with ``r_min < distance <= r_max`` for each query point."""
+    out: list[np.ndarray] = []
+    if len(ref) == 0:
+        return [np.empty(0, dtype=np.int64) for _ in range(len(query))]
+    if _use_scipy:
+        tree = _tree(ref)
+        lists = tree.query_ball_point(query, r_max)
+        for q, idx in zip(query, lists):
+            idx = np.asarray(idx, dtype=np.int64)
+            if len(idx):
+                d = np.hypot(ref[idx, 0] - q[0], ref[idx, 1] - q[1])
+                idx = np.sort(idx[d > r_min])
+            out.append(idx)
+        return out
+    step = _step(len(ref))
+    for s in range(0, len(query), step):
+        d = _dist_block(query[s : s + step], ref)
+        mask = (d > r_min) & (d <= r_max)
+        out.extend(np.flatnonzero(row) for row in mask)
+    return out
+
+
+def pair_counts(points: np.ndarray, radii: np.ndarray) -> np.ndarray:
+    """Number of *ordered* pairs ``(i, j), i != j`` with distance ``<= r`` for each radius."""
+    radii = np.asarray(radii, dtype=float)
+    n = len(points)
+    if n < 2:
+        return np.zeros(len(radii), dtype=np.int64)
+    if _use_scipy:
+        tree = _tree(points)
+        c = np.asarray(tree.count_neighbors(tree, radii), dtype=np.int64)
+        # count_neighbors includes the n self-pairs at distance 0.
+        return c - n
+    order = np.argsort(radii)
+    counts = np.zeros(len(radii), dtype=np.int64)
+    step = _step(n)
+    sorted_r = radii[order]
+    for s in range(0, n, step):
+        d = _dist_block(points[s : s + step], points).ravel()
+        d = np.sort(d)
+        counts[order] += np.searchsorted(d, sorted_r, side="right")
+    return counts - n

geomask/_utils.py

@@ -0,0 +1,77 @@
+"""Small shared helpers: input validation and random-number generators."""
+
+from __future__ import annotations
+
+from typing import Union
+
+import numpy as np
+
+#: Anything accepted as a seed: ``None`` (fresh entropy), an ``int`` or an existing
+#: :class:`numpy.random.Generator` (consumed in place).
+SeedLike = Union[None, int, np.random.Generator]
+
+
+def as_points(points: object, name: str = "points", allow_nan: bool = False) -> np.ndarray:
+    """Return ``points`` as a float ``(n, 2)`` array, validating shape and values."""
+    arr = np.asarray(points, dtype=float)
+    if arr.ndim == 1 and arr.size == 2:
+        arr = arr.reshape(1, 2)
+    if arr.ndim == 1 and arr.size == 0:
+        arr = arr.reshape(0, 2)
+    if arr.ndim != 2 or arr.shape[1] != 2:
+        raise ValueError(f"{name} must have shape (n, 2); got {arr.shape}")
+    if allow_nan:
+        if np.any(np.isinf(arr)):
+            raise ValueError(f"{name} contains infinite coordinates")
+    elif not np.all(np.isfinite(arr)):
+        raise ValueError(f"{name} contains NaN or infinite coordinates")
+    return arr
+
+
+def make_rng(seed: SeedLike) -> np.random.Generator:
+    """Return a :class:`numpy.random.Generator` for ``seed``."""
+    if isinstance(seed, np.random.Generator):
+        return seed
+    return np.random.default_rng(seed)
+
+
+def check_positive(value: float, name: str, allow_zero: bool = False) -> float:
+    """Validate a finite, positive (or non-negative) scalar."""
+    v = float(value)
+    if not np.isfinite(v) or v < 0 or (v == 0 and not allow_zero):
+        cond = ">= 0" if allow_zero else "> 0"
+        raise ValueError(f"{name} must be finite and {cond}; got {value!r}")
+    return v
+
+
+def check_k(k: int, name: str = "k") -> int:
+    """Validate a positive integer threshold."""
+    if isinstance(k, bool) or int(k) != k or k < 1:
+        raise ValueError(f"{name} must be an integer >= 1; got {k!r}")
+    return int(k)
+
+
+def random_directions(rng: np.random.Generator, n: int) -> np.ndarray:
+    """``n`` unit vectors with uniformly distributed angle, shape ``(n, 2)``."""
+    theta = rng.uniform(0.0, 2.0 * np.pi, n)
+    return np.column_stack([np.cos(theta), np.sin(theta)])
+
+
+def annulus_radii(
+    rng: np.random.Generator,
+    r_min: np.ndarray,
+    r_max: np.ndarray,
+    distribution: str = "area",
+) -> np.ndarray:
+    """Random distances in ``[r_min, r_max]``.
+
+    ``"area"`` makes the displaced point uniform over the annulus area
+    (density of the distance proportional to ``r``); ``"distance"`` makes the
+    distance itself uniform (the original donut formulation).
+    """
+    u = rng.uniform(0.0, 1.0, np.shape(r_min))
+    if distribution == "area":
+        return np.sqrt(r_min**2 + u * (r_max**2 - r_min**2))
+    if distribution == "distance":
+        return r_min + u * (r_max - r_min)
+    raise ValueError(f"distribution must be 'area' or 'distance'; got {distribution!r}")

geomask/aae.py

@@ -0,0 +1,214 @@
+"""Adaptive areal elimination (AAE) after Kounadi & Leitner (2016).
+
+AAE builds areas that each hold at least ``k`` people by merging small base
+units with their neighbours, then moves every point to a random location
+inside the merged area that contains it. Because each release area holds at
+least ``k`` population units, an adversary who knows the area learns only
+that the person is one of at least ``k`` residents (*areal* k-anonymity).
+
+This implementation uses a regular square grid as base units, so it needs
+nothing beyond NumPy. Pass address points, building centroids or the centres
+of a population raster (with ``population_weights``) as ``population``.
+"""
+
+from __future__ import annotations
+
+import heapq
+from dataclasses import dataclass
+
+import numpy as np
+
+from ._utils import SeedLike, as_points, check_k, check_positive, make_rng
+
+__all__ = ["AAEResult", "adaptive_areal_elimination"]
+
+
+@dataclass
+class AAEResult:
+    """Detailed output of :func:`adaptive_areal_elimination`.
+
+    Attributes:
+        points: masked coordinates, shape ``(n, 2)``.
+        region_of_point: release-area index of each input point.
+        region_population: population of each release area (``>= k`` for every
+            area that contains a point).
+        region_cells: number of base grid cells merged into each release area.
+        cell_region: release-area index of every base grid cell, shape
+            ``(ny, nx)`` (row 0 is the southernmost row).
+        origin: lower-left corner of the base grid.
+        cell_size: base grid cell size in metres.
+        k: anonymity threshold.
+    """
+
+    points: np.ndarray
+    region_of_point: np.ndarray
+    region_population: np.ndarray
+    region_cells: np.ndarray
+    cell_region: np.ndarray
+    origin: np.ndarray
+    cell_size: float
+    k: int
+
+    def region_of(self, xy: object) -> np.ndarray:
+        """Release-area index for arbitrary coordinates (``-1`` outside the grid)."""
+        p = as_points(xy, "xy")
+        ny, nx = self.cell_region.shape
+        ij = np.floor((p - self.origin) / self.cell_size).astype(np.int64)
+        inside = (ij[:, 0] >= 0) & (ij[:, 0] < nx) & (ij[:, 1] >= 0) & (ij[:, 1] < ny)
+        out = np.full(len(p), -1, dtype=np.int64)
+        out[inside] = self.cell_region[ij[inside, 1], ij[inside, 0]]
+        return out
+
+
+def adaptive_areal_elimination(
+    points: object,
+    population: object,
+    k: int,
+    cell_size: float,
+    seed: SeedLike = None,
+    *,
+    population_weights: object | None = None,
+    placement: str = "uniform",
+    return_details: bool = False,
+) -> np.ndarray | AAEResult:
+    """Mask points with adaptive areal elimination (AAE).
+
+    Algorithm:
+
+    1. Lay a square grid of ``cell_size`` metres over the points and the
+       population and count the population in each cell.
+    2. While some area that contains a point has fewer than ``k`` people,
+       take the one with the smallest population and merge it with the
+       edge-adjacent area of smallest population.
+    3. Move every point to a random location in its merged area:
+       ``placement="uniform"`` picks a uniform location over the area;
+       ``"population"`` picks a random population unit in the area
+       (weighted), which keeps points on plausible residential locations.
+
+    Args:
+        points: ``(n, 2)`` true locations (metres).
+        population: ``(m, 2)`` population unit locations.
+        k: minimum population per release area.
+        cell_size: base grid resolution in metres. Smaller cells give more
+            compact, data-adaptive areas at a higher computing cost.
+        seed: random seed or generator.
+        population_weights: optional people per population unit (default 1).
+        placement: ``"uniform"`` or ``"population"``.
+        return_details: return an :class:`AAEResult` instead of an array.
+
+    Raises:
+        ValueError: if the total population is below ``k``.
+    """
+    pts = as_points(points)
+    pop = as_points(population, "population")
+    k = check_k(k)
+    cs = check_positive(cell_size, "cell_size")
+    if placement not in {"uniform", "population"}:
+        raise ValueError("placement must be 'uniform' or 'population'")
+    if population_weights is None:
+        w = np.ones(len(pop))
+    else:
+        w = np.asarray(population_weights, dtype=float).reshape(-1)
+        if w.shape != (len(pop),) or np.any(w < 0) or not np.all(np.isfinite(w)):
+            raise ValueError("population_weights must be finite, >= 0, one per unit")
+    if w.sum() < k:
+        raise ValueError(f"total population {w.sum():g} is below k={k}")
+    rng = make_rng(seed)
+
+    allpts = np.vstack([pts, pop])
+    origin = np.floor(allpts.min(axis=0) / cs) * cs
+    nx, ny = (np.floor((allpts.max(axis=0) - origin) / cs).astype(np.int64) + 1).tolist()
+    ncell = nx * ny
+
+    def cell_index(p: np.ndarray) -> np.ndarray:
+        ij = np.floor((p - origin) / cs).astype(np.int64)
+        ij[:, 0] = np.clip(ij[:, 0], 0, nx - 1)
+        ij[:, 1] = np.clip(ij[:, 1], 0, ny - 1)
+        return np.asarray(ij[:, 1] * nx + ij[:, 0], dtype=np.int64)
+
+    pt_cell = cell_index(pts)
+    pop_cell = cell_index(pop)
+    cell_pop = np.bincount(pop_cell, weights=w, minlength=ncell)
+    has_pt = np.bincount(pt_cell, minlength=ncell) > 0
+
+    parent = np.arange(ncell)
+    rpop: dict[int, float] = {c: float(cell_pop[c]) for c in range(ncell)}
+    rhas: dict[int, bool] = {c: bool(has_pt[c]) for c in range(ncell)}
+    nbrs: dict[int, set[int]] = {}
+    for c in range(ncell):
+        cx, cy = c % nx, c // nx
+        s: set[int] = set()
+        if cx > 0:
+            s.add(c - 1)
+        if cx < nx - 1:
+            s.add(c + 1)
+        if cy > 0:
+            s.add(c - nx)
+        if cy < ny - 1:
+            s.add(c + nx)
+        nbrs[c] = s
+
+    heap = [(rpop[c], c) for c in range(ncell) if rhas[c] and rpop[c] < k]
+    heapq.heapify(heap)
+    while heap:
+        p_a, a = heapq.heappop(heap)
+        if a not in rpop or rpop[a] != p_a or rpop[a] >= k:
+            continue
+        # Total population >= k guarantees a neighbour exists while rpop[a] < k.
+        b = min(nbrs[a], key=lambda r: (rpop[r], r))
+        # Merge b into a.
+        parent[b] = a
+        rpop[a] += rpop.pop(b)
+        rhas[a] = rhas[a] or rhas.pop(b)
+        for nb in nbrs.pop(b):
+            nbrs[nb].discard(b)
+            if nb != a:
+                nbrs[nb].add(a)
+                nbrs[a].add(nb)
+        nbrs[a].discard(b)
+        nbrs[a].discard(a)
+        if rpop[a] < k:
+            heapq.heappush(heap, (rpop[a], a))
+
+    # Resolve union-find roots (path compression by repeated lookup).
+    root = parent.copy()
+    while True:
+        nxt = root[root]
+        if np.array_equal(nxt, root):
+            break
+        root = nxt
+    roots, cell_region = np.unique(root, return_inverse=True)
+    cell_region = cell_region.reshape(-1)
+    n_reg = len(roots)
+    region_population = np.bincount(cell_region, weights=cell_pop, minlength=n_reg)
+    region_cells = np.bincount(cell_region, minlength=n_reg)
+    region_of_point = cell_region[pt_cell]
+
+    out = np.empty_like(pts)
+    order = np.argsort(cell_region, kind="stable")
+    starts = np.concatenate([[0], np.cumsum(region_cells)])
+    pop_region = cell_region[pop_cell]
+    for i in range(len(pts)):
+        reg = region_of_point[i]
+        if placement == "uniform":
+            cells = order[starts[reg] : starts[reg + 1]]
+            c = cells[rng.integers(len(cells))]
+            ll = origin + cs * np.array([c % nx, c // nx], dtype=float)
+            out[i] = ll + rng.uniform(0.0, cs, 2)
+        else:
+            cand = np.flatnonzero((pop_region == reg) & (w > 0))
+            pr = w[cand] / w[cand].sum()
+            out[i] = pop[cand[rng.choice(len(cand), p=pr)]]
+
+    if return_details:
+        return AAEResult(
+            points=out,
+            region_of_point=region_of_point,
+            region_population=region_population,
+            region_cells=region_cells,
+            cell_region=cell_region.reshape(ny, nx),
+            origin=origin,
+            cell_size=cs,
+            k=k,
+        )
+    return out