PolicyEngine / PolicyEngine/microcosm

Drop the derived first/second_home_mortgage_interest export columns (pe-us#9275 atomic-inputs migration)

Open
#673 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
0
Forks
4
Avg merge
1d 3h
Merged PRs (30d)
94

Description

Companion to policyengine-us#9275 (atomic inputs) and policyengine-us#9276 (person-level home_mortgage_interest is now the canonical interest input; the structured interest inputs are deprecated fallbacks).

Ask

  1. Stop exporting first_home_mortgage_interest and second_home_mortgage_interest in the next certified US build. Keep exporting the person-level home_mortgage_interest column (already produced — the mortgage_conversion stage's own total) and the genuinely load-bearing structured columns: first/second_home_mortgage_balance and first/second_home_mortgage_origination_year (the §163(h)(3)(F) two-vintage caps need them; loans are joint, so tax_unit is their natural grain). The interest split is round-trip redundancy: the stage splits the person-level total into the two slots and the model sums them straight back — the deduction formula never uses the split.
  2. Reconciliation receipt (one diagnostic run on the current certified build): confirm per-record first + second_home_mortgage_interest == home_mortgage_interest (tax-unit aggregated), or report where they diverge (e.g. if the outlier screen applies between the person column and the split). pe-us#9276's arbitration flip is exactly microsim-neutral iff they agree; a divergence isn't a blocker — person-level is canonical by design — but it should be a known, quantified delta for the #511 pinning lane, not a surprise.

Sequencing

pe-us keeps reading the structured interest columns as a fallback until the first certified release without them, then deletes the inputs (stage 3 in pe-us#9275). No lockstep needed: h5s with the columns keep working on new pe-us, and h5s without them work as soon as pe-us#9276 ships. Note for anyone hand-mixing versions: policyengine-core's loader silently skips unknown h5 columns (core issue filed), so old-model + new-h5 combos before #9276 would silently drop mortgage interest — bundles pin versions, but worth the release-notes line.

Touchpoints found in the repo: mortgage_conversion stage outputs in packages/microcosm-build/src/microcosm/build/us/source_stages.json, release_input_coverage_manifest.json entries for the two columns, ecps_parity_reference.json.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the mortgage_conversion stage outputs in packages/microcosm-build/src/microcosm/build/us/source_stages.json, then inspect the matching entries in release_input_coverage_manifest.json and ecps_parity_reference.json. Run the requested diagnostic on the current certified build to compare the two structured interest columns with home_mortgage_interest at tax-unit grain. Done means the derived columns are no longer exported, load-bearing balance and origination-year columns remain, and the reconciliation result is recorded.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
build-system, data-engineering
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.