arealinterp 0.1.0__py3-none-any.whl

arealinterp/__init__.py

@@ -0,0 +1,106 @@
+"""arealinterp: areal interpolation between incompatible zone systems.
+
+Quick start::
+
+    from arealinterp import area_weighted, read_geojson
+
+    tracts = read_geojson("tracts.geojson", id_field="GEOID")
+    districts = read_geojson("districts.geojson", id_field="code")
+    res = area_weighted(tracts, districts, extensive="pop", intensive="income")
+    print(res.as_dict("pop"), res.volume["pop"])
+
+Methods: areal weighting (Goodchild & Lam 1980), target-density weighting
+(Schroeder 2007), binary / density / fixed-percentage dasymetric mapping
+(Eicher & Brewer 2001; Mennis 2003) and smooth pycnophylactic interpolation
+(Tobler 1979). Coordinates must be in a projected (planar) CRS.
+"""
+
+from ._version import __version__
+from .areal import area_weighted, target_density_weighted, zone_values
+from .dasymetric import (
+    UNCOVERED,
+    DensityEstimate,
+    binary_dasymetric,
+    class_key,
+    dasymetric,
+    estimate_class_densities,
+)
+from .diagnostics import InterpolationResult, VolumeReport, volume_report
+from .geometry import (
+    GeometryError,
+    box,
+    intersection,
+    intersection_area,
+    make_polygon,
+    point_in_region,
+    region_area,
+    region_from_geojson,
+    region_to_geojson,
+)
+from .io import (
+    join_csv,
+    looks_geographic,
+    read_csv_table,
+    read_geojson,
+    to_feature_collection,
+    write_csv,
+    write_geojson,
+    write_overlay_csv,
+    zones_from_geojson,
+)
+from .overlay import Overlay, Zone, get_backend, overlay
+from .pycno import PycnoResult, pycnophylactic, pycnophylactic_interpolate
+from .raster import Grid, Raster, rasterize, read_ascii_grid, write_ascii_grid, zonal_sum
+
+__all__ = [
+    "__version__",
+    # zones and overlay
+    "Zone",
+    "Overlay",
+    "overlay",
+    "get_backend",
+    # geometry
+    "GeometryError",
+    "box",
+    "make_polygon",
+    "region_area",
+    "region_from_geojson",
+    "region_to_geojson",
+    "intersection",
+    "intersection_area",
+    "point_in_region",
+    # methods
+    "area_weighted",
+    "target_density_weighted",
+    "dasymetric",
+    "binary_dasymetric",
+    "estimate_class_densities",
+    "DensityEstimate",
+    "UNCOVERED",
+    "class_key",
+    "pycnophylactic",
+    "pycnophylactic_interpolate",
+    "PycnoResult",
+    # diagnostics
+    "InterpolationResult",
+    "VolumeReport",
+    "volume_report",
+    "zone_values",
+    # raster
+    "Grid",
+    "Raster",
+    "rasterize",
+    "zonal_sum",
+    "read_ascii_grid",
+    "write_ascii_grid",
+    # io
+    "read_geojson",
+    "zones_from_geojson",
+    "write_geojson",
+    "to_feature_collection",
+    "write_csv",
+    "write_overlay_csv",
+    "read_csv_table",
+    "join_csv",
+    "looks_geographic",
+]

arealinterp/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m arealinterp``."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

arealinterp/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

arealinterp/areal.py

