nkde 0.1.0__py3-none-any.whl

nkde/__init__.py

@@ -0,0 +1,56 @@
+"""nkde: network kernel density estimation along street networks.
+
+Estimate the density of events (crashes, crimes, shops, ...) *along* a street
+network rather than across the plane: lixelisation, event snapping, the simple,
+discontinuous and continuous network KDE of Okabe & Sugihara, adaptive
+bandwidths, spatio-temporal TNKDE, planar KDE for comparison, the network
+K-function and hot-spot ranking.
+"""
+
+from .estimators import METHODS, NKDEResult, abramson_bandwidths, event_kernel, nkde
+from .hotspots import HotspotRanking, hotspot_clusters, monte_carlo_pvalues, rank_hotspots
+from .io import (
+    events_from_geojson,
+    network_from_geojson,
+    read_lines,
+    read_points,
+    result_to_geojson,
+)
+from .kernels import KERNELS, get_kernel
+from .kfunction import KFunctionResult, network_k_function, pairwise_network_distances
+from .network import Events, Lixels, Network
+from .planar import planar_kde
+from .projection import UTMZone, lonlat_to_utm, utm_to_lonlat, utm_transformers
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "KERNELS",
+    "METHODS",
+    "Events",
+    "HotspotRanking",
+    "KFunctionResult",
+    "Lixels",
+    "NKDEResult",
+    "Network",
+    "UTMZone",
+    "__version__",
+    "abramson_bandwidths",
+    "event_kernel",
+    "events_from_geojson",
+    "get_kernel",
+    "hotspot_clusters",
+    "lonlat_to_utm",
+    "monte_carlo_pvalues",
+    "network_from_geojson",
+    "network_k_function",
+    "nkde",
+    "pairwise_network_distances",
+    "planar_kde",
+    "rank_hotspots",
+    "read_lines",
+    "read_points",
+    "result_to_geojson",
+    "utm_to_lonlat",
+    "utm_transformers",
+]

nkde/__main__.py

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

nkde/cli.py

