Skip to content

Population code

population/cvae is a small PyTorch package with numbered steps; population/post adapts its output to the land-use model.

Library: population/cvae/vaelib

Module Role
config paths, recode maps, income bands, cardinalities (base year 2016; up to 7 persons; 18 age bands)
pums_io, preprocessing, crosswalks read and recode the PUMS; zone ↔ PUMA ↔ county
dataset tensors and the 80/10/10 split by PUMA
model the conditional VAE: one-hot input, PUMA embedding, encoder, decoder, household and person heads
train cross-entropy + KL with free bits, β annealing, PUMA marginal loss, EMA, early stopping
targets, generate PUMA targets; sampling
income_bins dollar income drawn within the band from the PUMA's records
consistency logical rules applied after sampling
zones, dwelling, workplace, silo_export zone placement, dwelling attributes, workplaces, SILO files
validate, diagnostics, analysis held-out validation and figures

Steps: population/cvae/steps

Step Does Writes
00_analyze_raw_acs.py statistics of the raw PUMS outputs/00_raw_analysis/
01_preprocess.py recode to the SILO schema 01_preprocessed/{hh,pp}.parquet
02_build_targets.py PUMA marginal targets 02_targets/
03_train.py train 03_training/<tag>/checkpoint_best.pt, history, split
04_generate.py sample households 04_generated/{hh,pp}.parquet
05_workplace.py workplaces 05_workplace/
06_silo_export.py dwellings, SILO CSV 06_silo_input/{hh,pp,dd,jj}_2016.csv
07_validate.py test-split validation 07_validation/<tag>/
08_figures.py, 09_study_areas.py figures; county checks

Training options: --epochs --latent --hidden --enc-depth --dec-depth --free-bits --beta --w-marginal --tag --smoke.

Post-processing: population/post

Script Does
rebalance_population.py redraw households per PUMA to ACS household and age controls; place them in zones
zone_weights_2016.py, zone_weights_2020.py occupied housing units per zone from Census blocks
employment_2016_lodes.py jobs by zone and type from LODES
market_vacancy_2016.py, zone_vacancy_2016.py vacant dwellings on the market
workplace_balanced.py gravity workplaces for residents outside the workplace-model area
export_silo_base.py final 2016 base files
validate_stage1*.py, figures_stage1.py validation tables and figures