Skip to main content

aadtkit

PyPI version Python versions pipeline License: MIT

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 aadtkit command 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_CLASS uses 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.0},
  url     = {https://gitlab.com/geophilo1/aadtkit_sdk}
}

License

MIT, see LICENSE. Contact: geospacephilo@gmail.com

Metadata

Release files for aadtkit 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aadtkit 0.1.0
File Size Uploaded Provenance Actions
aadtkit-0.1.0.tar.gz 42.0 kB Without provenance Details for aadtkit-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aadtkit 0.1.0
File Interpreter ABI Platform Actions
aadtkit-0.1.0-py3-none-any.whl Python 3 none any Details for aadtkit-0.1.0-py3-none-any.whl

Total release size: 75.3 kB

Release files / aadtkit-0.1.0.tar.gz

Download URL aadtkit-0.1.0.tar.gz
Size 42.0 kB
Tags Source
SHA-256 checksum
How to use checksums
321d0153139189f7790fbee6e9515f223a15bbb05fe375b0464d96a04bf7d0bc
BLAKE2b-256 checksum
How to use checksums
6d03c7f3dae7eabe120c6eb32228cc67e25defce6792a1c8991bb36e8dbd3bb5
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.0-py3-none-any.whl

Download URL aadtkit-0.1.0-py3-none-any.whl
Size 33.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2a0029ca50cb823ef076dfb53fc714c1bfcd47f4c1825f4520d36ac2cf6f4fb7
BLAKE2b-256 checksum
How to use checksums
36cf55523000cd9207572b8a940da8403f3f98927fefd37d6f8e195b77ed16fc
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.0

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page