retailgravity 0.1.0__py3-none-any.whl

retailgravity/__init__.py

@@ -0,0 +1,120 @@
+"""retailgravity: spatial interaction and retail catchment models for site analysis.
+
+Quick start::
+
+    from retailgravity import huff, distance_matrix
+
+    d = distance_matrix(origins_lonlat, stores_lonlat)          # km
+    res = huff(d, attractiveness=[5000, 12000, 3000], demand=population, beta=2)
+    res.probabilities        # (origins, stores), rows sum to 1
+    res.sales, res.market_share
+
+Modules: :mod:`~retailgravity.huff` (Huff), :mod:`~retailgravity.mci` (MCI and its
+log-centering calibration), :mod:`~retailgravity.reilly` (Reilly / Converse),
+:mod:`~retailgravity.wilson` (Wilson family, Furness balancing),
+:mod:`~retailgravity.calibrate` (distance-decay calibration),
+:mod:`~retailgravity.tradearea` (trade areas) and :mod:`~retailgravity.scenario`
+(what-if analysis and cannibalisation).
+"""
+
+from ._arrays import deterrence
+from ._version import __version__
+from .calibrate import (
+    CalibrationResult,
+    calibrate_beta,
+    goodness_of_fit,
+    poisson_log_likelihood,
+)
+from .distance import (
+    EARTH_RADIUS_KM,
+    distance_matrix,
+    euclidean_matrix,
+    haversine_matrix,
+    interpolate,
+)
+from .huff import HuffResult, huff, huff_probabilities, utilities
+from .io import (
+    Location,
+    attribute_array,
+    coordinates,
+    locations_from_records,
+    read_locations,
+    write_csv,
+)
+from .mci import HuffFit, MCIFit, fit_huff, fit_mci, mci_probabilities
+from .reilly import (
+    BreakingPoint,
+    breaking_point,
+    breaking_point_location,
+    breaking_points,
+    reilly_ratio,
+    reilly_shares,
+)
+from .scenario import Market, ScenarioComparison, Store, compare
+from .tradearea import (
+    DEFAULT_CUMULATIVE_LEVELS,
+    ProbabilitySurface,
+    contour_sets,
+    cumulative_trade_area,
+    dominant_store,
+    probability_bands,
+    probability_surface,
+)
+from .wilson import (
+    ConvergenceWarning,
+    SIResult,
+    furness,
+    mean_cost,
+    spatial_interaction,
+)
+
+__all__ = [
+    "__version__",
+    "EARTH_RADIUS_KM",
+    "DEFAULT_CUMULATIVE_LEVELS",
+    "BreakingPoint",
+    "CalibrationResult",
+    "ConvergenceWarning",
+    "HuffFit",
+    "HuffResult",
+    "Location",
+    "MCIFit",
+    "Market",
+    "ProbabilitySurface",
+    "SIResult",
+    "ScenarioComparison",
+    "Store",
+    "attribute_array",
+    "breaking_point",
+    "breaking_point_location",
+    "breaking_points",
+    "calibrate_beta",
+    "compare",
+    "contour_sets",
+    "coordinates",
+    "cumulative_trade_area",
+    "deterrence",
+    "distance_matrix",
+    "dominant_store",
+    "euclidean_matrix",
+    "fit_huff",
+    "fit_mci",
+    "furness",
+    "goodness_of_fit",
+    "haversine_matrix",
+    "huff",
+    "huff_probabilities",
+    "interpolate",
+    "locations_from_records",
+    "mci_probabilities",
+    "mean_cost",
+    "poisson_log_likelihood",
+    "probability_bands",
+    "probability_surface",
+    "read_locations",
+    "reilly_ratio",
+    "reilly_shares",
+    "spatial_interaction",
+    "utilities",
+    "write_csv",
+]

retailgravity/__main__.py

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

retailgravity/_arrays.py

