Metadata-Version: 2.4
Name: aadtkit
Version: 0.1.1
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.
Author-email: Yusuf Eminoğlu <geospacephilo@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/geophilo1/aadtkit_sdk
Project-URL: Repository, https://gitlab.com/geophilo1/aadtkit_sdk
Project-URL: Issues, https://gitlab.com/geophilo1/aadtkit_sdk/-/work_items
Project-URL: Changelog, https://gitlab.com/geophilo1/aadtkit_sdk/-/blob/main/CHANGELOG.md
Keywords: traffic,aadt,traffic-counts,traffic-monitoring,fhwa,expansion-factors,k-factor,transportation-planning,vehicle-classification,data-quality
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# aadtkit

[![PyPI version](https://img.shields.io/pypi/v/aadtkit.svg)](https://pypi.org/project/aadtkit/)
[![Python versions](https://img.shields.io/pypi/pyversions/aadtkit.svg)](https://pypi.org/project/aadtkit/)
[![pipeline](https://gitlab.com/geophilo1/aadtkit_sdk/badges/main/pipeline.svg)](https://gitlab.com/geophilo1/aadtkit_sdk/-/pipelines)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://gitlab.com/geophilo1/aadtkit_sdk/-/blob/main/LICENSE)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.24235596.svg)](https://doi.org/10.5281/zenodo.24235596)

**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.

```bash
pip install aadtkit
```

Requires Python 3.9 or newer.

---

## Quickstart

```python
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`](https://gitlab.com/geophilo1/aadtkit_sdk/-/blob/main/examples/quickstart.py).

### Command line

```bash
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

```text
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*):

```text
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):

```text
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

```bibtex
@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](https://gitlab.com/geophilo1/aadtkit_sdk/-/blob/main/LICENSE). Contact: geospacephilo@gmail.com
