policyengine-uk 2.35.0__py3-none-any.whl

policyengine_uk/tests/microsimulation/README.md

@@ -0,0 +1,126 @@
+# PolicyEngine UK reform impact tests
+
+This directory contains automated tests to monitor when model changes affect the fiscal impacts of policy reforms. It helps ensure that updates to the PolicyEngine UK model don't unexpectedly change reform outcomes.
+
+## Overview
+
+The testing framework consists of three main components:
+
+1. **reforms_config.yaml** - Configuration file containing reform definitions and their expected impacts
+2. **test_reform_impacts.py** - Pytest test suite that verifies reforms produce expected impacts
+3. **update_reform_impacts.py** - Script to update expected impacts when model changes are intentional
+
+## Quick start
+
+### Running tests
+
+To check if current model produces expected reform impacts:
+
+```bash
+pytest test_reform_impacts.py
+```
+
+To run with more detail:
+
+```bash
+pytest test_reform_impacts.py -v
+```
+
+### Updating expected impacts
+
+When model changes are intentional and you need to update the baseline expectations:
+
+```bash
+# Preview changes without updating
+python update_reform_impacts.py --dry-run
+
+# Update the configuration file
+python update_reform_impacts.py
+
+# Update with detailed output
+python update_reform_impacts.py --verbose
+```
+
+## Configuration file structure
+
+The `reforms_config.yaml` file defines each reform with:
+
+```yaml
+reforms:
+  - name: "Description of the reform"
+    expected_impact: 10.5  # Fiscal impact in billions
+    parameters:
+      "gov.some.parameter": 0.25
+      "gov.another.parameter": 1000
+```
+
+## Workflow
+
+### Regular testing
+
+1. Run `pytest policyengine_uk/tests/microsimulation/test_reform_impacts.py` as part of your CI/CD pipeline
+2. Tests will fail if any reform impact differs by more than £0.1 billion from expected
+3. This catches unintended consequences of model changes
+
+### After intentional model changes
+
+1. Run `python policyengine_uk/tests/microsimulation/update_reform_impacts.py --dry-run` to preview impact changes
+2. Review the changes to ensure they're expected
+3. Run `python policyengine_uk/tests/microsimulation/update_reform_impacts.py` to update the configuration
+4. Commit both the model changes and updated `reforms_config.yaml`
+
+### Adding new reforms
+
+1. Add a new entry to `reforms_config.yaml`:
+   ```yaml
+   - name: "Your new reform description"
+     expected_impact: 0.0  # Initial placeholder
+     parameters:
+       "gov.parameter.to.change": new_value
+   ```
+
+2. Run `python policyengine_uk/tests/microsimulation/update_reform_impacts.py` to calculate the actual impact
+3. Run `pytest policyengine_uk/tests/microsimulation/test_reform_impacts.py` to verify the test passes
+
+## Test tolerance
+
+Tests allow for a tolerance of £0.1 billion in fiscal impacts. This accounts for:
+- Minor numerical differences in calculations
+- Small variations from microsimulation sampling
+
+If you need to adjust this tolerance, modify the assertion in `test_reform_impacts.py`.
+
+## Troubleshooting
+
+### Tests failing after model update
+
+1. Check if the changes are expected by running the update script with `--dry-run`
+2. If changes are expected, update the configuration file
+3. If changes are unexpected, investigate the model modifications
+
+### Import errors
+
+Ensure you have the required dependencies:
+```bash
+pip install policyengine-uk pytest pyyaml
+```
+
+### Configuration file not found
+
+The tests expect `reforms_config.yaml` to be in the same directory as the test file. You can specify a different path:
+
+```bash
+python update_reform_impacts.py --config /path/to/reforms_config.yaml
+```
+
+## Example reforms
+
+The configuration includes various UK tax and benefit reforms:
+- Income tax rate changes (basic, higher, additional rates)
+- Personal allowance adjustments
+- National Insurance contribution rates
+- VAT rate changes
+- Universal Credit taper rate modifications
+- Child benefit amount changes
+
+Each reform's fiscal impact is measured as the change in government balance (in billions) for the year 2029.

policyengine_uk/tests/microsimulation/reforms_config.yaml

@@ -0,0 +1,33 @@
+reforms:
+- name: Raise basic rate by 1pp
+  expected_impact: 7.8
+  parameters:
+    gov.hmrc.income_tax.rates.uk[0].rate: 0.21
+- name: Raise higher rate by 1pp
+  expected_impact: 5.0
+  parameters:
+    gov.hmrc.income_tax.rates.uk[1].rate: 0.42
+- name: Raise personal allowance by ~800GBP/year
+  expected_impact: 0.8
+  parameters:
+    gov.hmrc.income_tax.allowances.personal_allowance.amount: 13000
+- name: Raise child benefit by 25GBP/week per additional child
+  expected_impact: -1.3
+  parameters:
+    gov.hmrc.child_benefit.amount.additional: 25
+- name: Reduce Universal Credit taper rate to 20%
+  expected_impact: -38.2
+  parameters:
+    gov.dwp.universal_credit.means_test.reduction_rate: 0.2
+- name: Raise Class 1 main employee NICs rate to 10%
+  expected_impact: 12.4
+  parameters:
+    gov.hmrc.national_insurance.class_1.rates.employee.main: 0.1
+- name: Raise VAT standard rate by 2pp
+  expected_impact: 19.5
+  parameters:
+    gov.hmrc.vat.standard_rate: 0.22
+- name: Raise additional rate by 3pp
+  expected_impact: 4.5
+  parameters:
+    gov.hmrc.income_tax.rates.uk[2].rate: 0.48

policyengine_uk/tests/microsimulation/test_reform_impacts.py

@@ -0,0 +1,83 @@
+"""
+Test suite for PolicyEngine UK reform fiscal impacts.
+This file tests that model changes don't unexpectedly change reform impacts.
+"""
+
+import pytest
+import yaml
+from pathlib import Path
+from policyengine_uk import Microsimulation
+
+
+# Load configuration from YAML file
+config_path = Path(__file__).parent / "reforms_config.yaml"
+with open(config_path, "r") as f:
+    config = yaml.safe_load(f)
+
+reforms_data = config["reforms"]
+
+# Initialize baseline simulation
+baseline = Microsimulation()
+
+
+def get_fiscal_impact(reform: dict) -> float:
+    """
+    Calculate the fiscal impact of a reform in billions.
+
+    Args:
+        reform: Dictionary of reform parameters
+
+    Returns:
+        Fiscal impact in billions (positive = revenue increase)
+    """
+    baseline_revenue = baseline.calculate("gov_balance", 2029).sum()
+    reform_simulation = Microsimulation(reform=reform)
+    reform_revenue = reform_simulation.calculate("gov_balance", 2029).sum()
+    return (reform_revenue - baseline_revenue) / 1e9
+
+
+# Extract test parameters from configuration
+test_params = [
+    (reform["parameters"], reform["name"], reform["expected_impact"])
+    for reform in reforms_data
+]
+
+reform_names = [reform["name"] for reform in reforms_data]
+
+
+@pytest.mark.parametrize(
+    "reform, reform_name, expected_impact",
+    test_params,
+    ids=reform_names,
+)
+def test_reform_fiscal_impacts(reform, reform_name, expected_impact):
+    """Test that each reform produces the expected fiscal impact."""
+    impact = get_fiscal_impact(reform)
+
+    # Allow for small numerical differences (0.1 billion tolerance)
+    assert (
+        abs(impact - expected_impact) < 0.1
+    ), f"Impact for {reform_name} is {impact:.1f} billion, expected {expected_impact:.1f} billion"
+
+
+def test_config_file_exists():
+    """Test that the configuration file exists and is valid."""
+    assert config_path.exists(), "reforms_config.yaml file not found"
+    assert "reforms" in config, "reforms key not found in configuration"
+    assert len(config["reforms"]) > 0, "No reforms defined in configuration"
+
+
+def test_all_reforms_have_required_fields():
+    """Test that all reforms have the required fields."""
+    required_fields = ["name", "expected_impact", "parameters"]
+
+    for i, reform in enumerate(reforms_data):
+        for field in required_fields:
+            assert (
+                field in reform
+            ), f"Reform {i} missing required field: {field}"
+
+        assert isinstance(
+            reform["parameters"], dict
+        ), f"Reform {i} parameters must be a dictionary"
+        assert len(reform["parameters"]) > 0, f"Reform {i} has no parameters"

policyengine_uk/tests/microsimulation/test_validity.py

@@ -0,0 +1,21 @@
+from policyengine import Simulation
+import pytest
+
+YEARS = range(2024, 2026)
+
+
+@pytest.mark.parametrize("year", YEARS)
+def test_not_nan(year):
+    baseline = Simulation(scope="macro", country="uk")
+    baseline = baseline.baseline_simulation
+    for variable in baseline.tax_benefit_system.variables:
+        requires_computation_after = baseline.tax_benefit_system.variables[
+            variable
+        ].requires_computation_after
+        if requires_computation_after:
+            continue
+        if (
+            baseline.tax_benefit_system.variables[variable].definition_period
+            == "year"
+        ):
+            assert ~baseline.calculate(variable, period=year).isna().any()

policyengine_uk/tests/microsimulation/update_reform_impacts.py

@@ -0,0 +1,158 @@
+"""
+Script to update the expected impacts in reforms_config.yaml with current model values.
+This should be run when you want to update the baseline expectations after model changes.
+"""
+
+import yaml
+from pathlib import Path
+from policyengine_uk import Microsimulation
+import argparse
+from datetime import datetime
+
+baseline = Microsimulation()
+
+
+def get_fiscal_impact(reform: dict) -> float:
+    """
+    Calculate the fiscal impact of a reform in billions.
+
+    Args:
+        reform: Dictionary of reform parameters
+
+    Returns:
+        Fiscal impact in billions (positive = revenue increase)
+    """
+
+    baseline_revenue = baseline.calculate("gov_balance", 2029).sum()
+    reform_simulation = Microsimulation(reform=reform)
+    reform_revenue = reform_simulation.calculate("gov_balance", 2029).sum()
+    return float((reform_revenue - baseline_revenue) / 1e9)
+
+
+def update_impacts(
+    config_path: Path, dry_run: bool = False, verbose: bool = True
+):
+    """
+    Update the expected impacts in the configuration file with current model values.
+
+    Args:
+        config_path: Path to the reforms_config.yaml file
+        dry_run: If True, show changes without writing to file
+        verbose: If True, show detailed output
+    """
+    # Load current configuration
+    with open(config_path, "r") as f:
+        config = yaml.safe_load(f)
+
+    if verbose:
+        print(f"Loaded configuration from {config_path}")
+        print(f"Found {len(config['reforms'])} reforms to update\n")
+
+    # Track changes
+    changes = []
+
+    # Update each reform's expected impact
+    for reform in config["reforms"]:
+        print(f"Processing reform: {reform['name']}") if verbose else None
+        old_impact = reform["expected_impact"]
+        new_impact = round(get_fiscal_impact(reform["parameters"]), 1)
+
+        if (
+            abs(old_impact - new_impact) > 0.01
+        ):  # Only record meaningful changes
+            changes.append(
+                {
+                    "name": reform["name"],
+                    "old": old_impact,
+                    "new": new_impact,
+                    "diff": new_impact - old_impact,
+                }
+            )
+
+        reform["expected_impact"] = new_impact
+
+        if verbose:
+            print(f"Reform: {reform['name']}")
+            print(f"  Old impact: {old_impact:.1f} billion")
+            print(f"  New impact: {new_impact:.1f} billion")
+            if abs(old_impact - new_impact) > 0.01:
+                print(f"  Change: {new_impact - old_impact:+.1f} billion")
+            print()
+
+    # Show summary of changes
+    if changes:
+        print("\nSummary of changes:")
+        print("-" * 70)
+        for change in changes:
+            print(
+                f"{change['name']:<50} {change['old']:>6.1f} → {change['new']:>6.1f} ({change['diff']:+.1f})"
+            )
+        print("-" * 70)
+        print(f"Total changes: {len(changes)}")
+    else:
+        print("\nNo significant changes detected.")
+
+    # Write updated configuration
+    if not dry_run:
+        # Create backup
+        backup_path = config_path.with_suffix(
+            f".yaml.backup_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+        )
+        with open(backup_path, "w") as f:
+            with open(config_path, "r") as original:
+                f.write(original.read())
+
+        # Remove backup
+        backup_path.unlink(missing_ok=True)
+
+        # Write updated config
+        with open(config_path, "w") as f:
+            yaml.dump(config, f, default_flow_style=False, sort_keys=False)
+
+        print(f"\nConfiguration updated successfully!")
+        print(f"Backup saved to: {backup_path}")
+    else:
+        print("\nDry run - no changes written to file.")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Update reform impact expectations with current model values"
+    )
+    parser.add_argument(
+        "--config",
+        type=Path,
+        default=Path(
+            "policyengine_uk/tests/microsimulation/reforms_config.yaml"
+        ),
+        help="Path to the reforms configuration file (default: reforms_config.yaml)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be changed without actually updating the file",
+    )
+    parser.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        default=True,
+        help="Show detailed output for each reform",
+    )
+
+    args = parser.parse_args()
+
+    if not args.config.exists():
+        print(f"Error: Configuration file '{args.config}' not found!")
+        return 1
+
+    try:
+        update_impacts(args.config, dry_run=args.dry_run, verbose=args.verbose)
+        return 0
+    except Exception as e:
+        print(f"Error updating impacts: {e}")
+        return 1
+
+
+if __name__ == "__main__":
+    exit(main())

