Merge pull request #505 from The-Strategy-Unit/add_params_module

tomjemmett · web-flow · commit 53c7b9914213 · 2025-10-09T12:58:58.000+01:00
adds schema/sample params to src
diff --git a/.github/workflows/build_schema.yaml b/.github/workflows/build_schema.yaml
@@ -1,12 +1,12 @@
-name: Deploy schema.json to GitHub Pages 
+name: Deploy schema.json to GitHub Pages
 
 on:
   workflow_call:
     inputs:
       schema-tag:
         required: true
         default: dev
-        type: string  
+        type: string
 
 permissions:
   pages: write
@@ -28,7 +28,7 @@ jobs:
       - name: Copy schema to app version path
         run: |
           mkdir -p schemas/${{ inputs.schema-tag }}
-          sed '/$id/ s/dev/${{ inputs.schema-tag }}/' params-schema.json > schemas/${{ inputs.schema-tag }}/params-schema.json
+          sed '/$id/ s/dev/${{ inputs.schema-tag }}/' src/nhp/model/params/params-schema.json > schemas/${{ inputs.schema-tag }}/params-schema.json
 
       - name: Commit the schema
         run: |
@@ -39,7 +39,7 @@ jobs:
           git commit -m "adding schema for ${{ inputs.schema-tag }}" || echo "No changes to commit"
           git push origin schemas
           popd
-      
+
       - name: Upload to GitHub Pages
         uses: actions/upload-pages-artifact@v4
         with:
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -21,8 +21,8 @@
     {
       "id": "params_file",
       "type": "promptString",
-      "description": "Path to parameters file",
-      "default": "queue/params-sample.json"
+      "description": "Path to parameters file (leave empty to use sample parameters)",
+      "default": ""
     },
     {
       "id": "type",
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -5,8 +5,7 @@
   ],
   "python.testing.pytestArgs": [
     "tests",
-    "--data-dir=data/synth",
-    "--params-file=queue/params-sample.json"
+    "--data-dir=data/synth"
   ],
   "python.testing.unittestEnabled": false,
   "python.testing.pytestEnabled": true,
