[MaxGhenis]

Summary

Max asked whether PolicyEngine-US should make its income concepts explicit, starting with Census money income. #10693 adds veterans' and railroad benefits to household benefits and cites Census's money income definition; this PR makes that definition a variable and checks the CBO income measures against CBO's published definitions.

• Census money income. census_money_income (person), census_family_money_income (family) and census_household_money_income (household) add the 18 sources in Current Population Reports P60-200 (1998), Appendix A, which the survey's current subject definitions still list. Each source is one list under gov.household.census_money_income_sources, citing the Appendix A pages that define it. Retirement account distributions count from age 58, as the survey has counted them since its 2019 redesign.
• CBO measures. Six fixes bring cbo_household_* in line with CBO's The Distribution of Household Income in 2021 (publication 60341), with a citation on every list.
• Parity tests. Every source that any income concept counts (household benefits, market income, the Census lists and the CBO lists: 139 variables from 2024) must be in each concept or in that concept's documented exclusion list. The tests check that each concept moves dollar for dollar with every source it lists and not at all with the sources it excludes.

Census money income

Appendix A source	Model variables
1. Earnings	employment_income, self_employment_income, sstb_self_employment_income, partnership_s_corp_income, farm_operations_income, farm_rent_income
2. Unemployment compensation	total_unemployment_compensation, strike_benefits (Appendix A counts union strike benefits here)
3. Workers' compensation	workers_compensation
4. Social Security	social_security
5. Supplemental Security Income	ssi and 45 state supplements
6. Public assistance	tanf, general_assistance, co_oap, ma_eaedc, wa_sfa, wa_rca
7. Veterans' payments	veterans_benefits
8. Survivor benefits	survivor_benefits, military_retirement_pay_survivors
9. Disability benefits	disability_benefits, pfml_benefits
10. Pension or retirement income	pension_income, military_retirement_pay, census_retirement_distributions, railroad_benefits
11. Interest	interest_income
12. Dividends	dividend_income
13. Rents, royalties, estates and trusts	rental_income, estate_income
14. Educational assistance	educational_assistance
15. Alimony	alimony_income
16. Child support	child_support_received
17. Financial assistance from outside the household	financial_assistance
18. Other income	gi_cash_assistance, ak_permanent_fund_dividend, ak_energy_relief, basic_income, trump_dividend, ca_la_infant_supplement, ca_la_expectant_parent_payment

