aadtkit 0.1.0__py3-none-any.whl

aadtkit/cli.py

@@ -0,0 +1,307 @@
+"""Command-line interface: ``aadtkit <command> ...``.
+
+Commands read the hourly CSV layout described in :mod:`aadtkit.io` and write
+CSV to standard output or to ``-o FILE``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Dict, List, Mapping, Optional, Sequence
+
+from . import __version__
+from .aadt import AADTResult, aadt_aashto, aadt_hourly_weighted, aadt_simple, daily_totals
+from .classification import CLASS_DESCRIPTIONS, class_shares
+from .errors import AADTKitError
+from .expand import short_count_aadt
+from .factors import cluster_stations, factors_from_result, group_factors
+from .io import (
+    by_direction,
+    by_station,
+    class_totals,
+    duplicate_keys,
+    read_factors_csv,
+    read_hourly_csv,
+    write_factors_csv,
+    write_rows_csv,
+)
+from .peak import d_factor, nth_highest_hour
+from .quality import check_hourly
+
+__all__ = ["main"]
+
+
+def _compute(series, method: str, year: Optional[int], allow_missing: bool) -> AADTResult:
+    if method == "hourly":
+        return aadt_hourly_weighted(series, year=year, allow_missing_cells=allow_missing)
+    daily = daily_totals(series)
+    if year is not None:
+        daily = {d: v for d, v in daily.items() if d.year == year}
+    if method == "aashto":
+        return aadt_aashto(daily, year=year, allow_missing_cells=allow_missing)
+    return aadt_simple(daily)
+
+
+def _emit(
+    args: argparse.Namespace, rows: Sequence[Mapping[str, object]], fields: Sequence[str]
+) -> None:
+    if getattr(args, "output", None):
+        write_rows_csv(args.output, rows, fields)
+    else:
+        write_rows_csv(sys.stdout, rows, fields)
+
+
+def _read(args: argparse.Namespace):
+    return read_hourly_csv(args.file, hour_convention="ending" if args.hour_ending else "beginning")
+
+
+def _cmd_aadt(args: argparse.Namespace) -> int:
+    rows = []
+    for st, series in by_station(_read(args)).items():
+        res = _compute(series, args.method, args.year, args.allow_missing)
+        rows.append(
+            {
+                "station": st,
+                "method": res.method,
+                "year": res.year if res.year is not None else "",
+                "aadt": f"{res.aadt:.1f}",
+                "complete_days": len(daily_totals(series)),
+                "missing_cells": len(res.missing_cells),
+            }
+        )
+    _emit(args, rows, ["station", "method", "year", "aadt", "complete_days", "missing_cells"])
+    return 0
+
+
+def _cmd_factors(args: argparse.Namespace) -> int:
+    sets = []
+    for st, series in by_station(_read(args)).items():
+        res = _compute(series, args.method, args.year, args.allow_missing)
+        sets.append(factors_from_result(res, name=st))
+    if args.group:
+        sets.append(group_factors(sets, name=args.group))
+    if args.output:
+        write_factors_csv(args.output, sets)
+    else:
+        write_factors_csv(sys.stdout, sets)
+    return 0
+
+
+def _cmd_cluster(args: argparse.Namespace) -> int:
+    sets = list(read_factors_csv(args.factors).values())
+    res = cluster_stations(sets, args.k, features=args.features, seed=args.seed)
+    rows = [{"station": s, "group": g} for s, g in res.labels.items()]
+    _emit(args, rows, ["station", "group"])
+    return 0
+
+
+def _cmd_expand(args: argparse.Namespace) -> int:
+    table = read_factors_csv(args.factors)
+    if args.group:
+        if args.group not in table:
+            raise AADTKitError(f"factor set {args.group!r} not in {sorted(table)}")
+        fs = table[args.group]
+    elif len(table) == 1:
+        fs = next(iter(table.values()))
+    else:
+        raise AADTKitError(f"factor file has several sets {sorted(table)}; pass --group")
+    rows = []
+    for st, series in by_station(_read(args)).items():
+        est = short_count_aadt(
+            series, fs, axle_factor=args.axle_factor, growth=args.growth, basis=args.basis
+        )
+        rows.append(
+            {
+                "station": st,
+                "periods": len(est.periods),
+                "raw_adt": f"{est.raw_adt:.1f}",
+                "aadt": f"{est.aadt:.1f}",
+                "factor_set": fs.name,
+            }
+        )
+    _emit(args, rows, ["station", "periods", "raw_adt", "aadt", "factor_set"])
+    return 0
+
+
+def _cmd_peak(args: argparse.Namespace) -> int:
+    recs = _read(args)
+    rows = []
+    for st, series in by_station(recs).items():
+        aadt = args.aadt
+        if aadt is None:
+            aadt = _compute(series, "hourly", args.year, True).aadt
+        hour, vol = nth_highest_hour(series, args.nth)
+        row: Dict[str, object] = {
+            "station": st,
+            "aadt": f"{aadt:.1f}",
+            "nth": args.nth,
+            "hour": hour.strftime("%Y-%m-%d %H:%M"),
+            "volume": f"{vol:g}",
+            "k_factor": f"{vol / aadt:.4f}",
+            "d_factor": "",
+            "peak_direction": "",
+        }
+        dirs = {k: v for k, v in by_direction(recs, st).items() if k}
+        if len(dirs) >= 2:
+            d = d_factor(dirs, args.nth)
+            row["d_factor"] = f"{d.d:.4f}"
+            row["peak_direction"] = d.peak_direction
+        rows.append(row)
+    _emit(
+        args,
+        rows,
+        ["station", "aadt", "nth", "hour", "volume", "k_factor", "d_factor", "peak_direction"],
+    )
+    return 0
+
+
+def _cmd_qc(args: argparse.Namespace) -> int:
+    recs = _read(args)
+    rows: List[Dict[str, object]] = []
+    for st, hour, direction, vc in duplicate_keys(recs):
+        rows.append(
+            {
+                "station": st,
+                "kind": "duplicate",
+                "start": hour.strftime("%Y-%m-%d %H:%M"),
+                "end": hour.strftime("%Y-%m-%d %H:%M"),
+                "hours": 1,
+                "detail": f"direction={direction!r} class={vc}",
+            }
+        )
+    for st, series in by_station(recs).items():
+        rep = check_hourly(
+            series,
+            zero_run_hours=args.zero_run,
+            constant_run_hours=args.constant_run,
+            max_hourly=args.max_hourly,
+            outlier_z=args.outlier_z,
+        )
+        for i in rep.issues:
+            rows.append(
+                {
+                    "station": st,
+                    "kind": i.kind,
+                    "start": i.start.strftime("%Y-%m-%d %H:%M"),
+                    "end": i.end.strftime("%Y-%m-%d %H:%M"),
+                    "hours": i.hours,
+                    "detail": i.detail,
+                }
+            )
+        print(
+            f"{st}: {rep.n_hours}/{rep.n_expected} hours ({rep.completeness:.1%}), "
+            f"{len(rep.issues)} issue(s)",
+            file=sys.stderr,
+        )
+    _emit(args, rows, ["station", "kind", "start", "end", "hours", "detail"])
+    return 1 if rows and args.strict else 0
+
+
+def _cmd_classes(args: argparse.Namespace) -> int:
+    recs = _read(args)
+    rows = []
+    stations = sorted({r.station for r in recs}) if args.station is None else [args.station]
+    for st in stations:
+        totals = class_totals(recs, st)
+        if not totals:
+            continue
+        shares = class_shares(totals)
+        for c in range(1, 14):
+            rows.append(
+                {
+                    "station": st,
+                    "class": c,
+                    "description": CLASS_DESCRIPTIONS[c],
+                    "volume": f"{totals.get(c, 0.0):g}",
+                    "share": f"{shares[c]:.4f}",
+                }
+            )
+    if not rows:
+        raise AADTKitError("no records with a vehicle_class column value")
+    _emit(args, rows, ["station", "class", "description", "volume", "share"])
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="aadtkit",
+        description="Traffic count processing and AADT estimation (FHWA Traffic Monitoring Guide).",
+    )
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    def common(sp: argparse.ArgumentParser, output: bool = True) -> None:
+        sp.add_argument("file", help="hourly count CSV")
+        sp.add_argument(
+            "--hour-ending", action="store_true", help="timestamps/hours mark the end of the hour"
+        )
+        if output:
+            sp.add_argument("-o", "--output", help="output CSV (default: stdout)")
+
+    def method(sp: argparse.ArgumentParser) -> None:
+        sp.add_argument("--method", choices=["hourly", "aashto", "simple"], default="hourly")
+        sp.add_argument("--year", type=int)
+        sp.add_argument(
+            "--allow-missing", action="store_true", help="skip empty month/day-of-week cells"
+        )
+
+    sp = sub.add_parser("aadt", help="AADT of continuous count stations")
+    common(sp)
+    method(sp)
+    sp.set_defaults(func=_cmd_aadt)
+
+    sp = sub.add_parser("factors", help="monthly and day-of-week factors per station")
+    common(sp)
+    method(sp)
+    sp.add_argument("--group", help="also write the average of all stations under this name")
+    sp.set_defaults(func=_cmd_factors)
+
+    sp = sub.add_parser("cluster", help="k-means factor groups from a factor CSV")
+    sp.add_argument("factors", help="factor CSV (from 'aadtkit factors')")
+    sp.add_argument("-k", type=int, required=True, help="number of groups")
+    sp.add_argument("--features", choices=["monthly", "dow", "both"], default="monthly")
+    sp.add_argument("--seed", type=int, default=0)
+    sp.add_argument("-o", "--output")
+    sp.set_defaults(func=_cmd_cluster)
+
+    sp = sub.add_parser("expand", help="expand short counts to AADT")
+    common(sp)
+    sp.add_argument("--factors", required=True, help="factor CSV")
+    sp.add_argument("--group", help="factor set name inside the factor CSV")
+    sp.add_argument("--axle-factor", type=float, default=1.0)
+    sp.add_argument("--growth", type=float, default=1.0)
+    sp.add_argument("--basis", choices=["calendar", "blocks"], default="calendar")
+    sp.set_defaults(func=_cmd_expand)
+
+    sp = sub.add_parser("peak", help="K-factor (n-th highest hour) and D-factor")
+    common(sp)
+    sp.add_argument("--aadt", type=float, help="AADT (default: computed, hourly method)")
+    sp.add_argument("--nth", type=int, default=30)
+    sp.add_argument("--year", type=int)
+    sp.set_defaults(func=_cmd_peak)
+
+    sp = sub.add_parser("qc", help="data-quality checks")
+    common(sp)
+    sp.add_argument("--zero-run", type=int, default=6)
+    sp.add_argument("--constant-run", type=int, default=4)
+    sp.add_argument("--max-hourly", type=float)
+    sp.add_argument("--outlier-z", type=float, default=5.0)
+    sp.add_argument("--strict", action="store_true", help="exit 1 when issues are found")
+    sp.set_defaults(func=_cmd_qc)
+
+    sp = sub.add_parser("classes", help="FHWA 13-class vehicle shares")
+    common(sp)
+    sp.add_argument("--station")
+    sp.set_defaults(func=_cmd_classes)
+    return p
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """Entry point of the ``aadtkit`` command."""
+    args = build_parser().parse_args(argv)
+    try:
+        return int(args.func(args))
+    except (AADTKitError, ValueError, OSError) as exc:
+        print(f"aadtkit: error: {exc}", file=sys.stderr)
+        return 2

aadtkit/errors.py

@@ -0,0 +1,17 @@
+"""Exceptions raised by aadtkit."""
+
+from __future__ import annotations
+
+__all__ = ["AADTKitError", "CSVFormatError", "InsufficientDataError"]
+
+
+class AADTKitError(Exception):
+    """Base class for aadtkit errors."""
+
+
+class InsufficientDataError(AADTKitError, ValueError):
+    """The data do not meet the minimum requirements of the requested method."""
+
+
+class CSVFormatError(AADTKitError, ValueError):
+    """A CSV file is missing required columns or holds unparsable values."""

aadtkit/expand.py

@@ -0,0 +1,148 @@
+"""Expansion of short-duration counts to AADT.
+
+A short count (typically 24-48 h, or 7 days with automatic counters; TMG
+2022, Sections 3.2.1 and 3.4.2) is converted to AADT with multiplicative
+adjustment factors::
+
+    AADT_est = VOL_24 * M * D * A * G
+
+where ``VOL_24`` is a 24-hour volume, ``M`` the monthly (seasonal) factor,
+``D`` the day-of-week factor (or a single month x day-of-week factor ``M*D``),
+``A`` the axle-correction factor (only for axle-sensor counts) and ``G`` a
+growth factor when the count year differs from the estimate year. The 2001 TMG
+(Section 3) lists the adjustments as axle correction, day-of-week and month;
+TMG 2022 Section 3.2.8 applies them multiplicatively, seasonality first, e.g.
+``518 x 0.95 x 1.24 = 610``. With several 24-hour periods the factored daily
+values are averaged. (The single-line equation above is the conventional
+textbook notation; FHWA prints it as images, so it is reproduced here from the
+described procedure rather than quoted.)
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass, field
+from typing import Dict, List, Mapping, Tuple
+
+from .aadt import daily_totals
+from .errors import InsufficientDataError
+from .factors import FactorSet
+
+__all__ = [
+    "ShortCountEstimate",
+    "expand_volume",
+    "growth_factor",
+    "short_count_aadt",
+    "split_24h_blocks",
+]
+
+
+def growth_factor(annual_rate: float, years: float) -> float:
+    """Compound growth factor ``(1 + r) ** years`` (``years`` may be negative)."""
+    if annual_rate <= -1:
+        raise ValueError("annual_rate must be > -1")
+    return float((1.0 + annual_rate) ** years)
+
+
+def expand_volume(
+    volume: float,
+    day: dt.date,
+    factors: FactorSet,
+    *,
+    axle_factor: float = 1.0,
+    growth: float = 1.0,
+    use_month_dow: bool = True,
+) -> float:
+    """Expand one 24-hour volume counted on ``day`` to an AADT estimate."""
+    return volume * factors.factor(day, use_month_dow=use_month_dow) * axle_factor * growth
+
+
+@dataclass
+class ShortCountEstimate:
+    """AADT estimated from a short count.
+
+    Attributes:
+        aadt: mean of the factored 24-hour estimates.
+        raw_adt: mean unfactored 24-hour volume (average daily traffic of the count).
+        periods: ``(period start, raw 24-h volume, combined factor, estimate)``.
+        axle_factor, growth: factors applied to every period.
+    """
+
+    aadt: float
+    raw_adt: float
+    periods: List[Tuple[dt.datetime, float, float, float]] = field(default_factory=list)
+    axle_factor: float = 1.0
+    growth: float = 1.0
+
+
+def split_24h_blocks(hourly: Mapping[dt.datetime, float]) -> List[List[dt.datetime]]:
+    """Split hour stamps into non-overlapping runs of 24 consecutive hours.
+
+    Gaps break runs; leftover hours at the end of a run (< 24) are discarded.
+    """
+    hours = sorted({ts.replace(minute=0, second=0, microsecond=0) for ts in hourly})
+    blocks: List[List[dt.datetime]] = []
+    run: List[dt.datetime] = []
+    for h in hours:
+        if run and h - run[-1] != dt.timedelta(hours=1):
+            run = []
+        run.append(h)
+        if len(run) == 24:
+            blocks.append(run)
+            run = []
+    return blocks
+
+
+def short_count_aadt(
+    hourly: Mapping[dt.datetime, float],
+    factors: FactorSet,
+    *,
+    axle_factor: float = 1.0,
+    growth: float = 1.0,
+    basis: str = "calendar",
+    use_month_dow: bool = True,
+) -> ShortCountEstimate:
+    """Estimate AADT from an hourly short count.
+
+    Args:
+        hourly: ``{hour-start datetime: volume}`` of the short count.
+        factors: station or group factors, e.g. from :func:`~aadtkit.group_factors`.
+        axle_factor: axle-correction factor for axle-sensor counts (1 otherwise).
+        growth: growth factor to the estimate year.
+        basis: ``"calendar"`` uses complete calendar days (midnight to
+            midnight); ``"blocks"`` uses consecutive 24-hour blocks from the
+            first counted hour, so a 48-h count starting at noon yields two
+            periods; each hour is factored with the factor of its own calendar
+            day.
+        use_month_dow: prefer month x day-of-week factors when present.
+    """
+    hourly_n: Dict[dt.datetime, float] = {}
+    for ts, v in hourly.items():
+        h = ts.replace(minute=0, second=0, microsecond=0)
+        hourly_n[h] = hourly_n.get(h, 0.0) + float(v)
+    periods: List[Tuple[dt.datetime, float, float, float]] = []
+    if basis == "calendar":
+        for day, vol in daily_totals(hourly_n).items():
+            f = factors.factor(day, use_month_dow=use_month_dow)
+            start = dt.datetime.combine(day, dt.time())
+            periods.append((start, vol, f, vol * f * axle_factor * growth))
+    elif basis == "blocks":
+        for block in split_24h_blocks(hourly_n):
+            raw = sum(hourly_n[h] for h in block)
+            est = sum(
+                hourly_n[h] * factors.factor(h.date(), use_month_dow=use_month_dow) for h in block
+            )
+            f = est / raw if raw else factors.factor(block[0].date(), use_month_dow=use_month_dow)
+            periods.append((block[0], raw, f, est * axle_factor * growth))
+    else:
+        raise ValueError("basis must be 'calendar' or 'blocks'")
+    if not periods:
+        raise InsufficientDataError("short count contains no complete 24-hour period")
+    n = len(periods)
+    return ShortCountEstimate(
+        aadt=sum(p[3] for p in periods) / n,
+        raw_adt=sum(p[1] for p in periods) / n,
+        periods=periods,
+        axle_factor=axle_factor,
+        growth=growth,
+    )