diff --git a/docs/index.md b/docs/index.md
@@ -13,9 +13,21 @@ Welcome to the NHP Model documentation. This project provides modeling capabilit
 Download and install [`uv`](https://docs.astral.sh/uv/getting-started/installation/), then run `uv sync`. Download data locally, e.g., download a synthetic dataset to `data/synth`. Then, run the model with:
 
 ``` bash
-uv run python -m nhp.model queue/params-sample.json -d data/synth --type all
+uv run python -m nhp.model -d data/synth --type all
 ```
 
+to run the model with the sample parameters.
+
+### Generating Sample Parameters
+
+you can generate sample parameters using the CLI command:
+
+``` bash
+python -m nhp.model.params --dataset [dataset] --scenario [scenario] --app-version dev > params.json
+```
+
+replacing the values as needed. This will generate a file `params.json` with the sample parameters.
+
 ## API Reference
 
 See the [Model Reference](reference/nhp/model/index.md) for detailed documentation of all classes and functions.
diff --git a/pyproject.toml b/pyproject.toml
@@ -9,6 +9,8 @@ dependencies = [
     "azure-identity>=1.12",
     "azure-storage-blob>=12.15",
     "azure-storage-file-datalake>=12.10",
+    "importlib-resources>=6.5.2",
+    "jsonschema>=4.23.0",
     "numpy>=1.23",
     "pandas>=1.5",
     "pyarrow>=20.0",
@@ -28,14 +30,14 @@ where = ["src"]
 
 [tool.setuptools.package-data]
 "nhp.model.data.reference" = ["*.csv", "*.json"]
+"nhp.model.params" = ["*.json"]
 
 [project.optional-dependencies]
 dev = [
     "coverage>=7.2",
     "ipykernel>=6.21",
     "ipython>=8.11",
     "ipywidgets>=8.0",
-    "jsonschema>=4.23.0",
     "jupyter_client>=8.0",
     "jupyter_core>=5.2",
     "jupyterlab_pygments>=0.2",
@@ -121,4 +123,4 @@ version_file = "src/nhp/model/_version.py"
 fallback_version = "0.0.0"
 
 [tool.ty.src]
-exclude = ["notebooks", "docs"]
+exclude = ["notebooks", "docs"]
diff --git a/readme.md b/readme.md
@@ -43,6 +43,6 @@ The model is deployed to Azure Container Registry and GitHub Container Registry
 
 ## JSON Schema
 
-Parameters for the model are set in JSON format; an example can be seen in `queue/params-sample.json`. As the model develops, requirements for this JSON file change over time. We use [JSON schema](https://json-schema.org/understanding-json-schema/about) to manage changes to the parameters file. From model v3.5 onwards, these are deployed to GitHub pages, following this pattern:
+Parameters for the model are set in JSON format; an example can be seen in `src/nhp/model/params/params-sample.json`. As the model develops, requirements for this JSON file change over time. We use [JSON schema](https://json-schema.org/understanding-json-schema/about) to manage changes to the parameters file. From model v3.5 onwards, these are deployed to GitHub pages, following this pattern:
 - on merge to `main`, the schema is deployed to `https://the-strategy-unit.github.io/nhp_model/dev/params-schema.json`
 - on release of new model version vX.X, the schema is deployed to `https://the-strategy-unit.github.io/nhp_model/vX.X/params-schema.json`
diff --git a/src/nhp/docker/__main__.py b/src/nhp/docker/__main__.py
@@ -14,8 +14,6 @@ def parse_args():
     parser = argparse.ArgumentParser()
     parser.add_argument(
         "params_file",
-        nargs="?",
-        default="params-sample.json",
         help="Name of the parameters file stored in Azure",
     )
 
diff --git a/src/nhp/docker/run.py b/src/nhp/docker/run.py
@@ -13,7 +13,7 @@
 from azure.storage.filedatalake import DataLakeServiceClient
 
 from nhp.docker.config import Config
-from nhp.model.helpers import load_params
+from nhp.model.params import load_params
 from nhp.model.run import noop_progress_callback
 
 
diff --git a/src/nhp/model/__init__.py b/src/nhp/model/__init__.py
@@ -4,8 +4,8 @@
 from nhp.model.aae import AaEModel
 from nhp.model.activity_resampling import ActivityResampling
 from nhp.model.health_status_adjustment import HealthStatusAdjustmentInterpolated
-from nhp.model.helpers import load_params
 from nhp.model.inpatients import InpatientEfficiencies, InpatientsModel
 from nhp.model.model import Model
 from nhp.model.model_iteration import ModelIteration
 from nhp.model.outpatients import OutpatientsModel
+from nhp.model.params import load_params, load_sample_params
diff --git a/src/nhp/model/__main__.py b/src/nhp/model/__main__.py
@@ -17,9 +17,9 @@
 
 from nhp.model.aae import AaEModel
 from nhp.model.data import Local
-from nhp.model.helpers import load_params
 from nhp.model.inpatients import InpatientsModel
 from nhp.model.outpatients import OutpatientsModel
+from nhp.model.params import load_params, load_sample_params
 from nhp.model.run import run_all, run_single_model_run
 
 
@@ -28,8 +28,8 @@ def _parse_args() -> argparse.Namespace:  # pragma: no cover
     parser.add_argument(
         "params_file",
         nargs="?",
-        default="queue/params-sample.json",
-        help="Path to the params.json file",
+        default="",
+        help="Path to the params.json file (leave empty to use sample parameters).",
     )
     parser.add_argument("-d", "--data-path", help="Path to the data", default="data")
     parser.add_argument(
@@ -54,7 +54,10 @@ def main() -> None:
     """
     # Grab the Arguments
     args = _parse_args()
-    params = load_params(args.params_file)
+    if args.params_file == "":
+        params = load_sample_params()
+    else:
+        params = load_params(args.params_file)
     # define the model to run
     match args.type:
         case "all":
diff --git a/src/nhp/model/helpers.py b/src/nhp/model/helpers.py
@@ -35,16 +35,3 @@ def rnorm(rng: np.random.Generator, low: float, high: float) -> float:
     mean = (high + low) / 2
     stdev = (high - low) / q
     return rng.normal(mean, stdev)
-
-
-def load_params(filename: str) -> dict:
-    """Load a params file.
-
-    Args:
-        filename: The full name of the file that we wish to load.
-
-    Returns:
-        The model parameters.
-    """
-    with open(filename, "r", encoding="UTF-8") as prf:
-        return json.load(prf)
diff --git a/src/nhp/model/model.py b/src/nhp/model/model.py
@@ -22,8 +22,9 @@
     HealthStatusAdjustment,
     HealthStatusAdjustmentInterpolated,
 )
-from nhp.model.helpers import inrange, load_params, rnorm
+from nhp.model.helpers import inrange, rnorm
 from nhp.model.model_iteration import ModelIteration, ModelRunResult
+from nhp.model.params import load_params
 
 
 class Model:
@@ -50,8 +51,8 @@ class Model:
 
     Example:
         >>> from nhp.model.aae import AaEModel
-        >>> from nhp.model.helpers import load_params
-        >>> params = load_params("params-sample.json")
+        >>> from nhp.model.params import load_sample_params
+        >>> params = load_sample_params()
         >>> m = AaEModel(params, data)
         >>> model_iteration = ModelIteration(m, 0)
         >>> aggregated_results, step_counts = model_iteration.get_aggregate_results()
diff --git a/src/nhp/model/params/__init__.py b/src/nhp/model/params/__init__.py
@@ -0,0 +1,69 @@
+"""Module for working with model parameter files."""
+
+import json
+
+import jsonschema
+from importlib_resources import files
+
+from nhp.model import params as params_module
+
+
+def validate_params(params: dict) -> None:
+    """Validate model parameters.
+
+    Args:
+        params: The model parameters to validate.
+
+    Raises:
+        jsonschema.ValidationError: If the parameters are not valid.
+    """
+    with (
+        files(params_module)
+        .joinpath("params-schema.json")
+        .open("r", encoding="UTF-8") as schema_file
+    ):
+        schema = json.load(schema_file)
+
+    jsonschema.validate(instance=params, schema=schema)
+
+
+def load_params(filename: str) -> dict:
+    """Load a params file.
+
+    Args:
+        filename: The full name of the file that we wish to load.
+
+    Raises:
+        jsonschema.ValidationError: If the parameters are not valid.
+
+    Returns:
+        The model parameters.
+    """
+    with open(filename, "r", encoding="UTF-8") as prf:
+        params = json.load(prf)
+
+    validate_params(params)
+
+    return params
+
+
+def load_sample_params(**kwargs) -> dict:
+    """Load a sample params file.
+
+    Args:
+        **kwargs: Any parameters to override in the sample params.
+
+    Raises:
+        jsonschema.ValidationError: If the parameters are not valid.
+
+    Returns:
+        The model parameters.
+    """
+    with files(params_module).joinpath("params-sample.json").open("r", encoding="UTF-8") as prf:
+        params = json.load(prf)
+
+    params.update(kwargs)
+
+    validate_params(params)
+
+    return params
diff --git a/src/nhp/model/params/__main__.py b/src/nhp/model/params/__main__.py
@@ -0,0 +1,55 @@
+"""Generate sample parameters."""
+
+import argparse
+import json
+import random
+from datetime import datetime
+
+from . import load_sample_params
+
+
+def _parse_args():
+    parser = argparse.ArgumentParser(description="CLI for loading sample parameters.")
+    parser.add_argument("--dataset", required=True, help="Dataset name")
+    parser.add_argument("--scenario", required=True, help="Scenario name")
+    parser.add_argument("--app-version", default="dev", help="App version (default: dev)")
+    parser.add_argument("--model-runs", type=int, default=256, help="Model Runs (default: 256)")
+    parser.add_argument("--start-year", type=int, default=2023, help="Start year (default: 2023)")
+    parser.add_argument("--end-year", type=int, default=2041, help="End year (default: 2041)")
+    parser.add_argument(
+        "--seed",
+        type=int,
+        default=None,
+        help="Random seed (default: a random integer between 0 and 10000)",
+    )
+
+    return parser.parse_args()
+
+
+def main():
+    """Generate sample parameters and print them to the console."""
+    args = _parse_args()
+
+    if args.seed is None:
+        args.seed = random.randint(0, 10000)
+
+    params = load_sample_params(
+        dataset=args.dataset,
+        scenario=args.scenario,
+        app_version=args.app_version,
+        start_year=args.start_year,
+        end_year=args.end_year,
+        seed=args.seed,
+    )
+
+    params["create_datetime"] = datetime.now().strftime("%Y%m%d_%H%M%S")
+
+    print(json.dumps(params, indent=2))
+
+
+def _init():
+    main()
+
+
+if __name__ == "__main__":
+    _init()
diff --git a/src/nhp/model/params/params-sample.json b/src/nhp/model/params/params-sample.json
@@ -27,20 +27,6 @@
     ],
     "level_down": []
   },
-  "op": {
-    "first": [
-      1.017960,
-      1.017960
-    ],
-    "followup": [
-      1.014095,
-      1.014095
-    ],
-    "procedure": [
-      1.026097,
-      1.026097
-    ]
-  },
   "expat": {
     "ip": {
       "elective": {
diff --git a/src/nhp/model/params/params-schema.json b/src/nhp/model/params/params-schema.json
@@ -32,7 +32,7 @@
         },
         "app_version": {
             "type": "string",
-            "pattern": "^(v\\d+\\.\\d+|dev)$"
+            "pattern": "^(v\\d+\\.\\d+|dev|pr-\\d+)$"
         },
         "create_datetime": {
             "type": "string"
diff --git a/tests/conftest.py b/tests/conftest.py
@@ -2,17 +2,9 @@
 
 
 def pytest_addoption(parser):
-    parser.addoption("--data-dir", help="Directory containing data", default="data/dev")
-    parser.addoption(
-        "--params-file", help="Path to the parameters file", default="queue/params-sample.json"
-    )
+    parser.addoption("--data-dir", help="Directory containing data", default="data/synth")
 
 
 @pytest.fixture
 def data_dir(request):
     return request.config.getoption("--data-dir")
-
-
-@pytest.fixture
-def params_path(request):
-    return request.config.getoption("--params-file")
diff --git a/tests/integration/nhp/model/test_run_model.py b/tests/integration/nhp/model/test_run_model.py
diff --git a/tests/unit/nhp/docker/test___main__.py b/tests/unit/nhp/docker/test___main__.py
diff --git a/tests/unit/nhp/model/test__main__.py b/tests/unit/nhp/model/test__main__.py
diff --git a/tests/unit/nhp/model/test_helpers.py b/tests/unit/nhp/model/test_helpers.py
diff --git a/tests/unit/nhp/model/test_params.py b/tests/unit/nhp/model/test_params.py
diff --git a/uv.lock b/uv.lock

Original file line number	Diff line number	Diff line change
`@@ -21,8 +21,8 @@`
`21`	`21`	`{`
`22`	`22`	`"id": "params_file",`
`23`	`23`	`"type": "promptString",`
`24`		`- "description": "Path to parameters file",`
`25`		`- "default": "queue/params-sample.json"`
	`24`	`+ "description": "Path to parameters file (leave empty to use sample parameters)",`
	`25`	`+ "default": ""`
`26`	`26`	`},`
`27`	`27`	`{`
`28`	`28`	`"id": "type",`
Original file line number	Diff line number	Diff line change
`@@ -14,8 +14,6 @@ def parse_args():`
`14`	`14`	`parser = argparse.ArgumentParser()`
`15`	`15`	`parser.add_argument(`
`16`	`16`	`"params_file",`
`17`		`- nargs="?",`
`18`		`- default="params-sample.json",`
`19`	`17`	`help="Name of the parameters file stored in Azure",`
`20`	`18`	`)`
`21`	`19`