From 1f950854faaa1bd6b12a2faa89eeacb88fdacaa8 Mon Sep 17 00:00:00 2001 From: PavelMakarchuk Date: Wed, 5 Nov 2025 08:14:04 -0500 Subject: [PATCH] Add options for the UK and Canada Fixes #13 --- POLICYENGINE_UK_QUICK_REFERENCE.md | 251 ++++ POLICYENGINE_UK_STRUCTURE.md | 462 ++++++++ UK_ADAPTATION_GUIDE.md | 257 ++++ UK_DOCUMENTATION_INDEX.md | 287 +++++ UK_EXPLORATION_SUMMARY.md | 368 ++++++ src/App.tsx | 76 +- src/components/CountrySelector.tsx | 71 ++ src/components/FilterBar.tsx | 13 +- src/components/MatrixView.tsx | 44 +- src/data/countries/canada/programs.ts | 404 +++++++ src/data/countries/index.ts | 31 + src/data/countries/uk/programs.ts | 236 ++++ src/data/countries/us/programs.ts | 1556 +++++++++++++++++++++++++ src/types/Country.ts | 129 ++ src/types/Program.ts | 8 +- 15 files changed, 4131 insertions(+), 62 deletions(-) create mode 100644 POLICYENGINE_UK_QUICK_REFERENCE.md create mode 100644 POLICYENGINE_UK_STRUCTURE.md create mode 100644 UK_ADAPTATION_GUIDE.md create mode 100644 UK_DOCUMENTATION_INDEX.md create mode 100644 UK_EXPLORATION_SUMMARY.md create mode 100644 src/components/CountrySelector.tsx create mode 100644 src/data/countries/canada/programs.ts create mode 100644 src/data/countries/index.ts create mode 100644 src/data/countries/uk/programs.ts create mode 100644 src/data/countries/us/programs.ts create mode 100644 src/types/Country.ts diff --git a/POLICYENGINE_UK_QUICK_REFERENCE.md b/POLICYENGINE_UK_QUICK_REFERENCE.md new file mode 100644 index 0000000..88c31cd --- /dev/null +++ b/POLICYENGINE_UK_QUICK_REFERENCE.md @@ -0,0 +1,251 @@ +================================================================================ + POLICYENGINE UK - QUICK REFERENCE +================================================================================ + +1. DIRECTORY STRUCTURE (High Level) +================================================================================ +policyengine_uk/ + ├── parameters/ YAML files - all rates, amounts, eligibility thresholds + ├── variables/ Python formulas - all calculations for benefits/taxes + ├── reforms/ Policy change definitions + ├── tests/ Test suite + ├── entities.py Defines: State, Household, BenUnit, Person + └── system.py TaxBenefitSystem initialization + +2. JURISDICTIONS (13 Regions, NOT State-by-State) +================================================================================ +Region (Enum): + ENGLAND: + - North East + - North West + - Yorkshire and the Humber + - East Midlands + - West Midlands + - East of England + - London + - South East + - South West + SCOTLAND (devolved - has Scottish Social Security programs) + WALES (devolved - some specific programs) + NORTHERN_IRELAND (devolved - different rates for some programs) + +Pattern: Derived Country -> used for conditional benefit eligibility + country = ENGLAND | SCOTLAND | WALES | NORTHERN_IRELAND + +3. MAJOR PROGRAMS (20 DWP Benefits + 8 Tax Types) +================================================================================ + +DWP (Department for Work & Pensions) - Social Security: + Core Income Support: + • Universal Credit (primary working-age benefit) + • Pension Credit (means-tested for pensioners) + • Housing Benefit (legacy, being replaced by UC) + + Disability/Caring: + • Personal Independence Payment (PIP) + • Disability Living Allowance (DLA) + • Attendance Allowance + • Carers Allowance + • Severe Disablement Allowance (SDA) + • Industrial Injuries Disablement Benefit (IIDB) + • Constant Attendance Allowance (CAA) + + Employment Support: + • Employment Support Allowance (ESA) + • Job Seeker's Allowance (JSA) + • Income Support (IS) + + Child Support (Legacy - mostly replaced by UC): + • Child Tax Credit (CTC) + • Working Tax Credit (WTC) + + Other: + • State Pension + • Winter Fuel Allowance + • Benefit Cap (aggregated limit across all benefits) + +HMRC (Her Majesty's Revenue & Customs) - Taxes: + • Income Tax + • National Insurance (social security contributions) + • Child Benefit + • Capital Gains Tax + • Stamp Duty + • VAT (limited modeling) + • Business Rates + • Fuel Duty + +Education (DfE): + • Universal Childcare Entitlement + • Extended Childcare Entitlement + • Targeted Childcare Entitlement + • Care to Learn + +Scotland-Specific: + • Parent & Widow Housing Payment (PAWHP) + • Scottish tax variations + +4. PARAMETER ORGANIZATION (YAML Files) +================================================================================ +parameters/gov/ +├── dwp/ (20+ benefits) +│ ├── universal_credit/ +│ │ ├── standard_allowance/amount.yaml +│ │ ├── elements/ +│ │ │ ├── housing/ +│ │ │ ├── childcare/ +│ │ │ └── ... +│ │ └── ... +│ ├── pension_credit/ +│ ├── housing_benefit/ +│ ├── [18 other benefits] +│ └── benefit_cap.yaml +├── hmrc/ (taxes) +│ ├── income_tax/ +│ ├── national_insurance/ +│ ├── child_benefit/ +│ └── ... +├── dfe/ (education) +├── social_security_scotland/ (Scottish programs) +├── indices/ (inflation indices for uprating) +└── [other departments] + +Pattern: parameters/gov/{DEPARTMENT}/{BENEFIT}/{COMPONENT}/values.yaml + +Example Parameter File (YAML): +--- +description: Universal Credit standard allowance. +SINGLE_YOUNG: + values: + 2024-04-01: 311.68 + 2025-04-01: 316.98 + metadata: + uprating: gov.benefit_uprating_cpi # Auto-uprated by CPI + unit: currency-GBP + period: month +SINGLE_OLD: + values: + 2024-04-01: 393.45 + 2025-04-01: 400.14 + ... + +5. VARIABLES ORGANIZATION (Python Formulas) +================================================================================ +variables/gov/ +├── dwp/ (100+ benefit calculation modules) +│ ├── universal_credit/ (8 modules for UC alone) +│ │ ├── universal_credit.py (main amount) +│ │ ├── universal_credit_pre_benefit_cap.py +│ │ ├── uc_maximum_amount.py +│ │ ├── is_uc_eligible.py +│ │ └── would_claim_uc.py +│ ├── pension_credit/ +│ ├── housing_benefit/ +│ └── [18+ other benefits] +├── hmrc/ (50+ tax modules) +└── [other departments] + +variables/household/ +├── demographic/ (95+ demographic variables) +│ ├── country.py (ENGLAND | SCOTLAND | WALES | NORTHERN_IRELAND) +│ ├── benunit_region.py +│ ├── geography.py (Region enum definition) +│ └── [90+ others: age, family type, disability, etc.] +└── [benefits, income, consumption, wealth, etc.] + +Example Variable (Python): +--- +class universal_credit(Variable): + label = "Universal Credit" + entity = BenUnit # Calculated at benefit unit level + definition_period = YEAR # Annual calculation + value_type = float + unit = GBP + + def formula(benunit, period, parameters): + uc_max = benunit("universal_credit_pre_benefit_cap", period) + cap_reduction = benunit("benefit_cap_reduction", period) + return max_(uc_max - cap_reduction, 0) + +6. ENTITY HIERARCHY +================================================================================ +State (country) + ├── Household (residence, building) + │ └── BenUnit (family/benefit unit) + │ └── Person + └── Person (directly) + +Total: 4 entities, hierarchical structure + +7. ENTITIES (entities.py) +================================================================================ +State: + - Contains people as members + - Represents the nation + +Household: + - Contains people as members + - Contains benefit units + - Represents a residence + +BenUnit (Benefit Unit / Family): + - Contains people as members + - Contained in household and state + - Legal family unit for means-testing + +Person: + - Individual + - Can be member of household/benunit/state + +8. KEY DIFFERENCES FROM US SYSTEM +================================================================================ +ASPECT UK US +Jurisdictions National + 4 countries 50+ states + DC +Regional Scope Mostly national State-by-state variation +Benefit Coordination Unified benefit cap State-specific programs +Parameter Structure Nested YAML, auto-uprating Flat or state-specific +Regional Logic Only Scotland/Wales/NI All benefits vary by state +Entity Model State/HH/BenUnit/Person Household/Person (state vars) +Variables Count 154+ government variables [Check policyengine-us] +Tax Integration Unified HMRC system IRS + state/local taxes +Disability Support Separate programs (PIP, DLA) Varies by state + +9. KEY DESIGN PATTERNS FOR COVERAGE TRACKER +================================================================================ +1. Region Mapping: + - Maintain 13-region enum (9 English + 3 countries) + - Calculate country from region (not vice versa) + - Use country for conditional benefit logic (Scotland != England) + +2. Benefit Organization: + - Organize by department folder (dwp, hmrc, dfe, etc.) + - Each benefit can have sub-folders (universal_credit/elements/) + - Metadata propagates down hierarchies + +3. Parameter Uprating: + - All time-varying parameters link to indices (CPI) + - Support metadata: unit, period, label, reference + - Categories for enum values (SINGLE_YOUNG, COUPLE_OLD, etc.) + +4. Eligibility Cascade: + - is_eligible -> would_claim -> actual_amount + - Many benefits are conditional (defined_for="would_claim_x") + - Use cascading formula structure + +5. Regional Variations: + - Most benefits are national + - Only specific benefits vary by country (flag with country check) + - Housing Benefit has regional LHA rates + +6. Benefit Cap: + - Unified aggregation across multiple benefits + - Calculate total benefit entitlements + - Apply cap reduction + +7. Time-Varying Parameters: + - All amounts/rates should support multiple values + - Link to automatic uprating indices + - Include references to legislation + +================================================================================ +For detailed analysis, see: POLICYENGINE_UK_STRUCTURE.md +================================================================================ diff --git a/POLICYENGINE_UK_STRUCTURE.md b/POLICYENGINE_UK_STRUCTURE.md new file mode 100644 index 0000000..99a45b3 --- /dev/null +++ b/POLICYENGINE_UK_STRUCTURE.md @@ -0,0 +1,462 @@ +# PolicyEngine UK Repository Exploration + +## 1. Overall Directory Structure + +``` +policyengine-uk/ +├── policyengine_uk/ # Main package directory +│ ├── entities.py # Defines: State, Household, BenUnit, Person +│ ├── system.py # TaxBenefitSystem configuration +│ ├── model_api.py # Core API exports +│ ├── parameters/ # All tax-benefit system parameters (YAML) +│ ├── variables/ # All calculated variables (Python formulas) +│ ├── reforms/ # Policy reform definitions +│ ├── tests/ # Test suite +│ └── utils/ # Utility functions +├── docs/ # Documentation +├── setup.py # Package setup +└── CHANGELOG.md # Version history +``` + +## 2. Regional/Jurisdictional Breakdown + +The UK system recognizes **4 countries** plus **9 English regions**: + +### Hierarchy +``` +Region (Enum - 13 values) +├── UNKNOWN +├── NORTH_EAST (England) +├── NORTH_WEST (England) +├── YORKSHIRE (England) +├── EAST_MIDLANDS (England) +├── WEST_MIDLANDS (England) +├── EAST_OF_ENGLAND (England) +├── LONDON (England) +├── SOUTH_EAST (England) +├── SOUTH_WEST (England) +├── WALES +├── SCOTLAND +└── NORTHERN_IRELAND +``` + +### Implementation Pattern +- **Location**: `/variables/household/demographic/geography.py` (Region enum) +- **Location**: `/variables/household/demographic/country.py` (Country derived variable) +- **Derived Country Enum** (ENGLAND, SCOTLAND, WALES, NORTHERN_IRELAND, UNKNOWN) + - Calculated from region using a select formula +- **BRMA** (Broad Rental Market Area): Additional geographic level for housing benefit + - Location: `/variables/household/demographic/locations.py` (20KB file with detailed mappings) + +### Regional Implementation Examples +```python +# Winter Fuel Allowance (DWP) +in_scotland = (country == "SCOTLAND") +in_england_or_wales = (country == "ENGLAND") | (country == "WALES") + +# Scottish Specific Benefits +- Social Security Scotland: pawhp.py (Parent and Widow Housing Payment) +- Revenue Scotland: LBTT taxes (Land and Buildings Transaction Tax) +``` + +**Key Note**: UK is primarily **national-level** for most benefits with Scotland/Wales/Northern Ireland having devolved specific programs. NOT state-by-state like the US. + +## 3. Major Programs/Benefits Implemented + +### Department for Work and Pensions (DWP) - 20 Benefits +Located: `/parameters/gov/dwp/` and `/variables/gov/dwp/` + +**Major Income Support Benefits:** +1. **Universal Credit** - Primary working-age benefit + - Files: Multiple sub-modules (standard_allowance, elements/childcare, etc.) + - Parameters: 15+ parameter files (takeup, rollout, means-tests) + +2. **Pension Credit** - Means-tested support for pensioners + - Parameter: `/parameters/gov/dwp/pension_credit/` + +3. **Housing Benefit** - Support for renters (legacy system, being replaced by UC) + - Local Housing Allowance (LHA) rates by region + - Parameter: `/parameters/gov/dwp/housing_benefit/` + +**Disability & Caring Benefits:** +4. **Personal Independence Payment (PIP)** - Disability support +5. **Disability Living Allowance (DLA)** - Legacy disability benefit +6. **Attendance Allowance** - Support for disabled pensioners +7. **Carers Allowance** - Support for unpaid carers +8. **Severe Disablement Allowance (SDA)** - Legacy benefit + +**Employment Benefits:** +9. **Employment Support Allowance (ESA)** - Support for sick/disabled not working +10. **Job Seeker's Allowance (JSA)** - Unemployment support +11. **Income Support (IS)** - Means-tested support for non-working + +**Social Protection:** +12. **State Pension** - Basic state pension (with triple-lock uprating) +13. **Constant Attendance Allowance (CAA)** - For severely disabled +14. **Industrial Injuries Disablement Benefit (IIDB)** - Work injuries + +**Child Support:** +15. **Child Tax Credit (CTC)** - Legacy child support (replaced by UC child elements) +16. **Working Tax Credit (WTC)** - Legacy work incentive (replaced by UC) + +**Winter Support:** +17. **Winter Fuel Payment/Allowance** - Heating cost support +18. **Tax Credits** - Family tax support + +**Other Benefits:** +19. **Disability Premium, Carer Premium, etc.** - Means-test add-ons +20. **Benefit Cap** - Benefit aggregation limit + +### Her Majesty's Revenue & Customs (HMRC) - Taxes +Located: `/parameters/gov/hmrc/` and `/variables/gov/hmrc/` + +**Key Taxes:** +1. **Income Tax** - Progressive income taxation +2. **National Insurance** - Social security contributions +3. **Child Benefit** - Universal support for families with children +4. **VAT** - Value Added Tax (not fully modeled) +5. **Stamp Duty** - Transaction taxes +6. **Capital Gains Tax (CGT)** +7. **Business Rates** - Commercial property tax +8. **Tax-Free Childcare** - Support for childcare costs (limited modeling) + +### Department for Education (DfE) +Located: `/parameters/gov/dfe/` + +**Education Benefits:** +1. **Universal Childcare Entitlement** - 15-30 hours free childcare +2. **Extended Childcare Entitlement** - Additional hours +3. **Targeted Childcare Entitlement** - For eligible families +4. **Care to Learn** - Childcare for young parents in education + +### Scottish-Specific Benefits +Located: `/parameters/gov/social_security_scotland/` and `/variables/gov/social_security_scotland/` + +**Programs:** +1. **Parent & Widow(er) Housing Payment (PAWHP)** - Housing support for specific groups + +### Other Government Departments +- **DfT** (Department for Transport): Fuel duty, transport support +- **DHSC** (Department of Health & Social Care): Health-related costs +- **WRA** (Welsh Revenue Authority): Wales-specific taxes +- **Revenue Scotland**: Scottish taxes +- **DCMS** (Department for Culture, Media & Sport): TV licence, arts funding +- **Local Authorities**: Council tax, rates + +## 4. Parameters Folder Structure + +### Organization Pattern +``` +parameters/ +├── gov/ # Government-wide parameters +│ ├── dwp/ # Department for Work & Pensions +│ │ ├── universal_credit/ +│ │ │ ├── standard_allowance/ +│ │ │ │ ├── amount.yaml +│ │ │ │ ├── claimant_type/ +│ │ │ │ └── README.md +│ │ │ ├── elements/ # UC components (housing, childcare, etc.) +│ │ │ │ ├── housing/ +│ │ │ │ ├── childcare/ +│ │ │ │ ├── disabled/ +│ │ │ │ └── child/ +│ │ │ ├── takeup_rate.yaml +│ │ │ └── README.md +│ │ ├── pension_credit/ +│ │ ├── housing_benefit/ +│ │ ├── state_pension/ +│ │ │ └── triple_lock/ # Special triple-lock uprating +│ │ ├── tax_credits/ +│ │ ├── [18 other benefits]/ +│ │ └── benefit_cap.yaml +│ │ +│ ├── hmrc/ # Tax system +│ │ ├── income_tax/ +│ │ ├── national_insurance/ +│ │ ├── child_benefit/ +│ │ ├── stamp_duty/ +│ │ ├── cgt/ +│ │ ├── business_rates/ +│ │ ├── fuel_duty/ +│ │ ├── vat/ +│ │ └── minimum_wage.yaml +│ │ +│ ├── dfe/ # Education +│ │ ├── universal_childcare_entitlement/ +│ │ ├── extended_childcare_entitlement/ +│ │ ├── targeted_childcare_entitlement/ +│ │ └── care_to_learn/ +│ │ +│ ├── social_security_scotland/ +│ ├── revenue_scotland/ +│ ├── wra/ # Welsh Revenue Authority +│ ├── dft/ # Transport +│ ├── dhsc/ # Health & Social Care +│ ├── dcms/ # Culture & Media +│ ├── local_authorities/ # Council tax, rates +│ ├── treasury/ # General economic parameters +│ ├── indices/ # Inflation indices (CPI, RPI) +│ ├── ons/ # Office for National Statistics +│ ├── obr/ # Office for Budget Responsibility (forecasts) +│ ├── contrib/ # Contribution-based benefits +│ └── simulation/ # Simulation-specific parameters +│ +└── household/ # Household-level parameters + ├── consumption/ + ├── demographic/ + ├── poverty/ + └── wealth/ +``` + +### Parameter File Structure (YAML) + +**Simple Scalar Parameter:** +```yaml +# takeup_rate.yaml +description: Take-up rate of Universal Credit. +values: + 2015-01-01: 0.55 +metadata: + unit: /1 + label: Universal Credit take-up rate +``` + +**Complex Nested Parameter with Multiple Versions:** +```yaml +# standard_allowance/amount.yaml +description: Universal Credit standard allowance. +SINGLE_YOUNG: + description: Standard allowance for single claimants under 25 + values: + 2015-04-01: 251.77 + 2020-04-06: 344.00 + 2021-10-06: 257.33 + 2024-04-01: + value: 311.68 + reference: + - title: Benefits Uprating 2024/25 + href: https://... + 2025-04-01: 316.98 + metadata: + label: Universal Credit single amount (under 25) + uprating: gov.benefit_uprating_cpi # Links to uprating mechanism + unit: currency-GBP + period: month +SINGLE_OLD: + # ... (similar structure) +COUPLE_YOUNG: + # ... (similar structure) +COUPLE_OLD: + # ... (similar structure) +metadata: + unit: currency-GBP + uprating: gov.benefit_uprating_cpi + propagate_metadata_to_children: true # Metadata inheritance + reference: + - https://www.legislation.gov.uk/uksi/2013/376/... +``` + +### Key Features of Parameter System +1. **Time-varying values**: Different values for different dates (uprating) +2. **Metadata inheritance**: `propagate_metadata_to_children: true` applies parent metadata to child nodes +3. **Structured hierarchies**: Parameters can be nested (e.g., `universal_credit/elements/childcare/cap.yaml`) +4. **Uprating mechanisms**: Links to inflation indices (CPI, RPI) for automatic uprating +5. **References**: Each parameter includes legislative/administrative references +6. **Categories/enum values**: Named categories (SINGLE_YOUNG, COUPLE_OLD) for flexibility + +### Parameter Folders by Entity +- **gov.dwp**: Department for Work & Pensions (20+ benefits) +- **gov.hmrc**: Tax parameters +- **gov.dfe**: Education parameters +- **gov.indices**: Inflation and indexation +- **gov.obr**: Office for Budget Responsibility (demographic forecasts) +- **household**: Household parameters (not government policies) + +## 5. Variables Folder Structure + +### Organization by Type +``` +variables/ +├── gov/ # Government-controlled programs +│ ├── dwp/ # Benefit calculations +│ │ ├── universal_credit/ # 8 calculation modules +│ │ │ ├── universal_credit.py (main calculation) +│ │ │ ├── universal_credit_pre_benefit_cap.py +│ │ │ ├── uc_maximum_amount.py +│ │ │ ├── is_uc_eligible.py +│ │ │ ├── would_claim_uc.py +│ │ │ ├── universal_credit_reported.py +│ │ │ └── [more modules] +│ │ ├── pension_credit/ +│ │ ├── housing_benefit/ +│ │ ├── pip/ +│ │ ├── dla/ +│ │ ├── attendance_allowance.py +│ │ ├── carers_allowance.py +│ │ ├── state_pension/ +│ │ ├── tax_credits/ +│ │ ├── [18+ benefit modules] +│ │ └── [100+ supporting calculations] +│ │ +│ ├── hmrc/ # Tax calculations (50+ modules) +│ │ ├── income_tax/ +│ │ ├── national_insurance/ +│ │ ├── child_benefit.py +│ │ ├── stamp_duty/ +│ │ └── [more tax modules] +│ │ +│ ├── dfe/ # Education benefits +│ ├── social_security_scotland/ # Scottish benefits +│ ├── revenue_scotland/ # Scottish taxes +│ ├── [other departments] +│ │ +│ └── simulation/ # Simulation utilities +│ +├── household/ # Household characteristics +│ ├── demographic/ # 95+ demographic variables +│ │ ├── country.py # Derived from region +│ │ ├── benunit_region.py # Benefit unit region +│ │ ├── geography.py # Region definitions +│ │ ├── age_under_18.py +│ │ ├── is_adult.py +│ │ ├── is_disabled_for_benefits.py +│ │ ├── family_type.py +│ │ ├── [50+ more demographic] +│ │ └── locations.py # 20KB BRMA mappings +│ │ +│ ├── benefits/ # Benefit aggregations +│ │ └── total_benefits.py +│ │ +│ ├── income/ # Income calculations +│ │ ├── total_income.py +│ │ └── [income components] +│ │ +│ ├── consumption/ # Consumer behavior +│ ├── wealth/ # Asset calculations +│ └── [other categories] +│ +├── input/ # Input variables (user-provided) +│ ├── consumption/ +│ └── [input-specific] +│ +├── contrib/ # Contributed variables (external orgs) +│ ├── labour/ +│ ├── policyengine/ +│ ├── cec/ +│ └── ubi_center/ +│ +└── misc/ # Miscellaneous + └── categories/ +``` + +### Variable File Pattern + +**Simple Variable:** +```python +from policyengine_uk.model_api import * + +class attendance_allowance(Variable): + value_type = float + entity = Person # Calculated at PERSON level + label = "Attendance Allowance" + definition_period = YEAR # Annual calculation + unit = GBP # Currency unit + + def formula(person, period, parameters): + aa = parameters(period).gov.dwp.attendance_allowance + category = person("aa_category", period) + return select( + [category == categories.HIGHER, category == categories.LOWER], + [aa.higher, aa.lower], + default=0, + ) * WEEKS_IN_YEAR +``` + +**Complex Benefit Calculation:** +```python +class universal_credit(Variable): + label = "Universal Credit" + entity = BenUnit # Calculated at BENUNIT level + definition_period = YEAR + value_type = float + unit = GBP + defined_for = "would_claim_uc" # Conditional on eligibility + + def formula(benunit, period, parameters): + uc_max = benunit("universal_credit_pre_benefit_cap", period) + cap_reduction = benunit("benefit_cap_reduction", period) + return max_(uc_max - cap_reduction, 0) +``` + +## 6. Test Structure + +``` +tests/ +├── code_health/ # Code quality & consistency tests +│ └── test_variables.py +├── policy/ +│ ├── baseline/ # Baseline system tests +│ ├── integration/ # Full system integration tests +│ └── reforms/ # Policy reform tests +├── microsimulation/ # Dataset-based calculations +│ └── test_validity.py +└── test_parameter_metadata.py +``` + +## 7. Entities Structure + +**Hierarchy** (from entities.py): +``` +State (country-level) +│ +├─ Household (buildings/residences) +│ │ +│ └─ BenUnit (families, benefit units) +│ │ +│ └─ Person (individuals) +│ +└─ Person (directly in state) +``` + +Each entity has roles and relationships: +- **State** contains: Members (people) +- **Household** contains: Members (people), contains BenUnits +- **BenUnit** contains: Members (people), contained in Household & State +- **Person** has role: member (of state, household, or benunit) + +## 8. Key Files for Reference + +| File | Purpose | +|------|---------| +| `/entities.py` | Entity definitions (State, Household, BenUnit, Person) | +| `/system.py` | TaxBenefitSystem initialization & processing | +| `/parameters/` | YAML parameter definitions (rates, amounts, eligibility) | +| `/variables/` | Python calculation formulas for all benefits & taxes | +| `/variables/household/demographic/geography.py` | Region & Country enums | +| `/variables/household/demographic/locations.py` | BRMA detailed mappings | +| `/modelled_policies.yaml` | Overview of what's modeled vs. not | +| `/reforms/` | Policy reform specifications | + +## 9. Key Differences from US System + +| Aspect | UK | US | +|--------|----|----| +| **Jurisdictions** | National + 4 countries + 9 regions | 50+ states + DC + territories | +| **Benefit Coordination** | Unified benefit cap | State-level program variations | +| **Parameter Structure** | Nested YAML with uprating | Flat or state-specific | +| **Regional Logic** | Country-level (Scotland/Wales/NI) | State-level (all programs vary) | +| **Entities** | State, Household, BenUnit, Person | Household, Person (state variations) | +| **Variable Count** | ~154 government benefit/tax variables | [Need to check policyengine-us] | + +## Key Learnings for Coverage Tracker Adaptation + +1. **Region Mapping**: Need to support 13 regions, not just 4 countries +2. **Benefit Cap**: UK has a unified benefit cap that needs aggregation +3. **Parameter Uprating**: Automatic uprating from inflation indices (CPI) +4. **Department Organization**: Parameters/Variables organized by department, not benefit type +5. **Eligibility Cascades**: Many benefits have complex eligibility (UC eligible → would claim → actual amount) +6. **Regional Variations**: Only specific benefits differ by country (Scotland/Wales/NI), not all +7. **Metadata Propagation**: Parameter metadata can be inherited down hierarchies +8. **Time-varying**: All parameters must support multiple values over time +9. **Scale**: 154+ variables, 20+ benefits, 8+ tax types in single country package + diff --git a/UK_ADAPTATION_GUIDE.md b/UK_ADAPTATION_GUIDE.md new file mode 100644 index 0000000..4d8f622 --- /dev/null +++ b/UK_ADAPTATION_GUIDE.md @@ -0,0 +1,257 @@ +# UK Coverage Tracker - Adaptation Guide + +This document provides guidance for adapting the coverage tracker to support the PolicyEngine UK system. + +## Files Generated + +1. **POLICYENGINE_UK_STRUCTURE.md** - Comprehensive detailed analysis (18KB) + - Complete directory structure + - All 20+ benefits listed with locations + - Parameter file examples with YAML structure + - Variable calculation patterns + - Full entity hierarchy + +2. **POLICYENGINE_UK_QUICK_REFERENCE.md** - Quick lookup guide + - High-level overview + - Major programs summary + - Key design patterns + - Differences from US system + +## Key Findings Summary + +### Structure +- **Jurisdictions**: 13 regions (9 English + Scotland + Wales + Northern Ireland) +- **Core Entity**: `BenUnit` (Benefit Unit / Family) - NOT state-based like US +- **Organization**: By government department (DWP, HMRC, DfE, etc.) + +### Benefits Count +- **DWP**: 20+ social security benefits +- **HMRC**: 8+ tax types +- **DfE**: 4 education/childcare programs +- **Scottish-specific**: 1+ devolved programs +- **Total**: 154+ government variables + +### Key Differences from US + +| Aspect | UK | US | +|--------|----|----| +| **Coverage Model** | National + 4 countries | 50+ states | +| **Region Pattern** | Country-based logic | State-based variations | +| **Regional Scope** | Most benefits national | All vary by state | +| **Benefit Cap** | Unified across all | N/A | +| **Tax Integration** | Single HMRC system | IRS + state/local | + +## Implementation Recommendations + +### 1. Benefit Tracking Structure +For UK coverage tracker, organize by department: +``` +Coverage/ +├── DWP (Social Security) +│ ├── Universal Credit +│ ├── Pension Credit +│ ├── Housing Benefit +│ ├── Disability Benefits (PIP, DLA, etc.) +│ ├── Employment Benefits (ESA, JSA, IS) +│ └── [17 other benefits] +├── HMRC (Taxes) +│ ├── Income Tax +│ ├── National Insurance +│ ├── Child Benefit +│ └── [5 other taxes] +└── Other Departments + ├── DfE (Education/Childcare) + ├── Scottish Social Security + └── [other departments] +``` + +### 2. Region/Jurisdiction Support +```python +# Enum definition needed +class Region(Enum): + # England (9 regions) + NORTH_EAST = "North East" + NORTH_WEST = "North West" + YORKSHIRE = "Yorkshire and the Humber" + EAST_MIDLANDS = "East Midlands" + WEST_MIDLANDS = "West Midlands" + EAST_OF_ENGLAND = "East of England" + LONDON = "London" + SOUTH_EAST = "South East" + SOUTH_WEST = "South West" + + # Countries + SCOTLAND = "Scotland" + WALES = "Wales" + NORTHERN_IRELAND = "Northern Ireland" + +# Derived at calculation time +def get_country(region: Region) -> str: + country_map = { + "SCOTLAND": "Scotland", + "WALES": "Wales", + "NORTHERN_IRELAND": "Northern Ireland", + # All English regions map to England + } + return country_map.get(region.name, "England") +``` + +### 3. Benefit Coverage Data Structure +For each benefit, track: +```json +{ + "benefit_id": "universal_credit", + "label": "Universal Credit", + "department": "DWP", + "type": "income_support", + "coverage_status": { + "ENGLAND": "fully_modeled", + "SCOTLAND": "fully_modeled", + "WALES": "fully_modeled", + "NORTHERN_IRELAND": "fully_modeled" + }, + "implementation": { + "parameters_path": "/gov/dwp/universal_credit/", + "variables_path": "/gov/dwp/universal_credit/", + "modules": [ + "universal_credit.py", + "is_uc_eligible.py", + "would_claim_uc.py", + "universal_credit_pre_benefit_cap.py" + ], + "entities": ["BenUnit"], + "parent_benefits": [], + "child_components": [ + "standard_allowance", + "housing_element", + "childcare_element", + "disability_element", + "child_element" + ] + }, + "notes": "Primary working-age benefit, replaced most legacy benefits" +} +``` + +### 4. Parameter Uprating Awareness +Many UK parameters auto-uprate via indices: +```yaml +metadata: + uprating: gov.benefit_uprating_cpi # Link to inflation index + unit: currency-GBP + period: month +``` + +Consider tracking: +- Base year for parameters +- Uprating index used +- Last confirmed values +- Next scheduled uprating date + +### 5. Regional Variations +Most benefits are **national**, but track exceptions: + +**Varies by Region/Country:** +- Housing Benefit: Local Housing Allowance (LHA) rates by BRMA (sub-regional) +- Winter Fuel Allowance: Different for Scotland vs England/Wales +- Council Tax: Local authority rates (200+ councils) + +**Scotland-specific:** +- Parent & Widow Housing Payment (PAWHP) +- Different tax rates + +**Treat as mostly national** unless specifically regional. + +### 6. Cascading Eligibility Pattern +Many benefits follow: +``` +Eligible → Would Claim → Actual Amount +``` + +Track all three levels: +1. `is_X_eligible` - Meets policy criteria +2. `would_claim_X` - Would claim based on means-testing +3. `X` - Final calculated amount + +### 7. Benefit Cap Tracking +UK has unified **benefit cap** that aggregates: +- Universal Credit +- Housing Benefit +- JSA/ESA/IS +- Child Tax Credit +- Working Tax Credit +- Disability elements +- Winter support payments + +Note: Not all benefits count towards cap (State Pension exempt, PIP exempt, etc.) + +### 8. Entities to Track +Unlike US (household/person), UK uses: +- **State**: National level +- **Household**: Residence/building +- **BenUnit**: Family/legal benefit unit (KEY FOR MEANS-TESTING) +- **Person**: Individual + +Most means-tested benefits calculated at **BenUnit** level, not household or individual. + +## Data Collection Priorities + +1. **Core Income Support** (3 major): + - Universal Credit (replacing most legacy benefits) + - Pension Credit (pensioners) + - Housing Benefit (legacy, being phased out) + +2. **Disability & Caring** (7 major): + - PIP, DLA, Attendance Allowance (disability) + - Carers Allowance (unpaid carers) + - Various premiums (additions to means-tested benefits) + +3. **Employment Support** (3 major): + - ESA (Employment Support Allowance) + - JSA (Job Seeker's Allowance) + - IS (Income Support) + +4. **Taxes** (3 major): + - Income Tax + - National Insurance + - Child Benefit (universal, not means-tested) + +5. **Education** (4 benefits): + - Various childcare entitlements + +## Regional Data Needs + +For tracking coverage completeness: +- National parameters: 1 copy per benefit +- Regional parameters: ~13 copies (by region) +- BRMA (housing): ~150+ sub-regions for LHA + +Most can be treated as **national** with exceptions noted. + +## Migration from US + +If migrating from US coverage tracker: + +1. **Simplify region logic**: Most UK benefits national +2. **Add BenUnit entity**: Can't just track household/person +3. **Add country distinction**: Scotland/Wales/NI have devolved programs +4. **Track benefit cap**: Unique to UK +5. **Parameter uprating**: Need to link to indices, not just dates +6. **Reduce state variations**: Only ~3 countries with variations + +## Next Steps + +1. Review full documentation: POLICYENGINE_UK_STRUCTURE.md +2. Choose benefits to track first (recommend Universal Credit + Income Tax) +3. Define data schema for benefit coverage +4. Set up regional/jurisdiction tracking +5. Create benefit inventory spreadsheet/database +6. Map parameter/variable files to coverage tracking +7. Implement cascading eligibility tracking + +## Additional Resources + +- PolicyEngine UK: https://github.com/PolicyEngine/policyengine-uk +- PolicyEngine Core: https://github.com/PolicyEngine/policyengine-core +- UK Legislation: https://www.legislation.gov.uk/ +- DWP Benefits: https://www.gov.uk/browse/benefits diff --git a/UK_DOCUMENTATION_INDEX.md b/UK_DOCUMENTATION_INDEX.md new file mode 100644 index 0000000..5a7c55d --- /dev/null +++ b/UK_DOCUMENTATION_INDEX.md @@ -0,0 +1,287 @@ +# UK PolicyEngine Documentation Index + +This index guides you through the exploration of the PolicyEngine UK system for coverage tracker adaptation. + +## Start Here + +### If you have 5 minutes: +- Read: **UK_EXPLORATION_SUMMARY.md** (this file gives you the executive summary) + +### If you have 20 minutes: +- Read: **POLICYENGINE_UK_QUICK_REFERENCE.md** (overview of structure and major programs) +- Then: **UK_ADAPTATION_GUIDE.md** (practical implementation guidance) + +### If you have 1+ hour: +- Read: **POLICYENGINE_UK_STRUCTURE.md** (comprehensive technical reference) +- Reference: **POLICYENGINE_UK_QUICK_REFERENCE.md** (for specific lookups) +- Use: **UK_ADAPTATION_GUIDE.md** (for implementation decisions) + +--- + +## Document Overview + +### 1. UK_EXPLORATION_SUMMARY.md (This File) +**Length**: ~300 lines | **Reading Time**: 5-10 minutes + +**What it contains:** +- Executive summary: UK is NATIONAL, not state-by-state +- Key insight: Simpler structure than US (4 countries vs 50 states) +- 154+ government variables overview +- Directory structure diagram +- Jurisdictional structure (13 regions) +- Three layers of implementation (Parameters, Variables, Entities) +- 4 major concepts for adaptation +- Statistics and quick answers + +**When to use:** +- Quick overview before diving deeper +- To understand the scale and scope +- To see the big picture differences from US + +**Key takeaway:** UK system is national with 4 countries + 9 English regions, organized by department (DWP, HMRC, DfE) + +--- + +### 2. POLICYENGINE_UK_QUICK_REFERENCE.md +**Length**: ~250 lines | **Reading Time**: 15-20 minutes + +**What it contains:** +- Directory structure (high level) +- 13 jurisdictions with full breakdown +- 20 DWP benefits listed +- 8+ HMRC tax types listed +- 4 DfE education programs +- Scottish-specific benefits +- Parameter organization tree +- Parameter file examples (YAML) +- Variables organization tree +- Variable code examples (Python) +- Entity hierarchy +- Key differences from US system (table) +- 7 key design patterns for tracker + +**When to use:** +- Quick reference for program names and locations +- Understanding parameter structure +- Understanding variable patterns +- Comparing UK vs US approaches + +**Key takeaway:** Comprehensive structured overview of what exists and where to find it + +--- + +### 3. POLICYENGINE_UK_STRUCTURE.md +**Length**: ~460 lines (18KB) | **Reading Time**: 45 minutes - 1 hour + +**What it contains:** +- Complete directory structure with all benefits +- Full list of 13 regions with hierarchy +- All 20+ DWP benefits with descriptions +- All HMRC taxes listed +- All DfE education programs +- All Scottish-specific programs +- Detailed parameter folder structure (9 subsections) +- Parameter file structure patterns (YAML examples with full content) +- Key features of parameter system (6 points) +- Complete variables folder structure +- Variable file pattern examples (Python code) +- Test structure +- Entity hierarchy and definitions +- Key files reference table +- 8 key differences from US system (detailed table) +- Key learnings for coverage tracker adaptation + +**When to use:** +- Deep technical understanding needed +- Detailed implementation planning +- Understanding exact parameter/variable organization +- Finding specific benefits or tax types + +**Key takeaway:** Complete technical reference for understanding the entire UK system structure + +--- + +### 4. UK_ADAPTATION_GUIDE.md +**Length**: ~250 lines (7.4KB) | **Reading Time**: 20-30 minutes + +**What it contains:** +- File overview (summary of the 3 documents) +- Key findings summary (structure, benefits count, differences) +- Implementation recommendations (8 detailed sections): + 1. Benefit tracking structure (organized by department) + 2. Region/jurisdiction enum design (Python code example) + 3. Benefit coverage data structure (JSON example) + 4. Parameter uprating awareness + 5. Regional variations handling + 6. Cascading eligibility pattern + 7. Benefit cap tracking + 8. Entity handling (BenUnit focus) +- Data collection priorities (5 categories) +- Regional data needs +- Migration steps from US system +- Next steps (7-item action plan) +- Additional resources + +**When to use:** +- Planning how to implement UK support in coverage tracker +- Deciding on data schema and structure +- Understanding what to prioritize +- Getting specific implementation recommendations + +**Key takeaway:** Practical guidance for adapting coverage tracker, with code examples and data schemas + +--- + +## Feature Comparison Table + +| Feature | Summary | Full Details | +|---------|---------|--------------| +| **Jurisdictions** | 13 regions (9 English + 4 countries) | POLICYENGINE_UK_STRUCTURE.md, Section 2 | +| **Benefits Count** | 20+ DWP, 8+ HMRC, 4+ DfE | POLICYENGINE_UK_QUICK_REFERENCE.md, Section 3 | +| **Directory Structure** | parameters/ and variables/ by department | POLICYENGINE_UK_STRUCTURE.md, Section 4 | +| **Parameter Format** | YAML with time-varying values & metadata | POLICYENGINE_UK_STRUCTURE.md, Section 4 | +| **Variable Format** | Python classes with formula methods | POLICYENGINE_UK_STRUCTURE.md, Section 5 | +| **Entities** | State, Household, BenUnit, Person | POLICYENGINE_UK_STRUCTURE.md, Section 7 | +| **Implementation Guide** | Practical recommendations with examples | UK_ADAPTATION_GUIDE.md, all sections | + +--- + +## Quick Navigation by Topic + +### Understanding the Structure +1. Start: **UK_EXPLORATION_SUMMARY.md** (Executive Summary) +2. Deep dive: **POLICYENGINE_UK_STRUCTURE.md** (Section 1) + +### Finding Programs +1. Quick lookup: **POLICYENGINE_UK_QUICK_REFERENCE.md** (Section 3) +2. Full details: **POLICYENGINE_UK_STRUCTURE.md** (Section 3) + +### Understanding Parameters +1. Overview: **POLICYENGINE_UK_QUICK_REFERENCE.md** (Section 4) +2. Detailed patterns: **POLICYENGINE_UK_STRUCTURE.md** (Section 4) +3. Examples: Both documents have YAML examples + +### Understanding Variables +1. Overview: **POLICYENGINE_UK_QUICK_REFERENCE.md** (Section 5) +2. Detailed patterns: **POLICYENGINE_UK_STRUCTURE.md** (Section 5) +3. Examples: Both documents have Python code examples + +### Understanding Jurisdictions +1. Quick overview: **POLICYENGINE_UK_QUICK_REFERENCE.md** (Section 2) +2. Full details: **POLICYENGINE_UK_STRUCTURE.md** (Section 2) +3. Implementation: **UK_ADAPTATION_GUIDE.md** (Section 2) + +### Planning Implementation +1. Start: **UK_EXPLORATION_SUMMARY.md** (4 Major Concepts) +2. Plan: **UK_ADAPTATION_GUIDE.md** (all sections) +3. Reference: **POLICYENGINE_UK_STRUCTURE.md** (for details as needed) + +--- + +## Key Concepts Explained + +### BenUnit (Benefit Unit) +- **What**: Family/legal family unit for means-testing purposes +- **Why it matters**: Most UK benefits calculated at this level, not household/person +- **Reference**: UK_ADAPTATION_GUIDE.md, Section 8; POLICYENGINE_UK_STRUCTURE.md, Section 7 +- **Impact**: Must track eligibility at BenUnit level, not just household + +### Cascading Eligibility +- **Pattern**: Eligible → Would Claim → Actual Amount +- **Why it matters**: Many benefits have three calculation levels +- **Reference**: UK_ADAPTATION_GUIDE.md, Section 6 +- **Impact**: Need to track all three levels in coverage tracking + +### Benefit Cap +- **What**: Unified limit on total benefits received +- **Why it matters**: Unique to UK, aggregates multiple benefits +- **Reference**: UK_ADAPTATION_GUIDE.md, Section 7 +- **Impact**: Need to aggregate across benefits for cap calculation + +### Parameter Uprating +- **Pattern**: Link to inflation indices (CPI, RPI) for auto-uprating +- **Why it matters**: Parameters update automatically, need to track mechanism +- **Reference**: UK_ADAPTATION_GUIDE.md, Section 4 +- **Impact**: Need to understand uprating links when tracking parameters + +### Regional vs National +- **Pattern**: Most benefits national, only Scotland/Wales/NI vary +- **Why it matters**: Simpler than US where all vary by state +- **Reference**: UK_ADAPTATION_GUIDE.md, Section 5 +- **Impact**: Can treat most benefits as national with exceptions + +--- + +## Statistics Summary + +| Metric | Value | Reference | +|--------|-------|-----------| +| Total Variables | 154+ | UK_EXPLORATION_SUMMARY.md | +| DWP Benefits | 20+ | All documents | +| HMRC Tax Types | 8+ | All documents | +| Education Programs | 4 | All documents | +| Regions | 13 | POLICYENGINE_UK_QUICK_REFERENCE.md, Section 2 | +| Entities | 4 | POLICYENGINE_UK_STRUCTURE.md, Section 7 | +| Parameter Folders | 20+ | POLICYENGINE_UK_STRUCTURE.md, Section 4 | +| Variable Modules | 150+ | POLICYENGINE_UK_STRUCTURE.md, Section 5 | + +--- + +## Common Questions & Answers + +**Q: Is the UK system like the US state-by-state?** +A: No. UK is national with 4 countries. Most benefits identical across UK. Reference: UK_EXPLORATION_SUMMARY.md (Key Insight section) + +**Q: How many benefits are there?** +A: 20+ DWP social security benefits, 8+ HMRC taxes, 4 education programs. Reference: UK_EXPLORATION_SUMMARY.md (What's Implemented) + +**Q: What are the regions?** +A: 13 total: 9 English regions + Scotland + Wales + Northern Ireland. Reference: UK_EXPLORATION_SUMMARY.md (Jurisdictional Structure) + +**Q: Where are parameters stored?** +A: `/parameters/gov/{DEPARTMENT}/{BENEFIT}/` as YAML files. Reference: POLICYENGINE_UK_STRUCTURE.md, Section 4 + +**Q: Where are benefit calculations?** +A: `/variables/gov/{DEPARTMENT}/{BENEFIT}/` as Python classes. Reference: POLICYENGINE_UK_STRUCTURE.md, Section 5 + +**Q: What are the main entities?** +A: State, Household, BenUnit, Person. BenUnit is key for means-testing. Reference: POLICYENGINE_UK_STRUCTURE.md, Section 7 + +**Q: How do I adapt the US tracker for UK?** +A: Follow UK_ADAPTATION_GUIDE.md. Key changes: add BenUnit, simplify regions, track benefit cap. Reference: UK_ADAPTATION_GUIDE.md (all sections) + +**Q: What are the key differences from US?** +A: National vs state-by-state, unified benefit cap, BenUnit entity, cascading eligibility. Reference: UK_EXPLORATION_SUMMARY.md (3 Key Differences) + +--- + +## Source Information + +**Source Repository**: `/Users/pavelmakarchuk/policyengine-uk` +**Documentation Location**: `/Users/pavelmakarchuk/policyengine-coverage-tracker/` +**Generated**: November 5, 2025 +**Based on**: Direct exploration of policyengine-uk repository structure, parameters, and variables + +--- + +## File Sizes & Line Counts + +| Document | Size | Lines | Type | +|----------|------|-------|------| +| UK_EXPLORATION_SUMMARY.md | 10KB | 330 | Overview | +| POLICYENGINE_UK_QUICK_REFERENCE.md | 9KB | 251 | Quick Ref | +| POLICYENGINE_UK_STRUCTURE.md | 18KB | 462 | Detailed | +| UK_ADAPTATION_GUIDE.md | 7KB | 257 | Practical | +| UK_DOCUMENTATION_INDEX.md | 8KB | 250 | This file | + +--- + +## Next Steps + +1. **If new to UK system**: Start with UK_EXPLORATION_SUMMARY.md +2. **If need quick reference**: Use POLICYENGINE_UK_QUICK_REFERENCE.md +3. **If planning implementation**: Read UK_ADAPTATION_GUIDE.md +4. **If need technical details**: Deep dive into POLICYENGINE_UK_STRUCTURE.md +5. **If confused about something**: Search this index for the topic + +Good luck with your coverage tracker adaptation! diff --git a/UK_EXPLORATION_SUMMARY.md b/UK_EXPLORATION_SUMMARY.md new file mode 100644 index 0000000..a84f80a --- /dev/null +++ b/UK_EXPLORATION_SUMMARY.md @@ -0,0 +1,368 @@ +# PolicyEngine UK - Exploration Summary + +**Date**: November 5, 2025 +**Source**: `/Users/pavelmakarchuk/policyengine-uk` +**Purpose**: Understanding UK system structure for coverage tracker adaptation + +--- + +## Executive Summary + +The UK PolicyEngine system is fundamentally different from the US system in structure and scope: + +### Key Insight +**The UK is primarily NATIONAL, not state-by-state.** +- One national system with 4 countries (England, Scotland, Wales, Northern Ireland) +- 9 English regions (for data/analysis purposes, not separate policy) +- Most benefits are the same across the UK with only 3 countries having devolved programs +- Much simpler regional structure compared to US 50-state system + +--- + +## What's Implemented (154+ Government Variables) + +### By Department + +**Department for Work & Pensions (DWP)** - 20+ Social Security Benefits +- Universal Credit (primary benefit replacing most others) +- Pension Credit, Housing Benefit +- PIP, DLA, Attendance Allowance (disability) +- Carers Allowance, Carers Premium +- ESA, JSA, Income Support +- State Pension, Child Tax Credit, Working Tax Credit +- Severe Disablement Allowance, Industrial Injuries Disablement Benefit +- Constant Attendance Allowance, Disability Premiums +- Winter Fuel Allowance +- **Benefit Cap** (unified limit across all benefits) + +**Her Majesty's Revenue & Customs (HMRC)** - 8+ Tax Types +- Income Tax, National Insurance +- Child Benefit (universal, not means-tested) +- Capital Gains Tax, Stamp Duty, VAT, Business Rates, Fuel Duty + +**Department for Education (DfE)** - 4 Education Benefits +- Universal Childcare Entitlement +- Extended Childcare Entitlement +- Targeted Childcare Entitlement +- Care to Learn + +**Other Departments** - 10+ Programs +- Scottish Social Security (Parent & Widow Housing Payment) +- Scottish Taxes (Revenue Scotland) +- Welsh Programs (WRA - Welsh Revenue Authority) +- Transport, Health, Media, Local Authorities + +--- + +## Directory Structure + +``` +policyengine_uk/ +├── parameters/ YAML files with rates, thresholds, amounts +│ ├── gov/ +│ │ ├── dwp/ 20+ benefit parameter folders +│ │ ├── hmrc/ Tax parameters +│ │ ├── dfe/ Education parameters +│ │ ├── indices/ Inflation indices (for uprating) +│ │ └── [other depts] +│ └── household/ Household-level parameters +│ +├── variables/ Python formulas - benefit/tax calculations +│ ├── gov/ +│ │ ├── dwp/ 100+ benefit calculation modules +│ │ ├── hmrc/ 50+ tax calculation modules +│ │ └── [other depts] +│ │ +│ └── household/ +│ ├── demographic/ 95+ demographic variables (region, country, family type, age, etc.) +│ ├── benefits/ Benefit aggregations +│ ├── income/ Income calculations +│ └── [other categories] +│ +├── entities.py Defines: State, Household, BenUnit, Person +├── system.py TaxBenefitSystem initialization +├── reforms/ Policy change definitions +├── tests/ Test suite +└── utils/ Utility functions +``` + +--- + +## Jurisdictional Structure (13 Regions) + +### Hierarchy +``` +Region Enum (13 values) +├── England (9 regions) +│ ├── North East +│ ├── North West +│ ├── Yorkshire and the Humber +│ ├── East Midlands +│ ├── West Midlands +│ ├── East of England +│ ├── London +│ ├── South East +│ └── South West +├── Scotland (devolved) +├── Wales (devolved) +└── Northern Ireland (devolved) + +Derived: Country (Enum) +└── ENGLAND | SCOTLAND | WALES | NORTHERN_IRELAND +``` + +### Regional Implementation Pattern +```python +# Most benefits are national +# Only specific benefits vary by country +if country == "SCOTLAND": + # Scotland-specific logic +elif country in ["ENGLAND", "WALES"]: + # England/Wales logic +``` + +--- + +## Three Layers of Implementation + +### 1. Parameters (YAML) +**Location**: `/parameters/gov/{DEPARTMENT}/{BENEFIT}/` + +**Example**: Universal Credit Standard Allowance +```yaml +SINGLE_YOUNG: + values: + 2024-04-01: 311.68 + 2025-04-01: 316.98 + metadata: + uprating: gov.benefit_uprating_cpi # Auto-uprated by inflation + unit: currency-GBP + period: month +``` + +### 2. Variables (Python) +**Location**: `/variables/gov/{DEPARTMENT}/{BENEFIT}/` + +**Example**: Universal Credit Calculation +```python +class universal_credit(Variable): + entity = BenUnit # Calculated at benefit unit level + definition_period = YEAR + unit = GBP + + def formula(benunit, period, parameters): + # Get maximum entitlement + uc_max = benunit("universal_credit_pre_benefit_cap", period) + # Apply benefit cap + cap_reduction = benunit("benefit_cap_reduction", period) + return max_(uc_max - cap_reduction, 0) +``` + +### 3. Entities +**Location**: `/entities.py` + +Four entities in hierarchical structure: +- **State**: National level (contains people, households) +- **Household**: Residence/building (contains people, benefit units) +- **BenUnit**: Family/legal benefit unit (KEY - used for means-testing) +- **Person**: Individual + +--- + +## 4 Major Concepts for Adaptation + +### 1. Entity Level: BenUnit, Not Household +- Most means-tested benefits calculated at **BenUnit** level +- BenUnit = family unit for benefit purposes +- Unlike US where calculations often at household/person level +- Affects how you aggregate and track benefit eligibility + +### 2. Cascading Eligibility Pattern +Many benefits have three levels: +``` +is_X_eligible → Meets policy criteria + ↓ +would_claim_X → Would claim based on means-test + ↓ +X → Final calculated amount +``` + +Track all three in coverage tracking. + +### 3. Unified Benefit Cap +UK has ONE benefit cap that aggregates: +- Universal Credit +- Housing Benefit +- JSA/ESA/IS +- Child Tax Credit +- Working Tax Credit +- Various disability elements +- Winter payments + +**Note**: Some benefits exempt (State Pension, PIP, DLA) + +### 4. Parameter Uprating via Indices +Parameters link to inflation indices: +```yaml +metadata: + uprating: gov.benefit_uprating_cpi # Automatic CPI uprating +``` + +- Need to track uprating mechanism +- Auto-uprating dates (usually April for benefits) +- Different indices for different benefits (CPI vs RPI) + +--- + +## 3 Key Differences from US + +### Regional Complexity +- **US**: 50+ states, each with different programs +- **UK**: National + 4 countries, most benefits identical + +### Benefit Organization +- **US**: State-specific variations in most programs +- **UK**: Department-based (DWP, HMRC, DfE), mostly national + +### Parameter Structure +- **US**: Likely flat or state-specific +- **UK**: Nested hierarchies, automatic uprating via indices + +--- + +## Major Programs by Category + +### Income Support (3 main) +1. **Universal Credit** - Primary working-age benefit +2. **Pension Credit** - Means-tested for pensioners +3. **Housing Benefit** - Legacy, being phased to Universal Credit + +### Disability & Caring (7 main) +1. PIP - Personal Independence Payment +2. DLA - Disability Living Allowance +3. Attendance Allowance +4. Carers Allowance +5-7. Various premiums (enhancements to other benefits) + +### Employment Support (3 main) +1. ESA - Employment Support Allowance +2. JSA - Job Seeker's Allowance +3. IS - Income Support + +### Taxes (3 major) +1. Income Tax +2. National Insurance (social security contribution) +3. Child Benefit (universal, not means-tested) + +### Education/Childcare (4) +1-4. Various childcare entitlements (universal, extended, targeted, care to learn) + +--- + +## Documentation Files Generated + +### 1. **POLICYENGINE_UK_STRUCTURE.md** (18KB, 462 lines) +Complete technical reference including: +- Full directory structure with all benefits +- Parameter organization patterns (YAML examples) +- Variable calculation examples (Python) +- Entity hierarchy details +- Test structure +- All 154+ variables organized by department +- Key design patterns + +**Use for**: Deep technical understanding, detailed implementation + +### 2. **POLICYENGINE_UK_QUICK_REFERENCE.md** (9KB, 251 lines) +Quick lookup including: +- Directory structure overview +- All jurisdictions (13 regions) +- All major programs (20 DWP + 8 taxes + others) +- Parameter file patterns +- Variable code patterns +- Entity structure +- Key design patterns for tracker + +**Use for**: Quick navigation, program overview, reference + +### 3. **UK_ADAPTATION_GUIDE.md** (7KB, 257 lines) +Practical guidance for adapting coverage tracker: +- Recommended benefit tracking structure (by department) +- Region/jurisdiction enum design +- Data structure schemas (JSON examples) +- Regional variation handling +- Cascading eligibility tracking +- Benefit cap aggregation +- Entity handling (BenUnit focus) +- Data collection priorities +- Migration steps from US system + +**Use for**: Implementation planning, schema design, next steps + +--- + +## Key Files in Source Repository + +| File | Purpose | Key Info | +|------|---------|----------| +| `/entities.py` | Define entities | State, Household, BenUnit, Person | +| `/system.py` | TaxBenefitSystem | Parameter loading, processing | +| `/parameters/gov/dwp/` | All DWP parameters | 20+ benefit folders with YAML | +| `/parameters/gov/hmrc/` | Tax parameters | Income tax, NI, child benefit, etc. | +| `/variables/gov/dwp/` | Benefit calculations | 100+ calculation modules | +| `/variables/gov/hmrc/` | Tax calculations | 50+ tax modules | +| `/variables/household/demographic/` | Region/country | 95+ demographic variables | +| `/variables/household/demographic/geography.py` | Region enum | 13 region definitions | +| `/variables/household/demographic/country.py` | Country logic | Derives country from region | +| `/modelled_policies.yaml` | Coverage overview | What's modeled vs not | + +--- + +## Next Steps for Coverage Tracker Adaptation + +1. **Review documentation** (start with QUICK_REFERENCE, then STRUCTURE) +2. **Define data schema** (use examples in ADAPTATION_GUIDE) +3. **Set up regions** (13 region enum, derive country) +4. **Choose initial benefits** (recommend: Universal Credit + Income Tax) +5. **Map files** (link benefits to parameter/variable files) +6. **Track cascading eligibility** (eligible → would_claim → amount) +7. **Plan benefit cap** (unified aggregation across programs) +8. **Add Scottish programs** (separate from English logic) + +--- + +## Statistics Summary + +| Metric | Value | +|--------|-------| +| Total Government Variables | 154+ | +| DWP Benefits | 20+ | +| HMRC Tax Types | 8+ | +| Education Programs | 4 | +| Regions (detailed) | 13 (9 English + 3 countries) | +| Jurisdictions | 4 (countries) | +| Entities | 4 (State, Household, BenUnit, Person) | +| Parameter Folders | 20+ | +| Variable Modules | 150+ | + +--- + +## Quick Answers to Original Questions + +### 1. Overall Directory Structure? +**Answer**: Organized by department (DWP, HMRC, DfE) with parameters (YAML) and variables (Python) folders + +### 2. UK Jurisdictions? +**Answer**: National-level with 4 countries + 9 English regions. Most benefits national, only Scotland/Wales/NI have devolved variations + +### 3. Programs Implemented? +**Answer**: 20 DWP social security benefits, 8+ HMRC taxes, 4 education programs, various department-specific programs + +### 4. Parameters Structure? +**Answer**: Nested YAML by department/benefit/component with metadata, time-varying values, uprating indices, and legislative references + +--- + +Generated: November 5, 2025 +Source Repository: `/Users/pavelmakarchuk/policyengine-uk` +Documentation Path: `/Users/pavelmakarchuk/policyengine-coverage-tracker/` diff --git a/src/App.tsx b/src/App.tsx index 07e39a6..6d7d389 100644 --- a/src/App.tsx +++ b/src/App.tsx @@ -5,7 +5,9 @@ import ProgramCard from './components/ProgramCard'; import ProgramGrid from './components/ProgramGrid'; import MatrixView from './components/MatrixView'; import ExecutiveSummary from './components/ExecutiveSummary'; -import { programs, getStatusCount } from './data/programs'; +import CountrySelector from './components/CountrySelector'; +import { getProgramsForCountry, getStatusCountForCountry } from './data/countries'; +import { CountryCode, COUNTRIES } from './types/Country'; import { CoverageStatus, Program } from './types/Program'; import { colors, typography, spacing } from './designTokens'; import { extractStatesFromPrograms } from './utils/extractStates'; @@ -15,6 +17,7 @@ type FilterMode = 'all' | 'federal' | 'state-local'; type DisplayMode = 'overview' | 'developer'; function App() { + const [selectedCountry, setSelectedCountry] = useState('us'); const [selectedStatus, setSelectedStatus] = useState('all'); const [filterMode, setFilterMode] = useState('all'); const [selectedAgency, setSelectedAgency] = useState('All'); @@ -23,8 +26,10 @@ function App() { const [viewMode, setViewMode] = useState('grid'); const [displayMode, setDisplayMode] = useState('overview'); - const statusCounts = getStatusCount(); + const programs = getProgramsForCountry(selectedCountry); + const statusCounts = getStatusCountForCountry(selectedCountry); const availableStates = extractStatesFromPrograms(programs); + const currentCountry = COUNTRIES[selectedCountry]; const handleStateSelect = (state: string) => { setFilterMode('state-local'); @@ -195,7 +200,7 @@ function App() { // If filterMode is 'all', show all programs without level filtering return filtered; - }, [selectedStatus, filterMode, selectedAgency, selectedState, searchQuery]); + }, [programs, selectedStatus, filterMode, selectedAgency, selectedState, searchQuery]); return (
@@ -208,34 +213,40 @@ function App() { }} >
-
- PolicyEngine Logo -
-

