policyengine-uk

Name: policyengine-uk
Author: PolicyEngine

31stars5forks

How to install policyengine-uk?

policyengine/policyengine-claude/policyengine-uk

$npx -y skills add PolicyEngine/policyengine-claude --skill policyengine-uk

Installs into the current project.

Summary

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.

Files · 1

View on GitHub

SKILL.md

1	# PolicyEngine UK
2
3	UK-specific facts for the PolicyEngine Python stack. Read the `policyengine` skill first for
4	the canonical `import policyengine as pe` interface, the population flow
5	(`ensure_datasets` / `Simulation` / `economic_impact_analysis`), the MicroSeries discipline,
6	and dataset handling — this skill only carries what is different about the UK.
7
8	Verified against policyengine 4.21.0 + policyengine-uk 2.89.2 + policyengine-core 3.30.0
9	(2026-07). UK examples are not in the `[us]`-only CI verify set, so they carry no
10	`<!-- verify -->` marker; each was run manually in a `policyengine[uk]` environment.
11
12	## Setup
13
14	The UK model is an extra — bare `policyengine` installs no country model:
15
16	```bash
17	uv pip install "policyengine[uk]" # UK model + certified UK data bundle metadata
18	```
19
20	Household calculations need no data download. Population runs need the UK dataset, which is a
21	private Hugging Face repo — see "Population data" below.
22
23	## Entity model — and the benunit trap
24
25	UK entities are `person` → `benunit` → `household`. There is no `tax_unit` and no
26	`spm_unit` / `marital_unit` / `family` — those are US entities. The single most common UK
27	mistake is reaching for `result.tax_unit` out of US habit; on a UK result it raises
28	`AttributeError` (verified: a UK result has `person`, `benunit`, `household` and no `tax_unit`).
29
30	\| Concept \| US entity \| UK entity \|
31	\|---\|---\|---\|
32	\| Means-tested assessment unit \| `tax_unit` (+ `spm_unit`) \| `benunit` (benefit unit) \|
33	\| Statistical unit for poverty \| `spm_unit` / `household` \| `household` \|
34	\| Individual \| `person` \| `person` \|
35
36	A benefit unit is a single adult or a couple plus their dependent children — the DWP
37	assessment unit for means-tested benefits (Universal Credit, Pension Credit, etc.). One
38	household can contain several benunits (e.g. adult children living with parents). Read
39	means-tested benefits at the benunit level, income tax and NI at the person level, and
40	net income and poverty at the household level.
41
42	## Household calculations
43
44	`pe.uk.calculate_household` mirrors the US call (keyword-only, `year` defaults to 2026), but
45	results are read on UK entities. Access is dot-attribute on singular entities; only
46	`result.person` is a list.
47
48	```python
49	import policyengine as pe
50
51	r = pe.uk.calculate_household(
52	people=[{"age": 35, "employment_income": 50_000}],
53	year=2026,
54	)
55	assert round(r.person[0].income_tax) == 7_486
56	assert round(r.person[0].national_insurance) == 2_994
57	assert round(r.household.hbai_household_net_income) == 39_520
58	```
59
60	Net income comes in two conventions: `hbai_household_net_income` follows the DWP
61	Households Below Average Income definition (the one PolicyEngine reports, and what the poverty
62	measures below use); `household_net_income` is the plain accounting definition. Prefer the
63	HBAI variable for anything compared against official UK statistics.
64
65	Benefit-unit variables read off `benunit` (a family with two children on £30k gross):
66
67	```python
68	r = pe.uk.calculate_household(
69	people=[
70	{"age": 35, "employment_income": 30_000},
71	{"age": 33},
72	{"age": 8},
73	{"age": 5},
74	],
75	household={"region": "NORTH_WEST"},
76	year=2026,
77	)
78	r.benunit.universal_credit # 6029.82
79	r.benunit.child_benefit # 2337.40
80	```
81
82	Reforms are the same flat `{parameter_path: value}` dict as the US package surface:
83
84	```python
85	reformed = pe.uk.calculate_household(
86	people=[{"age": 35, "employment_income": 50_000}],
87	year=2026,
88	reform={"gov.hmrc.income_tax.allowances.personal_allowance.amount": 15_000},
89	)
90	assert round(reformed.person[0].income_tax) == 7_000 # 2,430 more allowance x 20%
91	```
92
93	## Poverty — always state the measure
94
95	UK poverty is reported at the household level under two measures, and they can disagree
96	for the same household:
97
98	- `in_poverty_bhc` — Before Housing Costs.
99	- `in_poverty_ahc` — After Housing Costs.
100
101	`

People who liked this also viewed

6 picks

Type

policyengine-uk

31stars5forks

View on GitHub

How to install policyengine-uk?

policyengine/policyengine-claude/policyengine-uk

$npx -y skills add PolicyEngine/policyengine-claude --skill policyengine-uk

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# PolicyEngine UK
2
3	UK-specific facts for the PolicyEngine Python stack. Read the `policyengine` skill first for
4	the canonical `import policyengine as pe` interface, the population flow
5	(`ensure_datasets` / `Simulation` / `economic_impact_analysis`), the MicroSeries discipline,
6	and dataset handling — this skill only carries what is different about the UK.
7
8	Verified against policyengine 4.21.0 + policyengine-uk 2.89.2 + policyengine-core 3.30.0
9	(2026-07). UK examples are not in the `[us]`-only CI verify set, so they carry no
10	`<!-- verify -->` marker; each was run manually in a `policyengine[uk]` environment.
11
12	## Setup
13
14	The UK model is an extra — bare `policyengine` installs no country model:
15
16	```bash
17	uv pip install "policyengine[uk]" # UK model + certified UK data bundle metadata
18	```
19
20	Household calculations need no data download. Population runs need the UK dataset, which is a
21	private Hugging Face repo — see "Population data" below.
22
23	## Entity model — and the benunit trap
24
25	UK entities are `person` → `benunit` → `household`. There is no `tax_unit` and no
26	`spm_unit` / `marital_unit` / `family` — those are US entities. The single most common UK
27	mistake is reaching for `result.tax_unit` out of US habit; on a UK result it raises
28	`AttributeError` (verified: a UK result has `person`, `benunit`, `household` and no `tax_unit`).
29
30	\| Concept \| US entity \| UK entity \|
31	\|---\|---\|---\|
32	\| Means-tested assessment unit \| `tax_unit` (+ `spm_unit`) \| `benunit` (benefit unit) \|
33	\| Statistical unit for poverty \| `spm_unit` / `household` \| `household` \|
34	\| Individual \| `person` \| `person` \|
35
36	A benefit unit is a single adult or a couple plus their dependent children — the DWP
37	assessment unit for means-tested benefits (Universal Credit, Pension Credit, etc.). One
38	household can contain several benunits (e.g. adult children living with parents). Read
39	means-tested benefits at the benunit level, income tax and NI at the person level, and
40	net income and poverty at the household level.
41
42	## Household calculations
43
44	`pe.uk.calculate_household` mirrors the US call (keyword-only, `year` defaults to 2026), but
45	results are read on UK entities. Access is dot-attribute on singular entities; only
46	`result.person` is a list.
47
48	```python
49	import policyengine as pe
50
51	r = pe.uk.calculate_household(
52	people=[{"age": 35, "employment_income": 50_000}],
53	year=2026,
54	)
55	assert round(r.person[0].income_tax) == 7_486
56	assert round(r.person[0].national_insurance) == 2_994
57	assert round(r.household.hbai_household_net_income) == 39_520
58	```
59
60	Net income comes in two conventions: `hbai_household_net_income` follows the DWP
61	Households Below Average Income definition (the one PolicyEngine reports, and what the poverty
62	measures below use); `household_net_income` is the plain accounting definition. Prefer the
63	HBAI variable for anything compared against official UK statistics.
64
65	Benefit-unit variables read off `benunit` (a family with two children on £30k gross):
66
67	```python
68	r = pe.uk.calculate_household(
69	people=[
70	{"age": 35, "employment_income": 30_000},
71	{"age": 33},
72	{"age": 8},
73	{"age": 5},
74	],
75	household={"region": "NORTH_WEST"},
76	year=2026,
77	)
78	r.benunit.universal_credit # 6029.82
79	r.benunit.child_benefit # 2337.40
80	```
81
82	Reforms are the same flat `{parameter_path: value}` dict as the US package surface:
83
84	```python
85	reformed = pe.uk.calculate_household(
86	people=[{"age": 35, "employment_income": 50_000}],
87	year=2026,
88	reform={"gov.hmrc.income_tax.allowances.personal_allowance.amount": 15_000},
89	)
90	assert round(reformed.person[0].income_tax) == 7_000 # 2,430 more allowance x 20%
91	```
92
93	## Poverty — always state the measure
94
95	UK poverty is reported at the household level under two measures, and they can disagree
96	for the same household:
97
98	- `in_poverty_bhc` — Before Housing Costs.
99	- `in_poverty_ahc` — After Housing Costs.
100
101	`

People who liked this also viewed

6 picks

Type