Remove uprating metadata from formula variables

Author: MaxGhenis

changelog.d/remove-uprating-from-formula-variables.changed.md

@@ -0,0 +1 @@
+Remove redundant uprating metadata and class-level aggregation metadata from variables that already define their computation explicitly.

policyengine_us/data/economic_assumptions.py

@@ -13,6 +13,21 @@
 # extend to match — no hardcoded year constant to maintain.
 CPI_U_PARAM_PATH = "gov.bls.cpi.cpi_u"
 
+MICRODATA_UPRATING_OVERRIDES = {
+    "employment_income": "calibration.gov.irs.soi.employment_income",
+    "employment_income_last_year": "calibration.gov.irs.soi.employment_income",
+    "long_term_capital_gains": "calibration.gov.irs.soi.long_term_capital_gains",
+    "person_weight": "calibration.gov.census.populations.total",
+    "rent": "gov.bls.cpi.cpi_u",
+    "self_employment_income": "calibration.gov.irs.soi.self_employment_income",
+    "social_security": "calibration.gov.irs.soi.social_security",
+    "spm_unit_weight": "calibration.gov.census.populations.total",
+    "sstb_self_employment_income": "calibration.gov.irs.soi.self_employment_income",
+    "taxable_pension_income": "calibration.gov.irs.soi.taxable_pension_income",
+    "tax_unit_weight": "calibration.gov.census.populations.total",
+    "total_self_employment_income": "calibration.gov.irs.soi.self_employment_income",
+}
+
 
 def get_parameter_last_year(parameter) -> int:
     """Return the latest year explicitly defined in a parameter's YAML file.
@@ -100,11 +115,10 @@ def _apply_uprating(dataset: USMultiYearDataset, system=None) -> USMultiYearData
 def _apply_single_year_uprating(current, previous, system):
     """Apply multiplicative uprating from previous year to current year.
 
-    For each variable column in each entity DataFrame, looks up the
-    variable's uprating parameter path in ``system.variables``.  If the
-    variable has an uprating parameter, computes the growth factor as
-    ``param(current_year) / param(previous_year)`` and multiplies the
-    column by that factor.
+    For each variable column in each entity DataFrame, looks up its
+    dataset-extension uprating parameter path. Formula and adds/subtracts
+    variables cannot use Core variable-level uprating, so their dataset-only
+    upraters live in ``MICRODATA_UPRATING_OVERRIDES`` instead.
 
     Variables without an uprating parameter (or whose uprating parameter
     evaluates to 0 for the previous year) are left unchanged — they were
@@ -122,7 +136,9 @@ def _apply_single_year_uprating(current, previous, system):
             if col not in system.variables:
                 continue
             var = system.variables[col]
-            uprating_path = getattr(var, "uprating", None)
+            uprating_path = MICRODATA_UPRATING_OVERRIDES.get(col) or getattr(
+                var, "uprating", None
+            )
             if uprating_path is None:
                 continue
 

policyengine_us/tests/microsimulation/data/test_extend_single_year_dataset.py

@@ -125,6 +125,30 @@ def test_given_variable_without_uprating_then_values_unchanged(
         # Then — age has no uprating, should be unchanged
         np.testing.assert_array_equal(current.person["age"].values, AGE_BASE)
 
+    def test_given_computed_variable_with_microdata_override_then_values_scaled(
+        self, base_dataset
+    ):
+        # Given
+        current = base_dataset.copy()
+        current.time_period = str(BASE_YEAR + 1)
+        previous = base_dataset
+        variables = {
+            "employment_income": MockVariable("employment_income", uprating=None)
+        }
+        system = MockSystem(
+            variables=variables,
+            parameters=build_mock_parameters(
+                {EMPLOYMENT_INCOME_UPRATING: EMPLOYMENT_INCOME_PARAM_VALUES}
+            ),
+        )
+
+        # When
+        _apply_single_year_uprating(current, previous, system)
+
+        # Then
+        expected = EMPLOYMENT_INCOME_BASE * EMPLOYMENT_INCOME_GROWTH_FACTOR_2024_TO_2025
+        np.testing.assert_allclose(current.person["employment_income"].values, expected)
+
     def test_given_household_variable_with_uprating_then_values_scaled(
         self, base_dataset, mock_system
     ):

policyengine_us/tests/test_system_import.py

@@ -36,3 +36,25 @@ def test_package_import_does_not_raise():
     import policyengine_us
 
     importlib.reload(policyengine_us)
+
+
+def test_variables_use_at_most_one_computation_mode():
+    """Variables should choose exactly one computation mode after all
+    system-level mutations, including default uprating assignment.
+    """
+    from policyengine_us.system import CountryTaxBenefitSystem
+
+    system = CountryTaxBenefitSystem()
+    conflicts = []
+    for name, variable in system.variables.items():
+        modes = []
+        if variable.formulas:
+            modes.append("formula")
+        if variable.adds is not None or variable.subtracts is not None:
+            modes.append("adds/subtracts")
+        if variable.uprating is not None:
+            modes.append("uprating")
+        if len(modes) > 1:
+            conflicts.append(f"{name}: {', '.join(modes)}")
+
+    assert conflicts == []

policyengine_us/tools/default_uprating.py

@@ -98,7 +98,11 @@
 
 def add_default_uprating(system):
     for variable in system.variables.values():
-        if (variable.name in INPUT_VARIABLES) and (variable.uprating is None):
+        if (
+            (variable.name in INPUT_VARIABLES)
+            and (variable.uprating is None)
+            and variable.is_input_variable()
+        ):
             variable.uprating = (
                 "calibration.gov.cbo.income_by_source.adjusted_gross_income"
             )

policyengine_us/variables/gov/ssa/ss/social_security.py

@@ -12,4 +12,3 @@ class social_security(Variable):
         "social_security_" + i
         for i in ["dependents", "disability", "retirement", "survivors"]
     ]
-    uprating = "calibration.gov.irs.soi.social_security"

policyengine_us/variables/gov/states/tax/income/state_itemized_deductions.py

@@ -7,7 +7,6 @@ class state_itemized_deductions(Variable):
     label = "State itemized deductions"
     unit = USD
     definition_period = YEAR
-    adds = "gov.states.household.state_itemized_deductions"
 
     def formula(tax_unit, period, parameters):
         # States that adopt the federal itemized deductions

policyengine_us/variables/gov/states/tax/income/taxsim_state_agi.py

@@ -7,7 +7,6 @@ class taxsim_state_agi(Variable):
     label = "State adjusted gross income"
     unit = USD
     definition_period = YEAR
-    adds = "gov.states.household.state_agis"
 
     def formula(tax_unit, period, parameters):
         # States that adopt the federal AGI

policyengine_us/variables/household/demographic/weights/person_weight.py

@@ -6,7 +6,6 @@ class person_weight(Variable):
     entity = Person
     label = "Person weight"
     definition_period = YEAR
-    uprating = "calibration.gov.census.populations.total"
 
     def formula(person, period, parameters):
         return person.household("household_weight", period)

policyengine_us/variables/household/demographic/weights/spm_unit_weight.py

@@ -6,7 +6,6 @@ class spm_unit_weight(Variable):
     entity = SPMUnit
     label = "SPM unit weight"
     definition_period = YEAR
-    uprating = "calibration.gov.census.populations.total"
 
     def formula(spm_unit, period, parameters):
         # Use household weights if not provided