aadtkit 0.1.0__py3-none-any.whl

aadtkit/__init__.py

@@ -0,0 +1,134 @@
+"""aadtkit: traffic count processing and AADT estimation.
+
+Implements the continuous-count and short-count procedures of the FHWA
+*Traffic Monitoring Guide* (TMG 2022, with the AASHTO method as given in
+TMG 2013): AADT from continuous count stations, monthly and day-of-week
+expansion factors, factor groups, short-count expansion with axle-correction
+and growth factors, K-, D- and peak-hour factors, FHWA 13-class vehicle
+shares, data-quality checks and CSV I/O for hourly counts.
+"""
+
+from ._version import __version__
+from .aadt import (
+    DOW_NAMES,
+    AADTResult,
+    aadt_aashto,
+    aadt_hourly_weighted,
+    aadt_simple,
+    daily_totals,
+    dow_occurrences,
+    madt,
+)
+from .classification import (
+    CLASS_DESCRIPTIONS,
+    DEFAULT_GROUPS,
+    FHWAClass,
+    class_shares,
+    group_shares,
+    truck_share,
+)
+from .errors import AADTKitError, CSVFormatError, InsufficientDataError
+from .expand import (
+    ShortCountEstimate,
+    expand_volume,
+    growth_factor,
+    short_count_aadt,
+    split_24h_blocks,
+)
+from .factors import (
+    DEFAULT_AXLES_PER_CLASS,
+    ClusterResult,
+    FactorGroup,
+    FactorSet,
+    FactorStats,
+    axle_correction_factor,
+    axle_correction_from_classes,
+    cluster_stations,
+    factors_from_result,
+    group_factors,
+    t_critical_95,
+)
+from .io import (
+    HourlyRecord,
+    by_direction,
+    by_station,
+    class_totals,
+    duplicate_keys,
+    read_factors_csv,
+    read_hourly_csv,
+    to_series,
+    write_factors_csv,
+    write_hourly_csv,
+    write_rows_csv,
+)
+from .peak import (
+    DFactor,
+    PeakHour,
+    d_factor,
+    design_hour_volume,
+    highest_hours,
+    k_factor,
+    nth_highest_hour,
+    peak_hour_factor,
+)
+from .quality import QualityIssue, QualityReport, check_hourly, drop_flagged
+
+__all__ = [
+    "AADTKitError",
+    "AADTResult",
+    "CLASS_DESCRIPTIONS",
+    "CSVFormatError",
+    "ClusterResult",
+    "DEFAULT_AXLES_PER_CLASS",
+    "DEFAULT_GROUPS",
+    "DFactor",
+    "DOW_NAMES",
+    "FHWAClass",
+    "FactorGroup",
+    "FactorSet",
+    "FactorStats",
+    "HourlyRecord",
+    "InsufficientDataError",
+    "PeakHour",
+    "QualityIssue",
+    "QualityReport",
+    "ShortCountEstimate",
+    "__version__",
+    "aadt_aashto",
+    "aadt_hourly_weighted",
+    "aadt_simple",
+    "axle_correction_factor",
+    "axle_correction_from_classes",
+    "by_direction",
+    "by_station",
+    "check_hourly",
+    "class_shares",
+    "class_totals",
+    "cluster_stations",
+    "d_factor",
+    "daily_totals",
+    "design_hour_volume",
+    "dow_occurrences",
+    "drop_flagged",
+    "duplicate_keys",
+    "expand_volume",
+    "factors_from_result",
+    "group_factors",
+    "group_shares",
+    "growth_factor",
+    "highest_hours",
+    "k_factor",
+    "madt",
+    "nth_highest_hour",
+    "peak_hour_factor",
+    "read_factors_csv",
+    "read_hourly_csv",
+    "short_count_aadt",
+    "split_24h_blocks",
+    "t_critical_95",
+    "to_series",
+    "truck_share",
+    "write_factors_csv",
+    "write_hourly_csv",
+    "write_rows_csv",
+]

aadtkit/__main__.py

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

aadtkit/_version.py

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

aadtkit/aadt.py

