Repository navigation
FAQ
Quick answers to common questions about SANDAG PopulationSim.
PopulationSim is a demographic simulation tool that creates synthetic households and persons matching aggregate demographic forecasts. It takes aggregate totals (e.g., "1,000 households in area X") and generates individual-level microdata with detailed attributes while maintaining statistical consistency with the input controls.
Activity-Based Models (ABM) require individual-level data to simulate travel behavior, but we only have aggregate forecasts. PopulationSim bridges this gap by creating realistic synthetic individuals that match the aggregate constraints.
SANDAG uses PopulationSim v0.10.0 from the ActivitySim framework, customized for the San Diego region with specific control variables and geographic structure.
- First time: ~8-10 hours (includes seed data creation ~15 minutes + all 7 years)
- Subsequent runs: ~6-8 hours (seed data reused)
- Single year: ~70 minutes after seed data exists
Yes! Edit config.yml and comment out years you don't need:
years:
- 2022 # Keep only this one
# - 2026
# - 2029
# ... etcPython 3.9, 3.10, 3.11, and 3.12 are supported. Python 3.13+ is not yet supported by PopulationSim dependencies.
The current main.py workflow uses SQL Server queries to build seed data, controls, and the ABM MGRA file. Azure Data Lake access is also required when sql.load_to_database is enabled; set datalake.env and the corresponding SAS-token environment variable. Set that switch to False to keep outputs local and skip the export.
The current main.py workflow connects to SQL Server for input and ABM data. It can skip Azure access by setting sql.load_to_database: False, but it is not an offline workflow without changing how those SQL inputs are provided.
uv is a fast Rust-based package manager that:
- Resolves dependencies 10-100x faster than pip
- Automatically creates and manages virtual environments
- Provides better error messages
- Is the recommended tool for modern Python projects
You can still use pip if you prefer: pip install -e .
Recommended: 16GB RAM minimum, 32GB preferred. PopulationSim uses 22 parallel processes (one per PUMA) which can consume significant memory during synthesis.
- Minimum: 5GB free for outputs
- Recommended: 10GB free
- With database: Additional 5GB for SQL Server data files
Breakdown:
- Seed data: ~500MB
- Output per year: ~1.2GB
- All 7 years: ~8.4GB
Seed data is drawn from ACS PUMS (American Community Survey Public Use Microdata Sample) 2017-2021 5-year estimates. This provides actual households and persons from surveys that are weighted and resampled to match our control totals.
Control variables are demographic totals we want the synthetic population to match. SANDAG uses 56 controls including:
- Household size (1, 2, 3, 4+ persons)
- Income brackets (7 categories)
- Workers per household (0, 1, 2, 3+)
- Age groups (9 categories)
- Sex (Male/Female)
- Race/ethnicity (7 categories)
- Employment status (workers, unemployed, not in labor force)
- Demographic controls: UDM (Urban Data Models) staging database - SANDAG's forecast system
- Economic controls: Economic Team CSV file with employment and labor force
Three levels:
- Region: 1 (San Diego County)
- PUMA: 22 (Public Use Microdata Areas)
- MGRA: ~23,000 (Master Geographic Reference Areas)
Controls are specified at PUMA and MGRA levels, and PopulationSim balances hierarchically.
Not all MGRAs are residential. Some are:
- Commercial/industrial zones
- Parks and open space
- Transportation infrastructure
- Water bodies
These MGRAs will have zero households but may still have employment data.
Iterative Proportional Fitting (IPF) with simultaneous integerization. It's an optimization problem that:
- Starts with seed households/persons
- Assigns fractional weights to match control totals
- Integerizes weights (converts to whole numbers)
- Balances across geographic levels
Converting fractional household weights to whole numbers. You can't have 2.7 households - you need exactly 2 or 3. PopulationSim solves this while maintaining control totals.
When an MGRA has a control target (e.g., 50 households) but no suitable seed households can match, PopulationSim "backstops" by:
- Relaxing constraints
- Looking for near-matches from broader geography
- Accepting larger deviation to avoid zero households
This limits how many times a single seed household can be replicated. Setting it to 30 means one PUMS household can represent up to 30 synthetic households. This prevents over-reliance on single observations while allowing sufficient flexibility.
PopulationSim runs 22 parallel processes, one per PUMA:
- Each process handles only its assigned PUMA's MGRAs
- After PUMA-level balancing, results combine
- Then MGRA sub-balancing happens (also parallelized)
- Final expansion creates actual household records
MGRA-level summary file with demographic totals (households, population, group quarters, employment). The ABM reads this file for zonal data.
Check for:
- ✅ All output files exist
- ✅ Household and person counts are reasonable (~1.2M households, ~3.5M persons)
- ✅ No error messages in logs
- ✅ Summary files show small percent differences (<1% for most controls)
- ✅ Streamlit dashboard shows good control fits
Yes, but carefully:
- Ensure household-person linkage remains valid
- Maintain consistent mgra assignments
- Don't break demographic totals if precision is important
- Document any changes for reproducibility
Good fit:
- Regional controls: <0.1% difference
- PUMA controls: <1% difference
- MGRA controls: <5% difference (more tolerance at fine geography)
Warning signs:
- Any geography >10% difference
- Systematic bias (all controls too high or too low)
- Large number of zero-household MGRAs that should have households
An interactive web application for validating PopulationSim results. Launch with:
cd report
streamlit run report.pyFeatures:
- Control vs. result comparisons
- Local-output benchmarks marked Benchmark Only, separate from PopulationSim fitting controls
- Run-specific archived benchmark definitions when available
- Geographic distribution maps
- Demographic breakdowns
- Interactive filtering and drill-down
Check:
- GQ population totals match controls
- GQ types distributed correctly (military, college, other)
- No GQ persons in regular households
- GQ persons have consistent attributes (age appropriate for college dorms, etc.)
Causes:
- Impossible control combinations (e.g., more workers than persons)
- Seed data doesn't cover needed demographic profile
- Too-tight importance weights
Solutions:
- Check control data for errors
- Review
settings.yamlimportance weights - Lower importance for problematic controls
- Check logs for specific MGRA failures
Normal: ~15 minutes is expected for first run
Too slow (>1 hour):
- Database connection is slow
- Query performance issues
- Insufficient memory causing swapping
Solution: Check network speed to database, optimize SQL queries
Expected reasons:
- Control data changed (UDM updated)
- Different seed data (ACS vintage changed)
- Algorithm parameters modified
- Random seed different
Solution: Check config.yml and settings.yaml for changes
Ensure same:
- Seed data (same ACS vintage)
- Control data (same UDM query results)
- Config settings (
config.ymlandsettings.yaml) - PopulationSim version
- Random seed
Version control your config files!
Yes. The Streamlit report can read local output folders directly. The full main.py workflow still needs SQL Server for its seed, control, and ABM data queries. Azure Data Lake export is separate and can be skipped with sql.load_to_database: False.
Despite its legacy name, sql.load_to_database controls the optional Azure Data Lake export performed by main.py; it does not load outputs into SQL Server. The Streamlit report's database source is separate. The export includes the saved benchmark_comparisons.csv so downstream consumers can use the same benchmark results as the local report.
Not without code modifications. The ETL code (python/etl.py) is specific to SQL Server. You'd need to adapt:
- Connection strings
- SQL dialects
- Schema definitions
ABM reads:
-
households.csv- household attributes -
persons.csv- person attributes -
mgra_based_input_YYYY.csv- zonal summaries
These are created automatically by python/outputs.py after synthesis.
Yes, modify python/outputs.py function create_abm_outputs(). Add/remove columns as needed, but coordinate with ABM team on schema changes.
Group quarters persons are included in persons.csv with:
-
household_idstill assigned (for technical reasons) -
mgraindicates location - Specific
gq_typeattribute
ABM handles GQ persons differently than household residents.
Yes! Edit:
-
populationsim/configs/controls.csv- add control definition -
sql/mgra_controls.sql- query to fetch control values - Rerun with new configuration
Note: Control must be expressible using PUMS variables.
Yes, edit populationsim/configs/settings.yaml:
importance_weights:
Total_HH: 1000000000 # Highest (exact match)
HHSize_1: 250000 # High
Age_25to34: 100000 # Medium
# ... etcHigher importance = tighter constraint.
Yes, edit config.yml:
years:
- 2018
- 2023
- 2030
# Any years where UDM has forecastsMake sure UDM staging database has data for those years.
Still have questions?
- Check the comprehensive technical documentation
- Review Troubleshooting guide
- Contact the SANDAG Modeling team