spatialsample 0.1.0__py3-none-any.whl

spatialsample/cli.py

@@ -0,0 +1,184 @@
+"""Command-line interface: ``spatialsample <command> ...``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, List, Optional, Sequence
+
+from . import __version__
+from .accuracy import olofsson, sample_size
+from .balance import compare_designs, spatial_balance
+from .bas import bas
+from .designs import poisson_disk, srs, stratified, systematic
+from .grts import grts
+from .io import read_matrix_csv, read_points, read_region, read_strata
+from .lpm import lpm
+from .sample import Sample
+
+
+def _floats(s: str) -> List[float]:
+    return [float(v) for v in s.replace(";", ",").split(",") if v.strip()]
+
+
+def _write(sample: Sample, out: Optional[str], lines: bool = False) -> None:
+    if out is None:
+        json.dump(sample.to_geojson(include_lines=lines), sys.stdout)
+        sys.stdout.write("\n")
+        return
+    if out.lower().endswith(".csv"):
+        sample.to_csv(out)
+    else:
+        sample.to_geojson(out, include_lines=lines)
+    nb = len(sample.base())
+    print(f"{sample.design}: {nb} base + {len(sample) - nb} over sites -> {out}", file=sys.stderr)
+
+
+def _common(p: argparse.ArgumentParser, over: bool = False) -> None:
+    p.add_argument("area", help="polygon GeoJSON file (projected coordinates)")
+    p.add_argument("--n", type=int, required=True, help="base sample size")
+    if over:
+        p.add_argument("--over", type=int, default=0, help="oversample (replacement) sites")
+    p.add_argument("--seed", type=int, default=None, help="random seed")
+    p.add_argument("-o", "--output", default=None, help="output .geojson or .csv (default: stdout)")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(
+        prog="spatialsample",
+        description="Design-based spatial sampling: GRTS, BAS, LPM, stratified, "
+        "systematic designs, spatial balance and map accuracy assessment.",
+    )
+    ap.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = ap.add_subparsers(dest="command", required=True)
+
+    _common(sub.add_parser("srs", help="simple random sample"))
+    p = sub.add_parser("systematic", help="systematic square or hexagonal grid")
+    _common(p)
+    p.add_argument("--shape", choices=["square", "hex"], default="square")
+    p.add_argument("--random-rotation", action="store_true")
+    _common(sub.add_parser("grts", help="GRTS spatially balanced sample"), over=True)
+    _common(sub.add_parser("bas", help="balanced acceptance sample (Halton)"), over=True)
+    p = sub.add_parser("lpm", help="local pivotal method")
+    _common(p)
+    p.add_argument("--frame-size", type=int, default=None)
+    p = sub.add_parser("poisson", help="minimum-distance (Poisson-disk) sample")
+    _common(p)
+    p.add_argument("--min-dist", type=float, default=None)
+    p = sub.add_parser("stratified", help="stratified sample by a polygon attribute")
+    _common(p)
+    p.add_argument("--field", required=True, help="property holding the stratum label")
+    p.add_argument("--allocation", choices=["proportional", "equal"], default="proportional")
+    p.add_argument("--method", choices=["srs", "bas", "grts", "lpm"], default="srs")
+
+    p = sub.add_parser("balance", help="Voronoi spatial balance of a set of sites")
+    p.add_argument("sites", help="sites (GeoJSON points or CSV with x,y)")
+    p.add_argument("--frame", required=True, help="polygon GeoJSON of the sampled area")
+    p.add_argument("--frame-size", type=int, default=20000)
+    p.add_argument("--all-sites", action="store_true", help="include oversample sites")
+    p.add_argument("--json", action="store_true")
+
+    p = sub.add_parser("compare", help="compare the spatial balance of designs")
+    p.add_argument("area")
+    p.add_argument("--n", type=int, required=True)
+    p.add_argument("--reps", type=int, default=20)
+    p.add_argument("--seed", type=int, default=0)
+    p.add_argument("--json", action="store_true")
+
+    p = sub.add_parser("olofsson", help="accuracy and area estimates from an error matrix")
+    p.add_argument("matrix", help="CSV of sample counts (rows map, columns reference)")
+    p.add_argument(
+        "--areas", required=True, help="mapped area/pixels per map class, comma separated"
+    )
+    p.add_argument(
+        "--pixel-area", type=float, default=1.0, help="multiply areas by this (e.g. 0.09 ha)"
+    )
+    p.add_argument("--labels", default=None, help="comma-separated class names")
+    p.add_argument("--conf", type=float, default=0.95)
+    p.add_argument("--json", action="store_true")
+
+    p = sub.add_parser("samplesize", help="sample size for a target SE of overall accuracy")
+    p.add_argument("--areas", required=True)
+    p.add_argument("--users", required=True, help="conjectured user's accuracies")
+    p.add_argument("--target-se", type=float, default=0.01)
+    return ap
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    cmd = args.command
+    try:
+        return _run(cmd, args)
+    except (ValueError, KeyError, OSError) as exc:
+        print(f"spatialsample {cmd}: error: {exc}", file=sys.stderr)
+        return 2
+
+
+def _run(cmd: str, args: Any) -> int:
+    if cmd in ("srs", "systematic", "grts", "bas", "lpm", "poisson", "stratified"):
+        if cmd == "stratified":
+            strata = read_strata(args.area, args.field)
+            s = stratified(
+                strata, args.n, allocation=args.allocation, method=args.method, seed=args.seed
+            )
+        else:
+            region = read_region(args.area)
+            if cmd == "srs":
+                s = srs(region, args.n, seed=args.seed)
+            elif cmd == "systematic":
+                rot = "random" if args.random_rotation else 0.0
+                s = systematic(region, args.n, shape=args.shape, rotation=rot, seed=args.seed)
+            elif cmd == "grts":
+                s = grts(region, args.n, n_over=args.over, seed=args.seed)
+            elif cmd == "bas":
+                s = bas(region, args.n, n_over=args.over, seed=args.seed)
+            elif cmd == "lpm":
+                s = lpm(region, args.n, frame_size=args.frame_size, seed=args.seed)
+            else:
+                s = poisson_disk(region, args.n, min_dist=args.min_dist, seed=args.seed)
+        _write(s, args.output)
+        return 0
+    if cmd == "balance":
+        xy, props = read_points(args.sites)
+        if not args.all_sites and props and any("site_type" in p for p in props):
+            keep = [i for i, p in enumerate(props) if p.get("site_type", "base") == "base"]
+            xy = xy[keep]
+        res = spatial_balance(xy, domain=read_region(args.frame), frame_size=args.frame_size)
+        if args.json:
+            print(
+                json.dumps(
+                    {"n": res.n, "voronoi_balance": res.value, "max_deviation": res.max_deviation}
+                )
+            )
+        else:
+            print(f"sites: {res.n}")
+            print(f"Voronoi spatial balance (lower is better): {res.value:.4f}")
+            print(f"largest |v_i - 1|: {res.max_deviation:.4f}")
+        return 0
+    if cmd == "compare":
+        cmp = compare_designs(read_region(args.area), args.n, reps=args.reps, seed=args.seed)
+        if args.json:
+            print(json.dumps(cmp, indent=2))
+        else:
+            print(f"{'design':<20}{'balance':>10}{'sd':>10}{'mean n':>10}")
+            for k, v in sorted(cmp.items(), key=lambda kv: kv[1]["mean"]):
+                print(f"{k:<20}{v['mean']:>10.4f}{v['sd']:>10.4f}{v['mean_n']:>10.1f}")
+        return 0
+    if cmd == "olofsson":
+        mat, labels = read_matrix_csv(args.matrix)
+        if args.labels:
+            labels = [s.strip() for s in args.labels.split(",")]
+        areas = [a * args.pixel_area for a in _floats(args.areas)]
+        acc = olofsson(mat, areas, labels=labels, conf=args.conf)
+        print(json.dumps(acc.as_dict(), indent=2) if args.json else acc.summary())
+        return 0
+    if cmd == "samplesize":
+        n = sample_size(_floats(args.areas), _floats(args.users), args.target_se)
+        print(n)
+        return 0
+    raise AssertionError(cmd)  # pragma: no cover
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())