aadtkit 0.1.0__tar.gz

aadtkit-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-09
+### Added
+- Continuous-count AADT: AASHTO method from monthly average days of week (MADW),
+  the FHWA hour-based calendar-weighted procedure (TMG 2022, 3.1.4.7) and the simple mean;
+  complete-day aggregation, monthly ADT, calendar day-of-week occurrences.
+- Monthly, day-of-week and month x day-of-week expansion factors; factor groups with
+  per-factor standard deviation, CV and 95 % confidence half-width; k-means clustering of
+  stations on factor patterns.
+- Short-count expansion to AADT with axle-correction and growth factors, on calendar days or
+  consecutive 24-hour blocks; axle-correction factors from classification counts.
+- K-factor (n-th highest hour), D-factor, design hour volume and peak-hour factor.
+- FHWA 13-class vehicle categories, class and group shares, truck share.
+- Data-quality checks: missing hours, negative values, zero runs, constant runs, ceiling
+  and robust (median/MAD) outliers.
+- CSV I/O for hourly counts and factor tables; `aadtkit` command line with `aadt`,
+  `factors`, `cluster`, `expand`, `peak`, `qc` and `classes`.

aadtkit-0.1.0/CITATION.cff

@@ -0,0 +1,20 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+  - family-names: "Eminoğlu"
+    given-names: "Yusuf"
+    email: "geospacephilo@gmail.com"
+    orcid: "https://orcid.org/0009-0005-6000-2934"
+title: "aadtkit"
+version: "0.1.0"
+date-released: "2026-11-09"
+license: "MIT"
+repository-code: "https://gitlab.com/geophilo1/aadtkit_sdk"
+url: "https://pypi.org/project/aadtkit/"
+abstract: "Traffic count processing and AADT estimation following the FHWA Traffic Monitoring Guide: AASHTO and hour-based AADT for continuous count stations, monthly and day-of-week expansion factors, factor groups, short-count expansion with axle-correction factors, K-, D- and peak-hour factors, FHWA 13-class vehicle shares and data-quality checks."
+keywords:
+  - traffic
+  - AADT
+  - traffic monitoring
+  - expansion factors
+  - transportation planning

aadtkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yusuf Eminoğlu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aadtkit-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CITATION.cff
+include pyproject.toml
+include src/aadtkit/py.typed
+recursive-include src/aadtkit *.py
+recursive-include tests *.py
+recursive-include examples *.py

