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/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
+ [![PyPI version](https://img.shields.io/pypi/v/aadtkit.svg)](https://pypi.org/project/aadtkit/)
39
+ [![Python versions](https://img.shields.io/pypi/pyversions/aadtkit.svg)](https://pypi.org/project/aadtkit/)
40
+ [![pipeline](https://gitlab.com/geophilo1/aadtkit_sdk/badges/main/pipeline.svg)](https://gitlab.com/geophilo1/aadtkit_sdk/-/pipelines)
41
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ aadtkit = aadtkit.cli:main
@@ -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