odflows 0.1.0__py3-none-any.whl

odflows/clustering.py

@@ -0,0 +1,286 @@
+"""Flow similarity, clustering and bundling (pure numpy).
+
+A flow is treated as a point ``(x_o, y_o, x_d, y_d)`` in four dimensions. Following
+Tao & Thill (2016, "Spatial cluster detection in spatial flow data", Geographical
+Analysis 48(4), 355-372), the distance between flows ``i`` and ``j`` is
+
+.. math:: FD_{ij} = \\sqrt{\\alpha\\,d_O^2 + \\beta\\,d_D^2}
+
+with ``d_O`` / ``d_D`` the distances between their origins / destinations and
+``alpha + beta = 2`` (``alpha = beta = 1`` weighs both ends equally). The
+*flow dissimilarity*
+
+.. math:: FDS_{ij} = \\sqrt{\\frac{\\alpha\\,d_O^2 + \\beta\\,d_D^2}{L_i L_j}}
+
+divides by the flow lengths ``L``, so long flows may differ more in absolute terms and
+still count as similar. Coordinates must be planar (projected); longitude/latitude
+degrees are not a distance unit.
+
+Clustering methods work on any precomputed distance matrix:
+
+* :func:`hierarchical_clusters` - agglomerative clustering with single, complete or
+  average linkage (Lance & Williams 1967 update formula), cut by distance or count;
+* :func:`flow_dbscan` - DBSCAN (Ester et al. 1996) applied to flows, optionally
+  weighting each flow by its volume when counting neighbours;
+* :func:`bundle_flows` - one representative, volume-weighted flow per cluster
+  (a simple form of flow bundling / generalisation).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Tuple, Union
+
+import numpy as np
+
+from .errors import ODFlowsError
+from .matrix import ODMatrix
+
+
+class FlowSet:
+    """Flows with endpoint coordinates: the input to the clustering functions.
+
+    Attributes: ``origins``, ``destinations`` (zone ids), ``coords`` (``n x 4`` array
+    ``x_o, y_o, x_d, y_d``) and ``weights`` (flow volumes).
+    """
+
+    __slots__ = ("origins", "destinations", "coords", "weights")
+
+    def __init__(
+        self,
+        origins: Sequence[str],
+        destinations: Sequence[str],
+        coords: object,
+        weights: object,
+    ) -> None:
+        self.origins = [str(o) for o in origins]
+        self.destinations = [str(d) for d in destinations]
+        self.coords = np.asarray(coords, dtype=float).reshape(-1, 4)
+        self.weights = np.asarray(weights, dtype=float).reshape(-1)
+        n = len(self.origins)
+        if not (len(self.destinations) == n == len(self.coords) == len(self.weights)):
+            raise ODFlowsError("origins, destinations, coords and weights differ in length")
+
+    def __len__(self) -> int:
+        return len(self.origins)
+
+    @classmethod
+    def from_od(
+        cls,
+        od: ODMatrix,
+        centroids: Mapping[str, Sequence[float]],
+        min_flow: float = 0.0,
+    ) -> FlowSet:
+        """All positive off-diagonal flows ``>= min_flow`` with their centroid coordinates."""
+        o_ids: List[str] = []
+        d_ids: List[str] = []
+        coords: List[Tuple[float, float, float, float]] = []
+        w: List[float] = []
+        for o, d, f in od.iter_flows(include_intrazonal=False):
+            if f < min_flow:
+                continue
+            if o not in centroids or d not in centroids:
+                raise ODFlowsError(f"no centroid for {o if o not in centroids else d!r}")
+            a, b = centroids[o], centroids[d]
+            o_ids.append(o)
+            d_ids.append(d)
+            coords.append((float(a[0]), float(a[1]), float(b[0]), float(b[1])))
+            w.append(f)
+        return cls(o_ids, d_ids, np.array(coords).reshape(-1, 4), w)
+
+    @property
+    def lengths(self) -> np.ndarray:
+        """Planar length of every flow."""
+        c = self.coords
+        return np.hypot(c[:, 2] - c[:, 0], c[:, 3] - c[:, 1])
+
+
+def _check_ab(alpha: float, beta: float) -> None:
+    if alpha < 0 or beta < 0 or not np.isclose(alpha + beta, 2.0):
+        raise ODFlowsError("alpha and beta must be non-negative and sum to 2")
+
+
+def flow_distance_matrix(
+    flows: FlowSet,
+    alpha: float = 1.0,
+    beta: float = 1.0,
+    normalized: bool = False,
+) -> np.ndarray:
+    """Pairwise Tao & Thill flow distance (``normalized=False``) or dissimilarity.
+
+    The dissimilarity is undefined for zero-length flows and is returned as ``inf``
+    there (except on the diagonal, which is always 0).
+    """
+    _check_ab(alpha, beta)
+    c = flows.coords
+    do2 = (c[:, None, 0] - c[None, :, 0]) ** 2 + (c[:, None, 1] - c[None, :, 1]) ** 2
+    dd2 = (c[:, None, 2] - c[None, :, 2]) ** 2 + (c[:, None, 3] - c[None, :, 3]) ** 2
+    sq = alpha * do2 + beta * dd2
+    if not normalized:
+        return np.sqrt(sq)
+    ll = np.outer(flows.lengths, flows.lengths)
+    with np.errstate(divide="ignore", invalid="ignore"):
+        out = np.where(ll > 0, np.sqrt(sq / np.where(ll > 0, ll, 1.0)), np.inf)
+    np.fill_diagonal(out, 0.0)
+    return out
+
+
+def flow_neighbour_counts(
+    distances: np.ndarray, radius: float, weights: Optional[np.ndarray] = None
+) -> np.ndarray:
+    """Number (or total weight) of *other* flows within ``radius`` of each flow.
+
+    The local counting term behind Tao & Thill's flow K-function; no edge correction or
+    significance test is applied.
+    """
+    d = np.asarray(distances, dtype=float)
+    within = d <= radius
+    np.fill_diagonal(within, False)
+    if weights is None:
+        return within.sum(axis=1).astype(float)
+    return within.astype(float) @ np.asarray(weights, dtype=float)
+
+
+def hierarchical_clusters(
+    distances: np.ndarray,
+    n_clusters: Optional[int] = None,
+    threshold: Optional[float] = None,
+    linkage: str = "average",
+) -> np.ndarray:
+    """Agglomerative clustering of a precomputed distance matrix.
+
+    Exactly one of ``n_clusters`` (stop when that many clusters remain) or ``threshold``
+    (stop when the closest pair is farther apart than this) must be given. ``linkage``
+    is ``"single"``, ``"complete"`` or ``"average"`` (UPGMA), updated with the
+    Lance-Williams formula. Returns labels ``0..k-1`` numbered by first appearance.
+    O(n^3) time - intended for up to a few thousand flows.
+    """
+    if (n_clusters is None) == (threshold is None):
+        raise ODFlowsError("give exactly one of n_clusters or threshold")
+    if linkage not in ("single", "complete", "average"):
+        raise ODFlowsError(f"unknown linkage {linkage!r}")
+    D = np.array(distances, dtype=float)
+    n = D.shape[0]
+    if D.shape != (n, n):
+        raise ODFlowsError("distances must be a square matrix")
+    if n == 0:
+        return np.zeros(0, dtype=int)
+    target = max(1, n_clusters) if n_clusters is not None else 1
+    np.fill_diagonal(D, np.inf)
+    active = np.ones(n, dtype=bool)
+    size = np.ones(n)
+    label = np.arange(n)
+    k = n
+    while k > target:
+        sub = np.where(active[:, None] & active[None, :], D, np.inf)
+        flat = int(np.argmin(sub))
+        a, b = divmod(flat, n)
+        if a > b:
+            a, b = b, a
+        dist = sub[a, b]
+        if not np.isfinite(dist) or (threshold is not None and dist > threshold):
+            break
+        if linkage == "single":
+            new = np.minimum(D[a], D[b])
+        elif linkage == "complete":
+            new = np.maximum(D[a], D[b])
+        else:
+            new = (size[a] * D[a] + size[b] * D[b]) / (size[a] + size[b])
+        D[a, :] = new
+        D[:, a] = new
+        D[a, a] = np.inf
+        active[b] = False
+        D[b, :] = np.inf
+        D[:, b] = np.inf
+        size[a] += size[b]
+        label[label == b] = a
+        k -= 1
+    _, out = np.unique(label, return_inverse=True)
+    # renumber by first appearance for stable, readable labels
+    order: Dict[int, int] = {}
+    for v in out:
+        order.setdefault(int(v), len(order))
+    return np.array([order[int(v)] for v in out], dtype=int)
+
+
+def flow_dbscan(
+    distances: np.ndarray,
+    eps: float,
+    min_samples: float = 2,
+    weights: Optional[np.ndarray] = None,
+) -> np.ndarray:
+    """DBSCAN (Ester et al. 1996) on a precomputed flow distance matrix.
+
+    A flow is a *core* flow when the flows within ``eps`` (itself included) number at
+    least ``min_samples`` - or, when ``weights`` are given, carry at least that much
+    volume (so one huge flow can be a cluster on its own). Clusters are grown from core
+    flows; non-core flows reachable from a core flow are border members; the rest are
+    noise, labelled ``-1``. Labels ``0..k-1`` follow the order of discovery.
+    """
+    d = np.asarray(distances, dtype=float)
+    n = d.shape[0]
+    neigh = d <= eps
+    w = np.ones(n) if weights is None else np.asarray(weights, dtype=float)
+    core = (neigh.astype(float) @ w) >= min_samples
+    labels = np.full(n, -1, dtype=int)
+    cluster = 0
+    for i in range(n):
+        if labels[i] != -1 or not core[i]:
+            continue
+        labels[i] = cluster
+        stack = [i]
+        while stack:
+            p = stack.pop()
+            if not core[p]:
+                continue
+            for q in np.flatnonzero(neigh[p]):
+                if labels[q] == -1:
+                    labels[q] = cluster
+                    stack.append(int(q))
+        cluster += 1
+    return labels
+
+
+def bundle_flows(
+    flows: FlowSet, labels: Union[Sequence[int], np.ndarray], include_noise: bool = False
+) -> Dict[str, Any]:
+    """One representative flow per cluster as a GeoJSON FeatureCollection.
+
+    The representative runs from the volume-weighted mean origin to the volume-weighted
+    mean destination of the cluster's member flows and carries their total ``flow``,
+    ``n_flows`` and the member ``origins`` / ``destinations``. Noise (label ``-1``) is
+    skipped unless ``include_noise``, in which case each noise flow is its own bundle.
+    """
+    lab = np.asarray(labels, dtype=int)
+    if len(lab) != len(flows):
+        raise ODFlowsError("labels and flows differ in length")
+    groups: Dict[str, List[int]] = {}
+    for i, v in enumerate(lab):
+        if v < 0:
+            if include_noise:
+                groups[f"noise-{i}"] = [i]
+            continue
+        groups.setdefault(str(int(v)), []).append(i)
+    feats: List[Dict[str, Any]] = []
+    for key, idx in groups.items():
+        w = flows.weights[idx]
+        c = flows.coords[idx]
+        ww = w if w.sum() > 0 else np.ones_like(w)
+        mean = (c * ww[:, None]).sum(axis=0) / ww.sum()
+        feats.append(
+            {
+                "type": "Feature",
+                "geometry": {
+                    "type": "LineString",
+                    "coordinates": [[mean[0], mean[1]], [mean[2], mean[3]]],
+                },
+                "properties": {
+                    "cluster": key,
+                    "flow": float(w.sum()),
+                    "n_flows": len(idx),
+                    "origins": sorted({flows.origins[i] for i in idx}),
+                    "destinations": sorted({flows.destinations[i] for i in idx}),
+                },
+            }
+        )
+    feats.sort(key=lambda f: f["properties"]["flow"])
+    return {"type": "FeatureCollection", "features": feats}

odflows/errors.py

@@ -0,0 +1,11 @@
+"""Exception hierarchy."""
+
+from __future__ import annotations
+
+
+class ODFlowsError(ValueError):
+    """Raised for invalid input data or parameters."""
+
+
+class MissingDependencyError(ImportError):
+    """Raised when an optional dependency (pandas, shapely) is needed but not installed."""

odflows/filtering.py

@@ -0,0 +1,131 @@
+"""Flow filtering: keep the flows that matter for a map or an analysis.
+
+Every filter returns a new :class:`~odflows.ODMatrix` with the same zones in which the
+discarded flows are set to zero, so filters can be chained.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .errors import ODFlowsError
+from .matrix import ODMatrix
+
+
+def _candidate_mask(od: ODMatrix, include_intrazonal: bool) -> np.ndarray:
+    mask = od.values > 0
+    if not include_intrazonal:
+        np.fill_diagonal(mask, False)
+    return mask
+
+
+def _apply(od: ODMatrix, keep: np.ndarray, include_intrazonal: bool) -> ODMatrix:
+    arr = np.where(keep, od.values, 0.0)
+    if not include_intrazonal:
+        # Intrazonal flows are left untouched by filters that ignore them.
+        np.fill_diagonal(arr, np.diag(od.values))
+    return od.with_values(arr)
+
+
+def filter_min_flow(od: ODMatrix, min_flow: float, include_intrazonal: bool = False) -> ODMatrix:
+    """Keep flows ``>= min_flow``.
+
+    With ``include_intrazonal=False`` (default) the diagonal is not filtered.
+    """
+    keep = _candidate_mask(od, include_intrazonal) & (od.values >= min_flow)
+    return _apply(od, keep, include_intrazonal)
+
+
+def filter_top_k(od: ODMatrix, k: int, include_intrazonal: bool = False) -> ODMatrix:
+    """Keep the ``k`` largest flows.
+
+    Ties at the cut-off are broken by matrix order (row-major), so exactly ``k`` flows
+    survive. With ``include_intrazonal=False`` (default) only off-diagonal flows compete
+    and the diagonal is kept as is.
+    """
+    if k < 0:
+        raise ODFlowsError("k must be non-negative")
+    mask = _candidate_mask(od, include_intrazonal)
+    flat_idx = np.flatnonzero(mask)
+    vals = od.values.ravel()[flat_idx]
+    order = np.argsort(-vals, kind="stable")[:k]
+    keep = np.zeros(od.values.size, dtype=bool)
+    keep[flat_idx[order]] = True
+    return _apply(od, keep.reshape(od.values.shape), include_intrazonal)
+
+
+def filter_share(
+    od: ODMatrix,
+    min_share: float,
+    basis: str = "origin",
+    include_intrazonal: bool = False,
+) -> ODMatrix:
+    """Keep flows that are at least ``min_share`` of a total.
+
+    ``basis``:
+
+    * ``"origin"`` - ``T_ij / O_i`` (share of the origin's outflow; the classic
+      "dominant flow" criterion of Nystuen & Dacey 1961 uses the largest such flow),
+    * ``"destination"`` - ``T_ij / D_j`` (share of the destination's inflow),
+    * ``"either"`` - kept if either share qualifies,
+    * ``"total"`` - ``T_ij / sum(T)``.
+
+    Totals include intrazonal flows (the usual definition of ``O_i`` and ``D_j``).
+    """
+    if not 0.0 <= min_share <= 1.0:
+        raise ODFlowsError("min_share must be between 0 and 1")
+    T = od.values
+    with np.errstate(divide="ignore", invalid="ignore"):
+        by_o = np.nan_to_num(T / T.sum(axis=1, keepdims=True))
+        by_d = np.nan_to_num(T / T.sum(axis=0, keepdims=True))
+    if basis == "origin":
+        share = by_o
+    elif basis == "destination":
+        share = by_d
+    elif basis == "either":
+        share = np.maximum(by_o, by_d)
+    elif basis == "total":
+        share = T / od.total if od.total > 0 else np.zeros_like(T)
+    else:
+        raise ODFlowsError(f"unknown basis {basis!r}")
+    keep = _candidate_mask(od, include_intrazonal) & (share >= min_share)
+    return _apply(od, keep, include_intrazonal)
+
+
+def filter_cumulative(od: ODMatrix, share: float, include_intrazonal: bool = False) -> ODMatrix:
+    """Keep the largest flows until they account for ``share`` of the total.
+
+    Flows are ranked by size; the smallest prefix whose sum reaches ``share`` of the
+    candidate total is kept (e.g. ``share=0.8``: the flows that carry 80 % of all
+    trips). With ``include_intrazonal=False`` the total is the off-diagonal total.
+    """
+    if not 0.0 <= share <= 1.0:
+        raise ODFlowsError("share must be between 0 and 1")
+    mask = _candidate_mask(od, include_intrazonal)
+    flat_idx = np.flatnonzero(mask)
+    vals = od.values.ravel()[flat_idx]
+    order = np.argsort(-vals, kind="stable")
+    total = vals.sum()
+    keep = np.zeros(od.values.size, dtype=bool)
+    if total > 0 and share > 0:
+        csum = np.cumsum(vals[order])
+        n_keep = int(np.searchsorted(csum, share * total * (1 - 1e-12), side="left")) + 1
+        keep[flat_idx[order[:n_keep]]] = True
+    return _apply(od, keep.reshape(od.values.shape), include_intrazonal)
+
+
+def dominant_flows(od: ODMatrix) -> ODMatrix:
+    """Keep, for every origin, its single largest *outgoing* (off-diagonal) flow.
+
+    The first step of Nystuen & Dacey's (1961) nodal-region analysis ("A graph theory
+    interpretation of nodal regions", Papers of the Regional Science Association 7,
+    29-42). Ties are broken by matrix order; the diagonal is kept.
+    """
+    T = od.values.copy()
+    np.fill_diagonal(T, -1.0)
+    keep = np.zeros_like(od.values, dtype=bool)
+    for i in range(od.n):
+        j = int(np.argmax(T[i]))
+        if T[i, j] > 0:
+            keep[i, j] = True
+    return _apply(od, keep, include_intrazonal=False)