@@ -0,0 +1,183 @@
+"""Area-weighted and target-density-weighted interpolation."""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Iterable, Optional, Sequence, Union
+
+import numpy as np
+
+from .diagnostics import InterpolationResult, volume_report
+from .geometry import DEFAULT_TOLERANCE
+from .overlay import Overlay, Zone, overlay
+
+Names = Union[str, Iterable[str], None]
+
+
+def _names(v: Names) -> list:
+    if v is None:
+        return []
+    if isinstance(v, str):
+        return [v]
+    return list(v)
+
+
+def zone_values(zones: Sequence[Zone], variable: str) -> np.ndarray:
+    """Numeric values of ``variable`` for each zone (missing/blank -> NaN)."""
+    out = np.empty(len(zones), dtype=float)
+    for k, z in enumerate(zones):
+        v: Any = z.properties.get(variable)
+        if v is None or (isinstance(v, str) and v.strip() == ""):
+            out[k] = math.nan
+            continue
+        try:
+            out[k] = float(v)
+        except (TypeError, ValueError) as exc:
+            raise ValueError(f"zone {z.id!r}: value {v!r} of {variable!r} is not numeric") from exc
+    return out
+
+
+def _check_ids(ov: Overlay, sources: Sequence[Zone], targets: Sequence[Zone]) -> None:
+    if len(ov.source_ids) != len(sources) or len(ov.target_ids) != len(targets):
+        raise ValueError("the supplied overlay does not match the source/target zones")
+
+
+def area_weighted(
+    sources: Sequence[Zone],
+    targets: Sequence[Zone],
+    extensive: Names = None,
+    intensive: Names = None,
+    *,
+    allocate_total: bool = False,
+    backend: str = "auto",
+    tolerance: float = DEFAULT_TOLERANCE,
+    precomputed: Optional[Overlay] = None,
+) -> InterpolationResult:
+    """Areal weighting (Goodchild & Lam 1980).
+
+    Extensive (count) variables::
+
+        y_t = sum_s y_s * A_st / A_s
+
+    Intensive (rate/density) variables, as an area-weighted mean over the part
+    of ``t`` covered by source zones::
+
+        y_t = sum_s y_s * A_st / sum_s A_st
+
+    Here ``A_st`` is the area of ``s ∩ t`` and ``A_s`` the area of ``s``.
+    With ``allocate_total=True`` the extensive denominator becomes
+    ``sum_t A_st`` so that each source's whole value is handed to the targets
+    it touches (useful when targets do not quite cover the sources, e.g. a
+    coastline digitised differently). Source zones with NaN values contribute
+    nothing; targets touched by no source get NaN for intensive variables and
+    0 for extensive ones.
+
+    Reference: Goodchild, M. F. & Lam, N. S.-N. (1980). Areal interpolation:
+    a variant of the traditional spatial problem. *Geo-Processing* 1, 297-312.
+    """
+    ext = _names(extensive)
+    intens = _names(intensive)
+    if not ext and not intens:
+        raise ValueError("give at least one extensive or intensive variable")
+    ov = precomputed or overlay(sources, targets, backend=backend, tolerance=tolerance)
+    _check_ids(ov, sources, targets)
+    n_t = len(targets)
+    si, ti, a = ov.source_index, ov.target_index, ov.area
+    result = InterpolationResult([z.id for z in targets], {}, "area_weighted")
+    result.details["backend"] = ov.backend
+
+    if allocate_total:
+        denom_s = ov.covered_source_area()
+    else:
+        denom_s = ov.source_areas
+    with np.errstate(divide="ignore", invalid="ignore"):
+        w_ext = np.where(denom_s[si] > 0, a / denom_s[si], 0.0)
+
+    for name in ext:
+        y = zone_values(sources, name)
+        contrib = np.nan_to_num(y[si]) * w_ext
+        est = np.bincount(ti, contrib, minlength=n_t)
+        allocated = np.bincount(si, contrib, minlength=len(sources))
+        result.values[name] = est
+        result.volume[name] = volume_report(name, y, est, allocated)
+        if not result.volume[name].preserved(rtol=1e-6):
+            result.notes.append(
+                f"{name}: {result.volume[name].relative_error:+.3%} of the total did not "
+                "reach a target zone (sources not fully covered by targets)"
+            )
+
+    for name in intens:
+        y = zone_values(sources, name)
+        ok = ~np.isnan(y[si])
+        num = np.bincount(ti[ok], (y[si] * a)[ok], minlength=n_t)
+        den = np.bincount(ti[ok], a[ok], minlength=n_t)
+        with np.errstate(divide="ignore", invalid="ignore"):
+            result.values[name] = np.where(den > 0, num / den, np.nan)
+    return result
+
+
+def target_density_weighted(
+    sources: Sequence[Zone],
+    targets: Sequence[Zone],
+    extensive: Names,
+    target_variable: str,
+    *,
+    backend: str = "auto",
+    tolerance: float = DEFAULT_TOLERANCE,
+    precomputed: Optional[Overlay] = None,
+) -> InterpolationResult:
+    """Target-density weighting (TDW; Schroeder 2007).
+
+    An ancillary count ``z_t`` known for the *target* zones (for example the
+    population of the target year) is assumed uniformly spread inside each
+    target zone. Each source value is split among its intersections in
+    proportion to the ancillary amount they contain::
+
+        w_st = A_st * z_t / A_t
+        y_t  = sum_s y_s * w_st / sum_t' w_st'
+
+    Sources whose intersections all carry ``z = 0`` fall back to areal
+    weighting over their covered area (listed in ``details['fallback_sources']``).
+    Each source value is fully allocated to the targets it touches.
+
+    Reference: Schroeder, J. P. (2007). Target-density weighting interpolation
+    and uncertainty evaluation for temporal analysis of census data.
+    *Geographical Analysis* 39(3), 311-335.
+    """
+    ext = _names(extensive)
+    if not ext:
+        raise ValueError("give at least one extensive variable")
+    ov = precomputed or overlay(sources, targets, backend=backend, tolerance=tolerance)
+    _check_ids(ov, sources, targets)
+    n_s, n_t = len(sources), len(targets)
+    si, ti, a = ov.source_index, ov.target_index, ov.area
+    z = np.nan_to_num(zone_values(targets, target_variable))
+    if np.any(z < 0):
+        raise ValueError(f"target variable {target_variable!r} must be non-negative")
+    with np.errstate(divide="ignore", invalid="ignore"):
+        dens = np.where(ov.target_areas > 0, z / ov.target_areas, 0.0)
+    w = a * dens[ti]
+    wsum = np.bincount(si, w, minlength=n_s)
+    asum = np.bincount(si, a, minlength=n_s)
+    fallback = (wsum <= 0) & (asum > 0)
+    with np.errstate(divide="ignore", invalid="ignore"):
+        share = np.where(
+            fallback[si],
+            a / np.where(asum[si] > 0, asum[si], 1.0),
+            w / np.where(wsum[si] > 0, wsum[si], 1.0),
+        )
+    result = InterpolationResult([t.id for t in targets], {}, "target_density_weighted")
+    result.details["backend"] = ov.backend
+    result.details["fallback_sources"] = [sources[int(k)].id for k in np.nonzero(fallback)[0]]
+    if result.details["fallback_sources"]:
+        result.notes.append(
+            f"{len(result.details['fallback_sources'])} source zone(s) overlap only targets "
+            f"with {target_variable}=0; areal weighting used for them"
+        )
+    for name in ext:
+        y = zone_values(sources, name)
+        contrib = np.nan_to_num(y[si]) * share
+        est = np.bincount(ti, contrib, minlength=n_t)
+        result.values[name] = est
+        result.volume[name] = volume_report(name, y, est, np.bincount(si, contrib, minlength=n_s))
+    return result

