policyengine.py for UK tax and benefit analysis

pip install "policyengine[uk]"

import policyengine as pe

result = pe.uk.calculate_household(
    # One dict per person - keys are any person-level variable on the UK model.
    people=[
        {"age": 35, "employment_income": 30000},  # primary earner
        {"age": 33},                              # partner
        {"age": 8},                               # dependent
        {"age": 5},                               # dependent
    ],
    # Benefit unit (adult(s) + dependent children). Empty dict uses defaults.
    benunit={},
    # Household inputs.
    household={"rent": 12000, "region": "NORTH_WEST"},
    # Year determines which parameter values apply.
    year=2026,
)

# Attribute access on the typed result. Group entities (benunit, household)
# are single objects; person sections are lists (result.person[0]).

print(f"Net income: £{result.household.hbai_household_net_income:,.0f}")
print(f"Child benefit: £{result.benunit.child_benefit:,.0f}")
print(f"Universal credit: £{result.benunit.universal_credit:,.0f}")

Net income: £43,338
Child benefit: £2,328
Universal credit: £15,639

import policyengine as pe
from policyengine.core import Simulation

year = 2026
# ensure_datasets downloads from HuggingFace on first run, caches locally,
# and returns a {"<stem>_<year>": Dataset} dict.
datasets = pe.uk.ensure_datasets(
    datasets=["hf://policyengine/policyengine-uk-data/enhanced_frs_2023_24.h5"],
    years=[year],
    data_folder="./data",
)
dataset = datasets[f"enhanced_frs_2023_24_{year}"]

# pe.uk.model is the country model version pinned by this policyengine.py release.
simulation = Simulation(dataset=dataset, tax_benefit_model_version=pe.uk.model)
# ensure() loads a cached run if available, otherwise runs and caches.
simulation.ensure()

output = simulation.output_dataset.data
print(output.household[["household_net_income", "household_tax"]].head())

       weight  household_net_income  household_tax
0  808.091309          22852.031250    3373.469727
1  166.748154          29921.960938    4778.160645
2  467.949768         102740.921875   74814.242188
3  181.570221          33344.003906    5540.328613
4  515.411926          34987.277344    5446.388184

# Old mental model:
#   from policyengine_uk import Microsimulation
#   sim = Microsimulation(dataset=...)
#
# New policyengine.py mental model:
#   import policyengine as pe
#   datasets = pe.uk.ensure_datasets(...)
#   simulation = Simulation(dataset=dataset, tax_benefit_model_version=pe.uk.model)
import policyengine as pe
from policyengine.core import Simulation

dataset = datasets[f"enhanced_frs_2023_24_{year}"]
simulation = Simulation(dataset=dataset, tax_benefit_model_version=pe.uk.model)
simulation.ensure()

print(simulation.release_bundle["bundle_id"])
print(type(simulation.output_dataset.data.household).__name__)

uk-4.0.0
MicroDataFrame

# Step 1: pin the exact policyengine.py release in your environment.
# pip install "policyengine[uk]==4.3.0"

# Step 2: capture the certified runtime bundle next to every output you save.
import json
from pathlib import Path

import policyengine as pe
from policyengine.core import Simulation

datasets = pe.uk.ensure_datasets(years=[2026], data_folder="./data")
dataset = next(iter(datasets.values()))
simulation = Simulation(dataset=dataset, tax_benefit_model_version=pe.uk.model)
simulation.ensure()

bundle = simulation.release_bundle

Path("outputs").mkdir(exist_ok=True)
Path("outputs/release_bundle.json").write_text(json.dumps(bundle, indent=2, default=str))

print("bundle_id:", bundle["bundle_id"])
print("country:", bundle["country_id"])
print("model:", bundle["model_package"], bundle["model_version"])
print("data:", bundle["data_package"], bundle["data_version"])
print("dataset:", bundle["dataset_filepath"])

bundle_id: uk-4.0.0
country: uk
model: policyengine-uk 2.88.0
data: policyengine-uk-data 1.40.4
dataset: ./data/enhanced_frs_2023_24_year_2026.h5