# pynhts

> Typed, survey-weight-aware Python access to the US National Household Travel Survey (NHTS): waves 2001, 2009, 2017 and 2022. Validated against published FHWA tables; the known traps are documented and, where possible, guarded (see docs/guards.md for what is and is not).

Read AGENTS.md first.

## Docs
- [AGENTS.md](https://github.com/sabernaseralavi-60/pynhts/blob/main/AGENTS.md): ten rules, canonical recipes, what not to do
- [Defaults and guards](https://github.com/sabernaseralavi-60/pynhts/blob/main/docs/guards.md): each silent error and the guard that prevents it
- [From a study statement to tables](https://github.com/sabernaseralavi-60/pynhts/blob/main/docs/study.md): `pynhts.study`, sample flow, Table 1, figures, grading against published numbers
- [Comparing waves](https://github.com/sabernaseralavi-60/pynhts/blob/main/docs/waves.md): codes that change meaning, crosswalks
- [Methods](https://github.com/sabernaseralavi-60/pynhts/blob/main/docs/methods.md): variance designs, units of totals
- [Data notes](https://github.com/sabernaseralavi-60/pynhts/blob/main/docs/data_notes.md): per-wave pitfalls with evidence
- [Validation](https://github.com/sabernaseralavi-60/pynhts/blob/main/docs/validation.md): published numbers reproduced, gaps reported
- [Concept dictionary (YAML; JSON via pynhts.concepts.to_json())](https://github.com/sabernaseralavi-60/pynhts/blob/main/src/pynhts/concepts.yaml): per-wave variable, universe, comparability, pitfalls

- [Analysis toolkit](https://github.com/sabernaseralavi-60/pynhts/blob/main/docs/analysis.md): aggregate, features, eda, transform, trends
- [Feature registry](https://github.com/sabernaseralavi-60/pynhts/blob/main/docs/data/FEATURES.md): 93 features with formula, eligibility, denominator, weight

## Machine-readable facts
- `pynhts.concepts.to_json()`, `pynhts.concepts.find(variable, wave)`, `pynhts.describe(variable, wave)`
- `pynhts.harmonize.crosswalk(concept)`, `pynhts.harmonize.compare_waves(a, b)`
- `pynhts.features.registry()`, `pynhts.features.create_household_features(data)`, `pynhts.aggregate.aggregate(data, source, target, specs)`, `pynhts.valid(series)`