arealinterp/cli.py

@@ -0,0 +1,295 @@
+"""Command-line interface: ``arealinterp <command> ...``."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence
+
+from ._version import __version__
+from .areal import area_weighted, target_density_weighted
+from .dasymetric import Ancillary, binary_dasymetric, dasymetric, estimate_class_densities
+from .diagnostics import InterpolationResult
+from .io import (
+    join_csv,
+    looks_geographic,
+    read_geojson,
+    read_geojson_crs,
+    write_csv,
+    write_geojson,
+    write_overlay_csv,
+)
+from .overlay import Zone, overlay
+from .pycno import pycnophylactic, pycnophylactic_interpolate
+from .raster import read_ascii_grid, write_ascii_grid
+
+
+def _split(values: Optional[Sequence[str]]) -> List[str]:
+    out: List[str] = []
+    for v in values or []:
+        out.extend(x.strip() for x in v.split(",") if x.strip())
+    return out
+
+
+def _pairs(values: Optional[Sequence[str]], flag: str) -> Dict[str, float]:
+    out: Dict[str, float] = {}
+    for item in _split(values):
+        if "=" not in item:
+            raise SystemExit(f"arealinterp: {flag} expects CLASS=VALUE, got {item!r}")
+        k, v = item.split("=", 1)
+        try:
+            out[k.strip()] = float(v)
+        except ValueError:
+            raise SystemExit(f"arealinterp: {flag}: {v!r} is not a number") from None
+    return out
+
+
+def _load(path: str, id_field: Optional[str], role: str) -> List[Zone]:
+    zones = read_geojson(path, id_field)
+    if not zones:
+        raise SystemExit(f"arealinterp: no polygon features in {role} file {path}")
+    if looks_geographic(zones):
+        print(
+            f"arealinterp: warning: {role} coordinates look like longitude/latitude; "
+            "areas need a projected CRS (reproject first)",
+            file=sys.stderr,
+        )
+    return zones
+
+
+def _add_common(p: argparse.ArgumentParser, target: bool = True) -> None:
+    p.add_argument("source", help="source zones (GeoJSON)")
+    if target:
+        p.add_argument("target", help="target zones (GeoJSON)")
+    p.add_argument("--source-id", help="source id property (default: feature id or index)")
+    p.add_argument("--target-id", help="target id property (default: feature id or index)")
+    p.add_argument("--join", metavar="CSV", help="join source attributes from a CSV file")
+    p.add_argument("--join-id", help="id column of --join (default: --source-id or 'id')")
+    p.add_argument("-o", "--output", help="output .geojson or .csv (default: CSV on stdout)")
+    p.add_argument(
+        "--backend", default="auto", choices=["auto", "python", "shapely"], help="geometry engine"
+    )
+
+
+def _add_extensive(p: argparse.ArgumentParser, required: bool = True) -> None:
+    p.add_argument(
+        "-e",
+        "--extensive",
+        action="append",
+        required=required,
+        help="extensive (count) variable; repeat or comma-separate",
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(
+        prog="arealinterp",
+        description="Areal interpolation between incompatible zone systems.",
+    )
+    ap.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = ap.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("overlay", help="write the source x target intersection-area table")
+    _add_common(p)
+
+    p = sub.add_parser("areal", help="area-weighted interpolation (Goodchild & Lam 1980)")
+    _add_common(p)
+    _add_extensive(p, required=False)
+    p.add_argument("-i", "--intensive", action="append", help="intensive (rate) variable")
+    p.add_argument(
+        "--allocate-total",
+        action="store_true",
+        help="hand each source's whole value to the targets it touches",
+    )
+
+    p = sub.add_parser("tdw", help="target-density weighting (Schroeder 2007)")
+    _add_common(p)
+    _add_extensive(p)
+    p.add_argument("--target-weight", required=True, help="ancillary count on the target zones")
+
+    p = sub.add_parser("dasymetric", help="dasymetric mapping with land cover")
+    _add_common(p)
+    _add_extensive(p)
+    anc = p.add_mutually_exclusive_group(required=True)
+    anc.add_argument("--raster", help="land-cover raster (ESRI ASCII grid .asc)")
+    anc.add_argument("--landcover", help="land-cover polygons (GeoJSON)")
+    p.add_argument("--class-field", default="class", help="class property of --landcover")
+    how = p.add_mutually_exclusive_group(required=True)
+    how.add_argument("--inhabited", action="append", help="binary method: inhabited classes")
+    how.add_argument("--density", action="append", help="relative density CLASS=VALUE")
+    how.add_argument("--percent", action="append", help="fixed share CLASS=VALUE")
+    how.add_argument(
+        "--estimate", action="store_true", help="estimate densities by percent-cover sampling"
+    )
+    p.add_argument("--threshold", type=float, default=0.8, help="sampling threshold (0-1]")
+    p.add_argument("--preset", action="append", help="preset density CLASS=VALUE (--estimate)")
+    p.add_argument("--default-weight", type=float, default=0.0, help="weight of unlisted classes")
+    p.add_argument("--surface", help="write the dasymetric surface (raster input) to .asc")
+
+    p = sub.add_parser("pycno", help="pycnophylactic interpolation (Tobler 1979)")
+    _add_common(p, target=False)
+    p.add_argument("target", nargs="?", help="target zones (GeoJSON); optional")
+    _add_extensive(p)
+    p.add_argument("--cell-size", type=float, required=True, help="grid cell size (map units)")
+    p.add_argument("--max-iter", type=int, default=1000)
+    p.add_argument("--tolerance", type=float, default=1e-4)
+    p.add_argument("--relaxation", type=float, default=0.5)
+    p.add_argument("--boundary", choices=["neumann", "zero"], default="neumann")
+    p.add_argument("--surface", help="write the surface of the first variable to .asc")
+    return ap
+
+
+def _write_result(
+    result: InterpolationResult, targets: List[Zone], args: argparse.Namespace
+) -> None:
+    out = args.output
+    if out is None:
+        import csv
+        import math
+
+        w = csv.writer(sys.stdout, lineterminator="\n")
+        names = list(result.values)
+        w.writerow(["id", *names])
+        for row in result.records():
+            w.writerow(
+                [row["id"]]
+                + [
+                    "" if isinstance(row[n], float) and math.isnan(row[n]) else row[n]
+                    for n in names
+                ]
+            )
+    elif Path(out).suffix.lower() == ".csv":
+        write_csv(out, result)
+    else:
+        write_geojson(out, targets, result, crs=read_geojson_crs(args.target))
+    print(result.summary(), file=sys.stderr)
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return _run(args)
+    except (ValueError, KeyError, OSError, ImportError) as exc:
+        print(f"arealinterp: error: {exc}", file=sys.stderr)
+        return 2
+
+
+def _run(args: argparse.Namespace) -> int:
+    sources = _load(args.source, args.source_id, "source")
+    if args.join:
+        missing = join_csv(sources, args.join, args.join_id or args.source_id or "id")
+        if missing:
+            print(
+                f"arealinterp: warning: {len(missing)} source zone(s) without a CSV row",
+                file=sys.stderr,
+            )
+    targets = _load(args.target, args.target_id, "target") if args.target else None
+    ext = _split(getattr(args, "extensive", None))
+
+    if args.command == "overlay":
+        assert targets is not None
+        ov = overlay(sources, targets, backend=args.backend)
+        if args.output:
+            write_overlay_csv(args.output, ov)
+        else:
+            import csv
+
+            w = csv.DictWriter(
+                sys.stdout,
+                fieldnames=["source_id", "target_id", "area", "source_share", "target_share"],
+                lineterminator="\n",
+            )
+            w.writeheader()
+            for r in ov.records():
+                w.writerow(r)
+        print(f"overlay: {len(ov.area)} intersections ({ov.backend})", file=sys.stderr)
+        return 0
+
+    if args.command == "areal":
+        assert targets is not None
+        res = area_weighted(
+            sources,
+            targets,
+            ext,
+            _split(args.intensive),
+            allocate_total=args.allocate_total,
+            backend=args.backend,
+        )
+    elif args.command == "tdw":
+        assert targets is not None
+        res = target_density_weighted(
+            sources, targets, ext, args.target_weight, backend=args.backend
+        )
+    elif args.command == "dasymetric":
+        assert targets is not None
+        anc: Ancillary
+        if args.raster:
+            anc = read_ascii_grid(args.raster)
+        else:
+            anc = read_geojson(args.landcover)
+        kw: Dict[str, Any] = {"class_field": args.class_field, "backend": args.backend}
+        if args.inhabited:
+            res = binary_dasymetric(sources, targets, anc, ext, _split(args.inhabited), **kw)
+        elif args.density:
+            res = dasymetric(
+                sources,
+                targets,
+                anc,
+                ext,
+                densities=_pairs(args.density, "--density"),
+                default_weight=args.default_weight,
+                **kw,
+            )
+        elif args.percent:
+            res = dasymetric(
+                sources,
+                targets,
+                anc,
+                ext,
+                percentages=_pairs(args.percent, "--percent"),
+                default_weight=args.default_weight,
+                **kw,
+            )
+        else:
+            est = estimate_class_densities(
+                sources,
+                anc,
+                ext[0],
+                threshold=args.threshold,
+                presets=_pairs(args.preset, "--preset"),
+                **kw,
+            )
+            for c, d in est.densities.items():
+                print(
+                    f"density {c}: {d:.6g} ({est.origin[c]}, n={est.sampled[c]})", file=sys.stderr
+                )
+            res = dasymetric(sources, targets, anc, ext, densities=est.densities, **kw)
+        if args.surface:
+            surf = res.details.get("surfaces", {}).get(ext[0])
+            if surf is None:
+                raise ValueError("--surface needs --raster ancillary data")
+            write_ascii_grid(args.surface, surf)
+    else:  # pycno
+        kw = {
+            "max_iter": args.max_iter,
+            "tolerance": args.tolerance,
+            "relaxation": args.relaxation,
+            "boundary": args.boundary,
+        }
+        if targets is None:
+            pr = pycnophylactic(sources, ext[0], args.cell_size, **kw)
+            if not args.surface:
+                raise ValueError("pycno without target zones needs --surface")
+            write_ascii_grid(args.surface, pr.surface)
+            print(
+                f"pycnophylactic: {pr.iterations} iterations, converged={pr.converged}; "
+                f"{pr.volume}",
+                file=sys.stderr,
+            )
+            return 0
+        res = pycnophylactic_interpolate(sources, targets, ext, args.cell_size, **kw)
+        if args.surface:
+            write_ascii_grid(args.surface, res.details["pycno"][ext[0]].surface)
+    _write_result(res, targets, args)
+    return 0