Repository navigation
Control Variables
Complete list of all 56 control variables used in SANDAG PopulationSim.
Control variables are demographic totals that PopulationSim matches during synthesis. Each control has:
-
Target: Household (
household) or Person (person) -
Geography: Where control is applied (
region,puma, ormgra) - Importance: Weight for balancing (higher = more precise matching)
- Expression: PUMS variable logic for classification
- Description: Human-readable explanation
| Range | Meaning | Example Use |
|---|---|---|
| 1,000,000,000 | Critical - Must match exactly | Total households |
| 1,000,000 | Very High - Top priority | Sex totals |
| 250,000 | High - Important demographics | Household size |
| 100,000 | Medium - Standard controls | Income, age, race |
Higher importance = tighter constraint during IPF optimization.
| ID | Control Name | Geography | Importance | Expression | Description |
|---|---|---|---|---|---|
| 1 | Total_HH |
mgra | 1,000,000,000 | (WGTP > 0) & (WGTP < np.inf) |
Total households (highest priority) |
Note: This is the most important control - must match exactly. All other controls are secondary.
| ID | Control Name | Geography | Importance | Expression | Description |
|---|---|---|---|---|---|
| 2 | HHSize_1 |
mgra | 250,000 | NP == 1 |
Single-person households |
| 3 | HHSize_2 |
mgra | 250,000 | NP == 2 |
Two-person households |
| 4 | HHSize_3 |
mgra | 250,000 | NP == 3 |
Three-person households |
| 5 | HHSize_4Plus |
mgra | 250,000 | NP >= 4 |
Households with 4+ persons |
Sum constraint: HHSize_1 + HHSize_2 + HHSize_3 + HHSize_4Plus = Total_HH
| ID | Control Name | Geography | Importance | Expression | Description |
|---|---|---|---|---|---|
| 6 | HHInc_0to14999 |
mgra | 100,000 | (HHADJINC >= 0) & (HHADJINC <= 14999) |
Income: $0-$14,999 |
| 7 | HHInc_15000to29999 |
mgra | 100,000 | (HHADJINC >= 15000) & (HHADJINC <= 29999) |
Income: $15,000-$29,999 |
| 8 | HHInc_30000to59999 |
mgra | 100,000 | (HHADJINC >= 30000) & (HHADJINC <= 59999) |
Income: $30,000-$59,999 |
| 9 | HHInc_60000to99999 |
mgra | 100,000 | (HHADJINC >= 60000) & (HHADJINC <= 99999) |
Income: $60,000-$99,999 |
| 10 | HHInc_100000to149999 |
mgra | 100,000 | (HHADJINC >= 100000) & (HHADJINC <= 149999) |
Income: $100,000-$149,999 |
| 11 | HHInc_150000to199999 |
mgra | 100,000 | (HHADJINC >= 150000) & (HHADJINC <= 199999) |
Income: $150,000-$199,999 |
| 12 | HHInc_200000Plus |
mgra | 100,000 | (HHADJINC >= 200000) |
Income: $200,000+ |
Variable: HHADJINC = Adjusted household income (inflation-adjusted to ACS year)
| ID | Control Name | Geography | Importance | Expression | Description |
|---|---|---|---|---|---|
| 13 | HHWork_0 |
mgra | 100,000 | workers == 0 |
Zero-worker households |
| 14 | HHWork_1 |
mgra | 100,000 | workers == 1 |
One-worker households |
| 15 | HHWork_2 |
mgra | 100,000 | workers == 2 |
Two-worker households |
| 16 | HHWork_3Plus |
mgra | 100,000 | workers >= 3 |
Households with 3+ workers |
Variable: workers = Derived from person-level ESR (employment status) within household
| ID | Control Name | Geography | Importance | Expression | Description |
|---|---|---|---|---|---|
| 17 | HHChild_0 |
mgra | 100,000 | HUPAC == 4 |
No children present |
| 18 | HHChild_1Plus |
mgra | 100,000 | (HUPAC == 1) | (HUPAC == 2) | (HUPAC == 3) |
One or more children present |
Variable: HUPAC = HH presence and age of children
- 1 = With children under 6 only
- 2 = With children 6-17 only
- 3 = With children under 6 and 6-17
- 4 = No children
| ID | Control Name | Geography | Importance | Expression | Description |
|---|---|---|---|---|---|
| 19 | Male |
mgra | 1,000,000 | SEX == 1 |
Male persons |
| 20 | Female |
mgra | 1,000,000 | SEX == 2 |
Female persons |
Sum constraint: Male + Female = Total Population (household + GQ)
| ID | Control Name | Geography | Importance | Expression | Description |
|---|---|---|---|---|---|
| 21 | Age_LT5 |
mgra | 100,000 | (AGEP >= 0) & (AGEP <= 4) |
Age 0-4 years |
| 22 | Age_5to9 |
mgra | 100,000 | (AGEP >= 5) & (AGEP <= 9) |
Age 5-9 years |
| 23 | Age_10to14 |
mgra | 100,000 | (AGEP >= 10) & (AGEP <= 14) |
Age 10-14 years |
| 24 | Age_15to17 |
mgra | 100,000 | (AGEP >= 15) & (AGEP <= 17) |
Age 15-17 years |
| 25 | Age_18to24 |
mgra | 100,000 | (AGEP >= 18) & (AGEP <= 24) |
Age 18-24 years |
| 26 | Age_25to34 |
mgra | 100,000 | (AGEP >= 25) & (AGEP <= 34) |
Age 25-34 years |
| 27 | Age_35to49 |
mgra | 100,000 | (AGEP >= 35) & (AGEP <= 49) |
Age 35-49 years |
| 28 | Age_50to64 |
mgra | 100,000 | (AGEP >= 50) & (AGEP <= 64) |
Age 50-64 years |
| 29 | Age_65Plus |
mgra | 100,000 | (AGEP >= 65) |
Age 65+ years |
Variable: AGEP = Age in years at time of survey
| ID | Control Name | Geography | Importance | Expression | Description |
|---|---|---|---|---|---|
| 30 | race_White |
mgra | 100,000 | race == 1 |
White alone, non-Hispanic |
| 31 | race_Black |
mgra | 100,000 | race == 2 |
Black/African American alone |
| 32 | race_AmInd |
mgra | 100,000 | race == 3 |
American Indian/Alaska Native |
| 33 | race_Asian |
mgra | 100,000 | race == 4 |
Asian alone |
| 34 | race_PacIsl |
mgra | 100,000 | race == 5 |
Pacific Islander alone |
| 35 | race_Other |
mgra | 100,000 | race == 6 |
Other race or two+ races |
| 36 | race_Hispanic |
mgra | 100,000 | race == 7 |
Hispanic/Latino (any race) |
Variable: race = Derived from RAC1P (race) and HISP (Hispanic origin)
- If
HISP > 1: race = 7 (Hispanic) - Else: race = simplified RAC1P category
| ID | Control Name | Geography | Importance | Expression | Description |
|---|---|---|---|---|---|
| 37 | employed_civilians |
region | 100,000 | (ESR == 1) | (ESR == 2) | (ESR == 4) | (ESR == 5) |
Civilian employed persons |
| 38 | employed_military |
region | 100,000 | ESR == 6 |
Active duty military |
| 39 | unemployed |
region | 100,000 | ESR == 3 |
Unemployed persons |
Variable: ESR = Employment status recode
- 1 = Civilian employed, at work
- 2 = Civilian employed, with job but not at work
- 3 = Unemployed
- 4 = Armed forces, at work
- 5 = Armed forces, with job but not at work
- 6 = Not in labor force
| ID | Control Name | Geography | Importance | Expression | Description |
|---|---|---|---|---|---|
| 40 | workers_age16to19 |
region | 100,000 | ((ESR == 1) | (ESR == 2)) & (AGEP >= 16) & (AGEP <= 19) |
Workers age 16-19 |
| 41 | workers_age20to24 |
region | 100,000 | ((ESR == 1) | (ESR == 2)) & (AGEP >= 20) & (AGEP <= 24) |
Workers age 20-24 |
| 42 | workers_age25to34 |
region | 100,000 | ((ESR == 1) | (ESR == 2)) & (AGEP >= 25) & (AGEP <= 34) |
Workers age 25-34 |
| 43 | workers_age35to44 |
region | 100,000 | ((ESR == 1) | (ESR == 2)) & (AGEP >= 35) & (AGEP <= 44) |
Workers age 35-44 |
| 44 | workers_age45to54 |
region | 100,000 | ((ESR == 1) | (ESR == 2)) & (AGEP >= 45) & (AGEP <= 54) |
Workers age 45-54 |
| 45 | workers_age55to64 |
region | 100,000 | ((ESR == 1) | (ESR == 2)) & (AGEP >= 55) & (AGEP <= 64) |
Workers age 55-64 |
| 46 | workers_age65Plus |
region | 100,000 | ((ESR == 1) | (ESR == 2)) & (AGEP >= 65) |
Workers age 65+ |
| ID | Control Name | Geography | Importance | Expression | Description |
|---|---|---|---|---|---|
| 47 | labor_force_age16to19 |
region | 100,000 | (ESR <= 5) & (AGEP >= 16) & (AGEP <= 19) |
Labor force age 16-19 |
| 48 | labor_force_age20to24 |
region | 100,000 | (ESR <= 5) & (AGEP >= 20) & (AGEP <= 24) |
Labor force age 20-24 |
| 49 | labor_force_age25to34 |
region | 100,000 | (ESR <= 5) & (AGEP >= 25) & (AGEP <= 34) |
Labor force age 25-34 |
| 50 | labor_force_age35to44 |
region | 100,000 | (ESR <= 5) & (AGEP >= 35) & (AGEP <= 44) |
Labor force age 35-44 |
| 51 | labor_force_age45to54 |
region | 100,000 | (ESR <= 5) & (AGEP >= 45) & (AGEP <= 54) |
Labor force age 45-54 |
| 52 | labor_force_age55to64 |
region | 100,000 | (ESR <= 5) & (AGEP >= 55) & (AGEP <= 64) |
Labor force age 55-64 |
| 53 | labor_force_age65Plus |
region | 100,000 | (ESR <= 5) & (AGEP >= 65) |
Labor force age 65+ |
Note: Employment controls are region-level only (not MGRA-level) because:
- Employment data less reliable at fine geography
- Labor force participation is regional economic characteristic
- Reduces computational complexity
Group quarters controls use exact sampling (not IPF importance weights):
| ID | Control Name | Geography | Importance | Expression | Description |
|---|---|---|---|---|---|
| 57 | gq_mil_pop |
mgra | None | gq_type == 1 |
Military group quarters population |
| 58 | gq_college_pop |
mgra | None | gq_type == 2 |
College dormitory population |
| 59 | gq_other_pop |
mgra | None | gq_type == 3 |
Other group quarters population |
Process: After IPF synthesis, GQ persons are sampled from seed data to exactly match these totals (no balancing needed).
| Controls | Data Source | Query/File |
|---|---|---|
| 1-36 (HH & Person) | UDM Staging Database | sql/mgra_controls.sql |
| 37-53 (Employment) | Economic Team CSV | data/Economic Team Region Controls.csv |
| 57-59 (Group Quarters) | UDM Staging Database |
sql/mgra_controls.sql (separate section) |
Before running PopulationSim, verify controls pass these checks:
# All MGRAs should have controls (even if zero)
df_controls = pd.read_csv('populationsim/data/controls.csv')
unique_mgras = df_controls['mgra'].nunique()
assert unique_mgras == 23002, f"Missing MGRAs: {23002 - unique_mgras}"# Household size should sum to total households
for mgra in df_controls['mgra'].unique():
total_hh = df_controls.loc[(df_controls['mgra'] == mgra) &
(df_controls['target'] == 'Total_HH'), 'value'].sum()
size_sum = df_controls.loc[(df_controls['mgra'] == mgra) &
(df_controls['target'].isin(['HHSize_1', 'HHSize_2',
'HHSize_3', 'HHSize_4Plus'])),
'value'].sum()
assert abs(total_hh - size_sum) < 1, f"MGRA {mgra}: Size sum mismatch"# All controls must be >= 0
assert (df_controls['value'] >= 0).all(), "Negative control values found!"# Total HH should be in expected range
region_hh = df_controls.loc[df_controls['target'] == 'Total_HH', 'value'].sum()
assert 1_000_000 < region_hh < 2_000_000, f"Unreasonable HH total: {region_hh:,}"To add a new control variable:
1. Define in populationsim/configs/controls.csv:
target,control_name,seed_table,geography,importance
household,HHType_Family,households,mgra,1000002. Add expression to seed data creation:
# In python/build_seed_data.py
df_households['HHType_Family'] = (df_households['HHT'].isin([1, 2, 3, 4, 5, 6])).astype(int)3. Add to control generation query:
-- In sql/mgra_controls.sql
SELECT
mgra,
'HHType_Family' as target,
SUM(CASE WHEN household_type IN ('Family') THEN households ELSE 0 END) as value
FROM staging_table
GROUP BY mgra4. Test with small geography first:
# In config.yml, test with one year and verify
years:
- 2022Next: Algorithm Details - How PopulationSim balances these 56 controls