{modparams} 🛵📦📝

Set up and modify NHP model parameter lists, and export them as JSON files.

While the repository is nhp_set_model_params, the R package is just modparams.

Installation

You should be able to run the following R command to install {modparams}:

# install.packages("pak") # if not already installed
pak::pak("The-Strategy-Unit/nhp_set_model_params")

Usage

Requirements

You will need a dataframe of intervals data to create the custom params file.

This might be generated via the composite scheme and nee intervals project, by rendering the qmd file there. This method by default will save an rds file into your current working directory.

Use readRDS() to read the file into R, creating a list object that will contain multiple tables of interval data.

(Alternatively, extend the code within your own copy of the qmd file, processing the intervals_list object that is created, rather than using the rds file outside the qmd.)

Create custom params!

There are a couple of ways to approach this. The first option is probably preferable.

1. You might do something like this:

intervals_list <- readRDS("intervals_data_from_qmd.rds")

model_version <- "v4.4"
# config skeleton for NHP model version 4.4
config_file <- modparams::get_config_filepath(model_version)

# `write_params_json()` writes a file to disk, and returns the path to the file
file_out <- modparams::write_params_json(
  config_file,
  intervals_list[[1]], # it is probably safer to use the list element name
  dataset = "ZZZ",
  scenario = "my-custom-scenario", # check this matches the intervals data
  seed = 87654L, # can be any random integer
  user = "nhp.user", # you should use your own name/username
  end_year = 2039L # supply years as integers (with the `L` suffix) or strings
)

2. Or you could edit a YAML config file directly, in which case you can do:

config_file <- "custom_config.yaml"
file.copy(modparams::get_config_filepath(model_version), config_file)

# ! Now manually edit custom_config.yaml to add dataset, scenario, user etc.

file_out <- modparams::write_params_json(config_file, intervals_list[[1]])

Validate your generated params file

You can validate the file you have just created:

modparams::validate_files(file_out, model_version)

(note that write_params_json() returns the file path to the file it created.)

This should return TRUE if your file validates according to the NHP model JSON Schema, or return FALSE.

You can use error = TRUE to get the function to error if the file is invalid:

modparams::validate_files(file_out, model_version, error = TRUE)

Things to note

There are certain params you as the user must supply:

• config_file
• intervals_data
• dataset*
• scenario*
• seed*
• user*

* supplied within ... or by editing the config file

Other arguments can be used to overwrite the default values in the config file. This is probably easier than editing the config file directly; but whatever suits you.

In the above example, although end_year has a default value in the config file, this is overridden by the value passed into the function via ....

Limitations / future development

Please make suggestions for future development via the Issues area of the repo. And of course report any problems or bugs found, noting what you expected to happen and what you actually observed.

Currently (April 2026) we are at v4.4 of the NHP model:

• The package currently only handles NDG3 values.
• Only "linear" time profiles are catered for, which matches the current design of the NHP model.
• The v4.4 YAML config file included in the package is likely to be suitable for use with any later v4.x versions. But future versions (eg from v5) may require updated YAML skeleton configs.