tripdist 0.1.0__py3-none-any.whl

tripdist/__init__.py

@@ -0,0 +1,131 @@
+"""tripdist: trip generation and distribution (stages 1-2 of the four-step model).
+
+Trip generation by regression and cross-classification with production/attraction
+balancing; growth-factor methods (uniform, singly constrained, average, Detroit, Fratar,
+Furness); gravity models (unconstrained, production-, attraction- and doubly constrained)
+with exponential, power, combined (Tanner), gamma and tabulated deterrence functions;
+Hyman's (1969) calibration to an observed mean trip cost; trip length frequency
+distributions, K-factors, intrazonal handling and convergence diagnostics. Methods follow
+Ortúzar & Willumsen, *Modelling Transport* (4th ed., 2011).
+"""
+
+from ._common import TripDistError
+from ._version import __version__
+from .balancing import BalanceResult, furness, margin_error
+from .calibration import (
+    CalibrationResult,
+    FrictionCalibration,
+    calibrate_friction_factors,
+    hyman,
+    k_factors,
+    observed_mean_cost,
+)
+from .deterrence import (
+    DETERRENCE_FORMS,
+    Deterrence,
+    combined,
+    deterrence_from_dict,
+    exponential,
+    gamma,
+    power,
+    tabular,
+    tanner,
+)
+from .diagnostics import MatrixFit, MatrixSummary, aggregate, compare_matrices, geh, summarize
+from .generation import (
+    CategoryRates,
+    RegressionModel,
+    apply_category_rates,
+    balance_pa,
+    cross_classification_rates,
+    fit_regression,
+)
+from .gravity import (
+    CONSTRAINTS,
+    GravityResult,
+    gravity,
+    intrazonal_costs,
+    intrazonal_share,
+    mean_cost,
+)
+from .growth import (
+    GROWTH_METHODS,
+    GrowthResult,
+    average_factor,
+    detroit,
+    fratar,
+    furness_growth,
+    growth_factor,
+    singly_constrained_growth,
+    uniform_growth,
+)
+from .io import read_json, read_long, read_matrix, read_zone_table, write_json, write_matrix
+from .tlfd import TLFD, TLFDComparison, coincidence_ratio, compare_tlfd, cost_bins, tlfd
+
+__all__ = [
+    "__version__",
+    "TripDistError",
+    # generation
+    "fit_regression",
+    "RegressionModel",
+    "cross_classification_rates",
+    "apply_category_rates",
+    "CategoryRates",
+    "balance_pa",
+    # balancing and growth factors
+    "furness",
+    "margin_error",
+    "BalanceResult",
+    "uniform_growth",
+    "singly_constrained_growth",
+    "average_factor",
+    "detroit",
+    "fratar",
+    "furness_growth",
+    "growth_factor",
+    "GrowthResult",
+    "GROWTH_METHODS",
+    # deterrence and gravity
+    "Deterrence",
+    "exponential",
+    "power",
+    "combined",
+    "tanner",
+    "gamma",
+    "tabular",
+    "deterrence_from_dict",
+    "DETERRENCE_FORMS",
+    "gravity",
+    "GravityResult",
+    "CONSTRAINTS",
+    "mean_cost",
+    "intrazonal_costs",
+    "intrazonal_share",
+    # calibration
+    "hyman",
+    "observed_mean_cost",
+    "CalibrationResult",
+    "calibrate_friction_factors",
+    "FrictionCalibration",
+    "k_factors",
+    # TLFD and diagnostics
+    "tlfd",
+    "TLFD",
+    "compare_tlfd",
+    "TLFDComparison",
+    "coincidence_ratio",
+    "cost_bins",
+    "summarize",
+    "MatrixSummary",
+    "compare_matrices",
+    "MatrixFit",
+    "geh",
+    "aggregate",
+    # I/O
+    "read_matrix",
+    "write_matrix",
+    "read_zone_table",
+    "read_long",
+    "read_json",
+    "write_json",
+]

tripdist/__main__.py

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

tripdist/_common.py

