A county-first data lake and agent-based simulation engine for the Tennessee economy — ingest, normalize, and curate public economic data, then model how shocks propagate across the state's commuting and industry networks.
Commuting-network hub map: each node is a Tennessee county, sized and colored by network centrality. The top-5 structural hubs — Davidson, Williamson, Rutherford, Wilson, and Shelby — are starred. Faint edges show inter-county commuting flows.
The project has two layers:
- Data lake (Phase 1) — ingests, normalizes, curates, and exports county-level datasets that later stages build on. Sources include Census PEP and ACS demographics, PUMS household microdata, QCEW wages, CBP establishment counts, and Tennessee tax collections.
- Simulation engine (V1) — builds a calibrated "economic world" from the curated data, computes network centrality across the county commuting graph, and runs shock-propagation and spillover scenarios with interactive visual outputs.
The V1/ directory generates standalone HTML visualizations (Plotly). Included here:
V1/hub_map.html— the commuting-network hub map shown above, with a selectable centrality metric.V1/run_comparison.html— side-by-side comparison of two simulation runs.
The full set (county drilldowns, sector corridors, scenario diffs, animated economy) is generated by the scripts in V1/ from the local data lake.
| Path | What's inside |
|---|---|
pipelines/ |
Ingestion, transform, validation, and export code |
schemas/ |
Table contracts for curated and feature tables |
V1/ |
Simulation engine: calibration, centrality, scenario scripts + demo HTML |
infra/ |
Terraform for the S3 lake bucket, Glue databases, Athena workgroup |
docs/ |
Source registry, runbooks, reproducibility notes |
tests/ |
Fixture-backed pipeline tests that run locally without AWS |
This repository is a curated code + demo slice. The raw data lake, curated parquet outputs, trained models, and validation artifacts (tens of GB) are intentionally excluded — see .gitignore. The pipeline code regenerates them from public sources.