odflows/indicators.py

@@ -0,0 +1,119 @@
+"""Zone-level flow indicators for commuting and mobility analysis.
+
+Conventions (commuting): rows = place of residence, columns = place of work.
+
+* ``O_i = sum_j T_ij`` - resident workers / trips produced (outflow incl. intrazonal),
+* ``D_j = sum_i T_ij`` - jobs / trips attracted (inflow incl. intrazonal),
+* ``T_ii`` - people living and working in the same zone.
+
+Self-containment follows the supply/demand definitions used for labour market areas,
+e.g. Goodman (1970), "The definition and analysis of local labour markets: some
+empirical problems", British Journal of Industrial Relations 8(2), 179-196, and
+Casado-Diaz (2000), "Local labour market areas in Spain: a case study", Regional
+Studies 34(9), 843-856:
+
+* supply-side SC = ``T_ii / O_i`` (share of resident workers who work locally),
+* demand-side SC = ``T_ii / D_i`` (share of local jobs filled by residents).
+
+Labour-market-area methods such as the UK travel-to-work areas set minimum
+self-containment thresholds; no threshold is hard-coded here (pass your own to the
+filters or check :func:`region_summary` output after :func:`odflows.intramax`).
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List
+
+import numpy as np
+
+from .matrix import ODMatrix
+
+
+def _ratio(num: np.ndarray, den: np.ndarray) -> np.ndarray:
+    with np.errstate(divide="ignore", invalid="ignore"):
+        return np.where(den > 0, num / np.where(den > 0, den, 1.0), np.nan)
+
+
+def degree(od: ODMatrix, include_intrazonal: bool = False) -> Dict[str, np.ndarray]:
+    """In/out degree (number of linked zones) and weighted degree (flow strength).
+
+    Returns ``out_degree``, ``in_degree`` (counts of non-zero links) and ``out_strength``,
+    ``in_strength`` (flow totals). Self-loops are excluded unless ``include_intrazonal``.
+    """
+    T = od.values if include_intrazonal else od.without_intrazonal().values
+    links = T > 0
+    return {
+        "out_degree": links.sum(axis=1).astype(int),
+        "in_degree": links.sum(axis=0).astype(int),
+        "out_strength": T.sum(axis=1),
+        "in_strength": T.sum(axis=0),
+    }
+
+
+def self_containment(od: ODMatrix) -> Dict[str, np.ndarray]:
+    """Supply-side (``T_ii / O_i``) and demand-side (``T_ii / D_i``) self-containment.
+
+    ``nan`` where the denominator is zero.
+    """
+    t = od.intrazonal()
+    return {
+        "supply_sc": _ratio(t, od.outflows()),
+        "demand_sc": _ratio(t, od.inflows()),
+    }
+
+
+def job_ratio(od: ODMatrix) -> np.ndarray:
+    """Jobs-to-resident-workers ratio ``D_i / O_i`` from the flow matrix.
+
+    > 1: net importer of commuters (employment centre); < 1: dormitory zone.
+    Only commuters in the matrix are counted, so this is the *commuting* job ratio,
+    not one based on full employment and labour-force statistics.
+    """
+    return _ratio(od.inflows(), od.outflows())
+
+
+def net_balance(od: ODMatrix) -> np.ndarray:
+    """Net in-commuting ``D_i - O_i`` (inflow minus outflow)."""
+    return od.inflows() - od.outflows()
+
+
+def zone_summary(od: ODMatrix) -> List[Dict[str, object]]:
+    """One dict per zone with every indicator in this module."""
+    deg = degree(od)
+    sc = self_containment(od)
+    jr = job_ratio(od)
+    nb = net_balance(od)
+    out_tot, in_tot, t = od.outflows(), od.inflows(), od.intrazonal()
+    rows: List[Dict[str, object]] = []
+    for i, z in enumerate(od.zones):
+        rows.append(
+            {
+                "zone": z,
+                "outflow": float(out_tot[i]),
+                "inflow": float(in_tot[i]),
+                "intrazonal": float(t[i]),
+                "out_degree": int(deg["out_degree"][i]),
+                "in_degree": int(deg["in_degree"][i]),
+                "supply_sc": float(sc["supply_sc"][i]),
+                "demand_sc": float(sc["demand_sc"][i]),
+                "job_ratio": float(jr[i]),
+                "net_balance": float(nb[i]),
+            }
+        )
+    return rows
+
+
+def matrix_summary(od: ODMatrix) -> Dict[str, float]:
+    """Matrix-level figures: totals, intrazonal share, asymmetry, link density."""
+    n = od.n
+    off = od.without_intrazonal().values
+    links = int((off > 0).sum())
+    return {
+        "zones": float(n),
+        "total": od.total,
+        "intrazonal_total": float(od.intrazonal().sum()),
+        "intrazonal_share": float(od.intrazonal().sum() / od.total) if od.total else float("nan"),
+        "links": float(links),
+        "link_density": links / (n * (n - 1)) if n > 1 else float("nan"),
+        "asymmetry_index": od.asymmetry_index(),
+    }