crashmap 0.1.0__py3-none-any.whl

crashmap/__init__.py

@@ -0,0 +1,174 @@
+"""crashmap: road-safety network screening and crash hotspot analysis.
+
+Implements the network screening performance measures of the Highway Safety
+Manual (AASHTO 2010, Part B, Chapter 4), negative binomial safety performance
+functions, Empirical Bayes estimation, before-after evaluation (Hauer 1997)
+and spatial hotspot tools, on top of NumPy only.
+
+Typical workflow::
+
+    import crashmap as cm
+
+    crashes = cm.read_crashes_csv("crashes.csv")
+    roads = cm.read_roads_geojson("roads.geojson")
+    segments = cm.fixed_length_segments(roads, 500)
+    snap = cm.snap_to_lines(crashes, segments, max_distance=25)
+    sites = cm.build_segment_sites(segments, crashes, snap, years=5)
+    spf = cm.SPF.segment(a=-6.2, b=0.75, k=0.5, length_unit="km")
+    result = cm.screen(sites, "eb", spf=spf)
+    cm.write_geojson(result, "ranked.geojson")
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .before_after import (
+    BeforeAfterResult,
+    comparison_group_before_after,
+    eb_before_after,
+    naive_before_after,
+)
+from .data import (
+    CrashSet,
+    Road,
+    crashes_from_dataframe,
+    read_crashes_csv,
+    read_crashes_geojson,
+    read_roads_geojson,
+    roads_from_geodataframe,
+    write_crashes_csv,
+    write_roads_geojson,
+)
+from .geometry import LocalProjection
+from .nb2 import NB2Result, fit_nb2, fit_poisson, nb2_loglik
+from .ranking import rank, top_n
+from .report import ranked_geojson, to_html, to_markdown, write_geojson, write_report
+from .screening import (
+    METHODS,
+    ScreeningResult,
+    average_frequency,
+    crash_rate,
+    critical_rate,
+    eb_expected,
+    eb_weight,
+    epdo_score,
+    excess_predicted,
+    exposure_mev,
+    exposure_mvkt,
+    proportion_exceeding,
+    relative_severity_index,
+    screen,
+)
+from .segmentation import (
+    Segment,
+    Window,
+    fixed_length_segments,
+    homogeneous_segments,
+    roads_as_segments,
+    sliding_window_counts,
+    sliding_windows,
+)
+from .severity import (
+    DEFAULT_EPDO_WEIGHTS,
+    HSM_CRASH_COSTS,
+    KABCO,
+    epdo_weights_from_costs,
+    normalize_severity,
+    to_fss,
+)
+from .sites import Site, build_intersection_sites, build_segment_sites, build_window_sites
+from .snapping import Intersection, SnapResult, extract_intersections, snap_to_lines, snap_to_points
+from .spatial import (
+    distance_band_weights,
+    getis_ord_gi_star,
+    kde_at,
+    kde_grid,
+    network_kde,
+    touching_weights,
+)
+from .spf import SPF, CUREResult, FittedSPF, SPFTerm, cure_plot, fit_spf, load_spf
+from .synthetic import simulate_nb_counts, synthetic_network, synthetic_sites
+from .timeparse import parse_datetime
+
+__all__ = [
+    "DEFAULT_EPDO_WEIGHTS",
+    "HSM_CRASH_COSTS",
+    "KABCO",
+    "METHODS",
+    "SPF",
+    "BeforeAfterResult",
+    "CUREResult",
+    "CrashSet",
+    "FittedSPF",
+    "Intersection",
+    "LocalProjection",
+    "NB2Result",
+    "Road",
+    "SPFTerm",
+    "ScreeningResult",
+    "Segment",
+    "Site",
+    "SnapResult",
+    "Window",
+    "__version__",
+    "average_frequency",
+    "build_intersection_sites",
+    "build_segment_sites",
+    "build_window_sites",
+    "comparison_group_before_after",
+    "crash_rate",
+    "crashes_from_dataframe",
+    "critical_rate",
+    "cure_plot",
+    "distance_band_weights",
+    "eb_before_after",
+    "eb_expected",
+    "eb_weight",
+    "epdo_score",
+    "epdo_weights_from_costs",
+    "excess_predicted",
+    "exposure_mev",
+    "exposure_mvkt",
+    "extract_intersections",
+    "fit_nb2",
+    "fit_poisson",
+    "fit_spf",
+    "fixed_length_segments",
+    "getis_ord_gi_star",
+    "homogeneous_segments",
+    "kde_at",
+    "kde_grid",
+    "load_spf",
+    "naive_before_after",
+    "nb2_loglik",
+    "network_kde",
+    "normalize_severity",
+    "parse_datetime",
+    "proportion_exceeding",
+    "rank",
+    "ranked_geojson",
+    "read_crashes_csv",
+    "read_crashes_geojson",
+    "read_roads_geojson",
+    "relative_severity_index",
+    "roads_as_segments",
+    "roads_from_geodataframe",
+    "screen",
+    "simulate_nb_counts",
+    "sliding_window_counts",
+    "sliding_windows",
+    "snap_to_lines",
+    "snap_to_points",
+    "synthetic_network",
+    "synthetic_sites",
+    "to_fss",
+    "to_html",
+    "to_markdown",
+    "top_n",
+    "touching_weights",
+    "write_crashes_csv",
+    "write_geojson",
+    "write_report",
+    "write_roads_geojson",
+]

crashmap/_special.py

@@ -0,0 +1,91 @@
+"""Special functions without a hard SciPy dependency."""
+
+from __future__ import annotations
+
+import math
+from statistics import NormalDist
+
+__all__ = ["betainc", "norm_cdf", "norm_ppf", "norm_sf"]
+
+_STD = NormalDist()
+
+
+def norm_ppf(p: float) -> float:
+    """Standard normal quantile."""
+    if not 0.0 < p < 1.0:
+        raise ValueError("probability must be within (0, 1)")
+    return float(_STD.inv_cdf(p))
+
+
+def norm_cdf(z: float) -> float:
+    """Standard normal CDF."""
+    return 0.5 * math.erfc(-z / math.sqrt(2.0))
+
+
+def norm_sf(z: float) -> float:
+    """Standard normal survival function (accurate in the upper tail)."""
+    return 0.5 * math.erfc(z / math.sqrt(2.0))
+
+
+def _betacf(a: float, b: float, x: float) -> float:
+    # Modified Lentz continued fraction (Press et al., Numerical Recipes, 6.4).
+    fpmin = 1e-300
+    qab, qap, qam = a + b, a + 1.0, a - 1.0
+    c = 1.0
+    d = 1.0 - qab * x / qap
+    if abs(d) < fpmin:
+        d = fpmin
+    d = 1.0 / d
+    h = d
+    for m in range(1, 10_001):
+        m2 = 2 * m
+        aa = m * (b - m) * x / ((qam + m2) * (a + m2))
+        d = 1.0 + aa * d
+        d = fpmin if abs(d) < fpmin else d
+        c = 1.0 + aa / c
+        c = fpmin if abs(c) < fpmin else c
+        d = 1.0 / d
+        h *= d * c
+        aa = -(a + m) * (qab + m) * x / ((a + m2) * (qap + m2))
+        d = 1.0 + aa * d
+        d = fpmin if abs(d) < fpmin else d
+        c = 1.0 + aa / c
+        c = fpmin if abs(c) < fpmin else c
+        d = 1.0 / d
+        de = d * c
+        h *= de
+        if abs(de - 1.0) < 1e-15:
+            return h
+    raise ArithmeticError("incomplete beta continued fraction did not converge")
+
+
+def _betainc_pure(a: float, b: float, x: float) -> float:
+    if x <= 0.0:
+        return 0.0
+    if x >= 1.0:
+        return 1.0
+    lbt = (
+        math.lgamma(a + b) - math.lgamma(a) - math.lgamma(b) + a * math.log(x) + b * math.log1p(-x)
+    )
+    bt = math.exp(lbt)
+    if x < (a + 1.0) / (a + b + 2.0):
+        return bt * _betacf(a, b, x) / a
+    return 1.0 - bt * _betacf(b, a, 1.0 - x) / b
+
+
+def betainc(a: float, b: float, x: float, *, use_scipy: bool = True) -> float:
+    """Regularised incomplete beta function :math:`I_x(a, b)` (the Beta CDF).
+
+    Uses :func:`scipy.special.betainc` when SciPy is installed and
+    ``use_scipy`` is true, otherwise a continued-fraction evaluation.
+    """
+    if a <= 0 or b <= 0:
+        raise ValueError("beta parameters must be positive")
+    if use_scipy:
+        try:
+            from scipy.special import betainc as _sp_betainc
+        except ImportError:  # pragma: no cover - depends on the environment
+            pass
+        else:
+            return float(_sp_betainc(a, b, x))
+    return _betainc_pure(a, b, x)

crashmap/before_after.py

@@ -0,0 +1,251 @@
+"""Before-after evaluation of safety treatments (Hauer 1997).
+
+All three designs share Hauer's four-step framework: estimate ``pi``, the
+crashes expected in the after period had the treatment not been applied, and
+compare it with ``lambda``, the crashes observed after treatment. The index of
+effectiveness (crash modification factor, CMF) corrected for the bias of a
+ratio of random variables is::
+
+    theta = (lambda / pi) / (1 + Var(pi) / pi**2)
+    Var(theta) = theta**2 * (Var(lambda)/lambda**2 + Var(pi)/pi**2) / (1 + Var(pi)/pi**2)**2
+
+with ``Var(lambda) = lambda`` (Poisson). A CMF below 1 means fewer crashes.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Any, Union
+
+import numpy as np
+
+from ._special import norm_ppf
+
+__all__ = [
+    "BeforeAfterResult",
+    "comparison_group_before_after",
+    "eb_before_after",
+    "naive_before_after",
+]
+
+ArrayLike = Union[Sequence[float], np.ndarray, float]
+
+
+@dataclass
+class BeforeAfterResult:
+    """Outcome of a before-after study.
+
+    Attributes
+    ----------
+    method:
+        ``"naive"``, ``"comparison-group"`` or ``"empirical-bayes"``.
+    observed_after:
+        ``lambda``, crashes observed after treatment (all sites).
+    expected_after:
+        ``pi``, crashes expected after without treatment.
+    var_expected_after:
+        ``Var(pi)``.
+    cmf:
+        Bias-corrected index of effectiveness ``theta``.
+    se:
+        Standard error of ``theta``.
+    """
+
+    method: str
+    observed_after: float
+    expected_after: float
+    var_expected_after: float
+    cmf: float
+    se: float
+    n_sites: int
+    details: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def percent_change(self) -> float:
+        """``100 * (theta - 1)``; negative = crash reduction."""
+        return 100.0 * (self.cmf - 1.0)
+
+    @property
+    def crash_reduction(self) -> float:
+        """Crash reduction factor ``100 * (1 - theta)`` in percent."""
+        return 100.0 * (1.0 - self.cmf)
+
+    def confidence_interval(self, level: float = 0.95) -> tuple[float, float]:
+        """Normal-approximation confidence interval of the CMF."""
+        z = norm_ppf(0.5 + level / 2.0)
+        return (self.cmf - z * self.se, self.cmf + z * self.se)
+
+    @property
+    def significant(self) -> bool:
+        """True when the 95 % confidence interval excludes 1."""
+        lo, hi = self.confidence_interval(0.95)
+        return hi < 1.0 or lo > 1.0
+
+    def as_dict(self) -> dict[str, Any]:
+        """Flat dictionary for reports and JSON."""
+        lo, hi = self.confidence_interval()
+        return {
+            "method": self.method,
+            "n_sites": self.n_sites,
+            "observed_after": self.observed_after,
+            "expected_after": self.expected_after,
+            "var_expected_after": self.var_expected_after,
+            "cmf": self.cmf,
+            "se": self.se,
+            "ci95_low": lo,
+            "ci95_high": hi,
+            "percent_change": self.percent_change,
+            "significant": self.significant,
+            **self.details,
+        }
+
+
+def _hauer(lam: float, pi: float, var_pi: float) -> tuple[float, float]:
+    if pi <= 0:
+        raise ValueError("expected after-period crashes must be positive")
+    rel = var_pi / pi**2
+    theta = (lam / pi) / (1.0 + rel)
+    if lam > 0:
+        var_t = theta**2 * (1.0 / lam + rel) / (1.0 + rel) ** 2
+    else:
+        # lambda = 0 makes the Poisson estimate Var(lambda) = lambda vanish;
+        # use Var(lambda) = 1 (one crash) so the standard error stays honest.
+        var_t = (1.0 / pi**2) / (1.0 + rel) ** 2
+    return float(theta), float(math.sqrt(var_t))
+
+
+def _total(v: ArrayLike, name: str) -> tuple[float, int]:
+    a = np.asarray(v, dtype=float).ravel()
+    if a.size == 0 or np.any(a < 0) or not np.all(np.isfinite(a)):
+        raise ValueError(f"{name} must be non-negative and finite")
+    return float(a.sum()), int(a.size)
+
+
+def naive_before_after(
+    observed_before: ArrayLike,
+    observed_after: ArrayLike,
+    *,
+    years_before: float = 1.0,
+    years_after: float = 1.0,
+) -> BeforeAfterResult:
+    """Naive (simple) before-after study.
+
+    ``pi = r_d * K`` with ``K`` the before count and ``r_d`` the ratio of
+    after to before durations; ``Var(pi) = r_d**2 * K``. Ignores regression to
+    the mean and general trends, so it overstates benefits at sites chosen for
+    their high crash counts.
+    """
+    k, n_sites = _total(observed_before, "observed_before")
+    lam, n2 = _total(observed_after, "observed_after")
+    if n_sites != n2:
+        raise ValueError("before and after counts must cover the same sites")
+    if years_before <= 0 or years_after <= 0:
+        raise ValueError("period lengths must be positive")
+    rd = years_after / years_before
+    pi = rd * k
+    var_pi = rd**2 * k
+    theta, se = _hauer(lam, pi, var_pi)
+    return BeforeAfterResult("naive", lam, pi, var_pi, theta, se, n_sites, {"duration_ratio": rd})
+
+
+def comparison_group_before_after(
+    observed_before: ArrayLike,
+    observed_after: ArrayLike,
+    comparison_before: ArrayLike,
+    comparison_after: ArrayLike,
+    *,
+    comparison_ratio_variance: float | None = None,
+) -> BeforeAfterResult:
+    """Before-after study with a comparison group (Hauer 1997, ch. 9).
+
+    The comparison ratio ``r_C = N / M`` (comparison after over before
+    crashes) scales the before count: ``pi = r_C * K``. Unless given,
+    ``Var(r_C) / r_C**2`` is approximated by ``1/M + 1/N`` (comparison counts
+    Poisson, no extra variation between treated and comparison ratios) and
+    ``Var(pi) = pi**2 * (1/K + Var(r_C)/r_C**2)``.
+    """
+    k, n_sites = _total(observed_before, "observed_before")
+    lam, n2 = _total(observed_after, "observed_after")
+    if n_sites != n2:
+        raise ValueError("before and after counts must cover the same sites")
+    m, _ = _total(comparison_before, "comparison_before")
+    nn, _ = _total(comparison_after, "comparison_after")
+    if m <= 0 or nn <= 0 or k <= 0:
+        raise ValueError("comparison counts and treated before count must be positive")
+    rc = nn / m
+    rel_rc = (
+        (1.0 / m + 1.0 / nn)
+        if comparison_ratio_variance is None
+        else (comparison_ratio_variance / rc**2)
+    )
+    pi = rc * k
+    var_pi = pi**2 * (1.0 / k + rel_rc)
+    theta, se = _hauer(lam, pi, var_pi)
+    return BeforeAfterResult(
+        "comparison-group",
+        lam,
+        pi,
+        var_pi,
+        theta,
+        se,
+        n_sites,
+        {"comparison_ratio": rc, "comparison_ratio_rel_var": rel_rc},
+    )
+
+
+def eb_before_after(
+    observed_before: ArrayLike,
+    observed_after: ArrayLike,
+    predicted_before: ArrayLike,
+    predicted_after: ArrayLike,
+    k: ArrayLike,
+) -> BeforeAfterResult:
+    """Empirical Bayes before-after study (Hauer 1997; Persaud & Lyon 2007).
+
+    For every treated site ``i``, with SPF predictions summed over the before
+    (``P_b``) and after (``P_a``) periods::
+
+        w_i   = 1 / (1 + k_i * P_b)
+        E_b   = w_i * P_b + (1 - w_i) * K_i         EB estimate, before period
+        pi_i  = E_b * P_a / P_b                     expected after, untreated
+        Var(pi_i) = (P_a / P_b)**2 * (1 - w_i) * E_b
+
+    Sums over sites give ``pi`` and ``Var(pi)``; ``lambda`` is the summed
+    after count. ``k`` may be one value or one per site (e.g. ``k / L_i``).
+    """
+    kb = np.asarray(observed_before, dtype=float).ravel()
+    la = np.asarray(observed_after, dtype=float).ravel()
+    pb = np.asarray(predicted_before, dtype=float).ravel()
+    pa = np.asarray(predicted_after, dtype=float).ravel()
+    kk = np.broadcast_to(np.asarray(k, dtype=float), kb.shape)
+    if not (kb.shape == la.shape == pb.shape == pa.shape):
+        raise ValueError("all per-site arrays must have the same length")
+    if np.any(pb <= 0) or np.any(pa <= 0):
+        raise ValueError("predicted crashes must be positive")
+    if np.any(kb < 0) or np.any(la < 0) or np.any(kk < 0):
+        raise ValueError("counts and k must not be negative")
+    w = 1.0 / (1.0 + kk * pb)
+    eb_before = w * pb + (1.0 - w) * kb
+    ratio = pa / pb
+    pi_i = eb_before * ratio
+    var_i = ratio**2 * (1.0 - w) * eb_before
+    pi = float(pi_i.sum())
+    var_pi = float(var_i.sum())
+    lam = float(la.sum())
+    theta, se = _hauer(lam, pi, var_pi)
+    return BeforeAfterResult(
+        "empirical-bayes",
+        lam,
+        pi,
+        var_pi,
+        theta,
+        se,
+        int(kb.size),
+        {
+            "weights": w.tolist(),
+            "eb_before": eb_before.tolist(),
+            "expected_after_by_site": pi_i.tolist(),
+        },
+    )