@@ -0,0 +1,282 @@
+"""AADT computation for continuous count stations (CCS).
+
+Three estimators are provided:
+
+``aadt_aashto``
+    The AASHTO method as published in the FHWA *Traffic Monitoring Guide*
+    (TMG 2013, Section 3.2.1, Step 7; adopted by FHWA and by the AASHTO
+    *Guidelines for Traffic Data Programs*)::
+
+        AADT = 1/7 * sum_i [ 1/12 * sum_j ( 1/n_ij * sum_k VOL_ijk ) ]
+
+    where ``VOL_ijk`` is the daily traffic of the k-th occurrence of day of
+    week *i* in month *j* and ``n_ij`` the number of such days with data. The
+    inner mean is the *monthly average day of week* (MADW).
+
+``aadt_hourly_weighted``
+    The hour-based procedure recommended by FHWA since 2016 (TMG 2022,
+    Section 3.1.4.7, Step 3)::
+
+        MADT_m = sum_j w_jm * sum_h (1/n_hjm * sum_i VOL_ihjm) / sum_j w_jm
+        AADT   = sum_m d_m * MADT_m / sum_m d_m
+
+    with ``w_jm`` the number of times day of week *j* occurs in month *m* of
+    the calendar year (4 or 5) and ``d_m`` the number of days in month *m*.
+    Averaging at the hour level lets days with a few missing hours still
+    contribute, and the calendar weights remove the bias of giving every day
+    of week and every month the same weight.
+
+``aadt_simple``
+    Plain mean of all complete days (exact when a full year is available).
+
+Days of week are indexed 0 = Monday ... 6 = Sunday (Python ``weekday()``).
+Months are 1..12. Hourly series are mappings ``{hour-start datetime: volume}``.
+"""
+
+from __future__ import annotations
+
+import calendar
+import datetime as dt
+from collections import defaultdict
+from dataclasses import dataclass, field
+from typing import Dict, List, Mapping, Optional, Tuple
+
+from .errors import InsufficientDataError
+
+__all__ = [
+    "AADTResult",
+    "DOW_NAMES",
+    "aadt_aashto",
+    "aadt_hourly_weighted",
+    "aadt_simple",
+    "daily_totals",
+    "dow_occurrences",
+    "madt",
+]
+
+HourlySeries = Mapping[dt.datetime, float]
+DailySeries = Mapping[dt.date, float]
+
+#: Short names for day-of-week indices 0..6 (Monday first, as ``date.weekday()``).
+DOW_NAMES: Tuple[str, ...] = ("Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun")
+
+
+@dataclass
+class AADTResult:
+    """Result of a continuous-count AADT computation.
+
+    Attributes:
+        aadt: annual average daily traffic.
+        method: ``"aashto"``, ``"hourly_weighted"`` or ``"simple"``.
+        year: calendar year the estimate refers to (``None`` for ``simple``
+            over an arbitrary span).
+        madw: monthly average day-of-week volume keyed by ``(month, dow)``.
+        madt: monthly average daily traffic keyed by month, as used by the
+            method (unweighted mean of the seven MADW for ``aashto``,
+            calendar-weighted for ``hourly_weighted``).
+        n_days: number of days (or, for ``hourly_weighted``, the minimum
+            number of hour occurrences) behind each ``(month, dow)`` cell.
+        missing_cells: ``(month, dow)`` cells without data that were skipped.
+    """
+
+    aadt: float
+    method: str
+    year: Optional[int] = None
+    madw: Dict[Tuple[int, int], float] = field(default_factory=dict)
+    madt: Dict[int, float] = field(default_factory=dict)
+    n_days: Dict[Tuple[int, int], int] = field(default_factory=dict)
+    missing_cells: List[Tuple[int, int]] = field(default_factory=list)
+
+    def dow_average(self) -> Dict[int, float]:
+        """Annual average volume for each day of week (mean of its MADW over months)."""
+        acc: Dict[int, List[float]] = defaultdict(list)
+        for (_, j), v in self.madw.items():
+            acc[j].append(v)
+        return {j: sum(vs) / len(vs) for j, vs in sorted(acc.items())}
+
+
+def _hour_start(ts: dt.datetime) -> dt.datetime:
+    return ts.replace(minute=0, second=0, microsecond=0)
+
+
+def daily_totals(hourly: HourlySeries) -> Dict[dt.date, float]:
+    """Sum hourly volumes into daily totals, keeping only complete days.
+
+    A day is complete when all 24 hour-start slots 00..23 carry a value.
+    Incomplete days are dropped, never scaled up (TMG discourages imputation
+    of missing data, TMG 2013 Section 3.2.3).
+    """
+    hours: Dict[dt.date, Dict[int, float]] = defaultdict(dict)
+    for ts, vol in hourly.items():
+        h = _hour_start(ts)
+        slot = hours[h.date()]
+        slot[h.hour] = slot.get(h.hour, 0.0) + float(vol)
+    return {d: sum(s.values()) for d, s in sorted(hours.items()) if len(s) == 24}
+
+
+def aadt_simple(daily: DailySeries) -> AADTResult:
+    """AADT as the plain mean of the daily totals supplied."""
+    if not daily:
+        raise InsufficientDataError("no complete days available")
+    vals = list(daily.values())
+    years = {d.year for d in daily}
+    year = years.pop() if len(years) == 1 else None
+    return AADTResult(aadt=sum(vals) / len(vals), method="simple", year=year)
+
+
+def madt(daily: DailySeries) -> Dict[int, float]:
+    """Simple monthly average daily traffic (mean of the days in each month)."""
+    acc: Dict[int, List[float]] = defaultdict(list)
+    for d, v in daily.items():
+        acc[d.month].append(float(v))
+    return {m: sum(vs) / len(vs) for m, vs in sorted(acc.items())}
+
+
+def _pick_year(dates: List[dt.date], year: Optional[int]) -> int:
+    if year is not None:
+        return year
+    years = sorted({d.year for d in dates})
+    if not years:
+        raise InsufficientDataError("no data")
+    if len(years) > 1:
+        raise ValueError(f"data span several years {years}; pass year=")
+    return years[0]
+
+
+def aadt_aashto(
+    daily: DailySeries,
+    *,
+    year: Optional[int] = None,
+    allow_missing_cells: bool = False,
+) -> AADTResult:
+    """AADT by the AASHTO method from daily totals (TMG 2013, Section 3.2.1).
+
+    Args:
+        daily: complete-day totals, e.g. from :func:`daily_totals`.
+        year: calendar year to use; required if ``daily`` spans several years.
+        allow_missing_cells: the method needs at least one day for each of the
+            84 month x day-of-week cells. When ``True`` empty cells are skipped:
+            a month is averaged over its available days of week and the year
+            over the months that have any data. This departs from the standard
+            and is recorded in ``missing_cells``.
+
+    Raises:
+        InsufficientDataError: a cell is empty and ``allow_missing_cells`` is
+            ``False``, or there is no data at all.
+    """
+    y = _pick_year(list(daily), year)
+    cells: Dict[Tuple[int, int], List[float]] = defaultdict(list)
+    for d, v in daily.items():
+        if d.year == y:
+            cells[(d.month, d.weekday())].append(float(v))
+    if not cells:
+        raise InsufficientDataError(f"no complete days in {y}")
+    missing = [(m, j) for m in range(1, 13) for j in range(7) if (m, j) not in cells]
+    if missing and not allow_missing_cells:
+        raise InsufficientDataError(
+            f"{len(missing)} of 84 month/day-of-week cells have no complete day "
+            f"(first: month {missing[0][0]}, {DOW_NAMES[missing[0][1]]}); "
+            "use allow_missing_cells=True to skip them"
+        )
+    madw = {k: sum(v) / len(v) for k, v in sorted(cells.items())}
+    # Monthly means of MADW, then mean over months (summation order is
+    # immaterial when all 84 cells are present).
+    per_month: Dict[int, List[float]] = defaultdict(list)
+    for (m, _), v in madw.items():
+        per_month[m].append(v)
+    madt_m = {m: sum(vs) / len(vs) for m, vs in sorted(per_month.items())}
+    if missing:
+        aadt = sum(madt_m.values()) / len(madt_m)
+    else:
+        # Literal TMG order: average over months for each DOW, then over DOW.
+        aadt = sum(sum(madw[(m, j)] for m in range(1, 13)) / 12.0 for j in range(7)) / 7.0
+    return AADTResult(
+        aadt=aadt,
+        method="aashto",
+        year=y,
+        madw=madw,
+        madt=madt_m,
+        n_days={k: len(v) for k, v in cells.items()},
+        missing_cells=missing,
+    )
+
+
+def dow_occurrences(year: int, month: int) -> Dict[int, int]:
+    """Number of times each day of week (0=Mon) occurs in a calendar month (w_jm)."""
+    counts = dict.fromkeys(range(7), 0)
+    for day in range(1, calendar.monthrange(year, month)[1] + 1):
+        counts[dt.date(year, month, day).weekday()] += 1
+    return counts
+
+
+def aadt_hourly_weighted(
+    hourly: HourlySeries,
+    *,
+    year: Optional[int] = None,
+    allow_missing_cells: bool = False,
+) -> AADTResult:
+    """AADT by the FHWA hour-based weighted AASHTO procedure (TMG 2022, 3.1.4.7).
+
+    For every month *m*, day of week *j* and hour *h* the volumes of all
+    occurrences with data are averaged; the 24 hourly means are summed to the
+    MADW; months weight days of week by their calendar occurrences ``w_jm``
+    and the year weights months by their length ``d_m``.
+
+    Args:
+        hourly: ``{hour-start datetime: volume}``; partial days are allowed.
+        year: calendar year; required when the data span several years.
+        allow_missing_cells: a (month, dow) cell is usable only if all 24 hours
+            have at least one occurrence. When ``True``, unusable cells are
+            dropped from the weights of their month (and months without any
+            usable cell from the year); otherwise an error is raised.
+    """
+    y = _pick_year([ts.date() for ts in hourly], year)
+    acc: Dict[Tuple[int, int, int], List[float]] = defaultdict(list)
+    # Sum duplicates of the same hour first (e.g. per-direction rows).
+    per_hour: Dict[dt.datetime, float] = defaultdict(float)
+    for ts, v in hourly.items():
+        h = _hour_start(ts)
+        if h.year == y:
+            per_hour[h] += float(v)
+    for h, v in per_hour.items():
+        acc[(h.month, h.weekday(), h.hour)].append(v)
+    if not acc:
+        raise InsufficientDataError(f"no hourly data in {y}")
+
+    madw: Dict[Tuple[int, int], float] = {}
+    n_occ: Dict[Tuple[int, int], int] = {}
+    missing: List[Tuple[int, int]] = []
+    for m in range(1, 13):
+        for j in range(7):
+            hours = [acc.get((m, j, hr)) for hr in range(24)]
+            if any(not x for x in hours):
+                missing.append((m, j))
+                continue
+            madw[(m, j)] = sum(sum(x) / len(x) for x in hours if x)
+            n_occ[(m, j)] = min(len(x) for x in hours if x)
+    if missing and not allow_missing_cells:
+        m0, j0 = missing[0]
+        raise InsufficientDataError(
+            f"{len(missing)} of 84 month/day-of-week cells lack some hour of day "
+            f"(first: month {m0}, {DOW_NAMES[j0]}); use allow_missing_cells=True"
+        )
+    madt_m: Dict[int, float] = {}
+    for m in range(1, 13):
+        w = dow_occurrences(y, m)
+        num = sum(w[j] * madw[(m, j)] for j in range(7) if (m, j) in madw)
+        den = sum(w[j] for j in range(7) if (m, j) in madw)
+        if den:
+            madt_m[m] = num / den
+    if not madt_m:
+        raise InsufficientDataError(f"no usable month in {y}")
+    d = {m: calendar.monthrange(y, m)[1] for m in madt_m}
+    aadt = sum(d[m] * madt_m[m] for m in madt_m) / sum(d.values())
+    return AADTResult(
+        aadt=aadt,
+        method="hourly_weighted",
+        year=y,
+        madw=madw,
+        madt=madt_m,
+        n_days=n_occ,
+        missing_cells=missing,
+    )

