odflows 0.1.0__py3-none-any.whl

odflows/__init__.py

@@ -0,0 +1,102 @@
+"""odflows: origin-destination flow toolkit for mobility and commuting analysis.
+
+Quick start::
+
+    from odflows import ODMatrix, desire_lines, intramax, zone_summary
+
+    od = ODMatrix.from_long([("A", "B", 120), ("B", "A", 40), ("A", "A", 300)])
+    print(zone_summary(od))
+    fc = desire_lines(od, {"A": (0.0, 0.0), "B": (1000.0, 0.0)}, style="curved")
+"""
+
+from ._version import __version__
+from .clustering import (
+    FlowSet,
+    bundle_flows,
+    flow_dbscan,
+    flow_distance_matrix,
+    flow_neighbour_counts,
+    hierarchical_clusters,
+)
+from .errors import MissingDependencyError, ODFlowsError
+from .filtering import (
+    dominant_flows,
+    filter_cumulative,
+    filter_min_flow,
+    filter_share,
+    filter_top_k,
+)
+from .indicators import (
+    degree,
+    job_ratio,
+    matrix_summary,
+    net_balance,
+    self_containment,
+    zone_summary,
+)
+from .io import (
+    centroids_from_geojson,
+    geometry_centroid,
+    load_geojson,
+    read_centroids_csv,
+    read_matrix_csv,
+    read_od_csv,
+    write_flowmap_blue,
+    write_geojson,
+    write_kepler_csv,
+    write_matrix_csv,
+    write_od_csv,
+)
+from .lines import desire_lines, euclidean, haversine_km, line_coordinates
+from .matrix import ODMatrix
+from .pandas_ext import from_dataframe, to_dataframe
+from .regions import IntramaxResult, MergeStep, intramax, region_summary
+from .zones import ZoneLookup, aggregate, reaggregate
+
+__all__ = [
+    "FlowSet",
+    "IntramaxResult",
+    "MergeStep",
+    "MissingDependencyError",
+    "ODFlowsError",
+    "ODMatrix",
+    "ZoneLookup",
+    "__version__",
+    "aggregate",
+    "bundle_flows",
+    "centroids_from_geojson",
+    "degree",
+    "desire_lines",
+    "dominant_flows",
+    "euclidean",
+    "filter_cumulative",
+    "filter_min_flow",
+    "filter_share",
+    "filter_top_k",
+    "flow_dbscan",
+    "flow_distance_matrix",
+    "flow_neighbour_counts",
+    "from_dataframe",
+    "geometry_centroid",
+    "haversine_km",
+    "hierarchical_clusters",
+    "intramax",
+    "job_ratio",
+    "line_coordinates",
+    "load_geojson",
+    "matrix_summary",
+    "net_balance",
+    "read_centroids_csv",
+    "read_matrix_csv",
+    "read_od_csv",
+    "reaggregate",
+    "region_summary",
+    "self_containment",
+    "to_dataframe",
+    "write_flowmap_blue",
+    "write_geojson",
+    "write_kepler_csv",
+    "write_matrix_csv",
+    "write_od_csv",
+    "zone_summary",
+]

odflows/__main__.py

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

odflows/_version.py

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

odflows/cli.py

