Repository navigation
Home
Welcome to the SANDAG Population Synthesizer documentation wiki! This system generates synthetic populations for the San Diego region using the ActivitySim PopulationSim framework.
- Getting Started - New to PopulationSim? Start here
- Installation & Setup - Install dependencies and configure the system
- Running PopulationSim - Execute synthesis runs step-by-step
- Output Files - Understanding the generated data
- Validation & QA - Quality assurance procedures
- Getting Started - Quick start guide for first-time users
- System Overview - Architecture and key concepts
- FAQ - Frequently asked questions
- Installation & Setup - Python environment and dependencies
- Running PopulationSim - Complete execution workflow
- Data Preparation - Seed data and control generation
- Configuration Reference - Settings and parameters
- Troubleshooting - Common issues and solutions
SANDAG's PopulationSim creates synthetic households and persons that match regional forecasts:
- Input: Aggregate demographic forecasts (e.g., "1,000 households in MGRA 12345")
- Output: Individual synthetic households and persons with detailed attributes
- Coverage: ~23,000 MGRAs across San Diego County
- Forecast Years: 2022, 2026, 2029, 2032, 2035, 2040, 2050
flowchart LR
A[ACS PUMS<br/>Seed Data] --> D[PopulationSim<br/>Engine]
B[UDM Forecasts<br/>Control Totals] --> D
C[Economic<br/>Controls] --> D
D --> E[Synthetic<br/>Households]
D --> F[Synthetic<br/>Persons]
E --> G[ABM Model]
F --> G
β
56 control variables - Demographics, income, household size, workers, age, race/ethnicity
β
Three-level geography - Region β 22 PUMAs β ~23,000 MGRAs
β
Parallel processing - 22 simultaneous PUMA processes
β
Group quarters - Military, college dorms, other institutional
β
Quality assurance - Interactive Streamlit validation dashboard
β
Reporting benchmarks - Separate from fitting controls and saved with each run
β
ABM-ready outputs - Direct integration with activity-based travel model
- PopulationSim: v0.10.0 (ActivitySim framework)
- Python: 3.9 - 3.12 (3.13+ not yet supported)
- Package Manager: uv (fast dependency resolution)
- SQL inputs: Microsoft SQL Server
-
Run export: Optional Azure Data Lake export, controlled by
sql.load_to_database - Validation: Streamlit report for local output or its database source
The active seed vintage, forecast years, and export environment are configured in config.yml.
For questions or issues:
- Check the FAQ and Troubleshooting pages
- Review the comprehensive technical documentation
- Contact the SANDAG Modeling team
Population-Sim/
βββ config.yml # Main configuration file
βββ main.py # Entry point for full workflow
βββ pyproject.toml # Python dependencies
βββ data/ # Input data files
βββ documentation/ # Complete technical documentation
βββ populationsim/ # PopulationSim execution scripts
β βββ configs/ # PopulationSim settings
β βββ data/ # Geographic crosswalk
β βββ output/ # Synthesis results
βββ python/ # Data preparation modules
β βββ build_controls.py # Control generation
β βββ build_seed_data.py # Seed data preparation
β βββ etl.py # Legacy SQL Server output loading
β βββ datalake_exporter.py # Optional Azure Data Lake export
β βββ outputs.py # ABM output creation
βββ report/ # Validation dashboard
βββ sql/ # SQL queries for data extraction
Ready to get started? β Installation & Setup