policyengine 3.1.13__tar.gz → 3.1.15__tar.gz

{policyengine-3.1.13 → policyengine-3.1.15}/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), 
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.1.15] - 2025-12-14 23:51:27
+
+### Added
+
+- Household impacts
+
+## [3.1.14] - 2025-12-10 21:59:24
+
+### Fixed
+
+- Improvements to loading taxbenefitsystems.
+
 ## [3.1.13] - 2025-12-10 19:29:28
 
 ### Fixed
@@ -275,6 +287,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 
 
+[3.1.15]: https://github.com/PolicyEngine/policyengine.py/compare/3.1.14...3.1.15
+[3.1.14]: https://github.com/PolicyEngine/policyengine.py/compare/3.1.13...3.1.14
 [3.1.13]: https://github.com/PolicyEngine/policyengine.py/compare/3.1.12...3.1.13
 [3.1.12]: https://github.com/PolicyEngine/policyengine.py/compare/3.1.11...3.1.12
 [3.1.11]: https://github.com/PolicyEngine/policyengine.py/compare/3.1.10...3.1.11

{policyengine-3.1.13 → policyengine-3.1.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: policyengine
-Version: 3.1.13
+Version: 3.1.15
 Summary: A package to conduct policy analysis using PolicyEngine tax-benefit models.
 Author-email: PolicyEngine <hello@policyengine.org>
 License:                     GNU AFFERO GENERAL PUBLIC LICENSE

{policyengine-3.1.13 → policyengine-3.1.15}/changelog.yaml

@@ -225,3 +225,13 @@
     fixed:
     - Naming improvements.
   date: 2025-12-10 19:29:28
+- bump: patch
+  changes:
+    fixed:
+    - Improvements to loading taxbenefitsystems.
+  date: 2025-12-10 21:59:24
+- bump: patch
+  changes:
+    added:
+    - Household impacts
+  date: 2025-12-14 23:51:27

policyengine-3.1.15/examples/household_impact_example.py

@@ -0,0 +1,128 @@
+"""Example: Calculate household tax and benefit impacts.
+
+This script demonstrates using calculate_household_impact for both UK and US
+to compute taxes and benefits for custom households.
+
+Run: python examples/household_impact_example.py
+"""
+
+from policyengine.tax_benefit_models.uk import (
+    UKHouseholdInput,
+)
+from policyengine.tax_benefit_models.uk import (
+    calculate_household_impact as calculate_uk_impact,
+)
+from policyengine.tax_benefit_models.us import (
+    USHouseholdInput,
+)
+from policyengine.tax_benefit_models.us import (
+    calculate_household_impact as calculate_us_impact,
+)
+
+
+def uk_example():
+    """UK household impact example."""
+    print("=" * 60)
+    print("UK HOUSEHOLD IMPACT")
+    print("=" * 60)
+
+    # Single adult earning £50,000
+    household = UKHouseholdInput(
+        people=[{"age": 35, "employment_income": 50_000}],
+        year=2026,
+    )
+    result = calculate_uk_impact(household)
+
+    print("\nSingle adult, £50k income:")
+    print(
+        f"  Net income: £{result.household['hbai_household_net_income']:,.0f}"
+    )
+    print(f"  Income tax: £{result.person[0]['income_tax']:,.0f}")
+    print(
+        f"  National Insurance: £{result.person[0]['national_insurance']:,.0f}"
+    )
+    print(f"  Total tax: £{result.household['household_tax']:,.0f}")
+
+    # Family with two children, £30k income, renting
+    household = UKHouseholdInput(
+        people=[
+            {"age": 35, "employment_income": 30_000},
+            {"age": 33},
+            {"age": 8},
+            {"age": 5},
+        ],
+        benunit={
+            "would_claim_uc": True,
+            "would_claim_child_benefit": True,
+        },
+        household={
+            "rent": 12_000,  # £1k/month
+            "region": "NORTH_WEST",
+        },
+        year=2026,
+    )
+    result = calculate_uk_impact(household)
+
+    print("\nFamily (2 adults, 2 children), £30k income, renting:")
+    print(
+        f"  Net income: £{result.household['hbai_household_net_income']:,.0f}"
+    )
+    print(f"  Income tax: £{result.person[0]['income_tax']:,.0f}")
+    print(f"  Child benefit: £{result.benunit[0]['child_benefit']:,.0f}")
+    print(f"  Universal credit: £{result.benunit[0]['universal_credit']:,.0f}")
+    print(f"  Total benefits: £{result.household['household_benefits']:,.0f}")
+
+
+def us_example():
+    """US household impact example."""
+    print("\n" + "=" * 60)
+    print("US HOUSEHOLD IMPACT")
+    print("=" * 60)
+
+    # Single adult earning $50,000
+    household = USHouseholdInput(
+        people=[
+            {"age": 35, "employment_income": 50_000, "is_tax_unit_head": True}
+        ],
+        tax_unit={"filing_status": "SINGLE"},
+        household={"state_code_str": "CA"},
+        year=2024,
+    )
+    result = calculate_us_impact(household)
+
+    print("\nSingle adult, $50k income (California):")
+    print(f"  Net income: ${result.household['household_net_income']:,.0f}")
+    print(f"  Income tax: ${result.tax_unit[0]['income_tax']:,.0f}")
+    print(f"  Payroll tax: ${result.tax_unit[0]['employee_payroll_tax']:,.0f}")
+
+    # Married couple with children, lower income
+    household = USHouseholdInput(
+        people=[
+            {"age": 35, "employment_income": 40_000, "is_tax_unit_head": True},
+            {"age": 33, "is_tax_unit_spouse": True},
+            {"age": 8, "is_tax_unit_dependent": True},
+            {"age": 5, "is_tax_unit_dependent": True},
+        ],
+        tax_unit={"filing_status": "JOINT"},
+        household={"state_code_str": "TX"},
+        year=2024,
+    )
+    result = calculate_us_impact(household)
+
+    print("\nMarried couple with 2 children, $40k income (Texas):")
+    print(f"  Net income: ${result.household['household_net_income']:,.0f}")
+    print(f"  Federal income tax: ${result.tax_unit[0]['income_tax']:,.0f}")
+    print(f"  EITC: ${result.tax_unit[0]['eitc']:,.0f}")
+    print(f"  Child tax credit: ${result.tax_unit[0]['ctc']:,.0f}")
+    print(f"  SNAP: ${result.spm_unit[0]['snap']:,.0f}")
+
+
+def main():
+    uk_example()
+    us_example()
+    print("\n" + "=" * 60)
+    print("Done!")
+
+
+if __name__ == "__main__":
+    main()

{policyengine-3.1.13 → policyengine-3.1.15}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "policyengine"
-version = "3.1.13"
+version = "3.1.15"
 description = "A package to conduct policy analysis using PolicyEngine tax-benefit models."
 readme = "README.md"
 authors = [

{policyengine-3.1.13 → policyengine-3.1.15}/src/policyengine/core/tax_benefit_model_version.py

@@ -24,7 +24,15 @@ class TaxBenefitModelVersion(BaseModel):
 
     variables: list["Variable"] = Field(default_factory=list)
     parameters: list["Parameter"] = Field(default_factory=list)
-    parameter_values: list["ParameterValue"] = Field(default_factory=list)
+
+    @property
+    def parameter_values(self) -> list["ParameterValue"]:
+        """Aggregate all parameter values from all parameters."""
+        return [
+            pv
+            for parameter in self.parameters
+            for pv in parameter.parameter_values
+        ]
 
     # Lookup dicts for O(1) access (excluded from serialization)
     variables_by_name: dict[str, "Variable"] = Field(

{policyengine-3.1.13 → policyengine-3.1.15}/src/policyengine/outputs/decile_impact.py

@@ -2,6 +2,10 @@ import pandas as pd
 from pydantic import ConfigDict
 
 from policyengine.core import Output, OutputCollection, Simulation
+from policyengine.core.dataset import Dataset
+from policyengine.core.dynamic import Dynamic
+from policyengine.core.policy import Policy
+from policyengine.core.tax_benefit_model_version import TaxBenefitModelVersion
 
 
 class DecileImpact(Output):
@@ -93,8 +97,11 @@ class DecileImpact(Output):
 
 
 def calculate_decile_impacts(
-    baseline_simulation: Simulation,
-    reform_simulation: Simulation,
+    dataset: Dataset,
+    tax_benefit_model_version: TaxBenefitModelVersion,
+    baseline_policy: Policy | None = None,
+    reform_policy: Policy | None = None,
+    dynamic: Dynamic | None = None,
     income_variable: str = "equiv_hbai_household_net_income",
     entity: str | None = None,
     quantiles: int = 10,
@@ -104,6 +111,19 @@ def calculate_decile_impacts(
     Returns:
         OutputCollection containing list of DecileImpact objects and DataFrame
     """
+    baseline_simulation = Simulation(
+        dataset=dataset,
+        tax_benefit_model_version=tax_benefit_model_version,
+        policy=baseline_policy,
+        dynamic=dynamic,
+    )
+    reform_simulation = Simulation(
+        dataset=dataset,
+        tax_benefit_model_version=tax_benefit_model_version,
+        policy=reform_policy,
+        dynamic=dynamic,
+    )
+
     results = []
     for decile in range(1, quantiles + 1):
         impact = DecileImpact(

{policyengine-3.1.13 → policyengine-3.1.15}/src/policyengine/tax_benefit_models/uk/__init__.py

@@ -5,7 +5,12 @@ from importlib.util import find_spec
 if find_spec("policyengine_uk") is not None:
     from policyengine.core import Dataset
 
-    from .analysis import general_policy_reform_analysis
+    from .analysis import (
+        UKHouseholdInput,
+        UKHouseholdOutput,
+        calculate_household_impact,
+        economic_impact_analysis,
+    )
     from .datasets import (
         PolicyEngineUKDataset,
         UKYearData,
@@ -37,7 +42,10 @@ if find_spec("policyengine_uk") is not None:
         "PolicyEngineUKLatest",
         "uk_model",
         "uk_latest",
-        "general_policy_reform_analysis",
+        "economic_impact_analysis",
+        "calculate_household_impact",
+        "UKHouseholdInput",
+        "UKHouseholdOutput",
         "ProgrammeStatistics",
     ]
 else:

policyengine-3.1.15/src/policyengine/tax_benefit_models/uk/analysis.py

@@ -0,0 +1,268 @@
+"""General utility functions for UK policy reform analysis."""
+
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+from microdf import MicroDataFrame
+from pydantic import BaseModel, Field, create_model
+
+from policyengine.core import OutputCollection, Simulation
+from policyengine.core.policy import Policy
+from policyengine.outputs.decile_impact import (
+    DecileImpact,
+    calculate_decile_impacts,
+)
+
+from .datasets import PolicyEngineUKDataset, UKYearData
+from .model import uk_latest
+from .outputs import ProgrammeStatistics
+
+
+def _create_entity_output_model(
+    entity: str, variables: list[str]
+) -> type[BaseModel]:
+    """Create a dynamic Pydantic model for entity output variables."""
+    fields = {var: (float, ...) for var in variables}
+    return create_model(f"{entity.title()}Output", **fields)
+
+
+# Create output models dynamically from uk_latest.entity_variables
+PersonOutput = _create_entity_output_model(
+    "person", uk_latest.entity_variables["person"]
+)
+BenunitOutput = _create_entity_output_model(
+    "benunit", uk_latest.entity_variables["benunit"]
+)
+HouseholdEntityOutput = _create_entity_output_model(
+    "household", uk_latest.entity_variables["household"]
+)
+
+
+class UKHouseholdOutput(BaseModel):
+    """Output from a UK household calculation with all entity data."""
+
+    person: list[dict[str, Any]]
+    benunit: list[dict[str, Any]]
+    household: dict[str, Any]
+
+
+class UKHouseholdInput(BaseModel):
+    """Input for a UK household calculation."""
+
+    people: list[dict[str, Any]]
+    benunit: dict[str, Any] = Field(default_factory=dict)
+    household: dict[str, Any] = Field(default_factory=dict)
+    year: int = 2026
+
+
+def calculate_household_impact(
+    household_input: UKHouseholdInput,
+    policy: Policy | None = None,
+) -> UKHouseholdOutput:
+    """Calculate tax and benefit impacts for a single UK household."""
+    n_people = len(household_input.people)
+
+    # Build person data with defaults
+    person_data = {
+        "person_id": list(range(n_people)),
+        "person_benunit_id": [0] * n_people,
+        "person_household_id": [0] * n_people,
+        "person_weight": [1.0] * n_people,
+    }
+    # Add user-provided person fields
+    for i, person in enumerate(household_input.people):
+        for key, value in person.items():
+            if key not in person_data:
+                person_data[key] = [
+                    0.0
+                ] * n_people  # Default to 0 for numeric fields
+            person_data[key][i] = value
+
+    # Build benunit data with defaults
+    benunit_data = {
+        "benunit_id": [0],
+        "benunit_weight": [1.0],
+    }
+    for key, value in household_input.benunit.items():
+        benunit_data[key] = [value]
+
+    # Build household data with defaults (required for uprating)
+    household_data = {
+        "household_id": [0],
+        "household_weight": [1.0],
+        "region": ["LONDON"],
+        "tenure_type": ["RENT_PRIVATELY"],
+        "council_tax": [0.0],
+        "rent": [0.0],
+    }
+    for key, value in household_input.household.items():
+        household_data[key] = [value]
+
+    # Create MicroDataFrames
+    person_df = MicroDataFrame(
+        pd.DataFrame(person_data), weights="person_weight"
+    )
+    benunit_df = MicroDataFrame(
+        pd.DataFrame(benunit_data), weights="benunit_weight"
+    )
+    household_df = MicroDataFrame(
+        pd.DataFrame(household_data), weights="household_weight"
+    )
+
+    # Create temporary dataset
+    tmpdir = tempfile.mkdtemp()
+    filepath = str(Path(tmpdir) / "household_impact.h5")
+
+    dataset = PolicyEngineUKDataset(
+        name="Household impact calculation",
+        description="Single household for impact calculation",
+        filepath=filepath,
+        year=household_input.year,
+        data=UKYearData(
+            person=person_df,
+            benunit=benunit_df,
+            household=household_df,
+        ),
+    )
+
+    # Run simulation
+    simulation = Simulation(
+        dataset=dataset,
+        tax_benefit_model_version=uk_latest,
+        policy=policy,
+    )
+    simulation.run()
+
+    # Extract all output variables defined in entity_variables
+    output_data = simulation.output_dataset.data
+
+    def safe_convert(value):
+        """Convert value to float if numeric, otherwise return as string."""
+        try:
+            return float(value)
+        except (ValueError, TypeError):
+            return str(value)
+
+    person_outputs = []
+    for i in range(n_people):
+        person_dict = {}
+        for var in uk_latest.entity_variables["person"]:
+            person_dict[var] = safe_convert(output_data.person[var].iloc[i])
+        person_outputs.append(person_dict)
+
+    benunit_outputs = []
+    for i in range(len(output_data.benunit)):
+        benunit_dict = {}
+        for var in uk_latest.entity_variables["benunit"]:
+            benunit_dict[var] = safe_convert(output_data.benunit[var].iloc[i])
+        benunit_outputs.append(benunit_dict)
+
+    household_dict = {}
+    for var in uk_latest.entity_variables["household"]:
+        household_dict[var] = safe_convert(output_data.household[var].iloc[0])
+
+    return UKHouseholdOutput(
+        person=person_outputs,
+        benunit=benunit_outputs,
+        household=household_dict,
+    )
+
+
+class PolicyReformAnalysis(BaseModel):
+    """Complete policy reform analysis result."""
+
+    decile_impacts: OutputCollection[DecileImpact]
+    programme_statistics: OutputCollection[ProgrammeStatistics]
+
+
+def economic_impact_analysis(
+    baseline_simulation: Simulation,
+    reform_simulation: Simulation,
+) -> PolicyReformAnalysis:
+    """Perform comprehensive analysis of a policy reform.
+
+    Returns:
+        PolicyReformAnalysis containing decile impacts and programme statistics
+    """
+    baseline_simulation.ensure()
+    reform_simulation.ensure()
+
+    assert len(baseline_simulation.dataset.data.household) > 100, (
+        "Baseline simulation must have more than 100 households"
+    )
+    assert len(reform_simulation.dataset.data.household) > 100, (
+        "Reform simulation must have more than 100 households"
+    )
+
+    # Decile impact
+    decile_impacts = calculate_decile_impacts(
+        dataset=baseline_simulation.dataset,
+        tax_benefit_model_version=baseline_simulation.tax_benefit_model_version,
+        baseline_policy=baseline_simulation.policy,
+        reform_policy=reform_simulation.policy,
+        dynamic=baseline_simulation.dynamic,
+    )
+
+    # Major programmes to analyse
+    programmes = {
+        # Tax
+        "income_tax": {"entity": "person", "is_tax": True},
+        "national_insurance": {"entity": "person", "is_tax": True},
+        "vat": {"entity": "household", "is_tax": True},
+        "council_tax": {"entity": "household", "is_tax": True},
+        # Benefits
+        "universal_credit": {"entity": "person", "is_tax": False},
+        "child_benefit": {"entity": "person", "is_tax": False},
+        "pension_credit": {"entity": "person", "is_tax": False},
+        "income_support": {"entity": "person", "is_tax": False},
+        "working_tax_credit": {"entity": "person", "is_tax": False},
+        "child_tax_credit": {"entity": "person", "is_tax": False},
+    }
+
+    programme_statistics = []
+
+    for programme_name, programme_info in programmes.items():
+        entity = programme_info["entity"]
+        is_tax = programme_info["is_tax"]
+
+        stats = ProgrammeStatistics(
+            baseline_simulation=baseline_simulation,
+            reform_simulation=reform_simulation,
+            programme_name=programme_name,
+            entity=entity,
+            is_tax=is_tax,
+        )
+        stats.run()
+        programme_statistics.append(stats)
+
+    # Create DataFrame
+    programme_df = pd.DataFrame(
+        [
+            {
+                "baseline_simulation_id": p.baseline_simulation.id,
+                "reform_simulation_id": p.reform_simulation.id,
+                "programme_name": p.programme_name,
+                "entity": p.entity,
+                "is_tax": p.is_tax,
+                "baseline_total": p.baseline_total,
+                "reform_total": p.reform_total,
+                "change": p.change,
+                "baseline_count": p.baseline_count,
+                "reform_count": p.reform_count,
+                "winners": p.winners,
+                "losers": p.losers,
+            }
+            for p in programme_statistics
+        ]
+    )
+
+    programme_collection = OutputCollection(
+        outputs=programme_statistics, dataframe=programme_df
+    )
+
+    return PolicyReformAnalysis(
+        decile_impacts=decile_impacts,
+        programme_statistics=programme_collection,
+    )

{policyengine-3.1.13 → policyengine-3.1.15}/src/policyengine/tax_benefit_models/uk/datasets.py

@@ -196,8 +196,8 @@ def load_datasets(
         for year in years:
             filepath = f"{data_folder}/{Path(dataset).stem}_year_{year}.h5"
             uk_dataset = PolicyEngineUKDataset(
-                name=f"{dataset}-year-{year}",
-                description=f"UK Dataset for year {year} based on {dataset}",
+                name=f"{Path(dataset).stem}-year-{year}",
+                description=f"UK Dataset for year {year} based on {Path(dataset).stem}",
                 filepath=filepath,
                 year=int(year),
             )

{policyengine-3.1.13 → policyengine-3.1.15}/src/policyengine/tax_benefit_models/uk/model.py

@@ -9,12 +9,10 @@ from microdf import MicroDataFrame
 
 from policyengine.core import (
     Parameter,
-    ParameterValue,
     TaxBenefitModel,
     TaxBenefitModelVersion,
     Variable,
 )
-from policyengine.utils import parse_safe_date
 
 from .datasets import PolicyEngineUKDataset, UKYearData
 
@@ -108,6 +106,11 @@ class PolicyEngineUKLatest(TaxBenefitModelVersion):
             "rent",
             "council_tax",
             "tenure_type",
+            # Poverty measures
+            "in_poverty_bhc",
+            "in_poverty_ahc",
+            "in_relative_poverty_bhc",
+            "in_relative_poverty_ahc",
         ],
     }
 

{policyengine-3.1.13 → policyengine-3.1.15}/src/policyengine/tax_benefit_models/us/__init__.py

@@ -5,7 +5,12 @@ from importlib.util import find_spec
 if find_spec("policyengine_us") is not None:
     from policyengine.core import Dataset
 
-    from .analysis import general_policy_reform_analysis
+    from .analysis import (
+        USHouseholdInput,
+        USHouseholdOutput,
+        calculate_household_impact,
+        economic_impact_analysis,
+    )
     from .datasets import (
         PolicyEngineUSDataset,
         USYearData,
@@ -37,7 +42,10 @@ if find_spec("policyengine_us") is not None:
         "PolicyEngineUSLatest",
         "us_model",
         "us_latest",
-        "general_policy_reform_analysis",
+        "economic_impact_analysis",
+        "calculate_household_impact",
+        "USHouseholdInput",
+        "USHouseholdOutput",
         "ProgramStatistics",
     ]
 else: