Skip to content

Fill IRS SOI uprating series gaps with Publication 1304 actuals - #10128

Merged
MaxGhenis merged 6 commits into
mainfrom
fill-soi-uprating-gaps
Nov 14, 2026
Merged

MaxGhenis merged 6 commits into
mainfrom
fill-soi-uprating-gaps

Conversation

@MaxGhenis

@MaxGhenis MaxGhenis commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #4281

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. The model then uprated a dollar input dated in a gap year, or read in one, 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 main keyed to the wrong tax year or misread from the table.
  • Replaces rounded totals with the table's figures.
  • 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 their cells. 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 22 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 (methodology choice 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. Clarify/update Social Security SOI target #4281 reported this value and the missing table reference.
  • 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. This PR restates partnership 2015, rental 2015 and 2021, unemployment 2021 and alimony 2015 from the table.

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". Subparagraph (i)(1)(D) measures the next increase 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.

Methodology choices

  1. Short-term capital gains follow Table 1.4A's gain-only column, and the series changes sign. On main 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. The long-term series uses the matching column, "Net long-term capital gain". Every value turns positive, and 2022 moves from −$72B to +$77.7B. 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 stay the same and only the level flips sign. short_term_capital_gains can hold a loss, and a loss now moves with gains: −$10,000 dated 2021 reads −$3,710 in 2022.
  2. Two methods estimate the 2018 pension values. 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.
    • The taxable estimate rises 6.2% from 2017 and then 1.3% into 2019, and the tax-exempt one rises 7.0% in each year.
    • Each file states its method. Only inputs dated 2018, or read in 2018, use these values.
  3. gov.ssa.uprating carries the 2014 third-quarter level through 2016. The 2015Q3 average (233.278) fell below 2014Q3 (234.242), so SSA paid no COLA for 2016 and 2014Q3 stayed the latest computation quarter (42 U.S.C. 415(i)(1)(B)). The file holds 234.242 for 2015 and for 2016, so a benefit dated 2015 keeps its amount in 2016 and rises 0.35% in 2017. With the 2015Q3 average, it would fall 0.4% in 2016 and rise 0.8% in 2017. The index holds unrounded CPI-W averages, as main's values from 2022 do, so a ratio can differ from the rounded COLA: 2021 to 2022 gives ×1.0592, and the COLA was 5.9%.
  4. This PR fills interior gaps only. It fills the years between each series' first and last values, and it adds a later year to one series: unemployment compensation gains tax year 2022 (see the first judgment call below). Seven series still end at 2020 and six at 2021, though IRS has published Table 1.4 through tax year 2023, and each grows from its last value with its CBO series. Extend IRS SOI uprating series to tax year 2023 #10132 extends the series to tax year 2023.

Other judgment calls

  1. 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 this PR removes the override.
  2. 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 this branch keeps main's list. It drops its own SSA CPI-W page reference, which duplicates the BLS values, and ssa.gov refuses automated fetches.
  3. 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

Parameters. I dumped every leaf parameter after system init at main (3386304d28) and at this branch (ee4a74f1c9). 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 stays the same. 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 the ratio between any two years from the last authored year on stays the same.
  • 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 (22) 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 it multiplied a 2019 input 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 the model projects nothing.
  • In medicare_cost.yaml "unit test 5 - 2021 data, premium-free", the input is 0.

Tests

Pull request run 43547862788 at ee4a74f1c9 passed all 38 jobs on GitHub's merge with main 045d1aee97.

I computed each new case's expected value 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 CPI-W ratio behind 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. The guard checks every series and year.
  2. From its last authored year, each SOI series grows 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

Microsimulation impact

We estimate that this branch changes none of the outputs below in 2026 on the default dataset. We compared main at 3386304d28 with this branch at ee4a74f1c9. The PR changes parameter values dated 2015 to 2022 only.

Output Main total Change Records changed (weighted)
employment_income $11,738.1bn $0 0 (0)
taxable_pension_income $1,303.7bn $0 0 (0)
social_security $1,677.9bn $0 0 (0)
long_term_capital_gains $1,434.9bn $0 0 (0)
adjusted_gross_income $18,986.0bn $0 0 (0)
state_income_tax $577.2bn $0 0 (0)
income_tax $2,594.9bn $0 0 (0)
household_benefits $2,060.4bn $0 0 (0)
household_net_income $17,199.2bn $0 0 (0)

impact: none measured in 2026

axiom: n/a: calibration and uprating data (IRS SOI totals and third-quarter CPI-W levels); this PR changes how household inputs grow across years, and no provision's amount changes

🤖 Generated with Claude Code

The national-total uprating series under calibration.gov.irs.soi had no
values between 2015 and their next year, so each held its 2015 value
through the gap. Their per-capita siblings drifted down with population
and then jumped, and any input dated in or before the gap was uprated
past it by the wrong factor.

- Fill every missing year from IRS SOI Publication 1304 Table 1.4 (all
  returns) or Table 1.4A, using the same column as the series' existing
  values, and cite each tax year's file.
- Correct values keyed to the wrong tax year or misread: partnership and
  S corporation income at 2022 was the tax-year 2021 total; Social
  Security at 2021 was the tax-year 2020 total; farm rental income at
  2021 subtracted the number of returns with a loss, not the loss.
- Restate rounded totals (partnership 2015, rental 2015 and 2021,
  unemployment 2021) and alimony 2015 exactly.
- Replace the short-term capital gains placeholder (a PUF figure and a
  backcast) with Table 1.4A net short-term capital gain less loss
  (Schedule D line 7).
- 2018 pensions: the 2018 Form 1040 combined IRA distributions with
  pensions, so SOI has no separate figure; estimate and say how.
- Fill gov.ssa.uprating for 2015-2021 with third-quarter CPI-W; 2016
  keeps the 2014Q3 level because no COLA was payable.
- Guard: every series an input follows has a January 1 value for every
  year from its first to its last.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The long-term capital gains series uses Table 1.4A's net long-term
capital gain: returns with a gain, net losses left out. The short-term
series netted gains against losses and carryovers, a large negative
total that moves against gains (x4.1 from 2021 to 2022, the year gains
fell 63%). Use the gain column, so both series measure the same thing
and the index stays positive.

List the 2018 taxable pension estimate alongside the tax-exempt one in
the citation test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@MaxGhenis

Copy link
Copy Markdown
Contributor Author

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


Generated by Claude Code

Main rewrote gov.ssa.uprating for the 2027 COLA (#10225), so the
reference list conflicted. Main's list already cites 42 U.S.C. 415(i)
and the BLS CPI-W series (CWUR0000SA0) that the 2015-2021 third-quarter
averages come from, so it is kept as is; the branch's 2015-2021 values
merge cleanly above main's 2027 actual.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every series this branch fills or corrects now has a YAML case: an input
dated in one year and read in a later one, whose expected value is the
SOI table total (or the third-quarter CPI-W average) over population,
computed by hand and linked to its workbook. The cases cover the
corrected 2021 farm rental, 2020-2021 Social Security and 2021-2022
partnership totals, both 2018 pension estimates, the added 2022
unemployment total, the 2016 no-COLA hold and the 5.9% COLA for 2022.
Each fails on main and on mutants that undo the fix.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An uprating factor is a ratio of the series, so a series that crossed
zero would turn each input projected across it from an income into a
loss. This branch replaced the short-term capital gains placeholders
(negative) with SOI net short-term capital gain (positive); the guard
checks every series an input follows over its whole span.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@MaxGhenis

MaxGhenis commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor Author

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

@MaxGhenis
MaxGhenis marked this pull request as ready for review November 11, 2026 17:06
@MaxGhenis MaxGhenis closed this Nov 14, 2026
@MaxGhenis MaxGhenis reopened this Nov 14, 2026
@MaxGhenis
MaxGhenis merged commit 1ecf227 into main Nov 14, 2026
81 checks passed
@MaxGhenis

Copy link
Copy Markdown
Contributor Author

US + core hub merge audit, us#10128 at ee4a74f1c9f247da43bc18038aaec87753ee86c6 (squash): Fill IRS SOI uprating series gaps with Publication 1304 actuals.

  • Reviews:
    • The PR has no GitHub reviews. Three independent reviews ran outside GitHub, and each approved ee4a74f1c9.
    • A sources review fetched the 18 Publication 1304 workbooks for tax years 2015 to 2023 from irs.gov and found each column by its header label. All 115 table values at the head equal their cells, and the two 2018 pension estimates reproduce the method each file states. The seven new gov.ssa.uprating values equal SSA's published third-quarter CPI-W averages, and both quotes from 42 U.S.C. 415(i) match govinfo's text.
    • A code review dumped every leaf parameter at the merge base 3386304d28 and at the head. 35 differ: the 17 SOI totals, their per-capita siblings and gov.ssa.uprating. It recomputed all 19 new YAML expectations and the description's factor table by hand. test_uprating_series.py passed at the head and on a merge with main at a93cc58d7e, and the new unemployment case and the veterans case for 2021 to 2022 fail on the merge base with the values their comments give.
    • A third review checked the 117 SOI values against the workbooks again, recomputed two expectations and raised three non-blocking points.
    • The code review's one P2 concerned the description, and I corrected it before merge. The description no longer asks for Fill CBO total AGI for 2015-2018 with IRS SOI actuals #10114 to land first, counts 22 inputs on the employment series and closes Clarify/update Social Security SOI target #4281. It also states the methodology choices below, carries the impact section and uses an accepted axiom: form. From the third review, it now says that inputs dated in a gap year or read in one got the wrong factor, and that inputs dated or read in 2018 use the pension estimates.
  • Methodology choices for maintainers:
    • Short-term capital gains now follow Table 1.4A's net short-term capital gain, which counts returns with a gain and leaves net losses out, as the long-term series does. Main held negative placeholders (−$45bn for 2015 and −$72bn for 2022), so the series changes sign. A loss input now moves with gains: −$10,000 dated 2021 reads −$3,710 in 2022. Gain less loss, the alternative, runs negative and would multiply a 2021 input by 4.1 in 2022, when gains fell 63%.
    • Two methods estimate the 2018 pension values, since the 2018 Form 1040 combined pensions with IRA distributions. Taxable pensions take the combined taxable total times the mean pension share of 2017 and 2019. Tax-exempt pensions take the geometric mean of 2017 and 2019. The taxable estimate rises 6.2% into 2018 and 1.3% into 2019.
    • gov.ssa.uprating holds the 2014 third-quarter level, 234.242, for 2016. The 2015 third-quarter average fell to 233.278, so SSA paid no COLA for 2016 and 2014Q3 stayed the base under 42 U.S.C. 415(i)(1)(B) and (D). The index keeps unrounded CPI-W averages, so 2021 to 2022 gives ×1.0592 where the COLA was 5.9%.
    • The PR fills interior gaps only. Seven series still end at 2020 and six at 2021, though IRS has published Table 1.4 through tax year 2023.
  • Gates checked live at merge:
    • gh pr checks exits 0;
    • the latest Pull request run at the head, 43547862788, passed and tested this head merged into main at 045d1aee97;
    • MERGEABLE;
    • not a draft;
    • no reviewer's latest review requests changes;
    • the semantic-overlap guard: since 045d1aee97, main has changed no area this PR touches;
    • the merge pins the head.
  • Impact (default dataset, ee4a74f1c9 against main at 3386304d28): we estimate no change in 2026 in employment income, taxable pensions, Social Security, long-term capital gains, adjusted gross income, income taxes, household benefits or household net income. The PR changes parameter values dated 2015 to 2022 only.
  • Next:
    • Extend IRS SOI uprating series to tax year 2023 #10132, a draft, stacks on this branch at c96ccb7ba4 and must merge this PR's head, ee4a74f1c9. The two heads merge without conflict, and Extend IRS SOI uprating series to tax year 2023 #10132 extends the series to tax year 2023.
    • The contiguity guard reads January values only, so it checks CPI-U through 2026 and misses its February-keyed projections for 2027 to 2036.
    • test_default_series_has_a_value_for_every_year, from Fill CBO total AGI for 2015-2018 with IRS SOI actuals #10114, repeats the new guard's case for CBO AGI, and a follow-up can delete it.
    • The projection check stops at 2035. Nine SOI series have no test of their growth past 2036: farm, farm rent, rental, alimony, partnership, both capital gains, tax-exempt interest and non-qualified dividends.
    • The citation test compares years only and skips soi/agi/. A value keyed to a neighbouring tax year, the error this PR fixes for partnership 2022, would still pass, and so would a file that cites the wrong table.
    • veterans_benefits.yaml labels 10,592.28 as the 5.9% COLA for 2022, in a case name and a comment. A follow-up can label it as the CPI-W ratio, since a 5.9% COLA on $10,000 gives $10,590.
    • The guard's docstring says inputs dated "in or before" a gap got the wrong factor. A follow-up can narrow it to inputs dated in a gap year or read in one, as the description now says.
    • Two series concepts predate this PR. The self-employment series counts net income and leaves net losses out, and the rental series subtracts losses that returns couldn't deduct. A follow-up can decide whether either concept should change.
  • Axiom: n/a, since the PR changes calibration and uprating data and no provision's amount. TheAxiomFoundation/rulespec-us#1887 already queues the COLA rule that keeps the base quarter through a year with no COLA.

🤖 Generated with Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Clarify/update Social Security SOI target

2 participants