[MaxGhenis]

Land #10114 first. This PR's new guard covers every series that inputs follow, including CBO total AGI, which has no 2016-2018 values until #10114 lands.

What changes

The national totals under calibration/gov/irs/soi/ had no values between 2015 and their next year (2020, 2021, 2022 or 2023). parameter(instant) held the 2015 value through the gap, so each per-capita sibling (total ÷ population, built by tools/per_capita_uprating.py) drifted down with population and then jumped. Any dollar input dated in or before the gap was uprated past it by the wrong factor. Employment income per capita, for example:

	2015	2016	2017	2018	2019	2020
main	21,811	21,620	21,473	21,324	21,210	24,989
this PR	21,811	21,940	22,878	23,709	24,672	24,989

This PR:

• Fills every gap with IRS SOI Publication 1304 actuals.
• Corrects values that were keyed to the wrong tax year or misread from the table.
• Restates rounded totals exactly.
• Fills gov.ssa.uprating (the cost-of-living index that veterans' benefits follow) for 2015-2021 with third-quarter CPI-W.
• Adds a guard so a gap can't come back.

Sources

Every SOI value is the "All returns, total" row of Publication 1304 Table 1.4 (https://www.irs.gov/pub/irs-soi/YYin14ar.xls) for income items, or Table 1.4A (YYin14acg.xls) for capital gains, in thousands of dollars times 1,000. Each parameter file cites one workbook per tax year. The workbooks are XLS files, so no page anchor applies. For example, TY2016 Table 1.4 and TY2016 Table 1.4A.

I re-extracted every value from the IRS workbooks, locating each column by its header label, never by position. Layouts change: TY2018 combined IRA distributions with pensions, TY2021 split partnerships from S corporations, and TY2022 renamed wages. All 115 table values match exactly. The two 2018 pension estimates reproduce the method each file states.

Series	Inputs that follow it	Column, all returns	Years filled	Existing values
employment_income	20	salaries and wages	2016-2019	match
long_term_capital_gains	14	1.4A net long-term capital gain	2016-2019, 2021-2022	match
taxable_pension_income	13	pensions and annuities, taxable	2016-2019	match
tax_exempt_pension_income	6	pensions and annuities, total less taxable	2016-2019	match
self_employment_income	5	business or profession, net income	2016-2019	match
social_security	4	social security benefits, total	2016-2019	2021 held the TY2020 total: it moves to 2020, and 2021 takes TY2021
qualified_dividend_income	3	qualified dividends	2016-2019	match
non_qualified_dividend_income	1	ordinary less qualified dividends	2016-2019	match
alimony_income	2	alimony received	2016-2020	2015 was $2,000 high
farm_income	2	farm net income less net loss	2016-2020	match
farm_rent_income	1	farm rental net income less net loss	2016-2020	2021 subtracted the number of loss returns
partnership_s_corp_income	2	partnership and S corporation net income less net loss	2016-2020	2022 held the TY2021 total: it moves to 2021, and 2022 takes TY2022; 2015 rounded
rental_income	1	rent and royalty net income less net loss	2016-2020	2015 and 2021 rounded
short_term_capital_gains	1	1.4A net short-term capital gain	2015-2022, all new	placeholders, not SOI (judgment call 1)
tax_exempt_interest_income	1	tax-exempt interest	2016-2019	match
taxable_interest_income	1	taxable interest	2016-2019	match
unemployment_compensation	1	unemployment compensation	2016-2019, 2022	2021 rounded

Corrections

• Partnership and S corporation, 2022. 976B was the TY2021 total: 21in14ar partnership 469,816,308 − 168,152,043 plus S corporation 766,681,240 − 92,689,104 = 975,656,401 thousand. It moves to 2021, and 2022 takes TY2022, 1,031,207,920 thousand (22in14ar).
• Social Security, 2021. 774,017,713 thousand was the TY2020 total. It moves to 2020, and 2021 takes TY2021, 791,161,174 thousand.
• Farm rental, 2021. 6,114,025 thousand is 6,186,997 − 72,972. The 72,972 is the number of returns with a farm rental loss, the column beside the loss amount. The TY2021 net is 6,186,997 − 631,042 = 5,555,955 thousand.
• Rounded or mistyped totals. Partnership 2015, rental 2015 and 2021, unemployment 2021 and alimony 2015 are restated exactly.

Social Security cost-of-living index, 2015-2021

gov.ssa.uprating started in 2022, so backdate_parameters held 2022's value back to 2015. A veterans' benefit dated 2021 got no uprating into 2022, when the COLA was 5.9%. The new values are third-quarter averages of BLS CPI-W, not seasonally adjusted (CWUR0000SA0), the method the file already uses. All seven match BLS's monthly values. 2016 keeps the 2014Q3 level, because the 2015Q3 average (233.278) fell below 2014Q3 (234.242). Under 42 U.S.C. 415(i)(1)(B), a computation quarter is a third quarter "with respect to which the applicable increase percentage is greater than zero". Under (i)(1)(D), the next increase is measured from "the most recent cost-of-living computation quarter", so 2016Q3 ÷ 2014Q3 − 1 = 0.35% reproduces the 0.3% COLA for 2017. Main's own test_cpi_w_third_quarter_averages_reproduce_ssa_uprating encodes that rule independently, and it now checks these seven values too.

Judgment calls

1. Short-term capital gains concept. The file said "Taken from the IRS PUF in the absence of a SOI target". It held −72B at 2022, and 2015 = −72B × 63% (the old long-term 2015/2020 ratio). Table 1.4A does publish short-term gains. The series now uses its "Net short-term capital gain" column: returns with a gain, net losses left out. That is the counterpart of the long-term series, which uses "Net long-term capital gain". Gain less loss would be a large negative total that moves against gains, so as an uprating index it would multiply a 2021 input by 4.1 into 2022, the year gains fell 63%. From 2022 on, the series still grows with CBO net capital gains, so projected ratios are unchanged and only the level flips sign.
2. 2018 pensions. The 2018 Form 1040 combined IRA distributions with pensions and annuities, so SOI published no separate figure. Table 1.4 for TY2019, note 3 (19in14ar), says these items "were combined on one line on that year's tax form".
   • Taxable pensions 2018 = TY2018 combined taxable (1,087,228,437 thousand) × the mean of the pension share of that total in 2017 and 2019 (0.717927, 0.707093) = 774,661,125 thousand.
   • Tax-exempt pensions 2018 = the geometric mean of 2017 and 2019 = 473,418,497 thousand. The combined total also counts nontaxable IRA distributions, which no other year reports.
   • Each file says how its value was estimated. Only inputs dated exactly 2018 read these values.
3. Unemployment compensation start_instant. It existed because CBO's outlays start in 2022, a year after the old last SOI value. core's uprate_parameter projects from start_instant, or else from the last authored value. With TY2022 in the file, those are the same instant, so the override is removed.
4. Merge conflict in gov.ssa.uprating references. Main (Update Social Security and SSI parameters for the 2027 COLA #10225) rewrote the list. It already cites 42 U.S.C. 415(i) and the BLS CPI-W series these values come from, so main's list is kept. This branch's SSA CPI-W page reference is dropped: it duplicates the BLS values, and ssa.gov refuses automated fetches.
5. No Hypothesis tests. Every invariant below ranges over a finite set of series and years, so the tests enumerate all of it rather than sample it. A simulation-based property test would compute its expected factor from the same parameter that core reads. CLAUDE.md's test rules rule that out, and an independent review of Fill CBO total AGI for 2015-2018 with IRS SOI actuals #10114's equivalent test found it passes on main too.

Effect

impact: the hub will measure

Parameters. I dumped every leaf parameter after system init at main (4e71481e19) and at this branch. 35 differ: the 17 SOI totals, their 17 per-capita siblings and gov.ssa.uprating (2015-2021). Nothing else moves, including the SSI and state supplement amounts that uprate by gov.ssa.uprating. The variable-to-series map is unchanged. core's parameter uprating projects a series from its last authored value, so:

• Interior fills change only the filled years.
• Six series' last authored values changed: partnership, Social Security, farm rental, rental, short-term gains and unemployment. Each shifts every projected year by one constant factor, so ratios between any two years from the last authored year on are unchanged.
• For all 35 parameters, year-on-year ratios are identical from 2023→2024 onward. From 2022→2023 only long-term gains differ, since its filled 2022 sits before its 2023 value. extend_single_year_dataset grows each year from the dataset's base year, so a dataset based in 2023 or later reads only unchanged ratios.

Household inputs dated 2015-2022 and read in a later year are what change. Factor to 2025 for an input dated January 1 of year Y, main to this PR:

Series (inputs)	2016	2018	2019	2020	2021	2022
employment_income (20)	1.503 to 1.481	1.524 to 1.371	1.532 to 1.317	same	same	same
long_term_capital_gains (14)	2.081 to 2.404	2.110 to 1.626	2.121 to 1.831	same	1.474 to 0.816	1.481 to 1.166
taxable_pension_income (13)	1.820 to 1.811	1.846 to 1.644	1.856 to 1.632	same	same	same
social_security (4)	1.672 to 1.669	1.695 to 1.541	1.704 to 1.467	1.712 to 1.368	same	same
partnership_s_corp_income (2)	1.692 to 1.789	1.715 to 1.668	1.725 to 1.693	1.732 to 1.627	1.739 to 1.184	same
short_term_capital_gains (1)	1.918 to 2.393	1.945 to 1.887	1.955 to 1.618	1.964 to 0.635	1.971 to 0.459	same
unemployment_compensation (1)	8.433 to 1.313	8.550 to 1.539	8.597 to 1.591	0.580 to 0.084	1.134 to 0.164	same
gov.ssa.uprating (1)	1.150 to 1.318	1.150 to 1.288	1.150 to 1.253	1.150 to 1.234	1.150 to 1.218	same

Unemployment compensation was the worst case: main carried pandemic-year totals forward, so a 2019 input was multiplied by 8.6 by 2025.

Blast radius. I scanned every YAML test for an input of a variable that follows a changed series, dated year X, in a case whose period is a later year T where index(T) ÷ index(X) changes. Two existing cases match, and neither asserts a value that moves:

• medicare_irmaa_magi_two_years_prior.yaml Case 5 reads tax_exempt_interest_income dated 2015 at 2015 (two years before 2017), so nothing is projected.
• In medicare_cost.yaml "unit test 5 - 2021 data, premium-free", the input is 0.

Tests

Each new case's expected value is computed by hand from the SOI totals (or the CPI-W averages) and the population series. The comment beside it gives the arithmetic and links the workbook.

• New YAML, one case per changed series, each in its variable-named file:
  • alimony_income, tip_income (employment), farm_operations_income (farm, a series of net losses), farm_rent_income (corrected 2021);
  • long_term_capital_gains_on_collectibles, short_term_capital_gains, qualified_dividend_income, non_qualified_dividend_income;
  • partnership_income (corrected 2021 and 2022), partnership_self_employment_net_earnings (self-employment), rental_income, social_security_retirement_reported (corrected 2020 and 2021);
  • tax_exempt_interest_income, taxable_interest_income, tax_exempt_private_pension_income (from the 2018 estimate), taxable_private_pension_income (into the 2018 estimate), unemployment_compensation (added 2022);
  • veterans_benefits: 2015 to 2016 unchanged (no COLA) and 2021 to 2022 ×1.0592 (the 5.9% COLA).
• tests/core/test_uprating_series.py:
  • test_series_has_a_january_value_for_every_year, over every series an input follows;
  • test_soi_series_follows_its_projection_from_its_last_authored_year;
  • new test_series_keeps_one_sign.
• tests/test_parameter_files.py: every SOI value cites its own tax year's workbook, and the corrected values hold their table totals.

Invariants

1. Every series an input follows has a January 1 value for every year from its first to its last. A gap makes the per-capita index drift and jump. Checked over every series and year.
2. From its last authored year, each SOI series grows exactly with the series in its uprating metadata, so filling earlier years cannot move projected growth.
3. Every series an input follows keeps one sign over its whole span. An uprating factor is a ratio of the series, so a series that crossed zero would turn incomes into losses.
4. Each SOI value cites its own tax year's Table 1.4 or 1.4A workbook, except the two documented 2018 estimates.
5. gov.ssa.uprating holds the third-quarter CPI-W of the latest cost-of-living computation quarter, and so never falls. Main's test_cpi_w_third_quarter_averages_reproduce_ssa_uprating checks this against BLS monthly values.
6. Each per-capita series is its total over population at every instant. The existing test_every_per_capita_series_is_its_total_over_population checks this.

Overlaps

• Fill CBO total AGI for 2015-2018 with IRS SOI actuals #10114, ready: both add tests to tests/core/test_uprating_series.py, in separate hunks, and the two heads merge cleanly. Once Fill CBO total AGI for 2015-2018 with IRS SOI actuals #10114 lands and main is merged here, its test_default_series_has_a_value_for_every_year repeats this PR's guard case for CBO AGI and can be deleted.
• Extend IRS SOI uprating series to tax year 2023 #10132, draft, stacked on this branch: it appends TY2022/TY2023 values after this branch's last value in each SOI file, extends the reference lists, edits the header comment in employment_income.yaml and the metadata comment in unemployment_compensation.yaml, and adds two constants and two tests to tests/test_parameter_files.py next to this PR's SOI tests. This adoption touched none of those lines, and it merged main into the branch Extend IRS SOI uprating series to tax year 2023 #10132 is based on.

axiom: (hub files pe-parity before landing)

https://claude.ai/code/session_01WR8LHeQ5aRnbkFs53KAtPz

---

Generated by Claude Code

[MaxGhenis]

Picking this up for the US hub. I'll post a hand-off comment here when it's ready.

---

Generated by Claude Code

[MaxGhenis]

Ready for hub review

Head: 664ed5ebccee4d02bdf224cdd08c5e04287365ac

Starting head was c96ccb7ba4640c0b1f522d7a2c3dfeeb9bdb192b. Nobody had pushed since 2026-10-11. The PR stays a draft. CI skips drafts, so CI has not run on this head.

Land #10114 first. This PR's generalized guard covers CBO total AGI, which has no 2016-2018 values until #10114 lands. At this head that one case fails (below); it passes once #10114 is merged and main is merged here.

Still needed?

Yes. On origin/main (4e71481e19), every series under calibration/gov/irs/soi/ still jumps from 2015 to 2020, 2021, 2022 or 2023. gov.ssa.uprating still starts in 2022. The ten value defects this PR corrects are all still there:

• alimony 2015 is $2,000 high;
• farm rental 2021 is misread;
• partnership 2015 is rounded, and its 2022 holds the TY2021 total;
• rental 2015 and 2021 are rounded;
• short-term gains 2015 and 2022 are placeholders;
• Social Security 2021 holds the TY2020 total;
• unemployment 2021 is rounded.

No other open PR does this. #10132 is stacked on this branch and extends it to TY2023.

Correct?

• SOI values. I downloaded Tables 1.4 and 1.4A for TY2013-2023 from irs.gov and extracted each series by header label, never by column position. Every value in the 17 files matches its table total exactly: 115 table values. The two 2018 pension estimates reproduce the method their files state: 774,661,125.267 and 473,418,496.878 thousand, stored rounded.
• Corrections, checked against the workbooks:
  • partnership TY2021: 469,816,308 − 168,152,043 + 766,681,240 − 92,689,104 = 975,656,401 thousand;
  • TY2021 farm rental: the loss "Number of returns" is 72,972 and the loss "Amount" is 631,042, so main's 6,114,025 = 6,186,997 − 72,972;
  • Social Security TY2020 = 774,017,713 thousand.
• Note 3. TY2019 Table 1.4, note 3, says 2018's IRA distributions and pensions "were combined on one line on that year's tax form".
• Short-term gains. Gain less loss would multiply a 2021 input by 4.10 into 2022, while gains fell 63%: (77,731,595 − 630,379,422) / 339,654,000 over (208,522,006 − 342,812,493) / 338,039,000.
• CPI-W. I downloaded BLS's CPI-W file (CWUR0000SA0). The seven 2015-2021 values are its July-September averages for 2014 and 2016-2020. 2016 holds 2014Q3 because the 2015Q3 average (233.278) is lower. I fetched 42 U.S.C. 415(i) myself. Under (1)(B), a computation quarter is a base quarter "with respect to which the applicable increase percentage is greater than zero". Under (1)(D), the increase is measured from "the most recent cost-of-living computation quarter". 2016Q3 ÷ 2014Q3 − 1 = 0.348%, which rounds to the 0.3% COLA for 2017.
• start_instant. I read uprate_parameter in policyengine-core. It projects from start_instant, or else from the last authored value. With TY2022 authored at 2022-01-01, where CBO's unemployment series begins, those are the same instant, so removing the override changes nothing.

Merge main

git merge origin/main at 4e71481e19 gives merge commit 9c0890d415. One conflict, in the gov.ssa.uprating reference list; the values merged cleanly. I kept main's list, which already cites 42 U.S.C. 415(i) and BLS CWUR0000SA0, the source of the 2015-2021 values. I dropped this branch's SSA CPI-W page reference: it duplicates the BLS values, and ssa.gov returns 403 to automated fetches.

Main added test_cpi_w_third_quarter_averages_reproduce_ssa_uprating after this PR was written. It starts from the first listed year, so it now also checks 2015-2021 and the 2016 hold, independently. It passes.

Reviews

The PR had no reviews or comments. The original body reported two rounds of external review; this adoption didn't rely on them, since every value was re-derived independently.

Tests

Each new YAML case's expected value was computed by hand: the SOI totals from the workbooks over the population series, or the CPI-W averages. The comment beside each case shows the arithmetic and links the workbook.

At 664ed5ebcc, unless noted, one file per process:

File	Result
18 new YAML files (19 cases), each in its own process	19 passed
tests/core/test_uprating_series.py	200 passed, 1 failed: the CBO AGI case of test_series_has_a_january_value_for_every_year, which #10114 fixes
tests/core/test_uprating_series.py with #10114 merged in (trial merge, not committed)	202 passed
tests/test_parameter_files.py	10 passed (at 9c0890d415, the merge; unchanged since)
tests/policy/baseline/gov/bls/test_cpi_monthly_actuals.py (main's independent 415(i) and CPI-W check)	4 passed
tests/core/test_per_capita_uprating.py	51 passed
tests/policy/baseline/parameters/test_uprating_extensions.py	166 passed
tests/unit/test_ss_calculator_parameters.py	24 passed
tests/core/test_pre_first_modeled_year_uprated_inputs.py	48 passed
tests/core/test_trustees_2026_economic_assumptions.py	110 passed

The Python files above other than test_uprating_series.py ran at 9c0890d415. The later commits only add YAML files and the sign test.

Changed rules and their cases: gov/ssa/uprating.yaml:8 (2016 hold) is pinned by household/income/person/general/veterans_benefits.yaml. The 2018 estimates (taxable_pension_income.yaml:13, tax_exempt_pension_income.yaml:12) are pinned by taxable_private_pension_income.yaml and tax_exempt_private_pension_income.yaml. The corrected totals are pinned by farm_rent_income.yaml, partnership_income.yaml and social_security_retirement_reported.yaml. The new short-term series (short_term_capital_gains.yaml:7 on) is pinned by short_term_capital_gains.yaml. The guards are test_uprating_series.py:241 (every January value), :253 (one sign, new) and :278 (projection from the last authored year), plus test_parameter_files.py:204 (citations) and :222 (corrected totals).

Mutants

Each ran in its own process, and the file was restored after each.

Mutant	Tests that caught it
M1: 2016 COLA index set to the 2015Q3 average, 233.278 (no hold)	test_cpi_monthly_actuals.py 1 failed; veterans_benefits.yaml 1 of 2 failed
M2: drop the 2017 employment total (a gap again)	the guard 1 failed; tip_income.yaml 1 failed
M3: farm rental 2021 back to the misread 6,114,025 thousand	the corrected-values test 1 failed; farm_rent_income.yaml 1 failed
M4: short-term gains 2015 back to the −45B placeholder	the new sign test 1 failed
M5: partnership 2022 back to 976B (the TY2021 total, rounded)	the corrected-values test 1 failed; partnership_income.yaml 1 failed

All five were killed, and each file was restored with git checkout.

Correction to commit c8c555dc6d's message, which says every new case fails on main: the 2015 to 2016 veterans case passes on main as well. Main held 2022's index for every earlier year, which also gives ×1. Only mutant M1 catches it. Every other new case fails on main.

Parameter tree and blast radius

• Parameter tree. I dumped every leaf parameter after system init (125,303) at main and at this head. 35 differ: 17 SOI totals, 17 per-capita siblings, and gov.ssa.uprating at 2015-2021. No SSI or state supplement amount moves. The variable-to-series map is unchanged.
• Ratios. Year-on-year ratios are identical from 2023→2024 on for all 35. From 2022→2023 only long-term gains differs.
• Static YAML scan. I looked for an input of a variable that follows a changed series, dated X, in a case whose period T has a changed index(T)/index(X). Two pre-existing cases match, and neither asserts a moving value: IRMAA Case 5 reads its 2015 input at 2015, and medicare_cost.yaml unit test 5's input is 0. The other 18 matches are the new cases.

Judgment calls

1. Short-term gains concept (kept from the PR). The series takes SOI's net short-term capital gain, the counterpart of the long-term series.
2. 2018 pension estimates (kept from the PR). SOI published no separate 2018 figure.
3. start_instant removal (kept from the PR). It changes nothing (see above).
4. Conflict resolution. The reference list follows main's, as described above.
5. No Hypothesis tests.
   • I wrote and then deleted a Hypothesis file (simulation-based uprating, a COLA that never falls, sign preservation). Its simulation property computes the expected factor from the parameter core reads. An independent review of Fill CBO total AGI for 2015-2018 with IRS SOI actuals #10114's equivalent test found that it passes on main and that CLAUDE.md's test rules rule it out.
   • The invariants range over a finite set of series and years, so the tests enumerate all of it.
   • The one new invariant with distinct value, that every series an input follows keeps one sign, is now test_series_keeps_one_sign in test_uprating_series.py (policyengine_us/tests/core/test_uprating_series.py:253). It covers all 27 series, at parameter reads only.
   • The never-falls property is already covered for actuals by main's CPI-W test.
6. Cases in variable-named files that didn't exist yet. I created one file per input. Three series' own variables live under variables/input/, which has no test folder, so their cases use household-path inputs on the same series: tip_income (employment), farm_operations_income (farm) and partnership_self_employment_net_earnings (self-employment). All of the new files sit in folders that existing YAML shards run.

Overlaps

• Fill CBO total AGI for 2015-2018 with IRS SOI actuals #10114: both add tests to tests/core/test_uprating_series.py, in separate hunks, and the two adopted heads merge cleanly. Once Fill CBO total AGI for 2015-2018 with IRS SOI actuals #10114 lands and main is merged here, delete its test_default_series_has_a_value_for_every_year, since this PR's guard case for CBO AGI covers it.

• Extend IRS SOI uprating series to tax year 2023 #10132: stacked on this branch, and I didn't touch it. Its base branch has now moved by the main merge and my commits, so it will show as behind. Its shared lines are:

  • each SOI file's last value and reference list, where it appends TY2022/2023;
  • the header comment in employment_income.yaml (wages to line 1z from TY2022);
  • the metadata comment in unemployment_compensation.yaml ("the year of the last SOI total");
  • tests/test_parameter_files.py, where it adds SOI_LATEST_TAX_YEAR and SOI_LINE_1Z_WAGES right after SOI_CORRECTED_VALUES, and two tests right after test_soi_corrected_values_hold_their_table_1_4_totals. Both use the SOI_DIR this PR adds.

  This adoption changed none of those lines, so merging this branch into Extend IRS SOI uprating series to tax year 2023 #10132 should apply cleanly.

Follow-up issues I'd propose

• "Re-check gov.ssa.uprating forecast years against 415(i)." The 2028-2036 forecasts and the 2037-2100 extensions grow with CBO CPI-U. I found no test that checks the index never falls there, which 415(i)(1)(B) implies. On this head it doesn't fall, but nothing guards it.

---

Generated by Claude Code