Repository navigation
IRS SOI measure_id net_capital_gains_* names two different measures (Form 1040 line 7 vs Table 1.4 Schedule D gain) #307
Description
docs/architecture.md says that within a source_name, measure_id must distinguish different statistical measures. Two IRS SOI measure ids break that rule:
measure_id |
Packages | IRS measure | Concept (after #304) |
|---|---|---|---|
net_capital_gains_returns / _amount |
historic_table_2, historic_table_2_state_broad_2022, congressional_district_2022 (and TY2023 HT2 in #295) |
N01000/A01000, Form 1040 line 7 "net capital gain (less loss)": Schedule D gain, limited Schedule D loss, or distributions-only |
irs_soi.returns_with_form_1040_capital_gain_or_loss / irs_soi.form_1040_capital_gain_or_loss |
| same ids | table_1_4 |
cols 37/38 (TY2022–23; 25/26 earlier), Schedule D "Taxable net gain" | irs_soi.returns_with_taxable_net_capital_gains / irs_soi.taxable_net_capital_gains |
For TY2022 the US counts are 30,465,850 and 12,915,122.
#304 fixes the concepts and leaves measure_id alone on purpose. Microcosm selects SOI facts by measure_id: fiscal_targets.py maps net_capital_gains_returns to capital_gains_gross, and the capital-gains rebase control is keyed on (measure_id, filing_status, universe). Renaming either side therefore moves Microcosm's selector. microcosm#1036 and #1040 currently tell the two apart by record-set family instead.
To do. Give one side a distinct measure_id. For example, rename the line 7 pair to form_1040_capital_gain_or_loss_returns / _amount, in the same change as a Microcosm update that maps the new ids. Then drop the shared-id pin in tests/test_chronicle_soi_capital_gain_concepts.py::test_consumer_selector_survives_the_concept_rename and add a note to docs/concept-migrations.md.
Related, same packages. Historic Table 2 and the congressional-district file still give different concepts to 10 other IRS columns they both read (N/A00900, N/A01700, N/A06500, N/A25870, N/A26270). Check each against the IRS guides. For each pair that turns out to be the same IRS variable, give it one concept. Record each rename in docs/concept-migrations.md.
Activity
MaxGhenis commentedon Sep 29, 2026
Related gap from the chronicle#304 review:
tests/test_chronicle_soi_capital_gain_concepts.pyfinds a line 7 measure through itssource_column_idorexpected_column_headerguard. A measure that readsN01000/A01000by column letter alone would slip past it. The nationalhistoric_table_2package declares 13 of its 55 measures that way today, and none of them is a capital-gain measure. Closing the gap: require everyirs_soimeasure that reads a CSV variable to declaresource_column_idplus the header guard, as the TY2023 packages in #295 already do.MaxGhenis commentedon Oct 12, 2026
Two more items for this issue, found while pinning every IRS-variable measure to its documentation-guide definition in #345:
charitable_*has a split concept across packages. The congressional-district file usesirs_soi.charitable_contributions_deduction/irs_soi.returns_with_charitable_contributions_deductiononA19700/N19700; the guide calls these "Total charitable contributions", Schedule A:14. Table 2.1 usesirs_soi.contributions_deduction/irs_soi.returns_with_contributions_deductionfor the same measure ids.ctc_*(Historic Table 2 national and state broad) readsN07225/A07225. Every TY2022/TY2023 guide defines that column as "nonrefundable child and other dependent tax credit" (1040:19), but the concept isirs_soi.child_tax_creditand the label is "Child tax credit". The column is the only one the files publish, so the fix is the concept or label, not the column.#345's
tests/test_chronicle_soi_doc_guide_columns.pypins columns, not concepts, so it doesn't conflict with the renames tracked here.