PolicyEngine / PolicyEngine/policyengine-core
Add base year support for parameter uprating
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 22
- Forks
- 30
- Avg merge
- 14h 33m
- Merged PRs (30d)
- 7
Description
Summary
Add support for specifying a base year and base value in uprating metadata to match statutory language in tax codes like IRC §24(i), §63(c)(7), etc.
Current Behavior
Uprating currently uses incremental calculation:
value(2027) = value(2026) × (CPI(2026) / CPI(2025))
value(2028) = value(2027) × (CPI(2027) / CPI(2026))
Desired Behavior
Enable base-year calculation per statutory requirements:
value(year) = base_value × (CPI(year) / CPI(base_year))
Proposed API
metadata:
uprating:
parameter: gov.irs.uprating
base_year: 2017 # Calendar year for base inflation calculation
base_value: 1400 # Optional: for verification/documentation
rounding:
type: downwards
interval: 100
Key Requirements
- Manual values override calculation: If IRS announces a specific value (e.g., via Revenue Procedure), that takes precedence over calculated values
- Apply only beyond latest manual value: For years after the last manually-specified value, apply the base-year formula
- Backward compatible: Existing incremental uprating should continue to work
- Verification: Optionally check that base_value matches the parameter value at base_year
Mathematical Equivalence
Note: Incremental and base-year approaches are mathematically equivalent:
Incremental: 2028 = 2026 × (CPI_2027/CPI_2025)
Base-year: 2028 = base_2025 × (CPI_2027/CPI_2024) = 2026 × (CPI_2027/CPI_2025)
However, explicit base-year support improves:
- Traceability to statutory language
- Auditability (clear which base year each parameter uses)
- Documentation (matches how statutes are written)
Examples from US Tax Code
IRC §24(i)(1) - CTC Refundable:
"In the case of a taxable year beginning after 2024, the $1,400 amount in subsection (h)(5) shall be increased...determined by substituting 'calendar year 2017' for 'calendar year 2016'"
IRC §24(i)(2) - CTC Amount:
"In the case of a taxable year beginning after 2025, the $2,200 amount in subsection (h)(2) shall be increased...determined by substituting '2024' for '2016'"
IRC §63(c)(7)(B)(ii)(II) - Standard Deduction:
Uses "calendar year 2024" as reference for adjustments beginning after 2025
Use Case
PolicyEngine US issue #6671 adds 2026 IRS tax parameters. Several parameters specify base-year calculations in statute, but we currently implement them incrementally.
Related: PolicyEngine/policyengine-us#[WILL_CREATE]
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Search the repository for uprating metadata handling and the existing incremental calculation, then trace how manual parameter values and rounding are applied. Implement the proposed base_year and optional base_value behavior while preserving existing incremental uprating, and verify that manual values take precedence and later years use the base-year formula.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100