@@ -0,0 +1,340 @@
+"""Command-line interface: ``odflows summary | lines | filter | transform | aggregate |
+regions | cluster | export``."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence
+
+from ._version import __version__
+from .clustering import (
+    FlowSet,
+    bundle_flows,
+    flow_dbscan,
+    flow_distance_matrix,
+    hierarchical_clusters,
+)
+from .errors import MissingDependencyError, ODFlowsError
+from .filtering import filter_cumulative, filter_min_flow, filter_share, filter_top_k
+from .indicators import matrix_summary, zone_summary
+from .io import (
+    Centroids,
+    centroids_from_geojson,
+    read_centroids_csv,
+    read_matrix_csv,
+    read_od_csv,
+    write_flowmap_blue,
+    write_geojson,
+    write_kepler_csv,
+    write_matrix_csv,
+    write_od_csv,
+)
+from .lines import desire_lines
+from .matrix import ODMatrix
+from .regions import intramax, region_summary
+from .zones import ZoneLookup, reaggregate
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_USAGE = 2
+
+
+def _add_input(p: argparse.ArgumentParser) -> None:
+    p.add_argument("input", help="OD table (CSV, long form unless --matrix)")
+    p.add_argument("--matrix", action="store_true", help="input is a square matrix CSV")
+    p.add_argument("--origin-col", default="origin", help="origin column (long form)")
+    p.add_argument("--dest-col", default="destination", help="destination column (long form)")
+    p.add_argument("--flow-col", default="flow", help="flow column (long form)")
+    p.add_argument("--delimiter", default=None, help="CSV delimiter (default: sniffed)")
+
+
+def _add_centroids(p: argparse.ArgumentParser) -> None:
+    p.add_argument(
+        "--centroids", required=True, help="zones as GeoJSON (points or polygons) or CSV"
+    )
+    p.add_argument("--id-field", default=None, help="zone id property / CSV column")
+    p.add_argument("--x-col", default="lon", help="x column of a centroid CSV")
+    p.add_argument("--y-col", default="lat", help="y column of a centroid CSV")
+
+
+def _read_od(args: argparse.Namespace) -> ODMatrix:
+    if args.matrix:
+        return read_matrix_csv(args.input, delimiter=args.delimiter)
+    return read_od_csv(
+        args.input,
+        origin=args.origin_col,
+        destination=args.dest_col,
+        flow=args.flow_col,
+        delimiter=args.delimiter,
+    )
+
+
+def _read_centroids(args: argparse.Namespace) -> Centroids:
+    path = Path(args.centroids)
+    if path.suffix.lower() in (".csv", ".txt", ".tsv"):
+        return read_centroids_csv(
+            path, id_col=args.id_field or "id", x_col=args.x_col, y_col=args.y_col
+        )
+    return centroids_from_geojson(path, id_field=args.id_field)
+
+
+def _write_rows(rows: List[Dict[str, Any]], out: Optional[str]) -> None:
+    if not rows:
+        return
+    fh = open(out, "w", encoding="utf-8", newline="") if out else sys.stdout
+    try:
+        w = csv.DictWriter(fh, fieldnames=list(rows[0]), lineterminator="\n")
+        w.writeheader()
+        for r in rows:
+            w.writerow({k: (f"{v:.6g}" if isinstance(v, float) else v) for k, v in r.items()})
+    finally:
+        if out:
+            fh.close()
+
+
+def _write_od(od: ODMatrix, args: argparse.Namespace) -> None:
+    if getattr(args, "output_matrix", False):
+        write_matrix_csv(od, args.output)
+    else:
+        write_od_csv(od, args.output)
+
+
+def _cmd_summary(args: argparse.Namespace) -> int:
+    od = _read_od(args)
+    if args.json:
+        print(json.dumps(matrix_summary(od), indent=2))
+    else:
+        _write_rows(zone_summary(od), args.output)
+    return EXIT_OK
+
+
+def _cmd_lines(args: argparse.Namespace) -> int:
+    od = _read_od(args)
+    fc = desire_lines(
+        od,
+        _read_centroids(args),
+        min_flow=args.min_flow,
+        flows=args.flows,
+        style=args.style,
+        bend=args.bend,
+    )
+    write_geojson(fc, args.output)
+    print(f"{len(fc['features'])} desire lines -> {args.output}", file=sys.stderr)
+    return EXIT_OK
+
+
+def _cmd_filter(args: argparse.Namespace) -> int:
+    od = _read_od(args)
+    chosen = [x is not None for x in (args.top_k, args.min_flow, args.min_share, args.cumulative)]
+    if sum(chosen) != 1:
+        raise ODFlowsError("give exactly one of --top-k, --min-flow, --min-share, --cumulative")
+    keep_diag = args.include_intrazonal
+    if args.top_k is not None:
+        res = filter_top_k(od, args.top_k, include_intrazonal=keep_diag)
+    elif args.min_flow is not None:
+        res = filter_min_flow(od, args.min_flow, include_intrazonal=keep_diag)
+    elif args.min_share is not None:
+        res = filter_share(od, args.min_share, basis=args.basis, include_intrazonal=keep_diag)
+    else:
+        res = filter_cumulative(od, args.cumulative, include_intrazonal=keep_diag)
+    if args.drop_intrazonal:
+        res = res.without_intrazonal()
+    _write_od(res, args)
+    return EXIT_OK
+
+
+def _cmd_transform(args: argparse.Namespace) -> int:
+    od = _read_od(args)
+    ops = {
+        "net": od.net,
+        "gross": od.gross,
+        "symmetric": od.symmetric,
+        "transpose": od.transpose,
+        "no-intrazonal": od.without_intrazonal,
+    }
+    res = ops[args.op]()
+    if args.op == "gross" and not args.output_matrix:
+        with open(args.output, "w", encoding="utf-8", newline="") as fh:
+            w = csv.writer(fh, lineterminator="\n")
+            w.writerow(["origin", "destination", "flow"])
+            for o, d, f in res.iter_flows(upper_triangle=True):
+                w.writerow([o, d, f"{f:g}"])
+        return EXIT_OK
+    _write_od(res, args)
+    return EXIT_OK
+
+
+def _cmd_aggregate(args: argparse.Namespace) -> int:
+    od = _read_od(args)
+    lookup = ZoneLookup.from_csv(
+        args.lookup, source=args.source_col, target=args.target_col, weight=args.weight_col
+    )
+    _write_od(reaggregate(od, lookup), args)
+    return EXIT_OK
+
+
+def _cmd_regions(args: argparse.Namespace) -> int:
+    od = _read_od(args)
+    adjacency: Optional[Dict[str, List[str]]] = None
+    if args.adjacency:
+        adjacency = {}
+        with open(args.adjacency, encoding="utf-8-sig", newline="") as fh:
+            for row in csv.reader(fh):
+                if len(row) >= 2 and row[0].strip() and row[0].strip().lower() != "zone":
+                    adjacency.setdefault(row[0].strip(), []).append(row[1].strip())
+    res = intramax(od, adjacency=adjacency, stop_at=args.n_regions)
+    if res.min_regions > args.n_regions:
+        print(
+            f"warning: stopped at {res.min_regions} regions (no linked pairs left)",
+            file=sys.stderr,
+        )
+    member = res.membership(args.n_regions)
+    _write_rows([{"zone": z, "region": r} for z, r in member.items()], args.output)
+    if args.summary:
+        _write_rows(region_summary(od, member), args.summary)
+    return EXIT_OK
+
+
+def _cmd_cluster(args: argparse.Namespace) -> int:
+    od = _read_od(args)
+    flows = FlowSet.from_od(od, _read_centroids(args), min_flow=args.min_flow)
+    dist = flow_distance_matrix(
+        flows, alpha=args.alpha, beta=2.0 - args.alpha, normalized=args.normalized
+    )
+    if args.method == "dbscan":
+        if args.eps is None:
+            raise ODFlowsError("--eps is required for dbscan")
+        labels = flow_dbscan(
+            dist, args.eps, args.min_samples, weights=flows.weights if args.weighted else None
+        )
+    else:
+        labels = hierarchical_clusters(
+            dist, n_clusters=args.n_clusters, threshold=args.eps, linkage=args.linkage
+        )
+    fc = bundle_flows(flows, labels, include_noise=args.include_noise)
+    write_geojson(fc, args.output)
+    print(f"{len(flows)} flows -> {len(fc['features'])} bundles -> {args.output}", file=sys.stderr)
+    return EXIT_OK
+
+
+def _cmd_export(args: argparse.Namespace) -> int:
+    od = _read_od(args)
+    cents = _read_centroids(args)
+    if args.format == "flowmap":
+        base = Path(args.output)
+        stem = base.with_suffix("") if base.suffix.lower() == ".csv" else base
+        loc = Path(f"{stem}-locations.csv")
+        flo = Path(f"{stem}-flows.csv")
+        write_flowmap_blue(od, cents, loc, flo)
+        print(f"wrote {loc} and {flo}", file=sys.stderr)
+    elif args.format == "kepler":
+        write_kepler_csv(od, cents, args.output)
+    else:
+        write_geojson(desire_lines(od, cents), args.output)
+    return EXIT_OK
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """The ``odflows`` argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="odflows", description="Origin-destination flow toolkit for mobility and commuting."
+    )
+    parser.add_argument("--version", action="version", version=f"odflows {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("summary", help="per-zone indicators (CSV) or matrix statistics (--json)")
+    _add_input(p)
+    p.add_argument("-o", "--output", help="output CSV (default: stdout)")
+    p.add_argument("--json", action="store_true", help="print matrix-level statistics as JSON")
+    p.set_defaults(func=_cmd_summary)
+
+    p = sub.add_parser("lines", help="desire lines as GeoJSON")
+    _add_input(p)
+    _add_centroids(p)
+    p.add_argument("-o", "--output", required=True)
+    p.add_argument("--flows", choices=["directed", "net", "gross"], default="directed")
+    p.add_argument("--style", choices=["straight", "curved", "offset"], default="straight")
+    p.add_argument("--bend", type=float, default=0.15, help="curvature / offset (x length)")
+    p.add_argument("--min-flow", type=float, default=0.0)
+    p.set_defaults(func=_cmd_lines)
+
+    p = sub.add_parser("filter", help="keep the important flows")
+    _add_input(p)
+    p.add_argument("-o", "--output", required=True)
+    p.add_argument("--output-matrix", action="store_true", help="write a square matrix")
+    p.add_argument("--top-k", type=int)
+    p.add_argument("--min-flow", type=float)
+    p.add_argument("--min-share", type=float)
+    p.add_argument(
+        "--basis", choices=["origin", "destination", "either", "total"], default="origin"
+    )
+    p.add_argument("--cumulative", type=float, help="keep flows carrying this share of total")
+    p.add_argument(
+        "--include-intrazonal", action="store_true", help="let intrazonal flows compete too"
+    )
+    p.add_argument("--drop-intrazonal", action="store_true", help="remove intrazonal flows")
+    p.set_defaults(func=_cmd_filter)
+
+    p = sub.add_parser("transform", help="net, gross, symmetric, transpose, no-intrazonal")
+    _add_input(p)
+    p.add_argument("op", choices=["net", "gross", "symmetric", "transpose", "no-intrazonal"])
+    p.add_argument("-o", "--output", required=True)
+    p.add_argument("--output-matrix", action="store_true")
+    p.set_defaults(func=_cmd_transform)
+
+    p = sub.add_parser("aggregate", help="move flows to another zone system via a lookup")
+    _add_input(p)
+    p.add_argument("--lookup", required=True, help="CSV source,target[,weight]")
+    p.add_argument("--source-col", default="source")
+    p.add_argument("--target-col", default="target")
+    p.add_argument("--weight-col", default="weight")
+    p.add_argument("-o", "--output", required=True)
+    p.add_argument("--output-matrix", action="store_true")
+    p.set_defaults(func=_cmd_aggregate)
+
+    p = sub.add_parser("regions", help="functional regions with Intramax")
+    _add_input(p)
+    p.add_argument("-n", "--n-regions", type=int, required=True)
+    p.add_argument("--adjacency", help="CSV of zone,neighbour pairs (contiguity constraint)")
+    p.add_argument("-o", "--output", help="zone,region CSV (default: stdout)")
+    p.add_argument("--summary", help="also write per-region self-containment CSV")
+    p.set_defaults(func=_cmd_regions)
+
+    p = sub.add_parser("cluster", help="cluster similar flows and bundle them")
+    _add_input(p)
+    _add_centroids(p)
+    p.add_argument("-o", "--output", required=True, help="bundled flows GeoJSON")
+    p.add_argument("--method", choices=["hierarchical", "dbscan"], default="hierarchical")
+    p.add_argument("--n-clusters", type=int)
+    p.add_argument("--eps", type=float, help="distance threshold (hierarchical) / eps (dbscan)")
+    p.add_argument("--min-samples", type=float, default=2)
+    p.add_argument("--weighted", action="store_true", help="dbscan: count volume, not flows")
+    p.add_argument("--linkage", choices=["single", "complete", "average"], default="average")
+    p.add_argument("--alpha", type=float, default=1.0, help="origin weight (beta = 2 - alpha)")
+    p.add_argument("--normalized", action="store_true", help="use length-normalised FDS")
+    p.add_argument("--min-flow", type=float, default=0.0)
+    p.add_argument("--include-noise", action="store_true")
+    p.set_defaults(func=_cmd_cluster)
+
+    p = sub.add_parser("export", help="flowmap.blue CSVs, kepler.gl CSV or GeoJSON")
+    _add_input(p)
+    _add_centroids(p)
+    p.add_argument("--format", choices=["flowmap", "kepler", "geojson"], required=True)
+    p.add_argument("-o", "--output", required=True, help="file (flowmap: prefix)")
+    p.set_defaults(func=_cmd_export)
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """Entry point for the ``odflows`` command."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args))
+    except (ODFlowsError, MissingDependencyError, OSError) as exc:
+        print(f"odflows: error: {exc}", file=sys.stderr)
+        return EXIT_ERROR