@@ -0,0 +1,80 @@
+"""Small array helpers shared by the models (internal)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+
+FloatArray = npt.NDArray[np.float64]
+IntArray = npt.NDArray[np.intp]
+
+DETERRENCE_KINDS = ("power", "exponential")
+
+
+def as_matrix(values: Any, name: str) -> FloatArray:
+    """Return ``values`` as a 2-D float array or raise ``ValueError``."""
+    arr = np.asarray(values, dtype=float)
+    if arr.ndim != 2:
+        raise ValueError(f"{name} must be a 2-D matrix, got shape {arr.shape}")
+    if arr.shape[0] == 0 or arr.shape[1] == 0:
+        raise ValueError(f"{name} must not be empty")
+    if np.isnan(arr).any():
+        raise ValueError(f"{name} contains NaN")
+    return arr
+
+
+def as_vector(values: Any, name: str, length: int | None = None) -> FloatArray:
+    """Return ``values`` as a 1-D float array (optionally of a given length)."""
+    arr = np.asarray(values, dtype=float)
+    if arr.ndim == 0:
+        arr = arr.reshape(1)
+    if arr.ndim != 1:
+        raise ValueError(f"{name} must be 1-D, got shape {arr.shape}")
+    if length is not None and arr.shape[0] != length:
+        raise ValueError(f"{name} must have length {length}, got {arr.shape[0]}")
+    if not np.isfinite(arr).all():
+        raise ValueError(f"{name} must be finite")
+    return arr
+
+
+def deterrence(
+    cost: Any,
+    beta: float,
+    kind: str = "power",
+    *,
+    min_cost: float = 0.0,
+) -> FloatArray:
+    """Distance-deterrence function ``f(c)``.
+
+    ``kind="power"`` gives ``f(c) = c ** -beta`` (Huff 1963; Wilson 1971, "gravity" form) and
+    ``kind="exponential"`` gives ``f(c) = exp(-beta * c)`` (Wilson 1971, "entropy" form).
+
+    An infinite cost means "not reachable / not in the choice set" and yields ``f = 0``.
+    Costs below ``min_cost`` are raised to ``min_cost`` first. With the power form a zero
+    cost is undefined (``0 ** -beta``); pass a small positive ``min_cost`` (for example a
+    half grid cell or an intra-zonal distance) in that case.
+    """
+    if kind not in DETERRENCE_KINDS:
+        raise ValueError(f"deterrence must be one of {DETERRENCE_KINDS}, got {kind!r}")
+    c = np.asarray(cost, dtype=float)
+    if np.isnan(c).any():
+        raise ValueError("cost contains NaN")
+    if (c < 0).any():
+        raise ValueError("cost must be non-negative")
+    if min_cost < 0:
+        raise ValueError("min_cost must be non-negative")
+    c = np.maximum(c, min_cost)
+    finite = np.isfinite(c)
+    out = np.zeros_like(c, dtype=float)
+    if kind == "power":
+        if (c[finite] == 0).any() and beta > 0:
+            raise ValueError(
+                "zero cost/distance with power deterrence; pass min_cost/min_distance > 0"
+            )
+        with np.errstate(divide="ignore"):
+            out[finite] = np.power(c[finite], -float(beta))
+    else:
+        out[finite] = np.exp(-float(beta) * c[finite])
+    return out

retailgravity/_version.py

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

retailgravity/calibrate.py

@@ -0,0 +1,279 @@
+"""Calibration of the distance-decay parameter ``beta`` to observed flows.
+
+For every member of Wilson's family (with the balancing factors, or ``k`` fitted to the
+observed total, treated as free) the Poisson maximum-likelihood estimate of ``beta``
+satisfies a single moment condition: the modelled flows must reproduce the observed
+flow-weighted mean of the deterrence statistic ``g(c)``,
+
+.. math::
+
+    \\frac{\\sum_{ij} \\hat T_{ij}(\\beta)\\, g(c_{ij})}{\\sum \\hat T_{ij}} =
+    \\frac{\\sum_{ij} T_{ij}\\, g(c_{ij})}{\\sum T_{ij}},
+
+with ``g(c) = c`` for exponential and ``g(c) = ln c`` for power deterrence (Batty &
+Mackie 1972; Fotheringham & O'Kelly 1989, ch. 3). ``method="mle"`` solves that equation;
+``method="mean_trip_length"`` always matches the mean cost ``g(c) = c`` (the classic
+Hyman 1969 criterion), which coincides with the MLE for exponential deterrence. The
+modelled statistic decreases monotonically in ``beta``, so the root is bracketed and
+found by bisection.
+
+References
+----------
+* Hyman, G. M. (1969). The calibration of trip distribution models. *Environment and
+  Planning*, 1(1), 105-112.
+* Batty, M., & Mackie, S. (1972). The calibration of gravity, entropy, and related
+  models of spatial interaction. *Environment and Planning*, 4(2), 205-233.
+* Knudsen, D. C., & Fotheringham, A. S. (1986). Matrix comparison, goodness-of-fit, and
+  spatial interaction modeling. *International Regional Science Review*, 10(2), 127-147.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Tuple
+
+import numpy as np
+
+from ._arrays import FloatArray, as_matrix
+from .wilson import SIResult, spatial_interaction
+
+METHODS = ("mle", "mean_trip_length")
+
+
+@dataclass
+class CalibrationResult:
+    """Outcome of :func:`calibrate_beta`."""
+
+    beta: float
+    model: SIResult
+    method: str
+    statistic: str
+    observed_statistic: float
+    modelled_statistic: float
+    observed_mean_cost: float
+    modelled_mean_cost: float
+    log_likelihood: float
+    r_squared: float
+    srmse: float
+    iterations: int
+
+    def as_dict(self) -> Dict[str, Any]:
+        return {
+            "beta": self.beta,
+            "constraint": self.model.constraint,
+            "deterrence": self.model.deterrence,
+            "method": self.method,
+            "statistic": self.statistic,
+            "observed_statistic": self.observed_statistic,
+            "modelled_statistic": self.modelled_statistic,
+            "observed_mean_cost": self.observed_mean_cost,
+            "modelled_mean_cost": self.modelled_mean_cost,
+            "log_likelihood": self.log_likelihood,
+            "r_squared": self.r_squared,
+            "srmse": self.srmse,
+            "iterations": self.iterations,
+        }
+
+
+def poisson_log_likelihood(observed: Any, predicted: Any) -> float:
+    """Poisson log-likelihood ``sum(T ln T_hat - T_hat - ln T!)`` over all cells.
+
+    Cells with ``T_hat = 0`` contribute 0 when ``T = 0`` and ``-inf`` otherwise.
+    """
+    t = np.asarray(observed, dtype=float)
+    p = np.asarray(predicted, dtype=float)
+    pos = t > 0
+    if (pos & (p <= 0)).any():
+        return -math.inf
+    ll = float((t[pos] * np.log(p[pos])).sum() - p.sum())
+    lgamma = np.vectorize(math.lgamma)
+    return ll - float(lgamma(t[pos] + 1.0).sum())
+
+
+def goodness_of_fit(observed: Any, predicted: Any) -> Tuple[float, float]:
+    """``(r_squared, srmse)``: squared Pearson correlation and the standardised root mean
+    square error ``sqrt(sum (T - T_hat)^2 / nm) / (sum T / nm)`` (Knudsen & Fotheringham
+    1986)."""
+    t = np.asarray(observed, dtype=float).ravel()
+    p = np.asarray(predicted, dtype=float).ravel()
+    nm = t.size
+    mean_t = t.sum() / nm
+    srmse = float(math.sqrt(((t - p) ** 2).sum() / nm) / mean_t) if mean_t > 0 else math.nan
+    if t.std() == 0 or p.std() == 0:
+        r2 = math.nan
+    else:
+        r2 = float(np.corrcoef(t, p)[0, 1] ** 2)
+    return r2, srmse
+
+
+def _stat(flows: FloatArray, g: FloatArray, ok: Any) -> float:
+    tot = float(flows[ok].sum())
+    return float((flows[ok] * g[ok]).sum() / tot)
+
+
+def calibrate_beta(
+    observed: Any,
+    cost: Any,
+    *,
+    constraint: str = "doubly",
+    deterrence_kind: str = "exponential",
+    method: str = "mle",
+    origin_mass: Any = None,
+    destination_mass: Any = None,
+    mu: float = 1.0,
+    alpha: float = 1.0,
+    min_cost: float = 0.0,
+    lower: float = 0.0,
+    upper: Optional[float] = None,
+    tol: float = 1e-10,
+    max_iter: int = 200,
+) -> CalibrationResult:
+    """Calibrate ``beta`` so that the model reproduces the observed flows' statistic.
+
+    Parameters
+    ----------
+    observed:
+        ``(n, m)`` observed flows ``T_ij`` (trips, customers, spending).
+    cost:
+        ``(n, m)`` costs; ``inf`` marks impossible pairs (their flows must be 0).
+    constraint:
+        Model family member; the constrained margins are taken from ``observed``
+        (``O_i`` = row sums, ``D_j`` = column sums). For ``"unconstrained"`` the scale
+        ``k`` is set so the modelled total equals the observed total.
+    deterrence_kind:
+        ``"exponential"`` or ``"power"``.
+    method:
+        ``"mle"`` (Poisson maximum likelihood) or ``"mean_trip_length"``.
+    origin_mass, destination_mass, mu, alpha:
+        Masses ``V_i``, ``W_j`` used by the unconstrained, production- (``W``) and
+        attraction-constrained (``V``) models. For a Huff-style retail calibration use
+        ``constraint="production"``, ``deterrence_kind="power"`` and store
+        attractiveness as ``destination_mass``.
+    lower, upper:
+        Search interval for ``beta`` (``upper`` is expanded automatically when not
+        given). Observed flows that are *less* distance-sensitive than ``beta=lower``
+        raise ``ValueError``.
+    """
+    if method not in METHODS:
+        raise ValueError(f"method must be one of {METHODS}, got {method!r}")
+    t = as_matrix(observed, "observed")
+    if (t < 0).any() or not np.isfinite(t).all():
+        raise ValueError("observed flows must be finite and non-negative")
+    c = np.maximum(np.asarray(cost, dtype=float), min_cost)
+    if c.shape != t.shape:
+        raise ValueError(f"cost shape {c.shape} differs from observed shape {t.shape}")
+    ok = np.isfinite(c)
+    if (t[~ok] > 0).any():
+        raise ValueError("observed flow on a pair with infinite cost")
+    if deterrence_kind == "power":
+        if (c[ok] <= 0).any():
+            raise ValueError("power deterrence needs positive costs; pass min_cost")
+        # Rescaling c by a constant multiplies f by a constant, which every model
+        # absorbs (A_i, B_j or k); it keeps c**-beta in floating-point range.
+        c_model = c / c[ok].min()
+    elif deterrence_kind == "exponential":
+        c_model = c - c[ok].min()
+    else:
+        raise ValueError(f"unknown deterrence {deterrence_kind!r}")
+    if method == "mle" and deterrence_kind == "power":
+        g = np.where(ok, np.log(np.where(ok, c, 1.0)), 0.0)
+        stat_name = "mean_log_cost"
+    else:
+        g = np.where(ok, c, 0.0)
+        stat_name = "mean_cost"
+
+    total = float(t.sum())
+    kwargs: Dict[str, Any] = {
+        "constraint": constraint,
+        "deterrence_kind": deterrence_kind,
+        "origin_mass": origin_mass,
+        "destination_mass": destination_mass,
+        "mu": mu,
+        "alpha": alpha,
+    }
+    if constraint in ("production", "doubly"):
+        kwargs["outflows"] = t.sum(axis=1)
+    if constraint in ("attraction", "doubly"):
+        kwargs["inflows"] = t.sum(axis=0)
+    if constraint == "unconstrained":
+        kwargs["total"] = total
+
+    def fit(b: float) -> SIResult:
+        return spatial_interaction(c_model, beta=b, **kwargs)
+
+    def model_stat(b: float) -> float:
+        try:
+            res = fit(b)
+            val = _stat(res.flows, g, ok)
+        except (ValueError, FloatingPointError, ZeroDivisionError):
+            return -math.inf
+        return val if math.isfinite(val) else -math.inf
+
+    target = _stat(t, g, ok)
+    lo = float(lower)
+    s_lo = model_stat(lo)
+    if not math.isfinite(s_lo):
+        raise ValueError(f"model cannot be evaluated at beta={lo}")
+    if target >= s_lo:
+        if target - s_lo <= 1e-12 * max(1.0, abs(target)):
+            hi = lo
+        else:
+            raise ValueError(
+                f"observed {stat_name} ({target:.6g}) is not below the model value at "
+                f"beta={lo} ({s_lo:.6g}); lower the search bound to allow beta < {lo}"
+            )
+    if upper is not None:
+        hi = float(upper)
+        if model_stat(hi) > target:
+            raise ValueError(f"beta exceeds upper bound {hi}")
+    elif target < s_lo:
+        span = (
+            float(np.ptp(c_model[ok]))
+            if deterrence_kind == "exponential"
+            else float(np.log(c_model[ok]).max())
+        )
+        hi = lo + (1.0 / span if span > 0 else 1.0)
+        for _ in range(200):
+            if model_stat(hi) <= target:
+                break
+            hi = lo + 2.0 * (hi - lo)
+        else:  # pragma: no cover - pathological input
+            raise ValueError("could not bracket beta")
+    iterations = 0
+    if hi > lo:
+        for it in range(1, max_iter + 1):
+            iterations = it
+            mid = 0.5 * (lo + hi)
+            if model_stat(mid) > target:
+                lo = mid
+            else:
+                hi = mid
+            if hi - lo <= tol * max(1.0, abs(hi)):
+                break
+    beta = 0.5 * (lo + hi)
+    try:
+        # Refit on the original costs so A_i, B_j and k refer to them.
+        with np.errstate(over="raise", under="ignore"):
+            model = spatial_interaction(c, beta=beta, **kwargs)
+        if not np.isfinite(model.flows).all() or not np.allclose(
+            model.flows, fit(beta).flows, rtol=1e-6, atol=1e-9 * max(total, 1.0)
+        ):
+            raise FloatingPointError
+    except (ValueError, FloatingPointError):
+        model = fit(beta)  # balancing factors then refer to the rescaled costs
+    r2, srmse = goodness_of_fit(t, model.flows)
+    return CalibrationResult(
+        beta=beta,
+        model=model,
+        method=method,
+        statistic=stat_name,
+        observed_statistic=target,
+        modelled_statistic=_stat(model.flows, g, ok),
+        observed_mean_cost=_stat(t, np.where(ok, c, 0.0), ok),
+        modelled_mean_cost=_stat(model.flows, np.where(ok, c, 0.0), ok),
+        log_likelihood=poisson_log_likelihood(t, model.flows),
+        r_squared=r2,
+        srmse=srmse,
+        iterations=iterations,
+    )