aadtkit 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- aadtkit/__init__.py +134 -0
- aadtkit/__main__.py +7 -0
- aadtkit/_version.py +1 -0
- aadtkit/aadt.py +282 -0
- aadtkit/classification.py +105 -0
- aadtkit/cli.py +307 -0
- aadtkit/errors.py +17 -0
- aadtkit/expand.py +148 -0
- aadtkit/factors.py +372 -0
- aadtkit/io.py +312 -0
- aadtkit/peak.py +154 -0
- aadtkit/py.typed +0 -0
- aadtkit/quality.py +231 -0
- aadtkit-0.1.0.dist-info/METADATA +225 -0
- aadtkit-0.1.0.dist-info/RECORD +19 -0
- aadtkit-0.1.0.dist-info/WHEEL +5 -0
- aadtkit-0.1.0.dist-info/entry_points.txt +2 -0
- aadtkit-0.1.0.dist-info/licenses/LICENSE +21 -0
- aadtkit-0.1.0.dist-info/top_level.txt +1 -0
aadtkit/peak.py
ADDED
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
"""Design-hour characteristics: K-factor, D-factor and peak-hour factor.
|
|
2
|
+
|
|
3
|
+
* **K-factor** (design hour factor): ratio of the design hour volume to AADT,
|
|
4
|
+
where the design hour is conventionally the 30th highest hour of the year
|
|
5
|
+
(``K30 = DHV / AADT``). TMG 2022 Section 3.1.2 lists the 30th highest hour
|
|
6
|
+
among continuous-count outputs and Section 3.1.4.3 uses the ratio of the
|
|
7
|
+
30th highest hourly volume to AADT; the 30th-hour convention itself comes
|
|
8
|
+
from AASHTO *A Policy on Geometric Design of Highways and Streets* (the
|
|
9
|
+
"Green Book").
|
|
10
|
+
* **D-factor** (directional distribution): share of the design-hour volume
|
|
11
|
+
travelling in the peak direction (e.g. TxDOT *Transportation Planning
|
|
12
|
+
Manual* 3.2.1).
|
|
13
|
+
* **Peak-hour factor** (PHF): ``PHF = V / (4 * V15)``, the hourly volume of
|
|
14
|
+
the peak hour divided by four times its highest 15-minute volume, as defined
|
|
15
|
+
in the *Highway Capacity Manual* (TRB).
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
from __future__ import annotations
|
|
19
|
+
|
|
20
|
+
import datetime as dt
|
|
21
|
+
from dataclasses import dataclass
|
|
22
|
+
from typing import Dict, List, Mapping, Sequence, Tuple
|
|
23
|
+
|
|
24
|
+
from .errors import InsufficientDataError
|
|
25
|
+
|
|
26
|
+
__all__ = [
|
|
27
|
+
"DFactor",
|
|
28
|
+
"PeakHour",
|
|
29
|
+
"d_factor",
|
|
30
|
+
"design_hour_volume",
|
|
31
|
+
"highest_hours",
|
|
32
|
+
"k_factor",
|
|
33
|
+
"nth_highest_hour",
|
|
34
|
+
"peak_hour_factor",
|
|
35
|
+
]
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def _per_hour(hourly: Mapping[dt.datetime, float]) -> Dict[dt.datetime, float]:
|
|
39
|
+
out: Dict[dt.datetime, float] = {}
|
|
40
|
+
for ts, v in hourly.items():
|
|
41
|
+
h = ts.replace(minute=0, second=0, microsecond=0)
|
|
42
|
+
out[h] = out.get(h, 0.0) + float(v)
|
|
43
|
+
return out
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def highest_hours(
|
|
47
|
+
hourly: Mapping[dt.datetime, float], n: int = 30
|
|
48
|
+
) -> List[Tuple[dt.datetime, float]]:
|
|
49
|
+
"""The ``n`` highest hourly volumes, in descending order (ties by time)."""
|
|
50
|
+
ranked = sorted(_per_hour(hourly).items(), key=lambda kv: (-kv[1], kv[0]))
|
|
51
|
+
return ranked[:n]
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def nth_highest_hour(hourly: Mapping[dt.datetime, float], n: int = 30) -> Tuple[dt.datetime, float]:
|
|
55
|
+
"""The n-th highest hour ``(hour start, volume)``; ``n=30`` gives the design hour."""
|
|
56
|
+
if n < 1:
|
|
57
|
+
raise ValueError("n must be >= 1")
|
|
58
|
+
top = highest_hours(hourly, n)
|
|
59
|
+
if len(top) < n:
|
|
60
|
+
raise InsufficientDataError(f"only {len(top)} hours available, need {n}")
|
|
61
|
+
return top[n - 1]
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def k_factor(hourly: Mapping[dt.datetime, float], aadt: float, n: int = 30) -> float:
|
|
65
|
+
"""K-factor: n-th highest hourly two-way volume divided by AADT.
|
|
66
|
+
|
|
67
|
+
``hourly`` should cover a full year of the same station (and both
|
|
68
|
+
directions) for the conventional K30.
|
|
69
|
+
"""
|
|
70
|
+
if aadt <= 0:
|
|
71
|
+
raise ValueError("aadt must be positive")
|
|
72
|
+
return nth_highest_hour(hourly, n)[1] / aadt
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def design_hour_volume(aadt: float, k: float, d: float = 1.0) -> float:
|
|
76
|
+
"""Design hour volume ``AADT * K`` (times ``D`` for the directional DDHV)."""
|
|
77
|
+
return aadt * k * d
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
@dataclass
|
|
81
|
+
class DFactor:
|
|
82
|
+
"""Directional distribution at a ranked hour."""
|
|
83
|
+
|
|
84
|
+
d: float
|
|
85
|
+
peak_direction: str
|
|
86
|
+
hour: dt.datetime
|
|
87
|
+
two_way_volume: float
|
|
88
|
+
direction_volumes: Dict[str, float]
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def d_factor(by_direction: Mapping[str, Mapping[dt.datetime, float]], n: int = 30) -> DFactor:
|
|
92
|
+
"""D-factor: peak-direction share of the n-th highest two-way hour.
|
|
93
|
+
|
|
94
|
+
Only hours present for every direction are ranked.
|
|
95
|
+
"""
|
|
96
|
+
if len(by_direction) < 2:
|
|
97
|
+
raise InsufficientDataError("need volumes for at least two directions")
|
|
98
|
+
series = {k: _per_hour(v) for k, v in by_direction.items()}
|
|
99
|
+
common = set.intersection(*(set(s) for s in series.values()))
|
|
100
|
+
two_way = {h: sum(s[h] for s in series.values()) for h in common}
|
|
101
|
+
hour, vol = nth_highest_hour(two_way, n)
|
|
102
|
+
if vol <= 0:
|
|
103
|
+
raise InsufficientDataError("ranked hour has zero volume")
|
|
104
|
+
vols = {k: s[hour] for k, s in series.items()}
|
|
105
|
+
peak = max(vols, key=lambda k: (vols[k], k))
|
|
106
|
+
return DFactor(
|
|
107
|
+
d=vols[peak] / vol,
|
|
108
|
+
peak_direction=peak,
|
|
109
|
+
hour=hour,
|
|
110
|
+
two_way_volume=vol,
|
|
111
|
+
direction_volumes=vols,
|
|
112
|
+
)
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
@dataclass
|
|
116
|
+
class PeakHour:
|
|
117
|
+
"""Peak hour found in a sub-hourly series."""
|
|
118
|
+
|
|
119
|
+
phf: float
|
|
120
|
+
start_index: int
|
|
121
|
+
hourly_volume: float
|
|
122
|
+
max_interval_volume: float
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
def peak_hour_factor(volumes: Sequence[float], intervals_per_hour: int = 4) -> PeakHour:
|
|
126
|
+
"""Peak-hour factor from consecutive sub-hourly counts (HCM definition).
|
|
127
|
+
|
|
128
|
+
The peak hour is the window of ``intervals_per_hour`` consecutive intervals
|
|
129
|
+
with the largest total ``V``; ``PHF = V / (intervals_per_hour * Vmax)``,
|
|
130
|
+
where ``Vmax`` is the largest interval volume inside that window. With
|
|
131
|
+
15-minute data this is ``V / (4 * V15)``; PHF ranges from 0.25 to 1.
|
|
132
|
+
"""
|
|
133
|
+
k = intervals_per_hour
|
|
134
|
+
if k < 1:
|
|
135
|
+
raise ValueError("intervals_per_hour must be >= 1")
|
|
136
|
+
if len(volumes) < k:
|
|
137
|
+
raise InsufficientDataError(f"need at least {k} intervals")
|
|
138
|
+
vals = [float(v) for v in volumes]
|
|
139
|
+
best_i, best_v = 0, sum(vals[:k])
|
|
140
|
+
cur = best_v
|
|
141
|
+
for i in range(1, len(vals) - k + 1):
|
|
142
|
+
cur += vals[i + k - 1] - vals[i - 1]
|
|
143
|
+
if cur > best_v + 1e-12:
|
|
144
|
+
best_i, best_v = i, cur
|
|
145
|
+
best_v = sum(vals[best_i : best_i + k])
|
|
146
|
+
vmax = max(vals[best_i : best_i + k])
|
|
147
|
+
if vmax <= 0:
|
|
148
|
+
raise InsufficientDataError("peak hour has zero volume")
|
|
149
|
+
return PeakHour(
|
|
150
|
+
phf=best_v / (k * vmax),
|
|
151
|
+
start_index=best_i,
|
|
152
|
+
hourly_volume=best_v,
|
|
153
|
+
max_interval_volume=vmax,
|
|
154
|
+
)
|
aadtkit/py.typed
ADDED
|
File without changes
|
aadtkit/quality.py
ADDED
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
"""Data-quality checks for hourly traffic counts.
|
|
2
|
+
|
|
3
|
+
TMG 2022 (Chapter 3) asks agencies to
|
|
4
|
+
validate continuous-count data before computing AADT and factors, and TMG
|
|
5
|
+
2013 Section 3.2.3 discourages subjective editing and imputation. The checks
|
|
6
|
+
here flag, but never modify, suspicious data:
|
|
7
|
+
|
|
8
|
+
* ``missing`` - hour slots absent between the first and last hour;
|
|
9
|
+
* ``negative`` - negative volumes;
|
|
10
|
+
* ``zero_run`` - runs of consecutive zero hours (sensor or comms failure);
|
|
11
|
+
* ``constant_run`` - runs of identical non-zero values (stuck counter);
|
|
12
|
+
* ``max_volume`` - hours above a user ceiling (e.g. lane capacity);
|
|
13
|
+
* ``outlier`` - hours far from the typical value for the same day of
|
|
14
|
+
week and hour of day (robust z-score using median and MAD).
|
|
15
|
+
|
|
16
|
+
The default thresholds are engineering judgement, NOT values published by
|
|
17
|
+
FHWA; agencies apply their own validation rules, so every threshold is a
|
|
18
|
+
parameter.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
from __future__ import annotations
|
|
22
|
+
|
|
23
|
+
import datetime as dt
|
|
24
|
+
from collections import defaultdict
|
|
25
|
+
from dataclasses import dataclass, field
|
|
26
|
+
from statistics import median
|
|
27
|
+
from typing import Dict, List, Mapping, Optional, Set, Tuple
|
|
28
|
+
|
|
29
|
+
__all__ = ["QualityIssue", "QualityReport", "check_hourly", "drop_flagged"]
|
|
30
|
+
|
|
31
|
+
_HOUR = dt.timedelta(hours=1)
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
@dataclass
|
|
35
|
+
class QualityIssue:
|
|
36
|
+
"""One flagged hour or run of hours (``start`` .. ``end`` inclusive)."""
|
|
37
|
+
|
|
38
|
+
kind: str
|
|
39
|
+
start: dt.datetime
|
|
40
|
+
end: dt.datetime
|
|
41
|
+
detail: str = ""
|
|
42
|
+
|
|
43
|
+
@property
|
|
44
|
+
def hours(self) -> int:
|
|
45
|
+
return int((self.end - self.start) / _HOUR) + 1
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
@dataclass
|
|
49
|
+
class QualityReport:
|
|
50
|
+
"""Result of :func:`check_hourly`."""
|
|
51
|
+
|
|
52
|
+
first_hour: Optional[dt.datetime]
|
|
53
|
+
last_hour: Optional[dt.datetime]
|
|
54
|
+
n_hours: int
|
|
55
|
+
n_expected: int
|
|
56
|
+
issues: List[QualityIssue] = field(default_factory=list)
|
|
57
|
+
|
|
58
|
+
@property
|
|
59
|
+
def completeness(self) -> float:
|
|
60
|
+
"""Share of expected hour slots that carry data."""
|
|
61
|
+
return self.n_hours / self.n_expected if self.n_expected else 0.0
|
|
62
|
+
|
|
63
|
+
@property
|
|
64
|
+
def ok(self) -> bool:
|
|
65
|
+
return not self.issues
|
|
66
|
+
|
|
67
|
+
def by_kind(self) -> Dict[str, List[QualityIssue]]:
|
|
68
|
+
out: Dict[str, List[QualityIssue]] = defaultdict(list)
|
|
69
|
+
for i in self.issues:
|
|
70
|
+
out[i.kind].append(i)
|
|
71
|
+
return dict(out)
|
|
72
|
+
|
|
73
|
+
def flagged_hours(self, kinds: Optional[Set[str]] = None) -> Set[dt.datetime]:
|
|
74
|
+
"""Hour stamps covered by issues (``missing`` excluded unless asked)."""
|
|
75
|
+
ks = kinds if kinds is not None else {
|
|
76
|
+
"negative", "zero_run", "constant_run", "max_volume", "outlier",
|
|
77
|
+
} # fmt: skip
|
|
78
|
+
out: Set[dt.datetime] = set()
|
|
79
|
+
for i in self.issues:
|
|
80
|
+
if i.kind in ks:
|
|
81
|
+
h = i.start
|
|
82
|
+
while h <= i.end:
|
|
83
|
+
out.add(h)
|
|
84
|
+
h += _HOUR
|
|
85
|
+
return out
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def _runs(
|
|
89
|
+
hours: List[dt.datetime], series: Mapping[dt.datetime, float], pred, same_value: bool
|
|
90
|
+
) -> List[Tuple[dt.datetime, dt.datetime, int, float]]:
|
|
91
|
+
"""Maximal runs of consecutive hours satisfying ``pred`` (and equal values)."""
|
|
92
|
+
runs = []
|
|
93
|
+
start: Optional[dt.datetime] = None
|
|
94
|
+
prev: Optional[dt.datetime] = None
|
|
95
|
+
n = 0
|
|
96
|
+
for h in hours:
|
|
97
|
+
v = series[h]
|
|
98
|
+
cont = (
|
|
99
|
+
start is not None
|
|
100
|
+
and prev is not None
|
|
101
|
+
and h - prev == _HOUR
|
|
102
|
+
and pred(v)
|
|
103
|
+
and (not same_value or v == series[start])
|
|
104
|
+
)
|
|
105
|
+
if cont:
|
|
106
|
+
n += 1
|
|
107
|
+
else:
|
|
108
|
+
if start is not None and prev is not None:
|
|
109
|
+
runs.append((start, prev, n, series[start]))
|
|
110
|
+
start, n = (h, 1) if pred(v) else (None, 0)
|
|
111
|
+
prev = h
|
|
112
|
+
if start is not None and prev is not None:
|
|
113
|
+
runs.append((start, prev, n, series[start]))
|
|
114
|
+
return runs
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def check_hourly(
|
|
118
|
+
hourly: Mapping[dt.datetime, float],
|
|
119
|
+
*,
|
|
120
|
+
start: Optional[dt.datetime] = None,
|
|
121
|
+
end: Optional[dt.datetime] = None,
|
|
122
|
+
zero_run_hours: int = 6,
|
|
123
|
+
constant_run_hours: int = 4,
|
|
124
|
+
max_hourly: Optional[float] = None,
|
|
125
|
+
outlier_z: float = 5.0,
|
|
126
|
+
min_group_size: int = 4,
|
|
127
|
+
) -> QualityReport:
|
|
128
|
+
"""Flag missing hours, zero and constant runs and outliers in an hourly series.
|
|
129
|
+
|
|
130
|
+
Args:
|
|
131
|
+
hourly: ``{hour-start datetime: volume}`` for one station (and
|
|
132
|
+
direction or lane, if those are checked separately).
|
|
133
|
+
start, end: expected first and last hour; default to the data range.
|
|
134
|
+
zero_run_hours: flag runs of at least this many consecutive zero hours.
|
|
135
|
+
Night-time zeros are common on low-volume roads; raise the value
|
|
136
|
+
there. ``0`` disables the check.
|
|
137
|
+
constant_run_hours: flag runs of at least this many identical non-zero
|
|
138
|
+
values (``0`` disables).
|
|
139
|
+
max_hourly: flag hours above this volume (``None`` disables).
|
|
140
|
+
outlier_z: flag hours whose robust z-score ``0.6745 * |x - median| / MAD``
|
|
141
|
+
within their (day of week, hour of day) group exceeds this value
|
|
142
|
+
(Iglewicz & Hoaglin, 1993). ``0`` disables.
|
|
143
|
+
min_group_size: minimum observations in a group for the outlier test.
|
|
144
|
+
"""
|
|
145
|
+
series: Dict[dt.datetime, float] = {}
|
|
146
|
+
for ts, v in hourly.items():
|
|
147
|
+
h = ts.replace(minute=0, second=0, microsecond=0)
|
|
148
|
+
series[h] = series.get(h, 0.0) + float(v)
|
|
149
|
+
hours = sorted(series)
|
|
150
|
+
if not hours and (start is None or end is None):
|
|
151
|
+
return QualityReport(None, None, 0, 0)
|
|
152
|
+
first = start if start is not None else hours[0]
|
|
153
|
+
last = end if end is not None else hours[-1]
|
|
154
|
+
n_expected = int((last - first) / _HOUR) + 1
|
|
155
|
+
issues: List[QualityIssue] = []
|
|
156
|
+
|
|
157
|
+
# Missing hours, reported as runs.
|
|
158
|
+
present = set(series)
|
|
159
|
+
gap_start: Optional[dt.datetime] = None
|
|
160
|
+
h = first
|
|
161
|
+
while h <= last + _HOUR:
|
|
162
|
+
missing = h <= last and h not in present
|
|
163
|
+
if missing and gap_start is None:
|
|
164
|
+
gap_start = h
|
|
165
|
+
elif not missing and gap_start is not None:
|
|
166
|
+
gap_end = h - _HOUR
|
|
167
|
+
n = int((gap_end - gap_start) / _HOUR) + 1
|
|
168
|
+
issues.append(QualityIssue("missing", gap_start, gap_end, f"{n} missing hour(s)"))
|
|
169
|
+
gap_start = None
|
|
170
|
+
h += _HOUR
|
|
171
|
+
|
|
172
|
+
in_range = [x for x in hours if first <= x <= last]
|
|
173
|
+
for x in in_range:
|
|
174
|
+
if series[x] < 0:
|
|
175
|
+
issues.append(QualityIssue("negative", x, x, f"volume {series[x]:g}"))
|
|
176
|
+
if max_hourly is not None and series[x] > max_hourly:
|
|
177
|
+
issues.append(
|
|
178
|
+
QualityIssue("max_volume", x, x, f"volume {series[x]:g} > {max_hourly:g}")
|
|
179
|
+
)
|
|
180
|
+
if zero_run_hours > 0:
|
|
181
|
+
for s, e, n, _ in _runs(in_range, series, lambda v: v == 0, False):
|
|
182
|
+
if n >= zero_run_hours:
|
|
183
|
+
issues.append(QualityIssue("zero_run", s, e, f"{n} consecutive zero hours"))
|
|
184
|
+
if constant_run_hours > 0:
|
|
185
|
+
for s, e, n, v in _runs(in_range, series, lambda v: v != 0, True):
|
|
186
|
+
if n >= constant_run_hours:
|
|
187
|
+
issues.append(
|
|
188
|
+
QualityIssue("constant_run", s, e, f"{n} consecutive hours equal to {v:g}")
|
|
189
|
+
)
|
|
190
|
+
if outlier_z > 0:
|
|
191
|
+
groups: Dict[Tuple[int, int], List[dt.datetime]] = defaultdict(list)
|
|
192
|
+
for x in in_range:
|
|
193
|
+
groups[(x.weekday(), x.hour)].append(x)
|
|
194
|
+
for members in groups.values():
|
|
195
|
+
if len(members) < min_group_size:
|
|
196
|
+
continue
|
|
197
|
+
vals = [series[x] for x in members]
|
|
198
|
+
med = median(vals)
|
|
199
|
+
mad = median(abs(v - med) for v in vals)
|
|
200
|
+
if mad == 0:
|
|
201
|
+
continue
|
|
202
|
+
for x in members:
|
|
203
|
+
z = 0.6745 * abs(series[x] - med) / mad
|
|
204
|
+
if z > outlier_z:
|
|
205
|
+
issues.append(
|
|
206
|
+
QualityIssue(
|
|
207
|
+
"outlier", x, x, f"volume {series[x]:g}, median {med:g}, z={z:.1f}"
|
|
208
|
+
)
|
|
209
|
+
)
|
|
210
|
+
issues.sort(key=lambda i: (i.start, i.kind))
|
|
211
|
+
return QualityReport(
|
|
212
|
+
first_hour=first,
|
|
213
|
+
last_hour=last,
|
|
214
|
+
n_hours=len(in_range),
|
|
215
|
+
n_expected=n_expected,
|
|
216
|
+
issues=issues,
|
|
217
|
+
)
|
|
218
|
+
|
|
219
|
+
|
|
220
|
+
def drop_flagged(
|
|
221
|
+
hourly: Mapping[dt.datetime, float],
|
|
222
|
+
report: QualityReport,
|
|
223
|
+
kinds: Optional[Set[str]] = None,
|
|
224
|
+
) -> Dict[dt.datetime, float]:
|
|
225
|
+
"""Copy of ``hourly`` without the hours flagged in ``report``."""
|
|
226
|
+
bad = report.flagged_hours(kinds)
|
|
227
|
+
return {
|
|
228
|
+
ts: float(v)
|
|
229
|
+
for ts, v in hourly.items()
|
|
230
|
+
if ts.replace(minute=0, second=0, microsecond=0) not in bad
|
|
231
|
+
}
|
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: aadtkit
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Traffic count processing and AADT estimation following the FHWA Traffic Monitoring Guide: AASHTO and hour-based AADT, expansion factors, factor groups, short-count expansion, K/D/peak-hour factors, FHWA 13-class shares and data-quality checks.
|
|
5
|
+
Author-email: Yusuf Eminoğlu <geospacephilo@gmail.com>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://gitlab.com/geophilo1/aadtkit_sdk
|
|
8
|
+
Project-URL: Repository, https://gitlab.com/geophilo1/aadtkit_sdk
|
|
9
|
+
Project-URL: Issues, https://gitlab.com/geophilo1/aadtkit_sdk/-/work_items
|
|
10
|
+
Project-URL: Changelog, https://gitlab.com/geophilo1/aadtkit_sdk/-/blob/main/CHANGELOG.md
|
|
11
|
+
Keywords: traffic,aadt,traffic-counts,traffic-monitoring,fhwa,expansion-factors,k-factor,transportation-planning,vehicle-classification,data-quality
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Operating System :: OS Independent
|
|
20
|
+
Classifier: Environment :: Console
|
|
21
|
+
Classifier: Topic :: Scientific/Engineering
|
|
22
|
+
Classifier: Topic :: Scientific/Engineering :: GIS
|
|
23
|
+
Classifier: Intended Audience :: Science/Research
|
|
24
|
+
Classifier: Intended Audience :: Developers
|
|
25
|
+
Classifier: Typing :: Typed
|
|
26
|
+
Requires-Python: >=3.9
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
License-File: LICENSE
|
|
29
|
+
Provides-Extra: dev
|
|
30
|
+
Requires-Dist: pytest>=7.0.0; extra == "dev"
|
|
31
|
+
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
|
|
32
|
+
Requires-Dist: ruff>=0.1.0; extra == "dev"
|
|
33
|
+
Requires-Dist: mypy>=1.0.0; extra == "dev"
|
|
34
|
+
Dynamic: license-file
|
|
35
|
+
|
|
36
|
+
# aadtkit
|
|
37
|
+
|
|
38
|
+
[](https://pypi.org/project/aadtkit/)
|
|
39
|
+
[](https://pypi.org/project/aadtkit/)
|
|
40
|
+
[](https://gitlab.com/geophilo1/aadtkit_sdk/-/pipelines)
|
|
41
|
+
[](https://gitlab.com/geophilo1/aadtkit_sdk/-/blob/main/LICENSE)
|
|
42
|
+
|
|
43
|
+
**Traffic count processing and AADT estimation, following the FHWA *Traffic Monitoring Guide*.**
|
|
44
|
+
|
|
45
|
+
`aadtkit` turns hourly traffic counts into the numbers a traffic monitoring
|
|
46
|
+
program reports and a planner designs with:
|
|
47
|
+
|
|
48
|
+
- **AADT at continuous count stations**: the AASHTO method (averaging monthly
|
|
49
|
+
average days of week, MADW) and the hour-based, calendar-weighted
|
|
50
|
+
procedure FHWA has recommended since 2016 (TMG 2022);
|
|
51
|
+
- **expansion factors**: monthly, day-of-week and month x day-of-week;
|
|
52
|
+
- **factor groups**: group averages with dispersion and 95 % precision, and
|
|
53
|
+
k-means clustering of stations on their factor patterns;
|
|
54
|
+
- **short-count expansion** to AADT with axle-correction and growth factors;
|
|
55
|
+
- **design-hour characteristics**: K-factor (30th highest hour), D-factor,
|
|
56
|
+
design hour volume and peak-hour factor;
|
|
57
|
+
- **vehicle classification**: the FHWA 13 classes, class and group shares;
|
|
58
|
+
- **data-quality checks**: missing hours, zero runs, stuck counters, ceilings
|
|
59
|
+
and robust outliers;
|
|
60
|
+
- **CSV I/O** and an `aadtkit` command line.
|
|
61
|
+
|
|
62
|
+
It runs on the Python standard library alone.
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
pip install aadtkit
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Requires Python 3.9 or newer.
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## Quickstart
|
|
73
|
+
|
|
74
|
+
```python
|
|
75
|
+
import aadtkit as ak
|
|
76
|
+
|
|
77
|
+
records = ak.read_hourly_csv("ccs_2024.csv") # station,datetime,volume[,direction][,vehicle_class]
|
|
78
|
+
series = ak.to_series(records, station="CCS-1") # {hour-start datetime: volume}
|
|
79
|
+
|
|
80
|
+
report = ak.check_hourly(series) # flag, never modify
|
|
81
|
+
clean = ak.drop_flagged(series, report)
|
|
82
|
+
|
|
83
|
+
res = ak.aadt_hourly_weighted(clean) # TMG 2022 hour-based procedure
|
|
84
|
+
res_aashto = ak.aadt_aashto(ak.daily_totals(clean)) # AASHTO / MADW
|
|
85
|
+
print(res.aadt, res.madt[7], res.madw[(7, 4)]) # AADT, July MADT, July Fridays
|
|
86
|
+
|
|
87
|
+
factors = ak.factors_from_result(res, "CCS-1") # AADT/MADT, AADT/ADT_dow, AADT/MADW
|
|
88
|
+
|
|
89
|
+
short = ak.to_series(ak.read_hourly_csv("short_count.csv"))
|
|
90
|
+
est = ak.short_count_aadt(short, factors, axle_factor=0.92, growth=ak.growth_factor(0.015, 1))
|
|
91
|
+
print(est.aadt, est.raw_adt)
|
|
92
|
+
|
|
93
|
+
k = ak.k_factor(clean, res.aadt) # 30th highest hour / AADT
|
|
94
|
+
d = ak.d_factor(ak.by_direction(records, "CCS-1")) # peak-direction share at that hour
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
A complete runnable example on synthetic data is in
|
|
98
|
+
[`examples/quickstart.py`](https://gitlab.com/geophilo1/aadtkit_sdk/-/blob/main/examples/quickstart.py).
|
|
99
|
+
|
|
100
|
+
### Command line
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
aadtkit qc ccs.csv # issues as CSV, summary on stderr
|
|
104
|
+
aadtkit aadt ccs.csv --method hourly # or aashto / simple
|
|
105
|
+
aadtkit factors ccs.csv --group RURAL -o factors.csv
|
|
106
|
+
aadtkit cluster factors.csv -k 3 # factor groups by k-means
|
|
107
|
+
aadtkit expand short.csv --factors factors.csv --group RURAL --axle-factor 0.92
|
|
108
|
+
aadtkit peak ccs.csv --nth 30 # K- and D-factor
|
|
109
|
+
aadtkit classes class_counts.csv # FHWA 13-class shares
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Add `--hour-ending` when timestamps (or hours 1-24) mark the end of the hour.
|
|
113
|
+
|
|
114
|
+
### CSV layout
|
|
115
|
+
|
|
116
|
+
```text
|
|
117
|
+
station,datetime,volume,direction,vehicle_class
|
|
118
|
+
CCS-1,2024-01-01 00:00,312,NB,2
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
`datetime` may be replaced by `date` + `hour`; `direction` and
|
|
122
|
+
`vehicle_class` are optional. Empty or `NA` volumes are missing hours.
|
|
123
|
+
Factor tables use `name,type,month,dow,factor` with `type` in `monthly`,
|
|
124
|
+
`dow`, `month_dow`. Days of week are numbered 0 = Monday ... 6 = Sunday.
|
|
125
|
+
|
|
126
|
+
## API overview
|
|
127
|
+
|
|
128
|
+
| Area | Functions / classes |
|
|
129
|
+
| --- | --- |
|
|
130
|
+
| AADT | `daily_totals`, `aadt_aashto`, `aadt_hourly_weighted`, `aadt_simple`, `madt`, `dow_occurrences`, `AADTResult` |
|
|
131
|
+
| Factors | `factors_from_result`, `FactorSet.factor`, `group_factors`, `FactorGroup`, `FactorStats`, `cluster_stations`, `t_critical_95` |
|
|
132
|
+
| Axle correction | `axle_correction_factor`, `axle_correction_from_classes`, `DEFAULT_AXLES_PER_CLASS` |
|
|
133
|
+
| Short counts | `short_count_aadt`, `expand_volume`, `growth_factor`, `split_24h_blocks`, `ShortCountEstimate` |
|
|
134
|
+
| Design hour | `highest_hours`, `nth_highest_hour`, `k_factor`, `d_factor`, `design_hour_volume`, `peak_hour_factor` |
|
|
135
|
+
| Classification | `FHWAClass`, `CLASS_DESCRIPTIONS`, `class_shares`, `group_shares`, `truck_share` |
|
|
136
|
+
| Quality | `check_hourly`, `QualityReport`, `QualityIssue`, `drop_flagged` |
|
|
137
|
+
| I/O | `read_hourly_csv`, `write_hourly_csv`, `to_series`, `by_station`, `by_direction`, `class_totals`, `duplicate_keys`, `read_factors_csv`, `write_factors_csv` |
|
|
138
|
+
|
|
139
|
+
## Methods and sources
|
|
140
|
+
|
|
141
|
+
**AASHTO method** (TMG 2013, Section 3.2.1, Step 7; adopted by FHWA and the
|
|
142
|
+
AASHTO *Guidelines for Traffic Data Programs*):
|
|
143
|
+
|
|
144
|
+
```text
|
|
145
|
+
AADT = 1/7 * sum_i [ 1/12 * sum_j ( 1/n_ij * sum_k VOL_ijk ) ]
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
`VOL_ijk` is the daily volume of the k-th occurrence of day of week *i* in
|
|
149
|
+
month *j*; the inner mean is the monthly average day of week (MADW). All 84
|
|
150
|
+
month x day-of-week cells need at least one complete day; `allow_missing_cells`
|
|
151
|
+
relaxes this explicitly.
|
|
152
|
+
|
|
153
|
+
**Hour-based procedure** (TMG 2022, Section 3.1.4.7, Step 3):
|
|
154
|
+
|
|
155
|
+
```text
|
|
156
|
+
MADT_m = sum_j w_jm * sum_h (1/n_hjm * sum_i VOL_ihjm) / sum_j w_jm
|
|
157
|
+
AADT = sum_m d_m * MADT_m / sum_m d_m
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
`w_jm` is the number of times day of week *j* occurs in month *m* (4 or 5) and
|
|
161
|
+
`d_m` the number of days in the month. Hour-level averaging lets partial days
|
|
162
|
+
contribute; with a complete year it equals the plain mean of all 365/366 days.
|
|
163
|
+
|
|
164
|
+
**Factors** (TMG 2022, 3.1.4.7, Steps 4-5): monthly factor `AADT / MADT_m`,
|
|
165
|
+
day-of-week factor `AADT / ADT_j`, month x day-of-week factor
|
|
166
|
+
`AADT / MADW_mj`; group factors are the mean over the group's stations, with
|
|
167
|
+
precision `t(0.975, n-1) * s / sqrt(n)` (TMG 2022, 3.1.4.5 and 3.2.6.2).
|
|
168
|
+
|
|
169
|
+
**Short counts**: `AADT = VOL_24 * M * D * A * G`, applied seasonality first
|
|
170
|
+
(TMG 2022, 3.2.8, worked example `518 x 0.95 x 1.24 = 610`, reproduced in the
|
|
171
|
+
tests). The axle-correction factor is vehicles per axle pair from a
|
|
172
|
+
classification count, `ACF = vehicles / (axles / 2)` (TMG glossary: vehicles
|
|
173
|
+
divided by axles; the divisor 2 reflects counters that register one count per
|
|
174
|
+
two axle hits and is a parameter).
|
|
175
|
+
|
|
176
|
+
**Design hour**: `K = V30 / AADT` with `V30` the 30th highest hourly volume
|
|
177
|
+
of the year (TMG 2022, 3.1.2 and 3.1.4.3; AASHTO *Green Book*);
|
|
178
|
+
`D` = peak-direction share of that hour; `PHF = V / (4 * V15)` (*Highway
|
|
179
|
+
Capacity Manual*).
|
|
180
|
+
|
|
181
|
+
**Classification**: FHWA 13-category scheme; default groups follow HPMS
|
|
182
|
+
(single-unit truck and bus = classes 4-7, combination truck = 8-13).
|
|
183
|
+
|
|
184
|
+
**Quality**: robust z-score `0.6745 |x - median| / MAD` within each
|
|
185
|
+
day-of-week x hour group (Iglewicz and Hoaglin, 1993).
|
|
186
|
+
|
|
187
|
+
References:
|
|
188
|
+
|
|
189
|
+
- FHWA (2022). *Traffic Monitoring Guide*. U.S. Department of Transportation,
|
|
190
|
+
Federal Highway Administration. <https://www.fhwa.dot.gov/policyinformation/tmguide/>
|
|
191
|
+
- FHWA (2013). *Traffic Monitoring Guide*, Chapter 3.
|
|
192
|
+
- AASHTO (2009). *AASHTO Guidelines for Traffic Data Programs*, 2nd ed.
|
|
193
|
+
- Transportation Research Board. *Highway Capacity Manual*.
|
|
194
|
+
- NCHRP Research Report 1081 (2024). *Guide on Methods for Assigning Counts to
|
|
195
|
+
Adjustment Factor Groups*. National Academies Press.
|
|
196
|
+
|
|
197
|
+
## Limitations
|
|
198
|
+
|
|
199
|
+
- Quality thresholds (zero run 6 h, constant run 4 h, z > 5) are engineering
|
|
200
|
+
defaults, not FHWA values; set them to your agency's validation rules.
|
|
201
|
+
- `DEFAULT_AXLES_PER_CLASS` uses nominal axle numbers; classes 3, 4, 7, 8, 10,
|
|
202
|
+
11 and 13 cover ranges. Use measured axles per class where available.
|
|
203
|
+
- k-means on factor vectors is one of several grouping approaches; groups
|
|
204
|
+
should still be reviewed against road function and geography, and short
|
|
205
|
+
count sites must be assigned to groups by the analyst.
|
|
206
|
+
- Incomplete days are never imputed. Daylight-saving shifts are not handled;
|
|
207
|
+
supply local standard time or UTC.
|
|
208
|
+
- Only 95 % confidence intervals are tabulated (t values for df <= 30, 40, 60,
|
|
209
|
+
120, interpolated otherwise).
|
|
210
|
+
|
|
211
|
+
## Academic citation
|
|
212
|
+
|
|
213
|
+
```bibtex
|
|
214
|
+
@software{eminoglu_aadtkit,
|
|
215
|
+
author = {Eminoğlu, Yusuf},
|
|
216
|
+
title = {aadtkit},
|
|
217
|
+
year = {2026},
|
|
218
|
+
version = {0.1.0},
|
|
219
|
+
url = {https://gitlab.com/geophilo1/aadtkit_sdk}
|
|
220
|
+
}
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
## License
|
|
224
|
+
|
|
225
|
+
MIT, see [LICENSE](https://gitlab.com/geophilo1/aadtkit_sdk/-/blob/main/LICENSE). Contact: geospacephilo@gmail.com
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
aadtkit/__init__.py,sha256=SBoRsah-o0WAIWb_5-L9R3w6oMD9LUDhfKIvz7bARiw,3014
|
|
2
|
+
aadtkit/__main__.py,sha256=ZHGPTZ-FIN-XPFL01EZdnQPx60IF0vmDGGUijMaZCrs,82
|
|
3
|
+
aadtkit/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
|
|
4
|
+
aadtkit/aadt.py,sha256=A2Dxk0ttArJsP2rTZ6NCaBxCIZbi5_bJn7uofmMbCnU,11142
|
|
5
|
+
aadtkit/classification.py,sha256=CGHZbOpt9Nam32qByb9989YedbXG9WRag415Yj7sBlw,3311
|
|
6
|
+
aadtkit/cli.py,sha256=qAk6QVyzjPlEVFKGiYSq_Fu3Zl2hfWLR5R3X3tKSbKw,11152
|
|
7
|
+
aadtkit/errors.py,sha256=7a17ZcArPKx_uAB4lcsBJrpe5OxQquuaknqfoE_ZQ-0,482
|
|
8
|
+
aadtkit/expand.py,sha256=97JgNkwFXX0rwLBwHHw9N2n9UVSiO39_zqqXpmr0Qyg,5567
|
|
9
|
+
aadtkit/factors.py,sha256=oHMH2GK151UB0WyAeUV3cE0FU3GZig5jHDzI6LxxUjU,13180
|
|
10
|
+
aadtkit/io.py,sha256=xL0bgTxSb-ybX8zfjs-H7IDfNvNie85YPLtekHXX6Tk,11642
|
|
11
|
+
aadtkit/peak.py,sha256=ZMt2s3odmbjNnRMK5GTFQ4E3oqhyknMDc6fVMxdoQqY,5387
|
|
12
|
+
aadtkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
13
|
+
aadtkit/quality.py,sha256=HdZymKHCebQWtN7UQ0wR5KAVE6W3D_uedUyU8VwZNpE,8470
|
|
14
|
+
aadtkit-0.1.0.dist-info/licenses/LICENSE,sha256=Z9meOk3opsRgHOqC5mA4B8NjZoU5WU1Kqhn82FL4ICs,1072
|
|
15
|
+
aadtkit-0.1.0.dist-info/METADATA,sha256=ZxLr63bb5DRSiF3goEHbYSa1JfjNeL5xg9L0Re2hJyk,10341
|
|
16
|
+
aadtkit-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
17
|
+
aadtkit-0.1.0.dist-info/entry_points.txt,sha256=LWkDZDZmfQlCQWEvuf0lSolyGXmygMNwJzBEku-GQeM,45
|
|
18
|
+
aadtkit-0.1.0.dist-info/top_level.txt,sha256=QGkH1ByOL2bpuB9azndEvd0woCCQuaROykGeK-p12ec,8
|
|
19
|
+
aadtkit-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Yusuf Eminoğlu
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
aadtkit
|