aadtkit/classification.py

@@ -0,0 +1,105 @@
+"""FHWA 13-category vehicle classification and class shares.
+
+Class definitions follow the FHWA 13-category vehicle classification scheme
+reproduced in the *Traffic Monitoring Guide* (TMG 2022). The default aggregate groups follow HPMS reporting,
+which records single-unit truck and bus volume (classes 4-7) and combination
+truck volume (classes 8-13) separately; pass your own ``groups`` mapping to
+use another aggregation.
+"""
+
+from __future__ import annotations
+
+from enum import IntEnum
+from typing import Dict, Mapping, Optional, Sequence
+
+__all__ = [
+    "CLASS_DESCRIPTIONS",
+    "DEFAULT_GROUPS",
+    "FHWAClass",
+    "class_shares",
+    "group_shares",
+    "truck_share",
+]
+
+
+class FHWAClass(IntEnum):
+    """The 13 FHWA vehicle classes."""
+
+    MOTORCYCLE = 1
+    PASSENGER_CAR = 2
+    OTHER_2AXLE_4TIRE = 3
+    BUS = 4
+    SU_2AXLE_6TIRE = 5
+    SU_3AXLE = 6
+    SU_4PLUS_AXLE = 7
+    ST_4OR_FEWER_AXLE = 8
+    ST_5AXLE = 9
+    ST_6PLUS_AXLE = 10
+    MT_5OR_FEWER_AXLE = 11
+    MT_6AXLE = 12
+    MT_7PLUS_AXLE = 13
+
+
+#: Short descriptions of the FHWA classes.
+CLASS_DESCRIPTIONS: Dict[int, str] = {
+    1: "Motorcycles",
+    2: "Passenger cars",
+    3: "Other two-axle, four-tire single-unit vehicles",
+    4: "Buses",
+    5: "Two-axle, six-tire, single-unit trucks",
+    6: "Three-axle single-unit trucks",
+    7: "Four or more axle single-unit trucks",
+    8: "Four or fewer axle single-trailer trucks",
+    9: "Five-axle single-trailer trucks",
+    10: "Six or more axle single-trailer trucks",
+    11: "Five or fewer axle multi-trailer trucks",
+    12: "Six-axle multi-trailer trucks",
+    13: "Seven or more axle multi-trailer trucks",
+}
+
+#: Default aggregation of classes (HPMS-style).
+DEFAULT_GROUPS: Dict[str, Sequence[int]] = {
+    "motorcycles": (1,),
+    "passenger_vehicles": (2, 3),
+    "single_unit_truck_and_bus": (4, 5, 6, 7),
+    "combination_truck": (8, 9, 10, 11, 12, 13),
+}
+
+
+def _validate(counts: Mapping[int, float]) -> Dict[int, float]:
+    out: Dict[int, float] = {}
+    for c, n in counts.items():
+        ci = int(c)
+        if ci not in CLASS_DESCRIPTIONS:
+            raise ValueError(f"{c!r} is not an FHWA class 1-13")
+        if n < 0:
+            raise ValueError("class counts must be non-negative")
+        out[ci] = out.get(ci, 0.0) + float(n)
+    return out
+
+
+def class_shares(counts: Mapping[int, float]) -> Dict[int, float]:
+    """Share (0-1) of each FHWA class 1-13; absent classes get 0."""
+    c = _validate(counts)
+    total = sum(c.values())
+    if total <= 0:
+        raise ValueError("total count is zero")
+    return {k: c.get(k, 0.0) / total for k in range(1, 14)}
+
+
+def group_shares(
+    counts: Mapping[int, float], groups: Optional[Mapping[str, Sequence[int]]] = None
+) -> Dict[str, float]:
+    """Share of each class group (default :data:`DEFAULT_GROUPS`)."""
+    shares = class_shares(counts)
+    g = DEFAULT_GROUPS if groups is None else groups
+    return {name: sum(shares[int(k)] for k in classes) for name, classes in g.items()}
+
+
+def truck_share(counts: Mapping[int, float], classes: Sequence[int] = range(4, 14)) -> float:
+    """Share of heavy vehicles, by default classes 4-13 (buses and trucks).
+
+    Use ``classes=range(5, 14)`` to exclude buses.
+    """
+    shares = class_shares(counts)
+    return sum(shares[int(k)] for k in classes)