PolicyEngine / PolicyEngine/policyengine-core

Add base year support for parameter uprating

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

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

  1. Manual values override calculation: If IRS announces a specific value (e.g., via Revenue Procedure), that takes precedence over calculated values
  2. Apply only beyond latest manual value: For years after the last manually-specified value, apply the base-year formula
  3. Backward compatible: Existing incremental uprating should continue to work
  4. 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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.