Left out. Appendix A leaves out capital gains (capital_gains, non_sch_d_capital_gains, other_net_gain_person), tax refunds (salt_refund_income, and property tax relief such as nj_property_tax_relief) and lump-sum insurance payments (page A-3), and noncash benefits (page A-2): SNAP, WIC, school meals, CSFP, housing assistance, energy subsidies, child care subsidies, Head Start, Medicaid, CHIP, the Medicare Savings Programs, Medicare, the premium tax credit (paid to the insurer) and the 12 state health subsidies, plus discounts and rebates (ACP, EBB, CARE, FERA, vehicle and electrification rebates). The list treats renters' property tax relief like homeowners'. Discharged debt (debt_relief) is not money received. Income from bribes and other illegal activity (illicit_income) is not a regular payment under other income, and no other source covers it. miscellaneous_income stays out because no Appendix A source fits it: the default data fills it with Census other income on survey records and with Form 4797 business property gains and losses on tax records (microcosm#393), and the model cannot separate the two. The test file gives the reason for every variable in household market income or household benefits that the Census concept leaves out.

Gaps. The model lacks three Appendix A sources: Black lung payments, military family allotments and foreign government pensions. It has foster child payments only for Los Angeles County and no variable for interest earned inside retirement accounts, which the survey has counted as interest since 2019. Many listed variables hold $0 in the default dataset (listed under Impact), so sources 8 and 17 total $0 there, and source 18 falls short of Census's total because of miscellaneous_income above.

Conventions

• A benefit the model computes for a group goes to each member in equal shares, as household totals split group amounts. That covers TANF, nine state SSI supplements and cash programs (all paid to the SPM unit), basic_income (tax unit) and Los Angeles's infant supplement (household). The Current Population Survey records the payment for the person who reports it, so the person-level amounts differ while the family and household totals match.
• The person variable covers every age. Census asks the income questions of people 15 and older and records SSI for a child under 15 in the parent's SSI (IPUMS SSIKID). The family and household totals add every member.
• Appendix A counts military survivor pensions as survivor benefits, so the lists take military_retirement_income apart: retirement pay under source 10, survivor annuities under source 8. railroad_benefits holds the Railroad Retirement Board's retirement, disability and survivor annuities in one variable, so it stays under source 10, and the disability and survivor lists say so. Neither choice changes the total.
• Each Census list has one block, in effect in every year. Retirement account distributions count at any age through 2017, as Appendix A says, and from age 58 from 2018, because the survey's 2019 redesign, which collects 2018 income, leaves withdrawals by people under 58 out of total income. On the 2025 and 2026 public use files all 2,455 records with such withdrawals have other income (POTHVAL) equal to the sources without them, and all 9,770 records with distributions at 58 or older include them. The test uses age in the income year; Census uses age at the survey.

CBO income measures

Checked against 60341 Appendix D (definitions, PDF page 41), Appendix A note 3 (page 27) and the tax definitions (page 42):

1. Medicare net of premiums. Social insurance counted medicare_gross_cost; CBO measures Medicare as average cost net of offsetting receipts (note 3; also CBO 61157). The list now counts medicare_cost, which subtracts Part A and Part B premiums; Part D premiums stay in.
2. Premium tax credit. CBO's individual income taxes include refundable credits, the premium tax credit among them. income_tax leaves out the PTC (gov.irs.credits.refundable omits it), so the new cbo_federal_tax_subtractions list subtracts assigned_aca_ptc from CBO federal taxes.
3. Corporate income tax. CBO puts workers' share of corporate income tax in labor income and owners' share in capital income. cbo_corporate_income_tax (an optional household input, default 0) counted only in taxes; it now also counts in market income, so it nets out of income after taxes as CBO intends.
4. Retirement income for past services. CBO's market income includes "income received in retirement for past services". The PR adds railroad_benefits (the Current Population Survey records railroad retirement as retirement income: IPUMS INCSS) and survivor_benefits (survivor pensions and annuities).
5. Other nongovernmental income. Market income also includes "other nongovernmental sources of income"; CBO takes nontaxable income sources from the Current Population Survey (working paper 2017-09, page 37). The PR adds child_support_received and financial_assistance. educational_assistance stays out, as on main: it holds Pell Grants and other government aid beside private scholarships (IPUMS INCEDUC), the model doesn't split them, and CBO's transfer lists name no education grants.
6. Means-tested transfers. The PR adds wic (child nutrition programs: WIC is section 17 of the Child Nutrition Act, 42 U.S.C. 1786) and msp_cost (Medicaid pays Medicare premiums and cost sharing, 42 U.S.C. 1396a(a)(10)(E)) and the 45 state SSI supplements and four state cash programs (co_oap, ma_eaedc, wa_sfa, wa_rca) under CBO's SSI and state and local general assistance. CBO also counts Part D low-income subsidies and ACA cost-sharing subsidies, which the model does not value; the list says so.

Veterans' benefits stay out of the CBO measures. CBO's income categories have not named veterans' benefits since its report on 2014 (published March 2018); working paper 2017-09 counted them as means-tested transfers. Main also leaves them out. The test file records this as a documented exclusion, along with state paid family leave (outside CBO's four social insurance programs), guaranteed income pilots, the Alaska dividend and energy relief, and contributed reforms' payments.

Judgment calls

Each of these is a single reading where the sources leave room; each is disclosed in the list it touches and in the test file's exclusion reasons.