- PolicyEngine Coverage Tracker -

-

- Track the implementation status of government programs in PolicyEngine US -

+
+
+ PolicyEngine Logo +
+

+ PolicyEngine Coverage Tracker +

+

+ Track the implementation status of government programs in PolicyEngine {currentCountry.name} +

+
+
@@ -348,6 +359,7 @@ function App() { statusCounts={statusCounts} totalPrograms={programs.length} availableStates={availableStates} + country={currentCountry} /> )} @@ -484,7 +496,7 @@ function App() {
) : displayMode === 'overview' ? ( // Matrix view for Overview Mode - + ) : (() => { // Separate state programs from local programs when in state-local mode with a specific state selected const shouldSeparate = filterMode === 'state-local' && selectedState !== 'All'; @@ -544,7 +556,7 @@ function App() { fontWeight: typography.fontWeight.semibold, fontFamily: typography.fontFamily.primary }}> - State Programs ({statePrograms.length}) + {currentCountry.regionalLabel} Programs ({statePrograms.length})
{viewMode === 'grid' ? ( diff --git a/src/components/CountrySelector.tsx b/src/components/CountrySelector.tsx new file mode 100644 index 0000000..ad67352 --- /dev/null +++ b/src/components/CountrySelector.tsx @@ -0,0 +1,71 @@ +import React from 'react'; +import { CountryCode, COUNTRIES } from '../types/Country'; +import { colors, typography, spacing } from '../designTokens'; + +interface CountrySelectorProps { + selectedCountry: CountryCode; + onCountryChange: (country: CountryCode) => void; +} + +const CountrySelector: React.FC = ({ + selectedCountry, + onCountryChange, +}) => { + return ( +
+ {Object.values(COUNTRIES).map((country) => ( + + ))} +
+ ); +}; + +export default CountrySelector; diff --git a/src/components/FilterBar.tsx b/src/components/FilterBar.tsx index 6b35b82..1e73357 100644 --- a/src/components/FilterBar.tsx +++ b/src/components/FilterBar.tsx @@ -1,5 +1,6 @@ import React from 'react'; import { CoverageStatus } from '../types/Program'; +import { Country } from '../types/Country'; import { statusColors, colors } from '../designTokens'; type FilterMode = 'all' | 'federal' | 'state-local'; @@ -18,6 +19,7 @@ interface FilterBarProps { statusCounts: Record; totalPrograms: number; availableStates: string[]; + country: Country; } const FilterBar: React.FC = ({ @@ -34,9 +36,10 @@ const FilterBar: React.FC = ({ statusCounts, totalPrograms, availableStates, + country, }) => { const [isExpanded, setIsExpanded] = React.useState(false); - const federalAgencies = ['USDA', 'HHS', 'SSA', 'IRS', 'HUD', 'ED', 'DOL', 'FCC', 'ACA']; + const federalAgencies = country.agencies; // Check if any filters are active (not in reset state) const filtersActive = selectedStatus !== 'all' || @@ -54,8 +57,8 @@ const FilterBar: React.FC = ({ const filterModeOptions: Array<{ value: FilterMode; label: string }> = [ { value: 'all', label: 'All Programs' }, - { value: 'federal', label: 'Federal Agencies' }, - { value: 'state-local', label: 'State & Local' }, + { value: 'federal', label: `${country.federalLabel} Agencies` }, + { value: 'state-local', label: `${country.regionalLabel} & Local` }, ]; return ( @@ -278,7 +281,7 @@ const FilterBar: React.FC = ({ {filterMode === 'federal' && (