@@ -0,0 +1,106 @@
+"""Shared validation helpers and the package exception."""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Union
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+FloatArray = NDArray[np.float64]
+Number = Union[int, float]
+
+
+class TripDistError(ValueError):
+    """Raised for invalid input to a tripdist function."""
+
+
+def as_vector(values: ArrayLike, name: str, *, allow_negative: bool = False) -> FloatArray:
+    """Return ``values`` as a finite 1-D float array or raise :class:`TripDistError`."""
+    try:
+        arr = np.asarray(values, dtype=np.float64)
+    except (TypeError, ValueError):
+        raise TripDistError(f"{name} must be numeric") from None
+    if arr.ndim == 0:
+        arr = arr.reshape(1)
+    if arr.ndim != 1:
+        raise TripDistError(f"{name} must be one-dimensional, got shape {arr.shape}")
+    if arr.size == 0:
+        raise TripDistError(f"{name} is empty")
+    if not np.all(np.isfinite(arr)):
+        raise TripDistError(f"{name} contains NaN or infinite values")
+    if not allow_negative and np.any(arr < 0):
+        raise TripDistError(f"{name} contains negative values")
+    return arr
+
+
+def as_matrix(
+    values: ArrayLike,
+    name: str,
+    *,
+    square: bool = False,
+    allow_negative: bool = False,
+    allow_inf: bool = False,
+) -> FloatArray:
+    """Return ``values`` as a 2-D float array or raise :class:`TripDistError`.
+
+    ``allow_inf`` permits ``+inf`` entries, used for costs of impossible movements.
+    """
+    try:
+        arr = np.asarray(values, dtype=np.float64)
+    except (TypeError, ValueError):
+        raise TripDistError(f"{name} must be numeric") from None
+    if arr.ndim != 2:
+        raise TripDistError(f"{name} must be two-dimensional, got shape {arr.shape}")
+    if arr.size == 0:
+        raise TripDistError(f"{name} is empty")
+    if square and arr.shape[0] != arr.shape[1]:
+        raise TripDistError(f"{name} must be square, got shape {arr.shape}")
+    if np.any(np.isnan(arr)):
+        raise TripDistError(f"{name} contains NaN values")
+    if allow_inf:
+        if np.any(arr == -np.inf):
+            raise TripDistError(f"{name} contains -inf")
+    elif not np.all(np.isfinite(arr)):
+        raise TripDistError(f"{name} contains infinite values")
+    if not allow_negative and np.any(arr < 0):
+        raise TripDistError(f"{name} contains negative values")
+    return arr
+
+
+def check_length(arr: FloatArray, n: int, name: str) -> None:
+    if arr.shape[0] != n:
+        raise TripDistError(f"{name} has {arr.shape[0]} entries, expected {n}")
+
+
+def clean(value: Any) -> Any:
+    """Make ``value`` JSON-safe: arrays to lists, NaN/inf to ``None``."""
+    if isinstance(value, dict):
+        return {str(k): clean(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [clean(v) for v in value]
+    if isinstance(value, np.ndarray):
+        return clean(value.tolist())
+    if isinstance(value, (np.bool_, bool)):
+        return bool(value)
+    if isinstance(value, (np.integer,)):
+        return int(value)
+    if isinstance(value, (float, np.floating)):
+        f = float(value)
+        return f if math.isfinite(f) else None
+    return value
+
+
+def safe_div(num: FloatArray, den: FloatArray) -> FloatArray:
+    """Element-wise ``num / den`` with 0 where ``den == 0``."""
+    out = np.zeros(np.broadcast(num, den).shape, dtype=np.float64)
+    np.divide(num, den, out=out, where=den != 0)
+    return out
+
+
+def rel_error(actual: FloatArray, target: FloatArray) -> float:
+    """Largest ``|actual - target| / target`` (absolute difference where target is 0)."""
+    diff = np.abs(actual - target)
+    err = np.where(target > 0, diff / np.where(target > 0, target, 1.0), diff)
+    return float(err.max()) if err.size else 0.0

tripdist/_version.py

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

tripdist/balancing.py

@@ -0,0 +1,219 @@
+"""Biproportional matrix balancing (Furness method / iterative proportional fitting).
+
+The Furness (1965) iteration alternately scales the rows and the columns of a seed matrix
+until its margins match target origin and destination totals:
+
+    T_ij = A_i O_i B_j D_j t_ij   (Furness 1965; Ortúzar & Willumsen 2011, section 5.2)
+
+The same algorithm is known as iterative proportional fitting (Deming & Stephan 1940) and
+RAS (Bacharach 1970). It is the balancing engine for the Furness growth-factor method and
+for the doubly constrained gravity model.
+
+References
+----------
+Bacharach, M. (1970). *Biproportional Matrices and Input-Output Change*. Cambridge
+University Press.
+
+Deming, W. E. & Stephan, F. F. (1940). On a least squares adjustment of a sampled frequency
+table when the expected marginal totals are known. *Annals of Mathematical Statistics*
+11(4), 427-444.
+
+Furness, K. P. (1965). Time function iteration. *Traffic Engineering and Control* 7(7),
+458-460.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from ._common import FloatArray, TripDistError, as_matrix, as_vector, check_length, clean, rel_error
+
+__all__ = ["BalanceResult", "furness", "margin_error"]
+
+
+@dataclass
+class BalanceResult:
+    """Outcome of a biproportional balancing run.
+
+    ``history`` holds the largest relative margin error after each iteration, which is
+    the convergence diagnostic usually plotted for Furness runs.
+    """
+
+    matrix: FloatArray
+    row_factors: FloatArray
+    col_factors: FloatArray
+    iterations: int
+    converged: bool
+    max_error: float
+    history: List[float] = field(default_factory=list)
+
+    @property
+    def total(self) -> float:
+        return float(self.matrix.sum())
+
+    def to_dict(self, include_matrix: bool = True) -> Dict[str, Any]:
+        out: Dict[str, Any] = {
+            "iterations": self.iterations,
+            "converged": self.converged,
+            "max_error": self.max_error,
+            "total": self.total,
+            "row_factors": self.row_factors,
+            "col_factors": self.col_factors,
+            "history": self.history,
+        }
+        if include_matrix:
+            out["matrix"] = self.matrix
+        return clean(out)
+
+
+def margin_error(matrix: ArrayLike, row_targets: ArrayLike, col_targets: ArrayLike) -> float:
+    """Largest relative difference between a matrix's margins and the targets.
+
+    Each error is ``|sum - target| / target``; targets of zero use the absolute sum.
+    """
+    m = as_matrix(matrix, "matrix")
+    rt = as_vector(row_targets, "row_targets")
+    ct = as_vector(col_targets, "col_targets")
+    check_length(rt, m.shape[0], "row_targets")
+    check_length(ct, m.shape[1], "col_targets")
+    return _margin_error(m, rt, ct)
+
+
+def _margin_error(m: FloatArray, rt: FloatArray, ct: FloatArray) -> float:
+    return max(rel_error(m.sum(axis=1), rt), rel_error(m.sum(axis=0), ct))
+
+
+def furness(
+    seed: ArrayLike,
+    row_targets: ArrayLike,
+    col_targets: ArrayLike,
+    *,
+    tol: float = 1e-6,
+    max_iter: int = 1000,
+    total_mismatch: str = "error",
+    rel_tol_totals: float = 1e-6,
+    raise_on_fail: bool = False,
+) -> BalanceResult:
+    """Scale ``seed`` so that its row and column sums match the targets.
+
+    Parameters
+    ----------
+    seed:
+        Non-negative seed matrix (base-year trips, or ``O_i D_j f(c_ij)`` for a gravity
+        model). Cells that are zero stay zero.
+    row_targets, col_targets:
+        Target origin (row) and destination (column) totals.
+    tol:
+        Stop when the largest relative margin error falls below this value.
+    max_iter:
+        Maximum number of row-plus-column passes.
+    total_mismatch:
+        What to do when the two target vectors have different totals (the problem then has
+        no exact solution): ``"error"`` (default), ``"rows"`` scale the column targets to
+        the row total, ``"cols"`` scale the row targets to the column total, or
+        ``"average"`` scale both to their mean.
+    raise_on_fail:
+        Raise :class:`TripDistError` if the run has not converged after ``max_iter``.
+
+    The iteration converges when a solution exists, i.e. when the zero pattern of the seed
+    allows the targets (Bacharach 1970). Rows or columns of the seed that are entirely zero
+    but have a positive target make that impossible and raise an error.
+    """
+    t = as_matrix(seed, "seed")
+    rt = as_vector(row_targets, "row_targets")
+    ct = as_vector(col_targets, "col_targets")
+    check_length(rt, t.shape[0], "row_targets")
+    check_length(ct, t.shape[1], "col_targets")
+    if tol <= 0:
+        raise TripDistError("tol must be positive")
+    if max_iter < 1:
+        raise TripDistError("max_iter must be at least 1")
+    sr, sc = float(rt.sum()), float(ct.sum())
+    if sr <= 0 or sc <= 0:
+        raise TripDistError("targets must have positive totals")
+    if abs(sr - sc) > rel_tol_totals * max(sr, sc):
+        if total_mismatch == "error":
+            raise TripDistError(
+                f"row targets total {sr:g} but column targets total {sc:g}; "
+                "balance them first or pass total_mismatch"
+            )
+        if total_mismatch == "rows":
+            ct = ct * (sr / sc)
+        elif total_mismatch == "cols":
+            rt = rt * (sc / sr)
+        elif total_mismatch == "average":
+            avg = 0.5 * (sr + sc)
+            rt = rt * (avg / sr)
+            ct = ct * (avg / sc)
+        else:
+            raise TripDistError(f"unknown total_mismatch {total_mismatch!r}")
+    if np.any((t.sum(axis=1) == 0) & (rt > 0)):
+        bad = np.flatnonzero((t.sum(axis=1) == 0) & (rt > 0)).tolist()
+        raise TripDistError(f"seed rows {bad} are all zero but have positive targets")
+    if np.any((t.sum(axis=0) == 0) & (ct > 0)):
+        bad = np.flatnonzero((t.sum(axis=0) == 0) & (ct > 0)).tolist()
+        raise TripDistError(f"seed columns {bad} are all zero but have positive targets")
+
+    a = np.ones(t.shape[0])
+    b = np.ones(t.shape[1])
+    history: List[float] = []
+    converged = False
+    err = _margin_error(t, rt, ct)
+    it = 0
+    for it in range(1, max_iter + 1):  # noqa: B007 - it is reported after the loop
+        rows = t @ b
+        a = np.divide(rt, rows, out=np.zeros_like(rt), where=rows > 0)
+        cols = a @ t
+        b = np.divide(ct, cols, out=np.zeros_like(ct), where=cols > 0)
+        m = a[:, None] * t * b[None, :]
+        err = _margin_error(m, rt, ct)
+        history.append(err)
+        if err < tol:
+            converged = True
+            break
+    matrix = a[:, None] * t * b[None, :]
+    if not converged and raise_on_fail:
+        raise TripDistError(f"Furness did not converge in {max_iter} iterations (error {err:g})")
+    return BalanceResult(
+        matrix=matrix,
+        row_factors=a,
+        col_factors=b,
+        iterations=it,
+        converged=converged,
+        max_error=err,
+        history=history,
+    )
+
+
+def furness_from(
+    seed: ArrayLike,
+    row_targets: Optional[ArrayLike],
+    col_targets: Optional[ArrayLike],
+    **kwargs: Any,
+) -> BalanceResult:
+    """Furness with optional margins: a missing side is left free (single constraint)."""
+    t = as_matrix(seed, "seed")
+    if row_targets is not None and col_targets is not None:
+        return furness(t, row_targets, col_targets, **kwargs)
+    if row_targets is None and col_targets is None:
+        raise TripDistError("give at least one of row_targets and col_targets")
+    if row_targets is not None:
+        rt = as_vector(row_targets, "row_targets")
+        check_length(rt, t.shape[0], "row_targets")
+        rows = t.sum(axis=1)
+        a = np.divide(rt, rows, out=np.zeros_like(rt), where=rows > 0)
+        m = a[:, None] * t
+        err = rel_error(m.sum(axis=1), rt)
+        return BalanceResult(m, a, np.ones(t.shape[1]), 1, True, err, [err])
+    assert col_targets is not None
+    ct = as_vector(col_targets, "col_targets")
+    check_length(ct, t.shape[1], "col_targets")
+    cols = t.sum(axis=0)
+    b = np.divide(ct, cols, out=np.zeros_like(ct), where=cols > 0)
+    m = t * b[None, :]
+    err = rel_error(m.sum(axis=0), ct)
+    return BalanceResult(m, np.ones(t.shape[0]), b, 1, True, err, [err])