• Veterans' benefits: outside CBO's measures (above).
• educational_assistance: outside CBO's measures, since its government part (Pell Grants first) is not "nongovernmental" income and the model can't separate its private scholarships.
• Railroad retirement and survivor benefits as CBO retirement income for past services.
• WIC as a child nutrition program; the Medicare Savings Programs as Medicaid (means-tested).
• State SSI supplements and state cash programs as CBO means-tested transfers.
• pfml_benefits in Census disability benefits, outside CBO.
• partnership_s_corp_income in Census earnings (self-employment).
• Property tax relief as a tax refund, renters' relief included, and utility discounts and rebates as noncash, for Census.
• The survey's age-58 rule for retirement account distributions, applied from 2018, where Appendix A has no age limit.
• Net rental income: 60341 says "rental income"; working paper 2017-09 and the 2014 report said "positive rental income". The lists keep net rental income.

Invariants and tests

tests/test_income_concept_parity.py states five invariants and checks each for every year from 2022 to 2026. The last three hold each source as an input, because a program's own formula responds to income:

1. Coverage. Every source any list counts is in each concept (Census, CBO) or in that concept's documented exclusions; stale exclusions fail.
2. No double counting. No list repeats a variable; the 18 Census lists are disjoint; the CBO categories are disjoint; CBO additions don't repeat market_income_sources; CBO subtractions come from it; neither concept counts two variables that reach a common variable through adds, at any depth (CBO counts medicaid_cost through medicaid and the military parts through military_retirement_income; Census counts military_retirement_income through its parts), and each such variable must add exactly the parts the tests name.
3. Dollar for dollar. Each listed source moves the concept by its amount, at the person (equal share), family and household levels, and moves only its own CBO category (Hypothesis over amounts, losses and household sizes; one simulation holds a paid and an unpaid household for every source). Retirement account distributions move Census money income only from the age it counts them, tested at every age from 15 to 90 in 2017, 2018 and 2026.
4. Exclusions move nothing. Every excluded source leaves the concept unchanged.
5. Totals. Family and household totals equal the sum of members and match an independent numpy allocation, with SPM units, tax units and families drawn separately within a household and paying groups of each kind; census_household_money_income reconciles with household_market_income + household_benefits less the sources Census excludes plus the ones it adds, in each of the 51 states, for a working-age household with children, an aged person and a disabled person. That reconciliation reads the same lists as the variables, so it tests how the variables add them, not where a program belongs.

YAML: census_money_income.yaml (9 cases from Appendix A and the survey: a person with income from every source the model holds, the excluded receipts, an SPM-unit TANF split, group benefits split by the paying group, roommates in two families, a state cash program, and the age test at 58, at 57 and before the redesign) and, in cbo_household_income.yaml, three updated cases and one new one. test_aggregate_list_integrity.py now also checks that no year block of the new lists silently drops a variable.

tests/code_health/test_military_retirement_readers.py fails any benefit list that names military_retirement_pay without military_retirement_pay_survivors. The Census lists count the two under different sources, so its new SPLIT_YAML_FILES lets the pension list pass only while the survivor list holds the annuities.

Mutation checks. Removing the group-size division in census_money_income fails the dollar-for-dollar, totals and reconciliation tests. Moving snap into public assistance, adding railroad_benefits to market_income_sources and dropping wic from CBO means-tested transfers gives 15 failures, each naming the source. Counting military_retirement_income beside its parts fails test_no_source_counts_twice; dropping the survivor annuities fails test_census_classifies_every_source and test_exclusions_are_current; giving military_retirement_income a third part fails test_aliases_sum_exactly_their_parts. On the guard, taking the annuities out of the survivor list fails test_benefit_source_lists_do_not_read_raw_military_retirement_pay; listing them in the pension list itself, or dropping the raw input from it, fails test_split_yaml_files_still_need_their_partner.

On the logic the review added (run at 79f39e6152), each of ten mutations fails the test named:

• A minimum age of 57, or dropping the age test from the formula: test_census_counts_retirement_distributions_from_age_58 for 2018 and 2026 and a YAML age case.
• Dating the age rule 2019: the same test for 2018.
• Listing raw retirement_distributions beside the limited variable, or social_security_retirement beside social_security: test_no_source_counts_twice in every year.
• Dropping the limited variable from its list: test_no_source_counts_twice and test_census_classifies_every_source in every year.
• Listing tanf twice: test_no_list_names_a_source_twice.
• Making medicaid add chip: test_aliases_sum_exactly_their_parts.
• Splitting group benefits by household size: test_totals_sum_members_and_match_an_independent_allocation in every year and a YAML case.
• Listing the state SSI supplements only from 2023: test_census_classifies_every_source for 2022.

Why Python. The coverage and double-counting invariants iterate over every list and year, which YAML cannot do; the dollar-for-dollar and exclusion checks run every source (139 in 2024) through paired households; the totals check compares the model with an independent numpy allocation, not with its own formula. No existing test checks concept membership; test_aggregate_list_integrity.py checks year blocks only, and the PR extends it to the new lists.

Cost. New file: 958 lines. The tests build only household simulations on the shared system, with no reformed systems or datasets.

• Local macOS (Python 3.14), measured back to back on 2026-11-09. Main at 92caead63e, test_aggregate_list_integrity.py alone: 31 tests, 0.57 s of test time, 24.24 s elapsed, 1.15 GB peak RSS. This branch at 79f39e6152, that file plus test_income_concept_parity.py: 113 tests, 88.30 s of test time, 144.68 s elapsed, 3.90 GB peak RSS.
• Linux CI. The new file runs in Python shard 5's remaining-2 group (run 42606943944 at 79f39e6152): 63 tests in 111.1 s of test time, the largest 11.4 s, third by test time among the group's 73 files. That group took 29:19.97 and peaked at 7.52 GB, below the 8.19 GB that shard 4's remaining-1 group reached in the same run. The aggregate-list file, in remaining-1, took 0.46 s.

Impact

Four full microsimulation runs through the host's heavy-run queue, on hf://datasets/policyengine/populace-us/populace_us_2024.h5@populace-us-2024-spm-20260909: this branch for 2024, 2025 and 2026 (298 to 338 s each) and main for 2026 (246 s). The branch ran at 79f39e6152. Main ran at 92caead63e.

Census money income next to Census's published aggregates

Census table PINC-08 reports each source's recipients and mean for people 15 and older; its aggregate is their product and carries their rounding. Income year 2024 comes from the 2025 release and 2025 from the 2026 release. Census has not published 2026 income, so the 2026 column stands alone. Figures are billions of dollars for people 15 and older: PINC-08 reads age as of March of the following year, and the model reads it in the income year.

Appendix A source	PolicyEngine 2024	Census 2024	Ratio	PolicyEngine 2025	Census 2025	Ratio	PolicyEngine 2026
Earnings	12,673.3	12,645.3	1.00	13,095.6	13,272.0	0.99	13,683.0
Unemployment compensation	33.5	24.7	1.36	37.5	23.5	1.59	42.1
Workers compensation	4.8	19.6	0.25	5.1	27.1	0.19	5.3
Social security	1,463.0	1,226.5	1.19	1,584.6	1,333.8	1.19	1,675.8
Supplemental security income (a)	59.3	58.7	1.01	59.6	61.6	0.97	61.1
Public assistance (a)	5.7	8.6	0.67	6.1	6.1	1.01	6.0
Veterans payments	121.7	132.2	0.92	125.9	149.0	0.85	130.3
Survivor benefits	0.0	65.9	0.00	0.0	69.2	0.00	0.0
Disability benefits	20.7	43.5	0.48	21.8	46.4	0.47	22.7
Pension or retirement income	1,809.6	853.2	2.12	2,161.9	896.9	2.41	2,355.0
Interest	382.6	817.0	0.47	400.1	935.8	0.43	440.4
Dividends	457.5	216.4	2.11	470.4	280.5	1.68	500.6
Rents royalties estates and trusts	138.8	255.5	0.54	148.4	211.5	0.70	156.4
Educational assistance	81.1	81.4	1.00	86.7	85.2	1.02	91.4
Alimony	20.4	4.5	4.49	21.8	8.5	2.57	23.0
Child support	16.5	23.6	0.70	17.1	19.9	0.86	17.7
Financial assistance	0.0	40.0	0.00	0.0	31.6	0.00	0.0
Other income (a)	1.0	16.3	0.06	0.6	19.6	0.03	0.7
Money income	17,289.5	16,535.2	1.05	18,243.0	17,477.8	1.04	19,211.4