aadtkit-0.1.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: aadtkit
+Version: 0.1.0
+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)
+
+**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.0},
+  url     = {https://gitlab.com/geophilo1/aadtkit_sdk}
+}
+```
+
+## License
+
+MIT, see [LICENSE](https://gitlab.com/geophilo1/aadtkit_sdk/-/blob/main/LICENSE). Contact: geospacephilo@gmail.com

aadtkit-0.1.0/README.md

@@ -0,0 +1,190 @@
+# 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)
+
+**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.0},
+  url     = {https://gitlab.com/geophilo1/aadtkit_sdk}
+}
+```
+
+## License
+
+MIT, see [LICENSE](https://gitlab.com/geophilo1/aadtkit_sdk/-/blob/main/LICENSE). Contact: geospacephilo@gmail.com

aadtkit-0.1.0/examples/quickstart.py

@@ -0,0 +1,65 @@
+"""aadtkit quickstart on synthetic data (no files needed).
+
+Run with:  python examples/quickstart.py
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import math
+import random
+import tempfile
+from pathlib import Path
+
+import aadtkit as ak
+
+# --- 1. A synthetic continuous count station (one year, two directions) ------
+rng = random.Random(42)
+season = {m: 1 + 0.2 * math.sin((m - 4) / 12 * 2 * math.pi) for m in range(1, 13)}
+weekday = [1.0, 1.0, 1.02, 1.05, 1.15, 0.9, 0.8]
+profile = [1, 1, 1, 1, 2, 4, 7, 9, 8, 5, 4, 4, 5, 5, 5, 6, 8, 9, 7, 5, 4, 3, 2, 2]
+profile = [p / sum(profile) for p in profile]
+
+records = []
+day = dt.date(2024, 1, 1)
+while day.year == 2024:
+    total = 12000 * season[day.month] * weekday[day.weekday()]
+    for h in range(24):
+        ts = dt.datetime.combine(day, dt.time(h))
+        vol = total * profile[h] * rng.uniform(0.95, 1.05)
+        nb_share = 0.6 if h < 12 else 0.4
+        records.append(ak.HourlyRecord("CCS-1", ts, round(vol * nb_share), "NB"))
+        records.append(ak.HourlyRecord("CCS-1", ts, round(vol * (1 - nb_share)), "SB"))
+    day += dt.timedelta(days=1)
+
+with tempfile.TemporaryDirectory() as tmp:
+    path = Path(tmp) / "ccs.csv"
+    ak.write_hourly_csv(path, records)
+    records = ak.read_hourly_csv(path)
+
+series = ak.to_series(records, station="CCS-1")
+
+# --- 2. Quality checks -------------------------------------------------------
+report = ak.check_hourly(series)
+print(f"completeness {report.completeness:.1%}, issues: {len(report.issues)}")
+
+# --- 3. AADT -----------------------------------------------------------------
+hourly = ak.aadt_hourly_weighted(series)
+aashto = ak.aadt_aashto(ak.daily_totals(series))
+print(f"AADT (TMG 2022 hour-based) = {hourly.aadt:,.0f}")
+print(f"AADT (AASHTO, MADW)        = {aashto.aadt:,.0f}")
+
+# --- 4. Factors and short-count expansion ------------------------------------
+factors = ak.factors_from_result(hourly, "CCS-1")
+print("monthly factors:", {m: round(f, 3) for m, f in factors.monthly.items()})
+
+start = dt.datetime(2024, 4, 16, 9)  # a 48-hour count starting Tuesday 09:00
+short = {start + dt.timedelta(hours=i): series[start + dt.timedelta(hours=i)] for i in range(48)}
+est = ak.short_count_aadt(short, factors, basis="blocks")
+print(f"48-h count: raw ADT {est.raw_adt:,.0f} -> AADT estimate {est.aadt:,.0f}")
+
+# --- 5. Design hour ----------------------------------------------------------
+k = ak.k_factor(series, hourly.aadt)
+d = ak.d_factor(ak.by_direction(records, "CCS-1"))
+print(f"K30 = {k:.3f}, D = {d.d:.2f} ({d.peak_direction}), DHV = {hourly.aadt * k:,.0f}")
+print("PHF of 15-min counts:", round(ak.peak_hour_factor([210, 245, 260, 230, 190]).phf, 3))

aadtkit-0.1.0/pyproject.toml

@@ -0,0 +1,105 @@
+[build-system]
+requires = ["setuptools>=77.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aadtkit"
+version = "0.1.0"
+authors = [
+    { name = "Yusuf Eminoğlu", email = "geospacephilo@gmail.com" }
+]
+description = "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."
+keywords = [
+    "traffic",
+    "aadt",
+    "traffic-counts",
+    "traffic-monitoring",
+    "fhwa",
+    "expansion-factors",
+    "k-factor",
+    "transportation-planning",
+    "vehicle-classification",
+    "data-quality",
+]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Environment :: Console",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+]
+
+[project.scripts]
+aadtkit = "aadtkit.cli:main"
+
+[project.urls]
+Homepage = "https://gitlab.com/geophilo1/aadtkit_sdk"
+Repository = "https://gitlab.com/geophilo1/aadtkit_sdk"
+Issues = "https://gitlab.com/geophilo1/aadtkit_sdk/-/work_items"
+Changelog = "https://gitlab.com/geophilo1/aadtkit_sdk/-/blob/main/CHANGELOG.md"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+aadtkit = ["py.typed"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+exclude = [
+    "scratch",
+    ".venv",
+    "build",
+    "dist",
+]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "C4"]
+ignore = ["E501"]
+
+[tool.mypy]
+files = ["src"]
+warn_unused_ignores = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# Lets `pytest` run straight from a clone, without an editable install first.
+pythonpath = ["src"]
+filterwarnings = [
+    "ignore::DeprecationWarning",
+    "ignore::PendingDeprecationWarning",
+]
+
+[tool.coverage.run]
+source = ["aadtkit"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 85

aadtkit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+