policyengine 3.4.0__tar.gz → 3.4.2__tar.gz

{policyengine-3.4.0 → policyengine-3.4.2}/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [3.4.2] - 2026-04-12
+
+### Changed
+
+- Align the bundled UK release manifest with the pinned `policyengine-uk` package version and updated data package revisions.
+
+
+## [3.4.1] - 2026-04-09
+
+### Fixed
+
+- Fixed the UK paper reproduction workflow so the checked-in example runs on Python 3.14 and the associated analysis helpers handle that path cleanly.
+
+
 ## [3.4.0] - 2026-04-08
 
 ### Added

{policyengine-3.4.0 → policyengine-3.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: policyengine
-Version: 3.4.0
+Version: 3.4.2
 Summary: A package to conduct policy analysis using PolicyEngine tax-benefit models.
 Author-email: PolicyEngine <hello@policyengine.org>
 License:                     GNU AFFERO GENERAL PUBLIC LICENSE
@@ -678,10 +678,10 @@ Requires-Dist: requests>=2.31.0
 Requires-Dist: psutil>=5.9.0
 Provides-Extra: uk
 Requires-Dist: policyengine_core>=3.23.6; extra == "uk"
-Requires-Dist: policyengine-uk>=2.51.0; extra == "uk"
+Requires-Dist: policyengine-uk==2.78.0; extra == "uk"
 Provides-Extra: us
 Requires-Dist: policyengine_core>=3.23.6; extra == "us"
-Requires-Dist: policyengine-us>=1.213.1; extra == "us"
+Requires-Dist: policyengine-us==1.602.0; extra == "us"
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: furo; extra == "dev"
@@ -693,8 +693,8 @@ Requires-Dist: build; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.26.0; extra == "dev"
 Requires-Dist: ruff>=0.9.0; extra == "dev"
 Requires-Dist: policyengine_core>=3.23.6; extra == "dev"
-Requires-Dist: policyengine-uk>=2.51.0; extra == "dev"
-Requires-Dist: policyengine-us>=1.213.1; extra == "dev"
+Requires-Dist: policyengine-uk==2.78.0; extra == "dev"
+Requires-Dist: policyengine-us==1.602.0; extra == "dev"
 Requires-Dist: towncrier>=24.8.0; extra == "dev"
 Requires-Dist: mypy>=1.11.0; extra == "dev"
 Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
@@ -747,6 +747,7 @@ print(f"Total UC spending: £{agg.result / 1e9:.1f}bn")
 - `examples/income_distribution_us.py`: Analyse benefit distribution by decile
 - `examples/employment_income_variation_uk.py`: Model employment income phase-outs
 - `examples/policy_change_uk.py`: Analyse policy reform impacts
+- `examples/paper_repro_uk.py`: Reproduce the UK reform analysis used in the JOSS paper draft
 
 ## Installation
 
@@ -838,6 +839,16 @@ echo "Description of change" > changelog.d/my-change.added
 
 On merge, the versioning workflow bumps the version, builds the changelog, and creates a GitHub Release.
 
+## Paper reproduction
+
+Use the pinned interpreter and the UK extra to run the checked-in paper repro:
+
+```bash
+uv run --python 3.14 --extra uk python examples/paper_repro_uk.py
+```
+
+On first run this will create `./data/enhanced_frs_2023_24_year_2026.h5`.
+
 ## Features
 
 - **Multi-country support**: UK and US tax-benefit systems

{policyengine-3.4.0 → policyengine-3.4.2}/README.md

@@ -45,6 +45,7 @@ print(f"Total UC spending: £{agg.result / 1e9:.1f}bn")
 - `examples/income_distribution_us.py`: Analyse benefit distribution by decile
 - `examples/employment_income_variation_uk.py`: Model employment income phase-outs
 - `examples/policy_change_uk.py`: Analyse policy reform impacts
+- `examples/paper_repro_uk.py`: Reproduce the UK reform analysis used in the JOSS paper draft
 
 ## Installation
 
@@ -136,6 +137,16 @@ echo "Description of change" > changelog.d/my-change.added
 
 On merge, the versioning workflow bumps the version, builds the changelog, and creates a GitHub Release.
 
+## Paper reproduction
+
+Use the pinned interpreter and the UK extra to run the checked-in paper repro:
+
+```bash
+uv run --python 3.14 --extra uk python examples/paper_repro_uk.py
+```
+
+On first run this will create `./data/enhanced_frs_2023_24_year_2026.h5`.
+
 ## Features
 
 - **Multi-country support**: UK and US tax-benefit systems

policyengine-3.4.2/examples/paper_repro_uk.py

@@ -0,0 +1,76 @@
+"""Reproduce the UK policy-reform analysis used in the JOSS paper draft.
+
+This script uses the same reform shown in `paper.md`, but adds the missing
+dataset setup so it can run end-to-end from a fresh checkout.
+
+Run:
+    uv run --python 3.14 --extra uk python examples/paper_repro_uk.py
+"""
+
+from datetime import date
+
+from policyengine.core import Parameter, ParameterValue, Policy, Simulation
+from policyengine.tax_benefit_models.uk import (
+    economic_impact_analysis,
+    ensure_datasets,
+    uk_latest,
+)
+
+
+def load_dataset(year: int = 2026):
+    """Load or create the enhanced UK dataset used for population analysis."""
+    datasets = ensure_datasets(
+        datasets=["hf://policyengine/policyengine-uk-data/enhanced_frs_2023_24.h5"],
+        years=[year],
+    )
+    return datasets[f"enhanced_frs_2023_24_{year}"]
+
+
+def create_reform(year: int = 2026) -> Policy:
+    """Set the UK personal allowance to zero for one tax year."""
+    parameter = Parameter(
+        name="gov.hmrc.income_tax.allowances.personal_allowance.amount",
+        tax_benefit_model_version=uk_latest,
+    )
+
+    return Policy(
+        name="Zero personal allowance",
+        parameter_values=[
+            ParameterValue(
+                parameter=parameter,
+                start_date=date(year, 1, 1),
+                end_date=date(year, 12, 31),
+                value=0,
+            )
+        ],
+    )
+
+
+def main():
+    dataset = load_dataset()
+    reform = create_reform()
+
+    baseline = Simulation(
+        dataset=dataset,
+        tax_benefit_model_version=uk_latest,
+    )
+    reformed = Simulation(
+        dataset=dataset,
+        tax_benefit_model_version=uk_latest,
+        policy=reform,
+    )
+
+    analysis = economic_impact_analysis(baseline, reformed)
+
+    first_decile = analysis.decile_impacts.outputs[0]
+
+    print(f"Dataset: {dataset.filepath}")
+    print(f"Households: {len(dataset.data.household):,}")
+    print(f"Baseline Gini: {analysis.baseline_inequality.gini:.4f}")
+    print(f"Reform Gini: {analysis.reform_inequality.gini:.4f}")
+    print(f"Decile 1 mean change: {first_decile.absolute_change:,.2f}")
+    print(f"Programmes analysed: {len(analysis.programme_statistics.outputs)}")
+
+
+if __name__ == "__main__":
+    main()

{policyengine-3.4.0 → policyengine-3.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "policyengine"
-version = "3.4.0"
+version = "3.4.2"
 description = "A package to conduct policy analysis using PolicyEngine tax-benefit models."
 readme = "README.md"
 authors = [
@@ -28,11 +28,11 @@ dependencies = [
 [project.optional-dependencies]
 uk = [
     "policyengine_core>=3.23.6",
-    "policyengine-uk>=2.51.0",
+    "policyengine-uk==2.78.0",
 ]
 us = [
     "policyengine_core>=3.23.6",
-    "policyengine-us>=1.213.1",
+    "policyengine-us==1.602.0",
 ]
 dev = [
     "pytest",
@@ -45,8 +45,8 @@ dev = [
     "pytest-asyncio>=0.26.0",
     "ruff>=0.9.0",
     "policyengine_core>=3.23.6",
-    "policyengine-uk>=2.51.0",
-    "policyengine-us>=1.213.1",
+    "policyengine-uk==2.78.0",
+    "policyengine-us==1.602.0",
     "towncrier>=24.8.0",
     "mypy>=1.11.0",
     "pytest-cov>=5.0.0",

{policyengine-3.4.0 → policyengine-3.4.2}/src/policyengine/core/__init__.py

@@ -12,6 +12,13 @@ from .policy import Policy as Policy
 from .region import Region as Region
 from .region import RegionRegistry as RegionRegistry
 from .region import RegionType as RegionType
+from .release_manifest import CountryReleaseManifest as CountryReleaseManifest
+from .release_manifest import DataPackageVersion as DataPackageVersion
+from .release_manifest import DataReleaseArtifact as DataReleaseArtifact
+from .release_manifest import DataReleaseManifest as DataReleaseManifest
+from .release_manifest import PackageVersion as PackageVersion
+from .release_manifest import get_data_release_manifest as get_data_release_manifest
+from .release_manifest import get_release_manifest as get_release_manifest
 from .scoping_strategy import RegionScopingStrategy as RegionScopingStrategy
 from .scoping_strategy import RowFilterStrategy as RowFilterStrategy
 from .scoping_strategy import ScopingStrategy as ScopingStrategy

policyengine-3.4.2/src/policyengine/core/release_manifest.py

@@ -0,0 +1,178 @@
+import os
+from functools import lru_cache
+from importlib.resources import files
+from pathlib import Path
+
+import requests
+from pydantic import BaseModel, Field
+
+HF_REQUEST_TIMEOUT_SECONDS = 30
+
+
+class PackageVersion(BaseModel):
+    name: str
+    version: str
+
+
+class DataPackageVersion(PackageVersion):
+    repo_id: str
+    repo_type: str = "model"
+    release_manifest_path: str = "release_manifest.json"
+
+
+class CompatibleModelPackage(BaseModel):
+    name: str
+    specifier: str
+
+
+class ArtifactPathReference(BaseModel):
+    path: str
+
+
+class ArtifactPathTemplate(BaseModel):
+    path_template: str
+
+    def resolve(self, **kwargs: str) -> str:
+        return self.path_template.format(**kwargs)
+
+
+class DataReleaseArtifact(BaseModel):
+    kind: str
+    path: str
+    repo_id: str
+    revision: str
+    sha256: str | None = None
+    size_bytes: int | None = None
+
+    @property
+    def uri(self) -> str:
+        return build_hf_uri(
+            repo_id=self.repo_id,
+            path_in_repo=self.path,
+            revision=self.revision,
+        )
+
+
+class DataReleaseManifest(BaseModel):
+    schema_version: int
+    data_package: PackageVersion
+    compatible_model_packages: list[CompatibleModelPackage] = Field(
+        default_factory=list
+    )
+    default_datasets: dict[str, str] = Field(default_factory=dict)
+    artifacts: dict[str, DataReleaseArtifact] = Field(default_factory=dict)
+
+
+class CountryReleaseManifest(BaseModel):
+    country_id: str
+    policyengine_version: str
+    model_package: PackageVersion
+    data_package: DataPackageVersion
+    default_dataset: str
+    datasets: dict[str, ArtifactPathReference] = Field(default_factory=dict)
+    region_datasets: dict[str, ArtifactPathTemplate] = Field(default_factory=dict)
+
+    @property
+    def default_dataset_uri(self) -> str:
+        return resolve_dataset_reference(self.country_id, self.default_dataset)
+
+
+def build_hf_uri(repo_id: str, path_in_repo: str, revision: str) -> str:
+    return f"hf://{repo_id}/{path_in_repo}@{revision}"
+
+
+@lru_cache
+def get_release_manifest(country_id: str) -> CountryReleaseManifest:
+    manifest_path = files("policyengine").joinpath(
+        "data", "release_manifests", f"{country_id}.json"
+    )
+    if not manifest_path.is_file():
+        raise ValueError(f"No bundled release manifest for country '{country_id}'")
+
+    return CountryReleaseManifest.model_validate_json(manifest_path.read_text())
+
+
+def _data_release_manifest_url(data_package: DataPackageVersion) -> str:
+    return (
+        "https://huggingface.co/"
+        f"{data_package.repo_id}/resolve/{data_package.version}/"
+        f"{data_package.release_manifest_path}"
+    )
+
+
+@lru_cache
+def get_data_release_manifest(country_id: str) -> DataReleaseManifest:
+    country_manifest = get_release_manifest(country_id)
+    data_package = country_manifest.data_package
+
+    headers = {}
+    token = os.environ.get("HUGGING_FACE_TOKEN")
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    response = requests.get(
+        _data_release_manifest_url(data_package),
+        headers=headers,
+        timeout=HF_REQUEST_TIMEOUT_SECONDS,
+    )
+    if response.status_code in (401, 403):
+        raise ValueError(
+            "Could not fetch the data release manifest from Hugging Face. "
+            "If this country uses a private data repo, set HUGGING_FACE_TOKEN."
+        )
+    response.raise_for_status()
+    return DataReleaseManifest.model_validate_json(response.text)
+
+
+def resolve_dataset_reference(country_id: str, dataset: str) -> str:
+    if "://" in dataset:
+        return dataset
+
+    manifest = get_release_manifest(country_id)
+    path_reference = manifest.datasets.get(dataset)
+    if path_reference is not None:
+        return build_hf_uri(
+            repo_id=manifest.data_package.repo_id,
+            path_in_repo=path_reference.path,
+            revision=manifest.data_package.version,
+        )
+
+    data_release_manifest = get_data_release_manifest(country_id)
+    artifact = data_release_manifest.artifacts.get(dataset)
+    if artifact is None:
+        raise ValueError(
+            f"Unknown dataset '{dataset}' for country '{country_id}'. "
+            f"Known datasets: {sorted(manifest.datasets)}"
+        )
+
+    return artifact.uri
+
+
+def dataset_logical_name(dataset: str) -> str:
+    return Path(dataset.rsplit("@", 1)[0]).stem
+
+
+def resolve_default_datasets(country_id: str) -> list[str]:
+    manifest = get_release_manifest(country_id)
+    return list(manifest.datasets.keys())
+
+
+def resolve_region_dataset_path(
+    country_id: str,
+    region_type: str,
+    **kwargs: str,
+) -> str | None:
+    manifest = get_release_manifest(country_id)
+    template = manifest.region_datasets.get(region_type)
+    if template is None:
+        return None
+
+    resolved_path = template.resolve(**kwargs)
+    if "://" in resolved_path:
+        return resolved_path
+
+    return build_hf_uri(
+        repo_id=manifest.data_package.repo_id,
+        path_in_repo=resolved_path,
+        revision=manifest.data_package.version,
+    )

{policyengine-3.4.0 → policyengine-3.4.2}/src/policyengine/core/simulation.py

@@ -94,3 +94,17 @@ class Simulation(BaseModel):
     def load(self):
         """Load the simulation's output dataset."""
         self.tax_benefit_model_version.load(self)
+
+    @property
+    def release_bundle(self) -> dict[str, str | None]:
+        bundle = (
+            self.tax_benefit_model_version.release_bundle
+            if self.tax_benefit_model_version is not None
+            else {}
+        )
+        return {
+            **bundle,
+            "dataset_filepath": self.dataset.filepath
+            if self.dataset is not None
+            else None,
+        }

{policyengine-3.4.0 → policyengine-3.4.2}/src/policyengine/core/tax_benefit_model_version.py

@@ -4,6 +4,7 @@ from uuid import uuid4
 
 from pydantic import BaseModel, Field
 
+from .release_manifest import CountryReleaseManifest, PackageVersion
 from .tax_benefit_model import TaxBenefitModel
 
 if TYPE_CHECKING:
@@ -32,6 +33,13 @@ class TaxBenefitModelVersion(BaseModel):
     region_registry: "RegionRegistry | None" = Field(
         default=None, description="Registry of supported geographic regions"
     )
+    release_manifest: CountryReleaseManifest | None = Field(
+        default=None,
+        exclude=True,
+    )
+    model_package: PackageVersion | None = Field(default=None)
+    data_package: PackageVersion | None = Field(default=None)
+    default_dataset_uri: str | None = Field(default=None)
 
     @property
     def parameter_values(self) -> list["ParameterValue"]:
@@ -116,6 +124,28 @@ class TaxBenefitModelVersion(BaseModel):
             return None
         return self.region_registry.get(code)
 
+    @property
+    def release_bundle(self) -> dict[str, str | None]:
+        return {
+            "country_id": self.release_manifest.country_id
+            if self.release_manifest is not None
+            else None,
+            "policyengine_version": self.release_manifest.policyengine_version
+            if self.release_manifest is not None
+            else None,
+            "model_package": self.model_package.name
+            if self.model_package is not None
+            else None,
+            "model_version": self.version,
+            "data_package": self.data_package.name
+            if self.data_package is not None
+            else None,
+            "data_version": self.data_package.version
+            if self.data_package is not None
+            else None,
+            "default_dataset_uri": self.default_dataset_uri,
+        }
+
     def __repr__(self) -> str:
         # Give the id and version, and the number of variables, parameters, parameter nodes, parameter values
         return f"<TaxBenefitModelVersion id={self.id} variables={len(self.variables)} parameters={len(self.parameters)} parameter_nodes={len(self.parameter_nodes)} parameter_values={len(self.parameter_values)}>"

{policyengine-3.4.0 → policyengine-3.4.2}/src/policyengine/countries/uk/regions.py

@@ -15,6 +15,7 @@ import logging
 from typing import TYPE_CHECKING
 
 from policyengine.core.region import Region, RegionRegistry
+from policyengine.core.release_manifest import resolve_region_dataset_path
 from policyengine.core.scoping_strategy import (
     RowFilterStrategy,
     WeightReplacementStrategy,
@@ -127,7 +128,7 @@ def build_uk_region_registry(
             code="uk",
             label="United Kingdom",
             region_type="national",
-            dataset_path=f"{UK_DATA_BUCKET}/enhanced_frs_2023_24.h5",
+            dataset_path=resolve_region_dataset_path("uk", "national"),
         )
     )
 

{policyengine-3.4.0 → policyengine-3.4.2}/src/policyengine/countries/us/regions.py

@@ -8,6 +8,7 @@ in the data/ subdirectory:
 """
 
 from policyengine.core.region import Region, RegionRegistry
+from policyengine.core.release_manifest import resolve_region_dataset_path
 from policyengine.core.scoping_strategy import RowFilterStrategy
 
 from .data import AT_LARGE_STATES, DISTRICT_COUNTS, US_PLACES, US_STATES
@@ -40,7 +41,7 @@ def build_us_region_registry() -> RegionRegistry:
             code="us",
             label="United States",
             region_type="national",
-            dataset_path=f"{US_DATA_BUCKET}/enhanced_cps_2024.h5",
+            dataset_path=resolve_region_dataset_path("us", "national"),
         )
     )
 
@@ -52,7 +53,11 @@ def build_us_region_registry() -> RegionRegistry:
                 label=name,
                 region_type="state",
                 parent_code="us",
-                dataset_path=f"{US_DATA_BUCKET}/states/{abbrev}.h5",
+                dataset_path=resolve_region_dataset_path(
+                    "us",
+                    "state",
+                    state_code=abbrev,
+                ),
                 state_code=abbrev,
                 state_name=name,
             )
@@ -76,7 +81,11 @@ def build_us_region_registry() -> RegionRegistry:
                     label=label,
                     region_type="congressional_district",
                     parent_code=f"state/{state_abbrev.lower()}",
-                    dataset_path=f"{US_DATA_BUCKET}/districts/{district_code}.h5",
+                    dataset_path=resolve_region_dataset_path(
+                        "us",
+                        "congressional_district",
+                        district_code=district_code,
+                    ),
                     state_code=state_abbrev,
                     state_name=state_name,
                 )

policyengine-3.4.2/src/policyengine/data/release_manifests/uk.json

@@ -0,0 +1,27 @@
+{
+  "country_id": "uk",
+  "policyengine_version": "3.4.1",
+  "model_package": {
+    "name": "policyengine-uk",
+    "version": "2.78.0"
+  },
+  "data_package": {
+    "name": "policyengine-uk-data",
+    "version": "1.40.3",
+    "repo_id": "policyengine/policyengine-uk-data-private"
+  },
+  "default_dataset": "enhanced_frs_2023_24",
+  "datasets": {
+    "frs_2023_24": {
+      "path": "frs_2023_24.h5"
+    },
+    "enhanced_frs_2023_24": {
+      "path": "enhanced_frs_2023_24.h5"
+    }
+  },
+  "region_datasets": {
+    "national": {
+      "path_template": "enhanced_frs_2023_24.h5"
+    }
+  }
+}

policyengine-3.4.2/src/policyengine/data/release_manifests/us.json

@@ -0,0 +1,30 @@
+{
+  "country_id": "us",
+  "policyengine_version": "3.4.1",
+  "model_package": {
+    "name": "policyengine-us",
+    "version": "1.602.0"
+  },
+  "data_package": {
+    "name": "policyengine-us-data",
+    "version": "1.77.0",
+    "repo_id": "policyengine/policyengine-us-data"
+  },
+  "default_dataset": "enhanced_cps_2024",
+  "datasets": {
+    "enhanced_cps_2024": {
+      "path": "enhanced_cps_2024.h5"
+    }
+  },
+  "region_datasets": {
+    "national": {
+      "path_template": "enhanced_cps_2024.h5"
+    },
+    "state": {
+      "path_template": "states/{state_code}.h5"
+    },
+    "congressional_district": {
+      "path_template": "districts/{district_code}.h5"
+    }
+  }
+}

{policyengine-3.4.0 → policyengine-3.4.2}/src/policyengine/outputs/decile_impact.py

@@ -97,32 +97,48 @@ class DecileImpact(Output):
 
 
 def calculate_decile_impacts(
-    dataset: Dataset,
-    tax_benefit_model_version: TaxBenefitModelVersion,
+    dataset: Dataset | None = None,
+    tax_benefit_model_version: TaxBenefitModelVersion | None = None,
     baseline_policy: Policy | None = None,
     reform_policy: Policy | None = None,
     dynamic: Dynamic | None = None,
     income_variable: str = "equiv_hbai_household_net_income",
     entity: str | None = None,
     quantiles: int = 10,
+    baseline_simulation: Simulation | None = None,
+    reform_simulation: Simulation | None = None,
 ) -> OutputCollection[DecileImpact]:
     """Calculate decile-by-decile impact of a reform.
 
     Returns:
         OutputCollection containing list of DecileImpact objects and DataFrame
     """
-    baseline_simulation = Simulation(
-        dataset=dataset,
-        tax_benefit_model_version=tax_benefit_model_version,
-        policy=baseline_policy,
-        dynamic=dynamic,
-    )
-    reform_simulation = Simulation(
-        dataset=dataset,
-        tax_benefit_model_version=tax_benefit_model_version,
-        policy=reform_policy,
-        dynamic=dynamic,
-    )
+    if (baseline_simulation is None) != (reform_simulation is None):
+        raise ValueError(
+            "baseline_simulation and reform_simulation must be provided together"
+        )
+
+    if baseline_simulation is None:
+        if dataset is None or tax_benefit_model_version is None:
+            raise ValueError(
+                "dataset and tax_benefit_model_version are required when simulations are not provided"
+            )
+
+        baseline_simulation = Simulation(
+            dataset=dataset,
+            tax_benefit_model_version=tax_benefit_model_version,
+            policy=baseline_policy,
+            dynamic=dynamic,
+        )
+        reform_simulation = Simulation(
+            dataset=dataset,
+            tax_benefit_model_version=tax_benefit_model_version,
+            policy=reform_policy,
+            dynamic=dynamic,
+        )
+
+    baseline_simulation.ensure()
+    reform_simulation.ensure()
 
     results = []
     for decile in range(1, quantiles + 1):

{policyengine-3.4.0 → policyengine-3.4.2}/src/policyengine/tax_benefit_models/uk/__init__.py

@@ -31,6 +31,7 @@ if find_spec("policyengine_uk") is not None:
     UKYearData.model_rebuild()
     PolicyEngineUKDataset.model_rebuild()
     PolicyEngineUKLatest.model_rebuild()
+    ProgrammeStatistics.model_rebuild()
 
     __all__ = [
         "UKYearData",