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

policyengine/outputs/__init__.py

@@ -8,6 +8,22 @@ from policyengine.outputs.decile_impact import (
     DecileImpact,
     calculate_decile_impacts,
 )
+from policyengine.outputs.inequality import (
+    UK_INEQUALITY_INCOME_VARIABLE,
+    US_INEQUALITY_INCOME_VARIABLE,
+    Inequality,
+    calculate_uk_inequality,
+    calculate_us_inequality,
+)
+from policyengine.outputs.poverty import (
+    UK_POVERTY_VARIABLES,
+    US_POVERTY_VARIABLES,
+    Poverty,
+    UKPovertyType,
+    USPovertyType,
+    calculate_uk_poverty_rates,
+    calculate_us_poverty_rates,
+)
 
 __all__ = [
     "Output",
@@ -18,4 +34,16 @@ __all__ = [
     "ChangeAggregateType",
     "DecileImpact",
     "calculate_decile_impacts",
+    "Poverty",
+    "UKPovertyType",
+    "USPovertyType",
+    "UK_POVERTY_VARIABLES",
+    "US_POVERTY_VARIABLES",
+    "calculate_uk_poverty_rates",
+    "calculate_us_poverty_rates",
+    "Inequality",
+    "UK_INEQUALITY_INCOME_VARIABLE",
+    "US_INEQUALITY_INCOME_VARIABLE",
+    "calculate_uk_inequality",
+    "calculate_us_inequality",
 ]

policyengine/outputs/inequality.py

@@ -0,0 +1,276 @@
+"""Inequality analysis output types."""
+
+from typing import Any
+
+import numpy as np
+import pandas as pd
+from pydantic import ConfigDict
+
+from policyengine.core import Output, Simulation
+
+
+def _gini(values: np.ndarray, weights: np.ndarray) -> float:
+    """Calculate weighted Gini coefficient.
+
+    Args:
+        values: Array of income values
+        weights: Array of weights
+
+    Returns:
+        Gini coefficient between 0 (perfect equality) and 1 (perfect inequality)
+    """
+    # Handle edge cases
+    if len(values) == 0 or weights.sum() == 0:
+        return 0.0
+
+    # Sort by values
+    sorted_indices = np.argsort(values)
+    sorted_values = values[sorted_indices]
+    sorted_weights = weights[sorted_indices]
+
+    # Cumulative weights and weighted values
+    cumulative_weights = np.cumsum(sorted_weights)
+    total_weight = cumulative_weights[-1]
+    cumulative_weighted_values = np.cumsum(sorted_values * sorted_weights)
+    total_weighted_value = cumulative_weighted_values[-1]
+
+    if total_weighted_value == 0:
+        return 0.0
+
+    # Calculate Gini using the area formula
+    # Gini = 1 - 2 * (area under Lorenz curve)
+    lorenz_curve = cumulative_weighted_values / total_weighted_value
+    weight_fractions = sorted_weights / total_weight
+
+    # Area under Lorenz curve using trapezoidal rule
+    area = np.sum(weight_fractions * (lorenz_curve - weight_fractions / 2))
+
+    return float(1 - 2 * area)
+
+
+class Inequality(Output):
+    """Single inequality measure result - represents one database row.
+
+    This is a single-simulation output type that calculates inequality
+    metrics for a given income variable, optionally filtered by
+    demographic variables.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    simulation: Simulation
+    income_variable: str
+    entity: str = "household"
+
+    # Optional demographic filters
+    filter_variable: str | None = None
+    filter_variable_eq: Any | None = None
+    filter_variable_leq: Any | None = None
+    filter_variable_geq: Any | None = None
+
+    # Results populated by run()
+    gini: float | None = None
+    top_10_share: float | None = None
+    top_1_share: float | None = None
+    bottom_50_share: float | None = None
+
+    def run(self):
+        """Calculate inequality metrics."""
+        # Get income variable info
+        income_var_obj = (
+            self.simulation.tax_benefit_model_version.get_variable(
+                self.income_variable
+            )
+        )
+
+        # Get target entity data
+        target_entity = self.entity
+        data = getattr(self.simulation.output_dataset.data, target_entity)
+
+        # Map income variable to target entity if needed
+        if income_var_obj.entity != target_entity:
+            mapped = self.simulation.output_dataset.data.map_to_entity(
+                income_var_obj.entity,
+                target_entity,
+                columns=[self.income_variable],
+            )
+            income_series = mapped[self.income_variable]
+        else:
+            income_series = data[self.income_variable]
+
+        # Get weights
+        weight_col = f"{target_entity}_weight"
+        if weight_col in data.columns:
+            weights = data[weight_col]
+        else:
+            weights = pd.Series(np.ones(len(income_series)))
+
+        # Apply demographic filter if specified
+        if self.filter_variable is not None:
+            filter_var_obj = (
+                self.simulation.tax_benefit_model_version.get_variable(
+                    self.filter_variable
+                )
+            )
+
+            if filter_var_obj.entity != target_entity:
+                filter_mapped = (
+                    self.simulation.output_dataset.data.map_to_entity(
+                        filter_var_obj.entity,
+                        target_entity,
+                        columns=[self.filter_variable],
+                    )
+                )
+                filter_series = filter_mapped[self.filter_variable]
+            else:
+                filter_series = data[self.filter_variable]
+
+            # Build filter mask
+            mask = filter_series.notna()
+            if self.filter_variable_eq is not None:
+                mask &= filter_series == self.filter_variable_eq
+            if self.filter_variable_leq is not None:
+                mask &= filter_series <= self.filter_variable_leq
+            if self.filter_variable_geq is not None:
+                mask &= filter_series >= self.filter_variable_geq
+
+            # Apply mask
+            income_series = income_series[mask]
+            weights = weights[mask]
+
+        # Convert to numpy arrays
+        values = np.array(income_series)
+        weights_arr = np.array(weights)
+
+        # Remove NaN values
+        valid_mask = ~np.isnan(values) & ~np.isnan(weights_arr)
+        values = values[valid_mask]
+        weights_arr = weights_arr[valid_mask]
+
+        # Calculate Gini coefficient
+        self.gini = _gini(values, weights_arr)
+
+        # Calculate income shares
+        if len(values) > 0 and weights_arr.sum() > 0:
+            total_income = np.sum(values * weights_arr)
+
+            if total_income > 0:
+                # Sort by income
+                sorted_indices = np.argsort(values)
+                sorted_values = values[sorted_indices]
+                sorted_weights = weights_arr[sorted_indices]
+
+                # Cumulative weight fractions
+                cumulative_weights = np.cumsum(sorted_weights)
+                total_weight = cumulative_weights[-1]
+                weight_fractions = cumulative_weights / total_weight
+
+                # Top 10% share
+                top_10_mask = weight_fractions > 0.9
+                self.top_10_share = float(
+                    np.sum(
+                        sorted_values[top_10_mask]
+                        * sorted_weights[top_10_mask]
+                    )
+                    / total_income
+                )
+
+                # Top 1% share
+                top_1_mask = weight_fractions > 0.99
+                self.top_1_share = float(
+                    np.sum(
+                        sorted_values[top_1_mask] * sorted_weights[top_1_mask]
+                    )
+                    / total_income
+                )
+
+                # Bottom 50% share
+                bottom_50_mask = weight_fractions <= 0.5
+                self.bottom_50_share = float(
+                    np.sum(
+                        sorted_values[bottom_50_mask]
+                        * sorted_weights[bottom_50_mask]
+                    )
+                    / total_income
+                )
+            else:
+                self.top_10_share = 0.0
+                self.top_1_share = 0.0
+                self.bottom_50_share = 0.0
+        else:
+            self.top_10_share = 0.0
+            self.top_1_share = 0.0
+            self.bottom_50_share = 0.0
+
+
+# Default income variables for each country
+UK_INEQUALITY_INCOME_VARIABLE = "equiv_hbai_household_net_income"
+US_INEQUALITY_INCOME_VARIABLE = "household_net_income"
+
+
+def calculate_uk_inequality(
+    simulation: Simulation,
+    income_variable: str = UK_INEQUALITY_INCOME_VARIABLE,
+    filter_variable: str | None = None,
+    filter_variable_eq: Any | None = None,
+    filter_variable_leq: Any | None = None,
+    filter_variable_geq: Any | None = None,
+) -> Inequality:
+    """Calculate inequality metrics for a UK simulation.
+
+    Args:
+        simulation: The simulation to analyse
+        income_variable: Income variable to use (default: equiv_hbai_household_net_income)
+        filter_variable: Optional variable to filter by
+        filter_variable_eq: Filter for exact match
+        filter_variable_leq: Filter for less than or equal
+        filter_variable_geq: Filter for greater than or equal
+
+    Returns:
+        Inequality object with Gini and income share metrics
+    """
+    inequality = Inequality(
+        simulation=simulation,
+        income_variable=income_variable,
+        entity="household",
+        filter_variable=filter_variable,
+        filter_variable_eq=filter_variable_eq,
+        filter_variable_leq=filter_variable_leq,
+        filter_variable_geq=filter_variable_geq,
+    )
+    inequality.run()
+    return inequality
+
+
+def calculate_us_inequality(
+    simulation: Simulation,
+    income_variable: str = US_INEQUALITY_INCOME_VARIABLE,
+    filter_variable: str | None = None,
+    filter_variable_eq: Any | None = None,
+    filter_variable_leq: Any | None = None,
+    filter_variable_geq: Any | None = None,
+) -> Inequality:
+    """Calculate inequality metrics for a US simulation.
+
+    Args:
+        simulation: The simulation to analyse
+        income_variable: Income variable to use (default: household_net_income)
+        filter_variable: Optional variable to filter by
+        filter_variable_eq: Filter for exact match
+        filter_variable_leq: Filter for less than or equal
+        filter_variable_geq: Filter for greater than or equal
+
+    Returns:
+        Inequality object with Gini and income share metrics
+    """
+    inequality = Inequality(
+        simulation=simulation,
+        income_variable=income_variable,
+        entity="household",
+        filter_variable=filter_variable,
+        filter_variable_eq=filter_variable_eq,
+        filter_variable_leq=filter_variable_leq,
+        filter_variable_geq=filter_variable_geq,
+    )
+    inequality.run()
+    return inequality

policyengine/outputs/poverty.py

@@ -0,0 +1,238 @@
+"""Poverty analysis output types."""
+
+from enum import Enum
+from typing import Any
+
+import pandas as pd
+from pydantic import ConfigDict
+
+from policyengine.core import Output, OutputCollection, Simulation
+
+
+class UKPovertyType(str, Enum):
+    """UK poverty measure types."""
+
+    ABSOLUTE_BHC = "absolute_bhc"
+    ABSOLUTE_AHC = "absolute_ahc"
+    RELATIVE_BHC = "relative_bhc"
+    RELATIVE_AHC = "relative_ahc"
+
+
+class USPovertyType(str, Enum):
+    """US poverty measure types."""
+
+    SPM = "spm"
+    SPM_DEEP = "spm_deep"
+
+
+# Mapping from poverty type to variable name
+UK_POVERTY_VARIABLES = {
+    UKPovertyType.ABSOLUTE_BHC: "in_poverty_bhc",
+    UKPovertyType.ABSOLUTE_AHC: "in_poverty_ahc",
+    UKPovertyType.RELATIVE_BHC: "in_relative_poverty_bhc",
+    UKPovertyType.RELATIVE_AHC: "in_relative_poverty_ahc",
+}
+
+US_POVERTY_VARIABLES = {
+    USPovertyType.SPM: "spm_unit_is_in_spm_poverty",
+    USPovertyType.SPM_DEEP: "spm_unit_is_in_deep_spm_poverty",
+}
+
+
+class Poverty(Output):
+    """Single poverty measure result - represents one database row.
+
+    This is a single-simulation output type that calculates poverty
+    headcount and rate for a given poverty measure, optionally filtered
+    by demographic variables.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    simulation: Simulation
+    poverty_variable: str
+    entity: str = "person"
+
+    # Optional demographic filters
+    filter_variable: str | None = None
+    filter_variable_eq: Any | None = None
+    filter_variable_leq: Any | None = None
+    filter_variable_geq: Any | None = None
+
+    # Results populated by run()
+    headcount: float | None = None
+    total_population: float | None = None
+    rate: float | None = None
+
+    def run(self):
+        """Calculate poverty headcount and rate."""
+        # Get poverty variable info
+        poverty_var_obj = (
+            self.simulation.tax_benefit_model_version.get_variable(
+                self.poverty_variable
+            )
+        )
+
+        # Get target entity data
+        target_entity = self.entity
+        data = getattr(self.simulation.output_dataset.data, target_entity)
+
+        # Map poverty variable to target entity if needed
+        if poverty_var_obj.entity != target_entity:
+            mapped = self.simulation.output_dataset.data.map_to_entity(
+                poverty_var_obj.entity,
+                target_entity,
+                columns=[self.poverty_variable],
+            )
+            poverty_series = mapped[self.poverty_variable]
+        else:
+            poverty_series = data[self.poverty_variable]
+
+        # Apply demographic filter if specified
+        if self.filter_variable is not None:
+            filter_var_obj = (
+                self.simulation.tax_benefit_model_version.get_variable(
+                    self.filter_variable
+                )
+            )
+
+            if filter_var_obj.entity != target_entity:
+                filter_mapped = (
+                    self.simulation.output_dataset.data.map_to_entity(
+                        filter_var_obj.entity,
+                        target_entity,
+                        columns=[self.filter_variable],
+                    )
+                )
+                filter_series = filter_mapped[self.filter_variable]
+            else:
+                filter_series = data[self.filter_variable]
+
+            # Build filter mask
+            mask = filter_series.notna()
+            if self.filter_variable_eq is not None:
+                mask &= filter_series == self.filter_variable_eq
+            if self.filter_variable_leq is not None:
+                mask &= filter_series <= self.filter_variable_leq
+            if self.filter_variable_geq is not None:
+                mask &= filter_series >= self.filter_variable_geq
+
+            # Apply mask
+            poverty_series = poverty_series[mask]
+
+        # Calculate results using weighted counts
+        self.headcount = float((poverty_series == True).sum())  # noqa: E712
+        self.total_population = float(poverty_series.count())
+        self.rate = (
+            self.headcount / self.total_population
+            if self.total_population > 0
+            else 0.0
+        )
+
+
+def calculate_uk_poverty_rates(
+    simulation: Simulation,
+    filter_variable: str | None = None,
+    filter_variable_eq: Any | None = None,
+    filter_variable_leq: Any | None = None,
+    filter_variable_geq: Any | None = None,
+) -> OutputCollection[Poverty]:
+    """Calculate all UK poverty rates for a simulation.
+
+    Args:
+        simulation: The simulation to analyse
+        filter_variable: Optional variable to filter by (e.g., "is_child")
+        filter_variable_eq: Filter for exact match
+        filter_variable_leq: Filter for less than or equal
+        filter_variable_geq: Filter for greater than or equal
+
+    Returns:
+        OutputCollection containing Poverty objects for each UK poverty type
+    """
+    results = []
+
+    for poverty_variable in UK_POVERTY_VARIABLES.values():
+        poverty = Poverty(
+            simulation=simulation,
+            poverty_variable=poverty_variable,
+            entity="person",
+            filter_variable=filter_variable,
+            filter_variable_eq=filter_variable_eq,
+            filter_variable_leq=filter_variable_leq,
+            filter_variable_geq=filter_variable_geq,
+        )
+        poverty.run()
+        results.append(poverty)
+
+    df = pd.DataFrame(
+        [
+            {
+                "simulation_id": r.simulation.id,
+                "poverty_variable": r.poverty_variable,
+                "filter_variable": r.filter_variable,
+                "filter_variable_eq": r.filter_variable_eq,
+                "filter_variable_leq": r.filter_variable_leq,
+                "filter_variable_geq": r.filter_variable_geq,
+                "headcount": r.headcount,
+                "total_population": r.total_population,
+                "rate": r.rate,
+            }
+            for r in results
+        ]
+    )
+
+    return OutputCollection(outputs=results, dataframe=df)
+
+
+def calculate_us_poverty_rates(
+    simulation: Simulation,
+    filter_variable: str | None = None,
+    filter_variable_eq: Any | None = None,
+    filter_variable_leq: Any | None = None,
+    filter_variable_geq: Any | None = None,
+) -> OutputCollection[Poverty]:
+    """Calculate all US poverty rates for a simulation.
+
+    Args:
+        simulation: The simulation to analyse
+        filter_variable: Optional variable to filter by (e.g., "is_child")
+        filter_variable_eq: Filter for exact match
+        filter_variable_leq: Filter for less than or equal
+        filter_variable_geq: Filter for greater than or equal
+
+    Returns:
+        OutputCollection containing Poverty objects for each US poverty type
+    """
+    results = []
+
+    for poverty_variable in US_POVERTY_VARIABLES.values():
+        poverty = Poverty(
+            simulation=simulation,
+            poverty_variable=poverty_variable,
+            entity="person",
+            filter_variable=filter_variable,
+            filter_variable_eq=filter_variable_eq,
+            filter_variable_leq=filter_variable_leq,
+            filter_variable_geq=filter_variable_geq,
+        )
+        poverty.run()
+        results.append(poverty)
+
+    df = pd.DataFrame(
+        [
+            {
+                "simulation_id": r.simulation.id,
+                "poverty_variable": r.poverty_variable,
+                "filter_variable": r.filter_variable,
+                "filter_variable_eq": r.filter_variable_eq,
+                "filter_variable_leq": r.filter_variable_leq,
+                "filter_variable_geq": r.filter_variable_geq,
+                "headcount": r.headcount,
+                "total_population": r.total_population,
+                "rate": r.rate,
+            }
+            for r in results
+        ]
+    )
+
+    return OutputCollection(outputs=results, dataframe=df)

policyengine/tax_benefit_models/uk/analysis.py

@@ -14,6 +14,14 @@ 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
@@ -175,6 +183,10 @@ class PolicyReformAnalysis(BaseModel):
 
     decile_impacts: OutputCollection[DecileImpact]
     programme_statistics: OutputCollection[ProgrammeStatistics]
+    baseline_poverty: OutputCollection[Poverty]
+    reform_poverty: OutputCollection[Poverty]
+    baseline_inequality: Inequality
+    reform_inequality: Inequality
 
 
 def economic_impact_analysis(
@@ -262,7 +274,19 @@ def economic_impact_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

@@ -13,6 +13,10 @@ from policyengine.core import (
     TaxBenefitModelVersion,
     Variable,
 )
+from policyengine.utils.parameter_labels import (
+    build_scale_lookup,
+    generate_label_for_parameter,
+)
 
 from .datasets import PolicyEngineUKDataset, UKYearData
 
@@ -146,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/analysis.py

@@ -14,6 +14,14 @@ 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
@@ -193,6 +201,10 @@ class PolicyReformAnalysis(BaseModel):
 
     decile_impacts: OutputCollection[DecileImpact]
     program_statistics: OutputCollection[ProgramStatistics]
+    baseline_poverty: OutputCollection[Poverty]
+    reform_poverty: OutputCollection[Poverty]
+    baseline_inequality: Inequality
+    reform_inequality: Inequality
 
 
 def economic_impact_analysis(
@@ -283,6 +295,19 @@ def economic_impact_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

@@ -13,6 +13,10 @@ from policyengine.core import (
     TaxBenefitModelVersion,
     Variable,
 )
+from policyengine.utils.parameter_labels import (
+    build_scale_lookup,
+    generate_label_for_parameter,
+)
 
 from .datasets import PolicyEngineUSDataset, USYearData
 
@@ -55,6 +59,8 @@ class PolicyEngineUSLatest(TaxBenefitModelVersion):
             "person_weight",
             # Demographics
             "age",
+            "is_child",
+            "is_adult",
             # Income
             "employment_income",
             # Benefits
@@ -77,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",
@@ -134,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

policyengine/utils/parameter_labels.py

@@ -0,0 +1,213 @@
+"""Utilities for generating human-readable labels for tax-benefit parameters."""
+
+import re
+
+
+def generate_label_for_parameter(param_node, system, scale_lookup):
+    """
+    Generate a label for a parameter that doesn't have one.
+
+    For breakdown parameters: Uses parent label + enum value
+    For bracket parameters: Uses scale label + bracket info
+
+    Args:
+        param_node: The CoreParameter object
+        system: The tax-benefit system (has variables and parameters)
+        scale_lookup: Dict mapping scale names to ParameterScale objects
+
+    Returns:
+        str or None: Generated label, or None if cannot generate
+    """
+    if param_node.metadata.get("label"):
+        return param_node.metadata.get("label")
+
+    param_name = param_node.name
+
+    if "[" in param_name:
+        return _generate_bracket_label(param_name, scale_lookup)
+
+    # Check for breakdown - either direct child or nested
+    breakdown_parent = _find_breakdown_parent(param_node)
+    if breakdown_parent:
+        return _generate_breakdown_label(param_node, system, breakdown_parent)
+
+    return None
+
+
+def _find_breakdown_parent(param_node):
+    """
+    Walk up the tree to find the nearest ancestor with breakdown metadata.
+
+    Args:
+        param_node: The CoreParameter object
+
+    Returns:
+        The breakdown parent node, or None if not found
+    """
+    current = param_node.parent
+    while current:
+        if current.metadata.get("breakdown"):
+            return current
+        current = getattr(current, "parent", None)
+    return None
+
+
+def _generate_breakdown_label(param_node, system, breakdown_parent=None):
+    """
+    Generate label for a breakdown parameter using enum values.
+
+    Handles both single-level and nested breakdowns by walking up to the
+    breakdown parent and collecting all dimension values.
+
+    Args:
+        param_node: The CoreParameter object
+        system: The tax-benefit system
+        breakdown_parent: The ancestor node with breakdown metadata (optional)
+
+    Returns:
+        str or None: Generated label, or None if cannot generate
+    """
+    # Find breakdown parent if not provided
+    if breakdown_parent is None:
+        breakdown_parent = _find_breakdown_parent(param_node)
+        if not breakdown_parent:
+            return None
+
+    parent_label = breakdown_parent.metadata.get("label")
+    if not parent_label:
+        return None
+
+    breakdown_vars = breakdown_parent.metadata.get("breakdown", [])
+    breakdown_labels = breakdown_parent.metadata.get("breakdown_labels", [])
+
+    # Collect dimension values from breakdown parent to param_node
+    dimension_values = _collect_dimension_values(
+        param_node, breakdown_parent
+    )
+
+    if not dimension_values:
+        return None
+
+    # Generate labels for each dimension
+    formatted_parts = []
+    for i, (dim_key, dim_value) in enumerate(dimension_values):
+        var_name = breakdown_vars[i] if i < len(breakdown_vars) else None
+        dim_label = breakdown_labels[i] if i < len(breakdown_labels) else None
+
+        formatted_value = _format_dimension_value(
+            dim_value, var_name, dim_label, system
+        )
+        formatted_parts.append(formatted_value)
+
+    return f"{parent_label} ({', '.join(formatted_parts)})"
+
+
+def _collect_dimension_values(param_node, breakdown_parent):
+    """
+    Collect dimension keys and values from breakdown parent to param_node.
+
+    Args:
+        param_node: The CoreParameter object
+        breakdown_parent: The ancestor node with breakdown metadata
+
+    Returns:
+        list of (dimension_key, value) tuples, ordered from parent to child
+    """
+    # Build path from param_node up to breakdown_parent
+    path = []
+    current = param_node
+    while current and current != breakdown_parent:
+        path.append(current)
+        current = getattr(current, "parent", None)
+
+    # Reverse to get parent-to-child order
+    path.reverse()
+
+    # Extract dimension values
+    dimension_values = []
+    for i, node in enumerate(path):
+        key = node.name.split(".")[-1]
+        dimension_values.append((i, key))
+
+    return dimension_values
+
+
+def _format_dimension_value(value, var_name, dim_label, system):
+    """
+    Format a single dimension value with semantic label if available.
+
+    Args:
+        value: The raw dimension value (e.g., "SINGLE", "1", "CA")
+        var_name: The breakdown variable name (e.g., "filing_status", "range(1, 9)")
+        dim_label: The human-readable label for this dimension (e.g., "Household size")
+        system: The tax-benefit system
+
+    Returns:
+        str: Formatted dimension value
+    """
+    # First, try to get enum display value
+    if var_name and isinstance(var_name, str) and not var_name.startswith("range(") and not var_name.startswith("list("):
+        var = system.variables.get(var_name)
+        if var and hasattr(var, "possible_values") and var.possible_values:
+            try:
+                enum_value = var.possible_values[value].value
+                return str(enum_value)
+            except (KeyError, AttributeError):
+                pass
+
+    # For range() dimensions or when no enum found, use breakdown_label if available
+    if dim_label:
+        return f"{dim_label} {value}"
+
+    return value
+
+
+def _generate_bracket_label(param_name, scale_lookup):
+    """Generate label for a bracket parameter."""
+    match = re.match(r"^(.+)\[(\d+)\]\.(\w+)$", param_name)
+    if not match:
+        return None
+
+    scale_name = match.group(1)
+    bracket_index = int(match.group(2))
+    field_name = match.group(3)
+
+    scale = scale_lookup.get(scale_name)
+    if not scale:
+        return None
+
+    scale_label = scale.metadata.get("label")
+    scale_type = scale.metadata.get("type", "")
+
+    if not scale_label:
+        return None
+
+    bracket_num = bracket_index + 1
+
+    if scale_type in ("marginal_rate", "marginal_amount"):
+        bracket_desc = f"bracket {bracket_num}"
+    elif scale_type == "single_amount":
+        bracket_desc = f"tier {bracket_num}"
+    else:
+        bracket_desc = f"bracket {bracket_num}"
+
+    return f"{scale_label} ({bracket_desc} {field_name})"
+
+
+def build_scale_lookup(system):
+    """
+    Build a lookup dict mapping scale names to ParameterScale objects.
+
+    Args:
+        system: The tax-benefit system
+
+    Returns:
+        dict: Mapping of scale name -> ParameterScale object
+    """
+    from policyengine_core.parameters import ParameterScale
+
+    return {
+        p.name: p
+        for p in system.parameters.get_descendants()
+        if isinstance(p, ParameterScale)
+    }

{policyengine-3.1.15.dist-info → policyengine-3.1.16.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: policyengine
-Version: 3.1.15
+Version: 3.1.16
 Summary: A package to conduct policy analysis using PolicyEngine tax-benefit models.
 Author-email: PolicyEngine <hello@policyengine.org>
 License:                     GNU AFFERO GENERAL PUBLIC LICENSE
@@ -670,15 +670,15 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: pandas>=2.0.0
-Requires-Dist: microdf_python
+Requires-Dist: microdf_python>=1.2.1
 Requires-Dist: plotly>=5.0.0
 Requires-Dist: requests>=2.31.0
 Requires-Dist: psutil>=5.9.0
 Provides-Extra: uk
-Requires-Dist: policyengine_core>=3.10; extra == "uk"
+Requires-Dist: policyengine_core>=3.23.6; extra == "uk"
 Requires-Dist: policyengine-uk>=2.51.0; extra == "uk"
 Provides-Extra: us
-Requires-Dist: policyengine_core>=3.10; extra == "us"
+Requires-Dist: policyengine_core>=3.23.6; extra == "us"
 Requires-Dist: policyengine-us>=1.213.1; extra == "us"
 Provides-Extra: dev
 Requires-Dist: black; extra == "dev"
@@ -691,7 +691,7 @@ Requires-Dist: itables; extra == "dev"
 Requires-Dist: build; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.26.0; extra == "dev"
 Requires-Dist: ruff>=0.5.0; extra == "dev"
-Requires-Dist: policyengine_core>=3.10; extra == "dev"
+Requires-Dist: policyengine_core>=3.23.6; extra == "dev"
 Requires-Dist: policyengine-uk>=2.51.0; extra == "dev"
 Requires-Dist: policyengine-us>=1.213.1; extra == "dev"
 Dynamic: license-file

{policyengine-3.1.15.dist-info → policyengine-3.1.16.dist-info}/RECORD

@@ -1,5 +1,5 @@
 policyengine/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-policyengine/__pycache__/__init__.cpython-313.pyc,sha256=MPybDS-iHQgTbwpR0cZQ_5__Xexio_9dqsdZDdfQBtQ,175
+policyengine/__pycache__/__init__.cpython-313.pyc,sha256=pXlfNHK9qaW6hIe40yAYhaHxkBtl6c_uvAIzt-n6hzM,175
 policyengine/core/__init__.py,sha256=KBVhkqzkvjWLDDwk96vquQKL63ZFuLen5AzBOBnO9pg,912
 policyengine/core/cache.py,sha256=DcVVFaCt7k9PmqwlhXoNDMtJ8sF4neYP1uRqWik5QYg,1812
 policyengine/core/dataset.py,sha256=iJr9-J6w11uMRYy3EEJO9Gveku1m71AA1yzeo-0SiCs,16094
@@ -13,28 +13,31 @@ policyengine/core/simulation.py,sha256=h6QbFt3uEvyfRXRVbSFBlrOd6Ze03OeZkwX9oElmO
 policyengine/core/tax_benefit_model.py,sha256=2Yc1RlQrUG7djDMZbJOQH4Ns86_lOnLeISCGR4-9zMo,176
 policyengine/core/tax_benefit_model_version.py,sha256=iVzEKWzQxoPVicwxcqo9Fy8PfVX07faBvyL9NhVIjuU,3212
 policyengine/core/variable.py,sha256=AjSImORlRkh05xhYxyeT6GFMOfViRzYg0qRQAIj-mxo,350
-policyengine/outputs/__init__.py,sha256=IJUmLP0Og41VrwiqhJF-a9-3fIb4nlXpS7uFuVCINIs,515
+policyengine/outputs/__init__.py,sha256=fcqkl1iK4lMpkdS0OBj3wWGAd1zZjc6IiJ-nrXy9VU8,1254
 policyengine/outputs/aggregate.py,sha256=exI-U04OF5kVf2BBYV6sf8VldIWnT_IzxgkBs5wtnCw,4846
 policyengine/outputs/change_aggregate.py,sha256=tK4K87YlByKikqFaB7OHyh1SqAuGtUnLL7cSF_EhrOs,7373
 policyengine/outputs/decile_impact.py,sha256=f8nR3pea8_qDuQ-M6kaKnVKxbGnfL0IzpRfFTdi7TqA,5522
+policyengine/outputs/inequality.py,sha256=W_yc9Ibeavx7KA3reJTFArK3fR1kf_YFV0jAaC121w0,9356
+policyengine/outputs/poverty.py,sha256=h8dHj-S8YeEQ6CXqmWje3gEz30H8jgE-gmXQ0NoJTUU,7866
 policyengine/tax_benefit_models/uk.py,sha256=HzAG_dORmsj1NJ9pd9WrqwgZPe9DUDrZ1wV5LuVCKAg,950
 policyengine/tax_benefit_models/us.py,sha256=G51dAmHo8NJLb2mnbne6iO5eNaatCGUd_2unvawwF84,946
 policyengine/tax_benefit_models/uk/__init__.py,sha256=StjVt4mV0n2QxlM_2oCp_OqHJu7eyWNbdPndezC7ve0,1294
-policyengine/tax_benefit_models/uk/analysis.py,sha256=iw34SERGdjCO4GSnimOZwXRnzSV7nutoilkVxHaI5WM,8627
+policyengine/tax_benefit_models/uk/analysis.py,sha256=uPQt2EI2y6obibLfZfV-fHuN-FVzvUVUgeZY9kKSB5E,9527
 policyengine/tax_benefit_models/uk/datasets.py,sha256=N8pMrlhQFec_cbgvVf5HE2owU14VF1i8-ZUwZYBSeio,9043
-policyengine/tax_benefit_models/uk/model.py,sha256=woVnq5-HRt3EzRqvHr9TFMhWD06CHxc1H0zlo_LqEJ4,8796
+policyengine/tax_benefit_models/uk/model.py,sha256=8byY9n8rEWA2DxG3uq7N3SogZWvl_o9JqKcL0xfQ6fk,8984
 policyengine/tax_benefit_models/uk/outputs.py,sha256=2mYLwQW4QNvrOHtHfm_ACqE9gbmuLxvcCyldRU46s0o,3543
 policyengine/tax_benefit_models/us/__init__.py,sha256=0RtqCl01j-Z_T4i9LITBSePegO97gZ4IIYqt-nsv2O0,1290
-policyengine/tax_benefit_models/us/analysis.py,sha256=y-M4QAUyp44-Y9fbkKQ6KMbS9qS9eHju3D5QG3iJHf8,9435
+policyengine/tax_benefit_models/us/analysis.py,sha256=qJ9pZjyEY1xS7HCpT5-AETdPTtd-k7hWePxJz-NpXDE,10344
 policyengine/tax_benefit_models/us/datasets.py,sha256=OWqiYK8TWwdYP2qgUNIv6nIpqN5FVtyd8aYkVMUkAno,14757
-policyengine/tax_benefit_models/us/model.py,sha256=p5s8LHyGqkkVoJU1_7CGnwY8-KgXo_-3RSPuG9NO7Ww,15572
+policyengine/tax_benefit_models/us/model.py,sha256=t8YPeiEzOskzSnEIwCSZFPvdxFubtLTAUPkTEcG_JN8,15945
 policyengine/tax_benefit_models/us/outputs.py,sha256=GT8Eur8DfB9cPQRbSljEl9RpKSNHW80Fq_CBXCybvIU,3519
-policyengine/utils/__init__.py,sha256=1X-VYAWLyB9A0YRHwsGWrqQHns1WfeZ7ISC6DMU5myM,140
+policyengine/utils/__init__.py,sha256=qq9ElvVnZtmM0CAjbkJV_QFBHz3bAjOSCTJGqx29F0c,311
 policyengine/utils/dates.py,sha256=HnAqyl8S8EOYp8ibsnMTmECYoDWCSqwL-7A2_qKgxSc,1510
+policyengine/utils/parameter_labels.py,sha256=_QTCTOjOdaW-pPVOsYMn7VyN-75QTD6IILfH-6oAd7U,6549
 policyengine/utils/parametric_reforms.py,sha256=4P3U39-4pYTU4BN6JjgmVLUkCkBhRfZJ6UIWTlsjyQE,1155
 policyengine/utils/plotting.py,sha256=ZAzTWz38vIaW0c3Nt4Un1kfrNoXLyHCDd1pEJIlsRg4,5335
-policyengine-3.1.15.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
-policyengine-3.1.15.dist-info/METADATA,sha256=FkFNAnnQvw5prYSAd-CZeNxAroQ7p1C7vF8Re1q2fwo,45919
-policyengine-3.1.15.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-policyengine-3.1.15.dist-info/top_level.txt,sha256=_23UPobfkneHQkpJ0e0OmDJfhCUfoXj_F2sTckCGOH4,13
-policyengine-3.1.15.dist-info/RECORD,,
+policyengine-3.1.16.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
+policyengine-3.1.16.dist-info/METADATA,sha256=rmdahoK--THkMMXjckeYhFpagrIk6w_oANMFgTE9rts,45932
+policyengine-3.1.16.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+policyengine-3.1.16.dist-info/top_level.txt,sha256=_23UPobfkneHQkpJ0e0OmDJfhCUfoXj_F2sTckCGOH4,13
+policyengine-3.1.16.dist-info/RECORD,,

{policyengine-3.1.15.dist-info → policyengine-3.1.16.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.1)
 Root-Is-Purelib: true
 Tag: py3-none-any