policyengine 3.1.14__py3-none-any.whl → 3.1.16__py3-none-any.whl

policyengine/tax_benefit_models/uk/analysis.py

@@ -1,25 +1,195 @@
 """General utility functions for UK policy reform analysis."""
 
+import tempfile
+from pathlib import Path
+from typing import Any
+
 import pandas as pd
-from pydantic import BaseModel
+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 policyengine.outputs.inequality import (
+    Inequality,
+    calculate_uk_inequality,
+)
+from policyengine.outputs.poverty import (
+    Poverty,
+    calculate_uk_poverty_rates,
+)
 
+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]
+    baseline_poverty: OutputCollection[Poverty]
+    reform_poverty: OutputCollection[Poverty]
+    baseline_inequality: Inequality
+    reform_inequality: Inequality
 
 
-def general_policy_reform_analysis(
+def economic_impact_analysis(
     baseline_simulation: Simulation,
     reform_simulation: Simulation,
 ) -> PolicyReformAnalysis:
@@ -28,10 +198,23 @@ def general_policy_reform_analysis(
     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(
-        baseline_simulation=baseline_simulation,
-        reform_simulation=reform_simulation,
+        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
@@ -91,7 +274,19 @@ def general_policy_reform_analysis(
         outputs=programme_statistics, dataframe=programme_df
     )
 
+    # Calculate poverty rates for both simulations
+    baseline_poverty = calculate_uk_poverty_rates(baseline_simulation)
+    reform_poverty = calculate_uk_poverty_rates(reform_simulation)
+
+    # Calculate inequality for both simulations
+    baseline_inequality = calculate_uk_inequality(baseline_simulation)
+    reform_inequality = calculate_uk_inequality(reform_simulation)
+
     return PolicyReformAnalysis(
         decile_impacts=decile_impacts,
         programme_statistics=programme_collection,
+        baseline_poverty=baseline_poverty,
+        reform_poverty=reform_poverty,
+        baseline_inequality=baseline_inequality,
+        reform_inequality=reform_inequality,
     )

policyengine/tax_benefit_models/uk/model.py

@@ -9,12 +9,14 @@ from microdf import MicroDataFrame
 
 from policyengine.core import (
     Parameter,
-    ParameterValue,
     TaxBenefitModel,
     TaxBenefitModelVersion,
     Variable,
 )
-from policyengine.utils import parse_safe_date
+from policyengine.utils.parameter_labels import (
+    build_scale_lookup,
+    generate_label_for_parameter,
+)
 
 from .datasets import PolicyEngineUKDataset, UKYearData
 
@@ -108,6 +110,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",
         ],
     }
 
@@ -143,17 +150,21 @@ class PolicyEngineUKLatest(TaxBenefitModelVersion):
 
         from policyengine_core.parameters import Parameter as CoreParameter
 
+        scale_lookup = build_scale_lookup(system)
+
         for param_node in system.parameters.get_descendants():
             if isinstance(param_node, CoreParameter):
                 parameter = Parameter(
                     id=self.id + "-" + param_node.name,
                     name=param_node.name,
-                    label=param_node.metadata.get("label", param_node.name),
+                    label=generate_label_for_parameter(
+                        param_node, system, scale_lookup
+                    ),
                     tax_benefit_model_version=self,
                     description=param_node.description,
                     data_type=type(param_node(2025)),
                     unit=param_node.metadata.get("unit"),
-                    _core_param=param_node,  # Store for lazy value loading
+                    _core_param=param_node,
                 )
                 self.add_parameter(parameter)
 

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:

policyengine/tax_benefit_models/us/analysis.py

@@ -1,25 +1,213 @@
 """General utility functions for US policy reform analysis."""
 
+import tempfile
+from pathlib import Path
+from typing import Any
+
 import pandas as pd
-from pydantic import BaseModel
+from microdf import MicroDataFrame
+from pydantic import BaseModel, Field
 
 from policyengine.core import OutputCollection, Simulation
+from policyengine.core.policy import Policy
 from policyengine.outputs.decile_impact import (
     DecileImpact,
     calculate_decile_impacts,
 )
+from policyengine.outputs.inequality import (
+    Inequality,
+    calculate_us_inequality,
+)
+from policyengine.outputs.poverty import (
+    Poverty,
+    calculate_us_poverty_rates,
+)
 
+from .datasets import PolicyEngineUSDataset, USYearData
+from .model import us_latest
 from .outputs import ProgramStatistics
 
 
+class USHouseholdOutput(BaseModel):
+    """Output from a US household calculation with all entity data."""
+
+    person: list[dict[str, Any]]
+    marital_unit: list[dict[str, Any]]
+    family: list[dict[str, Any]]
+    spm_unit: list[dict[str, Any]]
+    tax_unit: list[dict[str, Any]]
+    household: dict[str, Any]
+
+
+class USHouseholdInput(BaseModel):
+    """Input for a US household calculation."""
+
+    people: list[dict[str, Any]]
+    marital_unit: dict[str, Any] = Field(default_factory=dict)
+    family: dict[str, Any] = Field(default_factory=dict)
+    spm_unit: dict[str, Any] = Field(default_factory=dict)
+    tax_unit: dict[str, Any] = Field(default_factory=dict)
+    household: dict[str, Any] = Field(default_factory=dict)
+    year: int = 2024
+
+
+def calculate_household_impact(
+    household_input: USHouseholdInput,
+    policy: Policy | None = None,
+) -> USHouseholdOutput:
+    """Calculate tax and benefit impacts for a single US household."""
+    n_people = len(household_input.people)
+
+    # Build person data with defaults
+    person_data = {
+        "person_id": list(range(n_people)),
+        "person_household_id": [0] * n_people,
+        "person_marital_unit_id": [0] * n_people,
+        "person_family_id": [0] * n_people,
+        "person_spm_unit_id": [0] * n_people,
+        "person_tax_unit_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 entity data with defaults
+    household_data = {
+        "household_id": [0],
+        "household_weight": [1.0],
+    }
+    for key, value in household_input.household.items():
+        household_data[key] = [value]
+
+    marital_unit_data = {
+        "marital_unit_id": [0],
+        "marital_unit_weight": [1.0],
+    }
+    for key, value in household_input.marital_unit.items():
+        marital_unit_data[key] = [value]
+
+    family_data = {
+        "family_id": [0],
+        "family_weight": [1.0],
+    }
+    for key, value in household_input.family.items():
+        family_data[key] = [value]
+
+    spm_unit_data = {
+        "spm_unit_id": [0],
+        "spm_unit_weight": [1.0],
+    }
+    for key, value in household_input.spm_unit.items():
+        spm_unit_data[key] = [value]
+
+    tax_unit_data = {
+        "tax_unit_id": [0],
+        "tax_unit_weight": [1.0],
+    }
+    for key, value in household_input.tax_unit.items():
+        tax_unit_data[key] = [value]
+
+    # Create MicroDataFrames
+    person_df = MicroDataFrame(
+        pd.DataFrame(person_data), weights="person_weight"
+    )
+    household_df = MicroDataFrame(
+        pd.DataFrame(household_data), weights="household_weight"
+    )
+    marital_unit_df = MicroDataFrame(
+        pd.DataFrame(marital_unit_data), weights="marital_unit_weight"
+    )
+    family_df = MicroDataFrame(
+        pd.DataFrame(family_data), weights="family_weight"
+    )
+    spm_unit_df = MicroDataFrame(
+        pd.DataFrame(spm_unit_data), weights="spm_unit_weight"
+    )
+    tax_unit_df = MicroDataFrame(
+        pd.DataFrame(tax_unit_data), weights="tax_unit_weight"
+    )
+
+    # Create temporary dataset
+    tmpdir = tempfile.mkdtemp()
+    filepath = str(Path(tmpdir) / "household_impact.h5")
+
+    dataset = PolicyEngineUSDataset(
+        name="Household impact calculation",
+        description="Single household for impact calculation",
+        filepath=filepath,
+        year=household_input.year,
+        data=USYearData(
+            person=person_df,
+            household=household_df,
+            marital_unit=marital_unit_df,
+            family=family_df,
+            spm_unit=spm_unit_df,
+            tax_unit=tax_unit_df,
+        ),
+    )
+
+    # Run simulation
+    simulation = Simulation(
+        dataset=dataset,
+        tax_benefit_model_version=us_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)
+
+    def extract_entity_outputs(
+        entity_name: str, entity_data, n_rows: int
+    ) -> list[dict[str, Any]]:
+        outputs = []
+        for i in range(n_rows):
+            row_dict = {}
+            for var in us_latest.entity_variables[entity_name]:
+                row_dict[var] = safe_convert(entity_data[var].iloc[i])
+            outputs.append(row_dict)
+        return outputs
+
+    return USHouseholdOutput(
+        person=extract_entity_outputs("person", output_data.person, n_people),
+        marital_unit=extract_entity_outputs(
+            "marital_unit", output_data.marital_unit, 1
+        ),
+        family=extract_entity_outputs("family", output_data.family, 1),
+        spm_unit=extract_entity_outputs("spm_unit", output_data.spm_unit, 1),
+        tax_unit=extract_entity_outputs("tax_unit", output_data.tax_unit, 1),
+        household={
+            var: safe_convert(output_data.household[var].iloc[0])
+            for var in us_latest.entity_variables["household"]
+        },
+    )
+
+
 class PolicyReformAnalysis(BaseModel):
     """Complete policy reform analysis result."""
 
     decile_impacts: OutputCollection[DecileImpact]
     program_statistics: OutputCollection[ProgramStatistics]
+    baseline_poverty: OutputCollection[Poverty]
+    reform_poverty: OutputCollection[Poverty]
+    baseline_inequality: Inequality
+    reform_inequality: Inequality
 
 
-def general_policy_reform_analysis(
+def economic_impact_analysis(
     baseline_simulation: Simulation,
     reform_simulation: Simulation,
 ) -> PolicyReformAnalysis:
@@ -28,10 +216,23 @@ def general_policy_reform_analysis(
     Returns:
         PolicyReformAnalysis containing decile impacts and program 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 (using household_net_income for US)
     decile_impacts = calculate_decile_impacts(
-        baseline_simulation=baseline_simulation,
-        reform_simulation=reform_simulation,
+        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,
         income_variable="household_net_income",
     )
 
@@ -94,6 +295,19 @@ def general_policy_reform_analysis(
         outputs=program_statistics, dataframe=program_df
     )
 
+    # Calculate poverty rates for both simulations
+    baseline_poverty = calculate_us_poverty_rates(baseline_simulation)
+    reform_poverty = calculate_us_poverty_rates(reform_simulation)
+
+    # Calculate inequality for both simulations
+    baseline_inequality = calculate_us_inequality(baseline_simulation)
+    reform_inequality = calculate_us_inequality(reform_simulation)
+
     return PolicyReformAnalysis(
-        decile_impacts=decile_impacts, program_statistics=program_collection
+        decile_impacts=decile_impacts,
+        program_statistics=program_collection,
+        baseline_poverty=baseline_poverty,
+        reform_poverty=reform_poverty,
+        baseline_inequality=baseline_inequality,
+        reform_inequality=reform_inequality,
     )

policyengine/tax_benefit_models/us/model.py

@@ -9,12 +9,14 @@ from microdf import MicroDataFrame
 
 from policyengine.core import (
     Parameter,
-    ParameterValue,
     TaxBenefitModel,
     TaxBenefitModelVersion,
     Variable,
 )
-from policyengine.utils import parse_safe_date
+from policyengine.utils.parameter_labels import (
+    build_scale_lookup,
+    generate_label_for_parameter,
+)
 
 from .datasets import PolicyEngineUSDataset, USYearData
 
@@ -57,6 +59,8 @@ class PolicyEngineUSLatest(TaxBenefitModelVersion):
             "person_weight",
             # Demographics
             "age",
+            "is_child",
+            "is_adult",
             # Income
             "employment_income",
             # Benefits
@@ -79,6 +83,9 @@ class PolicyEngineUSLatest(TaxBenefitModelVersion):
             "snap",
             "tanf",
             "spm_unit_net_income",
+            # Poverty measures
+            "spm_unit_is_in_spm_poverty",
+            "spm_unit_is_in_deep_spm_poverty",
         ],
         "tax_unit": [
             "tax_unit_id",
@@ -136,17 +143,21 @@ class PolicyEngineUSLatest(TaxBenefitModelVersion):
 
         from policyengine_core.parameters import Parameter as CoreParameter
 
+        scale_lookup = build_scale_lookup(system)
+
         for param_node in system.parameters.get_descendants():
             if isinstance(param_node, CoreParameter):
                 parameter = Parameter(
                     id=self.id + "-" + param_node.name,
                     name=param_node.name,
-                    label=param_node.metadata.get("label"),
+                    label=generate_label_for_parameter(
+                        param_node, system, scale_lookup
+                    ),
                     tax_benefit_model_version=self,
                     description=param_node.description,
                     data_type=type(param_node(2025)),
                     unit=param_node.metadata.get("unit"),
-                    _core_param=param_node,  # Store for lazy value loading
+                    _core_param=param_node,
                 )
                 self.add_parameter(parameter)
 

policyengine/utils/__init__.py

@@ -1,3 +1,7 @@
 from .dates import parse_safe_date as parse_safe_date
+from .parameter_labels import build_scale_lookup as build_scale_lookup
+from .parameter_labels import (
+    generate_label_for_parameter as generate_label_for_parameter,
+)
 from .plotting import COLORS as COLORS
 from .plotting import format_fig as format_fig