policyengine-uk
Load before writing PolicyEngine-UK code — UK household calculations, income tax (incl. Scottish and Welsh variations), National Insurance, Universal Credit and other benefits, poverty and reform analysis. Covers the person/benunit/household entity model (UK has NO tax_unit), pe.uk.calculate_household, BHC vs AHC poverty, ITL1 regions, populace_uk_2023 data, and the policyengine_uk Scenario surface for country-model development. Triggers: Microcosm (formerly Populace), policyengine uk, pe.uk, Universal Credit, child benefit, pension credit, housing benefit, council tax, income tax, national insurance, personal allowance, Scottish income tax, Welsh rate, benunit, hbai, in_poverty_bhc, in_poverty_ahc, ITL1 region, populace_uk, HUGGING_FACE_TOKEN, UK reform, Scenario. NOT for: US or Canada models (see policyengine-us / policyengine-canada), general microsimulation mechanics (see policyengine), or implementing new UK variables/parameters inside the model (see policyengine-model-development
PolicyEngine · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add PolicyEngine/policyengine-claude --skill policyengine-uk技能说明
name: policyengine-uk description: | Load before writing PolicyEngine-UK code — UK household calculations, income tax (incl. Scottish and Welsh variations), National Insurance, Universal Credit and other benefits, poverty and reform analysis. Covers the person/benunit/household entity model (UK has NO tax_unit), pe.uk.calculate_household, BHC vs AHC poverty, ITL1 regions, populace_uk_2023 data, and the policyengine_uk Scenario surface for country-model development. Triggers: Microcosm (formerly Populace), policyengine uk, pe.uk, Universal Credit, child benefit, pension credit, housing benefit, council tax, income tax, national insurance, personal allowance, Scottish income tax, Welsh rate, benunit, hbai, in_poverty_bhc, in_poverty_ahc, ITL1 region, populace_uk, HUGGING_FACE_TOKEN, UK reform, Scenario. NOT for: US or Canada models (see policyengine-us / policyengine-canada), general microsimulation mechanics (see policyengine), or implementing new UK variables/parameters inside the model (see policyengine-model-development). metadata: category: domain
PolicyEngine UK
UK-specific facts for the PolicyEngine Python stack. Read the policyengine skill first for
the canonical import policyengine as pe interface, the population flow
(ensure_datasets / Simulation / economic_impact_analysis), the MicroSeries discipline,
and dataset handling — this skill only carries what is different about the UK.
Verified against policyengine 4.21.0 + policyengine-uk 2.89.2 + policyengine-core 3.30.0
(2026-07). UK examples are not in the [us]-only CI verify set, so they carry no
<!-- verify --> marker; each was run manually in a policyengine[uk] environment.
Setup
The UK model is an extra — bare policyengine installs no country model:
uv pip install "policyengine[uk]" # UK model + certified UK data bundle metadata
Household calculations need no data download. Population runs need the UK dataset, which is a private Hugging Face repo — see "Population data" below.
Entity model — and the benunit trap
UK entities are person → benunit → household. There is no tax_unit and no
spm_unit / marital_unit / family — those are US entities. The single most common UK
mistake is reaching for result.tax_unit out of US habit; on a UK result it raises
AttributeError (verified: a UK result has person, benunit, household and no tax_unit).
| Concept | US entity | UK entity |
|---|---|---|
| Means-tested assessment unit | tax_unit (+ spm_unit) | benunit (benefit unit) |
| Statistical unit for poverty | spm_unit / household | household |
| Individual | person | person |
A benefit unit is a single adult or a couple plus their dependent children — the DWP assessment unit for means-tested benefits (Universal Credit, Pension Credit, etc.). One household can contain several benunits (e.g. adult children living with parents). Read means-tested benefits at the benunit level, income tax and NI at the person level, and net income and poverty at the household level.
Household calculations
pe.uk.calculate_household mirrors the US call (keyword-only, year defaults to 2026), but
results are read on UK entities. Access is dot-attribute on singular entities; only
result.person is a list.
import policyengine as pe
r = pe.uk.calculate_household(
people=[{"age": 35, "employment_income": 50_000}],
year=2026,
)
assert round(r.person[0].income_tax) == 7_486
assert round(r.person[0].national_insurance) == 2_994
assert round(r.household.hbai_household_net_income) == 39_520
Net income comes in two conventions: hbai_household_net_income follows the DWP
Households Below Average Income definition (the one PolicyEngine reports, and what the poverty
measures below use); household_net_income is the plain accounting definition. Prefer the
HBAI variable for anything compared against official UK statistics.
Benefit-unit variables read off benunit (a family with two children on £30k gross):
r = pe.uk.calculate_household(
people=[
{"age": 35, "employment_income": 30_000},
{"age": 33},
{"age": 8},
{"age": 5},
],
household={"region": "NORTH_WEST"},
year=2026,
)
r.benunit.universal_credit # 6029.82
r.benunit.child_benefit # 2337.40
Reforms are the same flat {parameter_path: value} dict as the US package surface:
reformed = pe.uk.calculate_household(
people=[{"age": 35, "employment_income": 50_000}],
year=2026,
reform={"gov.hmrc.income_tax.allowances.personal_allowance.amount": 15_000},
)
assert round(reformed.person[0].income_tax) == 7_000 # 2,430 more allowance x 20%
Poverty — always state the measure
UK poverty is reported at the household level under two measures, and they can disagree for the same household:
in_poverty_bhc— Before Housing Costs.in_poverty_ahc— After Housing Costs.
fam = pe.uk.calculate_household(
people=[{"age": 35, "employment_income": 16_000}, {"age": 33}, {"age": 4}, {"age": 2}],
household={"region": "WALES"},
year=2026,
)
fam.household.in_poverty_bhc # 1.0 (in poverty before housing costs)
fam.household.in_poverty_ahc # 0.0 (NOT in poverty after housing costs)
That verified split — same household, BHC in poverty, AHC not — is why a UK poverty figure is
meaningless without its measure. Name BHC or AHC in every result, and match whichever the
source you compare against used (DWP HBAI headline child-poverty figures are AHC). Deep-poverty
variants (in_deep_poverty_bhc / in_deep_poverty_ahc) follow the same convention. At
population scale these are the poverty variables behind compute_uk_* breakdowns and the
Poverty outputs described in the policyengine skill.
Parameter lookup
For "what is the rate/threshold?" questions, read the parameter tree directly (no simulation).
阅读完整来源 ↗