Correct uprating claims on the SPM poverty methodology page

[MaxGhenis]

Corrects the uprating paragraph in the Population section of docs-quarto/methodology/spm-poverty.qmd so it states only what the code does. Docs only: no model code changes.

What was wrong

The paragraph (added in #9438) made five uprating claims. Checked against CountryTaxBenefitSystem().variables[<name>].uprating after system init, where add_default_uprating has already run:

Claim in the old text	What the code does
CPI-U for rents	False. pre_subsidy_rent takes the default dollar-input uprating, CBO total adjusted gross income. rent is computed and has no uprating. No rent variable carries CPI-U.
CBO AGI by source for most income variables	Reversed. The main income sources follow IRS SOI series. The CBO parameter on variables is total AGI, and it is the default for every other dollar input.
IRS SOI series for others	True for the main income sources, with a caveat: every SOI parameter stops between 2020 and 2023 and carries parameter-level uprating metadata naming a CBO parameter, so the 2024 to 2025 growth is CBO's.
CMS per-capita spending for medical expenses	True for non-premium spending and other_health_insurance_premiums (calibration.gov.hhs.cms.moop_per_capita, per-capita out-of-pocket payments).
Census population estimates for the weights	The parameter is calibration.gov.census.populations.total, but its values and references are CBO's demographic outlook. Only household_weight (and family_weight) are uprated; person_weight and spm_unit_weight read household_weight.

CPI-U (gov.bls.cpi.cpi_u) does uprate 23 variables, none of them rent: child support paid and received, spm_unit_energy_subsidy, real_estate_taxes, and the asset and debt inputs.

Variables checked

uprating after system init, and the 2024 to 2025 ratio observed by calculating each input for both years on the default dataset (populace_us_2024.h5 at populace-us-2024-spm-20260909, time period 2024). Each ratio equals the uprating parameter's 2025 value over its 2024 value.

Variable	Input	uprating after init	Observed 2025/2024
pre_subsidy_rent	yes	calibration.gov.cbo.income_by_source.adjusted_gross_income (default)	1.06904
rent	no (formula)	None	n/a
spm_unit_pre_subsidy_childcare_expenses	yes	calibration.gov.cbo.income_by_source.adjusted_gross_income (default)	1.06904
employment_income_before_lsr	yes	calibration.gov.irs.soi.employment_income	1.04935
social_security_retirement	yes	calibration.gov.irs.soi.social_security	1.08312
unemployment_compensation	yes	calibration.gov.irs.soi.unemployment_compensation	1.13964
taxable_private_pension_income	yes	calibration.gov.irs.soi.taxable_pension_income	1.19468
long_term_capital_gains_before_response	yes	calibration.gov.irs.soi.long_term_capital_gains	1.27004
taxable_pension_income, long_term_capital_gains, employment_income, self_employment_income	no (formula)	None	n/a
other_medical_expenses	yes	calibration.gov.hhs.cms.moop_per_capita	1.03088
over_the_counter_health_expenses	yes	calibration.gov.hhs.cms.moop_per_capita	not run
other_health_insurance_premiums	yes	calibration.gov.hhs.cms.moop_per_capita	1.03088
health_insurance_premiums_without_medicare_part_b	yes	calibration.gov.hhs.cms.moop_per_capita	not run
health_insurance_premiums	yes	calibration.gov.cbo.income_by_source.adjusted_gross_income (default)	not run
child_support_expense	yes	gov.bls.cpi.cpi_u	1.02999
child_support_received	yes	gov.bls.cpi.cpi_u	1.02999
spm_unit_energy_subsidy	yes	gov.bls.cpi.cpi_u	1.02999
real_estate_taxes	yes	gov.bls.cpi.cpi_u	1.02999
net_worth	yes	gov.bls.cpi.cpi_u	1.02999
household_weight	yes	calibration.gov.census.populations.total	1.00928
family_weight	yes	calibration.gov.census.populations.total	not run
person_weight, spm_unit_weight, tax_unit_weight, marital_unit_weight	no (formula)	None	n/a
age, takes_up_snap_if_eligible, county_fips	yes	None	identical in both years

I also read uprating for all variables in the system. Across them, 278 carry the CBO total AGI parameter, 23 CPI-U, 17 the CMS parameter, 45 an IRS SOI series, 2 the population series and 1 (employer_sponsored_insurance_premiums) CBO employment income. No float dollar input is left without an uprating after init.

Of the columns in the default dataset, 33 follow an IRS SOI series, 44 the CBO total AGI default, 11 CPI-U, 4 the CMS parameter and 1 the population series. The rest have no uprating and carry over unchanged.

How the mechanism was confirmed

• Population runs: Microsimulation extends the single-year dataset with extend_single_year_dataset in policyengine_us/data/economic_assumptions.py. For each column it chains year-over-year ratios of the variable's uprating parameter, or of the path in MICRODATA_UPRATING_OVERRIDES for formula-owned columns. Columns without an uprating parameter carry forward unchanged. For the default dataset's columns the overrides name the same series as the variables. That table also maps rent to CPI-U, but the default dataset carries pre_subsidy_rent, not rent, so that override does not apply.
• Household situations: policyengine_core/simulations/simulation.py multiplies the latest known period's array by the uprating parameter's value at the requested period over its value at the known period. Inputs without an uprating fall to the carry-over branch, which policyengine_us/system.py enables with auto_carry_over_input_variables = True.
• Default: policyengine_us/tools/default_uprating.py assigns calibration.gov.cbo.income_by_source.adjusted_gross_income to any float dollar input whose uprating is None.
• Parameter level: each file under parameters/calibration/gov/irs/soi/ has its last value in 2020 to 2023 and uprating metadata pointing at a CBO parameter. After init, each SOI parameter's 2025/2024 ratio equals the ratio of the CBO parameter it names.
• Rent reaches SPM resources through pre_subsidy_rent, hud_gross_rent, hud_hap, housing_assistance, spm_unit_allocated_housing_subsidy and spm_unit_capped_housing_subsidy.

Checked on upstream/main at a998473: policyengine-us 2.6.7, policyengine-core 3.30.2, spm-calculator 1.0.0, Python 3.14.4, environment built with uv sync. quarto render methodology/spm-poverty.qmd passes locally.

Noted, not changed

These are properties of the parameters as they stand. This PR documents them and does not alter them.

• calibration.gov.irs.soi.unemployment_compensation is extended by calibration.gov.cbo.income_by_source.taxable_social_security.
• alimony_income follows the SOI self-employment income series.
• health_insurance_premiums follows the CBO total AGI default, while the other reported premium inputs follow the CMS parameter. It does not enter spm_unit_health_insurance_premiums.
• calibration.gov.census.populations.total sits under a census path but cites CBO's demographic outlook for its values.

🤖 Generated with Claude Code