policyengine_uk/tests/policy/baseline/consumption/rent/benunit_is_rent_liable.yaml

@@ -0,0 +1,13 @@
+- name: Liable
+  period: 2024
+  input:
+    benunit_rent: 1
+  output:
+    benunit_is_rent_liable: true
+
+- name: Not liable
+  period: 2024
+  input:
+    benunit_rent: 0
+  output:
+    benunit_is_rent_liable: false

policyengine_uk/tests/policy/baseline/consumption/rent/rent.yaml

@@ -0,0 +1,6 @@
+- name: Benefit unit rent is summed from personal rent
+  period: 2022
+  input:
+    personal_rent: 1
+  output:
+    benunit_rent: 1

policyengine_uk/tests/policy/baseline/contrib/labour/attends_private_school.yaml

@@ -0,0 +1,41 @@
+- name: Attends private school returns False when attendance rate is 0%
+  period: 2024
+  input:
+    gov.simulation.private_school_vat.private_school_attendance_rate.100: 0
+    gov.simulation.private_school_vat.private_school_attendance_rate.95: 0
+    people:
+      adult: 
+        age: 25
+      child:
+        age: 10
+    households:
+      household:
+        household_weight: 0.001
+        household_market_income: 1_000_000_000
+        household_benefits: 0
+        members: [
+          adult,
+          child
+        ]
+  output:
+    attends_private_school: [False, False]
+
+- name: Attends private school successfully returns False when household weights are 0
+  period: 2024
+  input:
+    people:
+      adult: 
+        age: 25
+      child:
+        age: 10
+    households:
+      household:
+        household_weight: 0
+        household_market_income: 1_000_000_000
+        household_benefits: 0
+        members: [
+          adult,
+          child
+        ]
+  output:
+    attends_private_school: [False, False]

policyengine_uk/tests/policy/baseline/contrib/labour/private_school_vat.yaml

@@ -0,0 +1,65 @@
+- name: Returns 0 when no children
+  period: 2024
+  input:
+    # Set private school VAT rate to 25% to ensure correct testing
+    gov.contrib.labour.private_school_vat: 0.25
+    people:
+      adult: 
+        age: 25
+    households:
+      household:
+        members: [
+          adult,
+        ]
+  output:
+    private_school_vat: 0
+
+- name: Returns correctly with one child
+  period: 2024
+  input:
+    # Set private school VAT rate to 25% to ensure correct testing
+    gov.contrib.labour.private_school_vat: 0.25
+    # Override other default settings for easier testing
+    gov.simulation.private_school_vat.private_school_vat_basis: 1
+    gov.simulation.private_school_vat.private_school_fees: 10_000
+    people:
+      adult: 
+        age: 25
+      child:
+        age: 10
+        attends_private_school: True
+    households:
+      household:
+        members: [
+          adult,
+          child
+        ]
+  output:
+    private_school_vat: 2_500
+
+- name: Returns correct value with 2+ children
+  period: 2024
+  input:
+    # Set private school VAT rate to 25% to ensure correct testing
+    gov.contrib.labour.private_school_vat: 0.25
+    # Override other default settings for easier testing
+    gov.simulation.private_school_vat.private_school_vat_basis: 1
+    gov.simulation.private_school_vat.private_school_fees: 10_000
+    people:
+      adult: 
+        age: 25
+      child1:
+        age: 10
+        attends_private_school: True
+      child2:
+        age: 12
+        attends_private_school: True
+    households:
+      household:
+        members: [
+          adult,
+          child1,
+          child2
+        ]
+  output:
+    private_school_vat: 5_000