(a) The source includes a benefit the model computes for a group. census_money_income splits it equally among the group's members. For the comparison with PINC-08, which records a payment for the person who reports it, these 15-and-older figures split it among the members 15 and older, each of whom counts as a recipient.

PolicyEngine's total exceeds Census's by 5% in 2024 and by 4% in 2025. The sources differ in both directions, as the ratios show. The table reports these gaps and doesn't attribute them: the PR adds no calibration and changes no dataset.

• Pension or retirement income. PINC-08's retirement income row includes payments reported as survivor or disability benefits, which also have their own rows, as the table's header says. Source 10 therefore compares with that row less those two ($853.2bn and $896.9bn), for which Census publishes no recipient count.
• Retirement accounts. Since its 2019 redesign the survey leaves withdrawals by people under 58 out of total income, so census_retirement_distributions counts from 58. In the default data retirement_distributions totals $890.4bn in 2024 and $1,063.7bn in 2025, and people 58 and older receive $526.4bn and $628.9bn of it. On the public use files, withdrawals by people under 58 total $57.4bn and $52.9bn; PINC-08's account row, for people 58 and older, shows $300.7bn and $321.6bn.
• Interest. The survey's interest includes interest earned inside retirement accounts, which it has asked about since 2019: $627.2bn of $816.7bn in 2024 and $752.6bn of $935.5bn in 2025 on the public use files. The model has no variable for that income.
• Other income. Source 18 holds guaranteed income, the Alaska payments, the two Los Angeles County payments and contributed reforms' payments. Census's other income reaches the model as miscellaneous_income on survey records, and tax records put Form 4797 business property gains and losses in the same variable (microcosm#393), so the concept leaves that variable out: it totals $-1.3bn in 2024 and $-1.4bn in 2025 for people 15 and older.

Year	People 15+ ($bn)	All ages ($bn)	Families ($bn)	Households ($bn)	Largest gap, variable less sum of items, one person ($)
2024	17,289.5	17,297.9	17,297.9	17,297.9	0.91
2025	18,243.0	18,252.5	18,252.5	18,252.5	0.77
2026	19,211.4	19,221.8	19,221.8	19,221.8	0.71

Parts of a source and recipient counts

Part of a source	PolicyEngine variables	PolicyEngine 2024	Census 2024	Ratio	PolicyEngine 2025	Census 2025	Ratio
Wages and salary	employment_income	10,736.3	12,072.4	0.89	11,266.1	12,614.6	0.89
Nonfarm self-employment	self_employment_income, sstb_self_employment_income, partnership_s_corp_income	1,905.0	534.0	3.57	1,795.2	600.9	2.99
Farm self-employment	farm_operations_income, farm_rent_income	32.0	34.0	0.94	34.2	52.7	0.65
Military retirement	military_retirement_pay	0.0	38.7	0.00	0.0	40.3	0.00
Railroad retirement	railroad_benefits	0.0			0.0	2.6	0.00
401(k), 403(b), IRA, Keogh, SEP and other accounts	census_retirement_distributions	526.4	300.7	1.75	628.9	321.6	1.96

Appendix A source	PolicyEngine 2025, 15+ (m)	Census 2025 (m)
Earnings	191.64	175.30
Unemployment compensation	4.82	3.57
Workers compensation	0.67	1.50
Social security	58.06	62.01
Supplemental security income (a)	8.74	5.75
Public assistance (a)	2.09	1.36
Veterans payments	5.17	5.98
Survivor benefits	0.00	3.38
Disability benefits	1.68	2.64
Pension or retirement income	46.90
Interest	88.27	158.10
Dividends	43.50	40.98
Rents royalties estates and trusts	15.48	12.52
Educational assistance	8.28	7.55
Alimony	0.30	0.15
Child support	3.49	2.95
Financial assistance	0.00	3.10
Other income (a)	0.60	2.60
Any money income	252.08	248.30

PINC-08's rows within retirement income include payments reported as survivor or disability benefits. (a) marks the sources described under the first table.

Zero in this dataset. 40 variables the Census lists count total exactly $0 in all three years: al_ssp, basic_income, ca_capi, ca_la_expectant_parent_payment, ca_la_infant_supplement, co_state_supplement, dc_ossp, de_ssp, financial_assistance, fl_oss, ga_ssp, general_assistance, gi_cash_assistance, hi_oss, ia_ssa, id_aabd, in_ssp, ks_sspp, ky_ssp, la_oss, md_paa, military_retirement_pay, military_retirement_pay_survivors, mo_ssp, mt_ssp, nc_sa, ne_aabd, nm_ssi_state_supplement, oh_rss, or_ssp, pfml_benefits, railroad_benefits, sc_ssi_state_supplement, strike_benefits, survivor_benefits, trump_dividend, tx_ssi_state_supplement, va_ag, wa_rca, wa_sfa. The lists still count them, and the dollar-for-dollar tests cover each on household situations; they move no national total here.

CBO income measures, 2026

Measure	main ($bn)	Branch ($bn)	Change ($bn)	Rebuilt before, less main ($)
household_market_income	19,306.0	19,306.0	+0.0
cbo_household_market_income	20,099.4	20,117.1	+17.7	-1,577
cbo_household_social_insurance_benefits	2,835.2	2,671.2	-163.9	3,338
cbo_household_means_tested_transfers	1,096.9	1,128.8	+31.9	493
cbo_household_federal_taxes	4,317.2	4,269.6	-47.6	63
cbo_household_income_before_transfers_and_taxes	22,934.6	22,788.3	-146.3	1,057
cbo_household_income_after_transfers_and_taxes	19,714.3	19,647.5	-66.8	3,987

Component the branch moved	Total ($bn)
medicare_cost	946.0
medicare_gross_cost	1,109.9
assigned_aca_ptc	47.6
cbo_corporate_income_tax	0.0
railroad_benefits	0.0
survivor_benefits	0.0
child_support_received	17.7
financial_assistance	0.0
wic	11.7
msp_cost	15.4
State cash assistance (co_oap, ma_eaedc, wa_sfa, wa_rca)	0.8
45 state SSI supplements	4.1

The last column of the first table rebuilds each measure before the change (the branch's value less the components it moved) and compares it with main's run. The differences are at most $3,987 on totals in the trillions, so each measure moved by the listed components and nothing else.

WIC. The $11.7bn shows WIC at full take-up among those eligible: wic follows takes_up_wic_if_eligible, which defaults to true, and the default data doesn't set it. The data's would_claim_wic column reaches no variable in this package.

Coordination

• Count veterans' and railroad retirement benefits in household and SPM benefits #10693 adds veterans' and railroad benefits to household benefits. The parity tests already classify both, so either merge order works.
• Keep every baseline benefit in SPM resources under reforms that pay a benefit #10662 also edits test_aggregate_list_integrity.py; whichever lands second rebases.

axiom: n/a: statistical income concepts (Census money income and the CBO household income measures), not legal provisions

🤖 Generated with Claude Code