aadtkit
Traffic count processing and AADT estimation, following the FHWA Traffic Monitoring Guide.
aadtkit turns hourly traffic counts into the numbers a traffic monitoring
program reports and a planner designs with:
- AADT at continuous count stations: the AASHTO method (averaging monthly average days of week, MADW) and the hour-based, calendar-weighted procedure FHWA has recommended since 2016 (TMG 2022);
- expansion factors: monthly, day-of-week and month x day-of-week;
- factor groups: group averages with dispersion and 95 % precision, and k-means clustering of stations on their factor patterns;
- short-count expansion to AADT with axle-correction and growth factors;
- design-hour characteristics: K-factor (30th highest hour), D-factor, design hour volume and peak-hour factor;
- vehicle classification: the FHWA 13 classes, class and group shares;
- data-quality checks: missing hours, zero runs, stuck counters, ceilings and robust outliers;
- CSV I/O and an
aadtkitcommand line.
It runs on the Python standard library alone.
pip install aadtkit
Requires Python 3.9 or newer.
Quickstart
import aadtkit as ak
records = ak.read_hourly_csv("ccs_2024.csv") # station,datetime,volume[,direction][,vehicle_class]
series = ak.to_series(records, station="CCS-1") # {hour-start datetime: volume}
report = ak.check_hourly(series) # flag, never modify
clean = ak.drop_flagged(series, report)
res = ak.aadt_hourly_weighted(clean) # TMG 2022 hour-based procedure
res_aashto = ak.aadt_aashto(ak.daily_totals(clean)) # AASHTO / MADW
print(res.aadt, res.madt[7], res.madw[(7, 4)]) # AADT, July MADT, July Fridays
factors = ak.factors_from_result(res, "CCS-1") # AADT/MADT, AADT/ADT_dow, AADT/MADW
short = ak.to_series(ak.read_hourly_csv("short_count.csv"))
est = ak.short_count_aadt(short, factors, axle_factor=0.92, growth=ak.growth_factor(0.015, 1))
print(est.aadt, est.raw_adt)
k = ak.k_factor(clean, res.aadt) # 30th highest hour / AADT
d = ak.d_factor(ak.by_direction(records, "CCS-1")) # peak-direction share at that hour
A complete runnable example on synthetic data is in
examples/quickstart.py.
Command line
aadtkit qc ccs.csv # issues as CSV, summary on stderr
aadtkit aadt ccs.csv --method hourly # or aashto / simple
aadtkit factors ccs.csv --group RURAL -o factors.csv
aadtkit cluster factors.csv -k 3 # factor groups by k-means
aadtkit expand short.csv --factors factors.csv --group RURAL --axle-factor 0.92
aadtkit peak ccs.csv --nth 30 # K- and D-factor
aadtkit classes class_counts.csv # FHWA 13-class shares
Add --hour-ending when timestamps (or hours 1-24) mark the end of the hour.
CSV layout
station,datetime,volume,direction,vehicle_class
CCS-1,2024-01-01 00:00,312,NB,2
datetime may be replaced by date + hour; direction and
vehicle_class are optional. Empty or NA volumes are missing hours.
Factor tables use name,type,month,dow,factor with type in monthly,
dow, month_dow. Days of week are numbered 0 = Monday ... 6 = Sunday.
API overview
| Area | Functions / classes |
|---|---|
| AADT | daily_totals, aadt_aashto, aadt_hourly_weighted, aadt_simple, madt, dow_occurrences, AADTResult |
| Factors | factors_from_result, FactorSet.factor, group_factors, FactorGroup, FactorStats, cluster_stations, t_critical_95 |
| Axle correction | axle_correction_factor, axle_correction_from_classes, DEFAULT_AXLES_PER_CLASS |
| Short counts | short_count_aadt, expand_volume, growth_factor, split_24h_blocks, ShortCountEstimate |
| Design hour | highest_hours, nth_highest_hour, k_factor, d_factor, design_hour_volume, peak_hour_factor |
| Classification | FHWAClass, CLASS_DESCRIPTIONS, class_shares, group_shares, truck_share |
| Quality | check_hourly, QualityReport, QualityIssue, drop_flagged |
| I/O | read_hourly_csv, write_hourly_csv, to_series, by_station, by_direction, class_totals, duplicate_keys, read_factors_csv, write_factors_csv |
Methods and sources
AASHTO method (TMG 2013, Section 3.2.1, Step 7; adopted by FHWA and the AASHTO Guidelines for Traffic Data Programs):
AADT = 1/7 * sum_i [ 1/12 * sum_j ( 1/n_ij * sum_k VOL_ijk ) ]
VOL_ijk is the daily volume of the k-th occurrence of day of week i in
month j; the inner mean is the monthly average day of week (MADW). All 84
month x day-of-week cells need at least one complete day; allow_missing_cells
relaxes this explicitly.
Hour-based procedure (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
w_jm is the number of times day of week j occurs in month m (4 or 5) and
d_m the number of days in the month. Hour-level averaging lets partial days
contribute; with a complete year it equals the plain mean of all 365/366 days.
Factors (TMG 2022, 3.1.4.7, Steps 4-5): monthly factor AADT / MADT_m,
day-of-week factor AADT / ADT_j, month x day-of-week factor
AADT / MADW_mj; group factors are the mean over the group's stations, with
precision t(0.975, n-1) * s / sqrt(n) (TMG 2022, 3.1.4.5 and 3.2.6.2).
Short counts: AADT = VOL_24 * M * D * A * G, applied seasonality first
(TMG 2022, 3.2.8, worked example 518 x 0.95 x 1.24 = 610, reproduced in the
tests). The axle-correction factor is vehicles per axle pair from a
classification count, ACF = vehicles / (axles / 2) (TMG glossary: vehicles
divided by axles; the divisor 2 reflects counters that register one count per
two axle hits and is a parameter).
Design hour: K = V30 / AADT with V30 the 30th highest hourly volume
of the year (TMG 2022, 3.1.2 and 3.1.4.3; AASHTO Green Book);
D = peak-direction share of that hour; PHF = V / (4 * V15) (Highway
Capacity Manual).
Classification: FHWA 13-category scheme; default groups follow HPMS (single-unit truck and bus = classes 4-7, combination truck = 8-13).
Quality: robust z-score 0.6745 |x - median| / MAD within each
day-of-week x hour group (Iglewicz and Hoaglin, 1993).
References:
- FHWA (2022). Traffic Monitoring Guide. U.S. Department of Transportation, Federal Highway Administration. https://www.fhwa.dot.gov/policyinformation/tmguide/
- FHWA (2013). Traffic Monitoring Guide, Chapter 3.
- AASHTO (2009). AASHTO Guidelines for Traffic Data Programs, 2nd ed.
- Transportation Research Board. Highway Capacity Manual.
- NCHRP Research Report 1081 (2024). Guide on Methods for Assigning Counts to Adjustment Factor Groups. National Academies Press.
Limitations
- Quality thresholds (zero run 6 h, constant run 4 h, z > 5) are engineering defaults, not FHWA values; set them to your agency's validation rules.
DEFAULT_AXLES_PER_CLASSuses nominal axle numbers; classes 3, 4, 7, 8, 10, 11 and 13 cover ranges. Use measured axles per class where available.- k-means on factor vectors is one of several grouping approaches; groups should still be reviewed against road function and geography, and short count sites must be assigned to groups by the analyst.
- Incomplete days are never imputed. Daylight-saving shifts are not handled; supply local standard time or UTC.
- Only 95 % confidence intervals are tabulated (t values for df <= 30, 40, 60, 120, interpolated otherwise).
Academic citation
@software{eminoglu_aadtkit,
author = {Eminoğlu, Yusuf},
title = {aadtkit},
year = {2026},
version = {0.1.1},
doi = {10.5281/zenodo.24235596},
url = {https://gitlab.com/geophilo1/aadtkit_sdk}
}
License
MIT, see LICENSE. Contact: geospacephilo@gmail.com
Metadata
Release files for aadtkit 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aadtkit-0.1.1.tar.gz | 42.2 kB | Without provenance | Details for aadtkit-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aadtkit-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for aadtkit-0.1.1-py3-none-any.whl |
Total release size: 75.6 kB
Release files / aadtkit-0.1.1.tar.gz
| Download URL | aadtkit-0.1.1.tar.gz |
|---|---|
| Size | 42.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
10c442723ad67665d7222f558ef0432f8e55058cfcfaa1dc1ce68273c24aee44
|
|
BLAKE2b-256 checksum How to use checksums |
3c79e2937d76e2eb32640cd47a8a13940aa8b056f9bd3a05d3533fc5517e72bf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Release files / aadtkit-0.1.1-py3-none-any.whl
| Download URL | aadtkit-0.1.1-py3-none-any.whl |
|---|---|
| Size | 33.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
16e0e45fe118f560fcbe0aa04cc267a384e9976e83cb288005e2d66c99fdd255
|
|
BLAKE2b-256 checksum How to use checksums |
72895b5683e6bbd1746a75eed464422bfdb20e52e08e0168bb4e1f70a5a08269
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Security for aadtkit 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.