policyengine_uk/tests/policy/baseline/contrib/ubi_center/basic_income/bi_maximum.yaml

@@ -0,0 +1,16 @@
+- name: £100 per person.
+  period: 2022
+  input:
+    gov.contrib.ubi_center.basic_income.amount.flat: 100
+  output:
+    bi_maximum: 5_200
+
+- name: £90 per adult, £50 per child, plus £10 for everyone. Adult.
+  period: 2022
+  input:
+    gov.contrib.ubi_center.basic_income.amount.flat: 10
+    gov.contrib.ubi_center.basic_income.amount.by_age.working_age: 90
+    gov.contrib.ubi_center.basic_income.amount.by_age.child: 50
+    age: 18
+  output:
+    bi_maximum: 5_200

policyengine_uk/tests/policy/baseline/demographic/benunit.yaml

@@ -0,0 +1,38 @@
+- name: Family type and relation type
+  period: 2020
+  absolute_error_margin: 0
+  input:
+    people:
+      adult:
+        age: 30
+      child:
+        age: 14
+    benunits:
+      benunit:
+        members: [adult, child]
+  output:
+    family_type: "LONE_PARENT"
+    relation_type: "SINGLE"
+- name: Age variables
+  period: 2020
+  absolute_error_margin: 0
+  input:
+    people:
+      adult_1:
+        age: 34
+      adult_2:
+        age: 35
+      child_1:
+        age: 3
+      child_2:
+        age: 4
+    benunits:
+      benunit:
+        members: [adult_1, adult_2, child_1, child_2]
+  output:
+    eldest_adult_age: 35
+    youngest_adult_age: 34
+    eldest_child_age: 4
+    youngest_child_age: 3
+    num_children: 2
+    num_adults: 2

policyengine_uk/tests/policy/baseline/demographic/household.yaml

@@ -0,0 +1,14 @@
+- name: Country from region - England
+  period: 2020
+  absolute_error_margin: 0
+  input:
+    region: "LONDON"
+  output:
+    country: "ENGLAND"
+- name: Country from region - Scotland
+  period: 2020
+  absolute_error_margin: 0
+  input:
+    region: "SCOTLAND"
+  output:
+    country: "SCOTLAND"

policyengine_uk/tests/policy/baseline/demographic/person.yaml

@@ -0,0 +1,21 @@
+- name: Over 16
+  period: 2020
+  absolute_error_margin: 0
+  input:
+    age: 64
+  output:
+    over_16: true
+- name: Under 16
+  period: 2020
+  absolute_error_margin: 0
+  input:
+    age: 15
+  output:
+    over_16: false
+- name: Birth year
+  period: 2020
+  absolute_error_margin: 0
+  input:
+    age: 5
+  output:
+    birth_year: 2015

policyengine_uk/tests/policy/baseline/finance/benefit/care.yaml

@@ -0,0 +1,9 @@
+- name: Carer from CA
+  period: 2020
+  absolute_error_margin: 40
+  input:
+    carers_allowance: 1 * 52
+  output:
+    is_carer_for_benefits: true
+    num_carers: 1
+    carer_premium: 37.5 * 52

policyengine_uk/tests/policy/baseline/finance/benefit/family/LHA.yaml

@@ -0,0 +1,26 @@
+- name: BRMA default value
+  period: 2020
+  absolute_error_margin: 20
+  input:
+    age: 18
+    LHA_category: C
+  output:
+    brma: MAIDSTONE
+    BRMA_LHA_rate: 9_771
+- name: BRMA inputs
+  period: 2020
+  absolute_error_margin: 0
+  input:
+    brma: GUILDFORD
+  output:
+    brma: GUILDFORD
+- name: BRMA and category
+  period: 2020
+  absolute_error_margin: 20
+  input:
+    brma: GUILDFORD
+    LHA_category: C
+  output:
+    brma: GUILDFORD
+    LHA_category: C
+    BRMA_LHA_rate: 13_164