@@ -0,0 +1,225 @@
+"""Command line interface: ``nkde run`` and ``nkde kfunction``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from typing import List, Optional, Sequence
+
+import numpy as np
+
+from . import __version__
+from .estimators import METHODS, nkde
+from .hotspots import rank_hotspots
+from .io import network_from_geojson, read_lines, read_points
+from .kernels import KERNELS
+from .kfunction import network_k_function
+from .projection import utm_transformers
+
+
+def _parse_times(text: str) -> np.ndarray:
+    """``start:stop:step`` (stop inclusive) or a comma separated list."""
+    if ":" in text:
+        parts = [float(p) for p in text.split(":")]
+        if len(parts) != 3 or parts[2] <= 0:
+            raise argparse.ArgumentTypeError("use start:stop:step with a positive step")
+        start, stop, step = parts
+        n = int(np.floor((stop - start) / step + 1e-9)) + 1
+        return start + step * np.arange(max(n, 1))
+    return np.array([float(p) for p in text.split(",") if p.strip()])
+
+
+def _load(args: argparse.Namespace):  # type: ignore[no-untyped-def]
+    forward = inverse = None
+    if args.lonlat:
+        lines, _ = read_lines(args.roads)
+        allc = np.vstack(lines)
+        forward, inverse, zone = utm_transformers(allc[:, 0], allc[:, 1])
+        print(
+            f"projected to UTM zone {zone.zone}{'S' if zone.south else 'N'} (EPSG:{zone.epsg})",
+            file=sys.stderr,
+        )
+    net = network_from_geojson(
+        args.roads,
+        transform=forward,
+        id_field=args.id_field,
+        split_at_intersections=args.split_crossings,
+    )
+    xy, t, w, _ = read_points(
+        args.events,
+        forward,
+        time_field=getattr(args, "time_field", None),
+        weight_field=getattr(args, "weight_field", None),
+    )
+    events = net.snap(xy, times=t, weights=w, max_distance=args.max_snap)
+    dropped = len(xy) - len(events)
+    print(
+        f"network: {net.n_nodes} nodes, {net.n_edges} edges, {net.total_length:.1f} m; "
+        f"events: {len(events)} snapped"
+        + (f", {dropped} dropped (> --max-snap)" if dropped else ""),
+        file=sys.stderr,
+    )
+    return net, events, inverse
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    net, events, inverse = _load(args)
+    if len(events) == 0:
+        print("error: no events left after snapping", file=sys.stderr)
+        return 2
+    times = None
+    if args.times is not None:
+        times = _parse_times(args.times)
+    t0 = time.perf_counter()
+    res = nkde(
+        net,
+        events,
+        args.bw,
+        lixel_length=args.lixel,
+        kernel=args.kernel,
+        method=args.method,
+        adaptive=args.adaptive,
+        trim_bw=args.trim_bw,
+        max_depth=args.max_depth,
+        times=times,
+        time_bw=args.time_bw,
+    )
+    elapsed = time.perf_counter() - t0
+    res.to_geojson(args.output, inverse_transform=inverse, precision=args.precision)
+    print(
+        f"{args.method} NKDE ({args.kernel}, bw={args.bw:g} m"
+        f"{', adaptive' if args.adaptive else ''}) on {len(res.lixels)} lixels "
+        f"in {elapsed:.2f} s -> {args.output}",
+        file=sys.stderr,
+    )
+    if args.top:
+        rk = rank_hotspots(res, top=args.top)
+        print("rank\tlixel\tedge\tdensity")
+        for r, li, d in zip(rk.rank.tolist(), rk.lixel.tolist(), rk.density.tolist()):
+            print(f"{r}\t{li}\t{int(res.lixels.edge[li])}\t{d:.6g}")
+    return 0
+
+
+def _cmd_kfunction(args: argparse.Namespace) -> int:
+    net, events, _ = _load(args)
+    t = np.arange(args.step, args.tmax + 1e-9, args.step)
+    res = network_k_function(net, events, t, n_simulations=args.nsim, seed=args.seed)
+    rows = []
+    for i in range(len(t)):
+        row = {"t": float(t[i]), "k": float(res.k[i])}
+        if res.lower is not None and res.upper is not None and res.mean is not None:
+            row.update(
+                lower=float(res.lower[i]), upper=float(res.upper[i]), mean=float(res.mean[i])
+            )
+        rows.append(row)
+    text: str
+    if args.output and args.output.lower().endswith(".json"):
+        text = json.dumps(rows, indent=1)
+    else:
+        cols = list(rows[0].keys())
+        text = "\n".join([",".join(cols)] + [",".join(f"{r[c]:.6g}" for c in cols) for r in rows])
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as fh:
+            fh.write(text + "\n")
+        print(f"K-function at {len(t)} distances -> {args.output}", file=sys.stderr)
+    else:
+        print(text)
+    return 0
+
+
+def _common(p: argparse.ArgumentParser) -> None:
+    p.add_argument("roads", help="GeoJSON line layer (projected metres unless --lonlat)")
+    p.add_argument("events", help="GeoJSON point layer")
+    p.add_argument(
+        "--lonlat",
+        action="store_true",
+        help="inputs are WGS84 lon/lat: project to UTM (output written back in lon/lat)",
+    )
+    p.add_argument(
+        "--max-snap",
+        type=float,
+        default=None,
+        help="drop events farther than this from the network (m)",
+    )
+    p.add_argument(
+        "--id-field", default=None, help="road property copied to the output as source_id"
+    )
+    p.add_argument(
+        "--split-crossings",
+        action="store_true",
+        help="planarise: add junctions where road lines cross without a shared vertex",
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="nkde", description="Network kernel density estimation along street networks."
+    )
+    parser.add_argument("--version", action="version", version=f"nkde {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    run = sub.add_parser("run", help="compute a (temporal) network KDE on lixels")
+    _common(run)
+    run.add_argument("--bw", type=float, required=True, help="bandwidth in metres")
+    run.add_argument(
+        "--lixel", type=float, default=10.0, help="lixel length in metres (default 10)"
+    )
+    run.add_argument("--method", choices=METHODS, default="continuous")
+    run.add_argument("--kernel", choices=KERNELS, default="quartic")
+    run.add_argument("--adaptive", action="store_true", help="Abramson adaptive bandwidths")
+    run.add_argument(
+        "--trim-bw", type=float, default=None, help="cap for adaptive bandwidths (default 3*bw)"
+    )
+    run.add_argument("--max-depth", type=int, default=None, help="max junctions crossed per branch")
+    run.add_argument("--weight-field", default=None, help="event property holding weights")
+    run.add_argument(
+        "--time-field", default=None, help="event property holding times (number or ISO date)"
+    )
+    run.add_argument(
+        "--time-bw",
+        type=float,
+        default=None,
+        help="temporal bandwidth (same unit as times; days for ISO dates)",
+    )
+    run.add_argument(
+        "--times", default=None, help="evaluation times: start:stop:step or comma list"
+    )
+    run.add_argument("--precision", type=int, default=3, help="decimals of output coordinates")
+    run.add_argument("--top", type=int, default=0, help="print the N highest-density lixels")
+    run.add_argument("-o", "--output", required=True, help="output GeoJSON path")
+    run.set_defaults(func=_cmd_run)
+
+    kf = sub.add_parser("kfunction", help="global network K-function with CSR envelopes")
+    _common(kf)
+    kf.add_argument("--tmax", type=float, required=True, help="largest distance (m)")
+    kf.add_argument("--step", type=float, required=True, help="distance step (m)")
+    kf.add_argument("--nsim", type=int, default=99, help="number of CSR simulations")
+    kf.add_argument("--seed", type=int, default=None)
+    kf.add_argument("-o", "--output", default=None, help="CSV or .json path (stdout if omitted)")
+    kf.set_defaults(func=_cmd_kfunction)
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(list(argv) if argv is not None else None)
+    if args.command == "run":
+        if (args.times is None) != (args.time_field is None) or (
+            args.times is not None and args.time_bw is None
+        ):
+            parser.error("temporal NKDE needs --time-field, --times and --time-bw together")
+    try:
+        code: int = args.func(args)
+    except (ValueError, OSError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    return code
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())
+
+
+__all__: List[str] = ["main", "build_parser"]