Create a Simulation Configuration File

This function generates a JSON/HDF5/YAML configuration file to be used as transmission model simulation parameters. It validates all input parameters and, if an output file path is provided, writes the parameters to a file. The file extension determines which output format is used:

.json or .json.gz → written with write_list_to_json,
.h5, .hdf5, .h5.gz or .hdf5.gz → written with write_list_to_hdf5,
.yaml or .yaml.gz → written with write_list_to_yaml.

Usage

make_simulation_config(
  output_file_path = NULL,
  seed = NULL,
  date_start = NULL,
  date_stop = NULL,
  location_name = NULL,
  N_j_initial = NULL,
  S_j_initial = NULL,
  E_j_initial = NULL,
  I_j_initial = NULL,
  R_j_initial = NULL,
  V1_j_initial = NULL,
  V2_j_initial = NULL,
  prop_S_initial = NULL,
  prop_E_initial = NULL,
  prop_I_initial = NULL,
  prop_R_initial = NULL,
  prop_V1_initial = NULL,
  prop_V2_initial = NULL,
  b_jt = NULL,
  d_jt = NULL,
  nu_1_jt = NULL,
  nu_2_jt = NULL,
  phi_1 = NULL,
  phi_2 = NULL,
  omega_1 = NULL,
  omega_2 = NULL,
  nu_jt_sources = c("S", "E", "Isym", "Iasym", "R"),
  iota = NULL,
  gamma_1 = NULL,
  gamma_2 = NULL,
  epsilon = NULL,
  mu_jt = NULL,
  mu_j_baseline = NULL,
  mu_j_slope = NULL,
  mu_j_epidemic_factor = NULL,
  rho = NULL,
  rho_deaths = NULL,
  sigma = NULL,
  chi_endemic = NULL,
  chi_epidemic = NULL,
  epidemic_threshold = NULL,
  delta_reporting_cases = NULL,
  delta_reporting_deaths = NULL,
  longitude = NULL,
  latitude = NULL,
  mobility_omega = NULL,
  mobility_gamma = NULL,
  tau_i = NULL,
  beta_j0_tot = NULL,
  p_beta = NULL,
  beta_j0_hum = NULL,
  a_1_j = NULL,
  a_2_j = NULL,
  b_1_j = NULL,
  b_2_j = NULL,
  p = 365L,
  alpha_1 = NULL,
  alpha_2 = NULL,
  beta_j0_env = NULL,
  theta_j = NULL,
  psi_jt = NULL,
  psi_star_a = NULL,
  psi_star_b = NULL,
  psi_star_z = NULL,
  psi_star_k = NULL,
  zeta_1 = NULL,
  zeta_2 = NULL,
  kappa = NULL,
  decay_days_short = NULL,
  decay_days_long = NULL,
  decay_shape_1 = NULL,
  decay_shape_2 = NULL,
  reported_cases = NULL,
  reported_deaths = NULL,
  epidemic_peaks = NULL,
  sigfigs = 8
)

Arguments

output_file_path: A character string representing the full file path of the output file. Must have a .json, .json.gz, .h5, .hdf5, .h5.gz, .hdf5.gz, .yaml, or .yaml.gz extension. If NULL, no file is written. The validated parameters are returned either way.
seed: Integer scalar giving the random seed value for the simulation run.

Initialization

Parameters defining the simulation window and the initial compartment sizes (and optional proportions) for each location.
date_start: Start date for the simulation period in "YYYY-MM-DD" format. If provided as a character string, it will be converted to a Date object.
date_stop: End date for the simulation period in "YYYY-MM-DD" format. If provided as a character string, it will be converted to a Date object.
location_name: A character vector giving the names of each metapopulation location. The order and names here must match those used in the initial population vectors.
N_j_initial: A named numeric or integer vector of length equal to location_name giving the total initial population size for each location. Note that total population size must be the sum of all model compartments.
S_j_initial: A named numeric or integer vector of length equal to location_name giving the starting number of susceptible individuals for each location. Names must match location_name.
E_j_initial: A named numeric or integer vector of length equal to location_name giving the starting number of exposed individuals for each location. Names must match location_name.
I_j_initial: A named numeric or integer vector of length equal to location_name giving the starting number of infected individuals for each location. Names must match location_name.
R_j_initial: A named numeric or integer vector of length equal to location_name giving the starting number of recovered individuals for each location. Names must match location_name.
V1_j_initial: A named numeric or integer vector of length equal to location_name giving the starting number of individuals in vaccine compartment V1 for each location. Names must match location_name.
V2_j_initial: A named numeric or integer vector of length equal to location_name giving the starting number of individuals in vaccine compartment V2 for each location. Names must match location_name.
prop_S_initial: Optional. A named numeric vector of length equal to location_name giving the starting proportion of susceptible individuals for each location. Values must be in [0,1]. Names must match location_name. These proportion fields are provided for analysis convenience but are not required by the transmission model.
prop_E_initial: Optional. A named numeric vector of length equal to location_name giving the starting proportion of exposed individuals for each location. Values must be in [0,1]. Names must match location_name.
prop_I_initial: Optional. A named numeric vector of length equal to location_name giving the starting proportion of infected individuals for each location. Values must be in [0,1]. Names must match location_name.
prop_R_initial: Optional. A named numeric vector of length equal to location_name giving the starting proportion of recovered individuals for each location. Values must be in [0,1]. Names must match location_name.
prop_V1_initial: Optional. A named numeric vector of length equal to location_name giving the starting proportion of individuals in vaccine compartment V1 for each location. Values must be in [0,1]. Names must match location_name.
prop_V2_initial: Optional. A named numeric vector of length equal to location_name giving the starting proportion of individuals in vaccine compartment V2 for each location. Values must be in [0,1]. Names must match location_name.

Demographics

Time-varying birth and mortality rate matrices.
b_jt: A matrix of birth rates with rows equal to length(location_name) and columns equal to the daily sequence from date_start to date_stop.
d_jt: A matrix of mortality rates with rows equal to length(location_name) and columns equal to the daily sequence from date_start to date_stop.

Vaccination

OCV dosing schedules, dose effectiveness, waning rates, and eligible source compartments.
nu_1_jt: A matrix of first-dose OCV vaccinations for each location and time step.
nu_2_jt: A matrix of second-dose OCV vaccinations for each location and time step.
phi_1: Effectiveness of one dose of OCV (numeric in [0, 1]).
phi_2: Effectiveness of two doses of OCV (numeric in [0, 1]).
omega_1: Waning immunity rate for one dose (numeric >= 0).
omega_2: Waning immunity rate for two doses (numeric >= 0).
nu_jt_sources: Character vector of compartment names eligible for first-dose vaccination (default c("S", "E", "Isym", "Iasym", "R")). Must be a non-empty subset of c("S", "E", "Isym", "Iasym", "R"). Passed to laser-cholera v0.12+ which draws first doses proportionally from all listed compartments.

Infection dynamics

Transition rates between SEIR compartments and the reported case fatality ratio mu_jt.
iota: Incubation rate E -> I (numeric > 0, per day). Note this is a rate, not a period – prior median ~0.71/day. The engine uses iota * E as the flow out of E.
gamma_1: Symptomatic shedding-duration rate I_sym -> R (numeric, >= 0, per day; "severe / symptomatic" branch).
gamma_2: Asymptomatic shedding-duration rate I_asym -> R (numeric, >= 0, per day; "mild / asymptomatic" branch).
epsilon: Natural-infection immunity waning rate R -> S (numeric, >= 0, per day). Distinct from vaccine waning (omega_1, omega_2).
mu_jt: Reported case fatality ratio (reported deaths per reported suspected case) by location and day: a matrix with rows equal to length(location_name) and columns equal to the daily sequence from date_start to date_stop, a per-location vector (constant in time) or a scalar. Values in [0, 1). The returned config always carries the full matrix. The engine converts it each tick to the probability that a new symptomatic onset is fatal, mu_jt * rho / (rho_deaths * chi_epidemic), so reported deaths over reported cases equal mu_jt on epidemic-PPV ticks. On endemic-PPV ticks the reported CFR is mu_jt * chi_endemic / chi_epidemic, so in an endemic-dominated location the calibrated mu_jt (and true deaths with it) can exceed the observed CFR by up to chi_epidemic / chi_endemic. Build it from WHO annual data with est_CFR_hierarchical() and make_mu_jt().
mu_j_baseline: Removed in v0.96.0. The pre-v0.96.0 baseline daily mortality hazard. Supplying it marks the input as a config written for the retired mortality model, whose mu_jt field was never read by any engine, so the call is refused rather than silently reinterpreting that matrix. Retained in the signature so the refusal names the problem.
mu_j_slope: Deprecated and ignored. The linear-in-time mortality trend (1 + mu_j_slope * tick/nticks) was removed from the engine in v0.95.0 (CFR restructure R3): it is not estimable from the deaths series, it double-counted the s(year) term already inside CFR_target, and no secular trend in cholera CFR is documented. Retained only so that existing calls that pass mu_j_slope explicitly do not fail with an unused-argument error; any value supplied is silently dropped and is not returned in the config.
mu_j_epidemic_factor: Removed in v0.96.0. The pre-v0.96.0 epidemic mortality multiplier; treated exactly like mu_j_baseline.

Observation Processes

Surveillance-cascade parameters mapping true infections and deaths to reported counts.
rho: Care-seeking rate: probability a symptomatic individual presents to surveillance (numeric in [0, 1]). Not a reporting fraction and not sigma – this is the upstream care-seeking step of the surveillance cascade.
rho_deaths: Death detection rate: probability a true cholera death is captured by surveillance (numeric in (0, 1]). The engine thins true deaths by it to produce reported_deaths, and divides by it when converting the reported CFR mu_jt to a per-onset fatality probability, so it sets true deaths without moving reported deaths.
sigma: Proportion of infections that are symptomatic (numeric in [0, 1]).
chi_endemic: Positive predictive value among suspected cases during endemic periods (numeric in (0, 1]).
chi_epidemic: Positive predictive value among suspected cases during epidemic periods (numeric in (0, 1]).
epidemic_threshold: Isym/N point prevalence threshold that switches the case-reporting PPV between chi_endemic and chi_epidemic. Numeric scalar or length-n vector in [0, 1].
delta_reporting_cases: Symptom-onset-to-surveillance reporting delay in days (non-negative integer). Not infection-to-report – incubation is handled separately by the E compartment and iota.
delta_reporting_deaths: Deprecated and ignored. Since v0.96.0 a death is reported on the same lag as its case (delta_reporting_cases), as the surveillance record it is scored against does. Retained so older configs still load; any value supplied is dropped and not returned.

Spatial model

Location coordinates and the gravity-model mobility parameters governing between-location movement.
longitude: A numeric vector of longitudes for each location. Must be same length as location_name.
latitude: A numeric vector of latitudes for each location. Must be same length as location_name.
mobility_omega: Exponent weight for destination population in the gravity mobility model. Must be numeric and non-negative.
mobility_gamma: Exponent weight for distance decay in the gravity mobility model. Must be numeric and non-negative.
tau_i: Departure probability for each origin location (numeric vector of length(location_name) in [0, 1]).

Force of Infection (human-to-human)

Baseline transmission rates, seasonal forcing harmonics, and FOI mixing exponents for direct human-to-human transmission.
beta_j0_tot: Total baseline transmission rate (human + environmental). Optional numeric vector of length(location_name). If provided with p_beta, used to derive beta_j0_hum and beta_j0_env.
p_beta: Proportion of total transmission that is human-to-human (0-1). Optional numeric vector of length(location_name). If provided with beta_j0_tot, used to derive beta_j0_hum and beta_j0_env.
beta_j0_hum: Baseline human-to-human transmission rate (numeric vector of length(location_name)). If beta_j0_tot and p_beta are provided, this will be validated against beta_j0_tot * p_beta.
a_1_j: Vector of sine amplitude coefficients (1st harmonic) for each location. Numeric, length = length(location_name).
a_2_j: Vector of sine amplitude coefficients (2nd harmonic) for each location. Numeric, length = length(location_name).
b_1_j: Vector of cosine amplitude coefficients (1st harmonic) for each location. Numeric, length = length(location_name).
b_2_j: Vector of cosine amplitude coefficients (2nd harmonic) for each location. Numeric, length = length(location_name).
p: Period of the seasonal forcing function. Scalar numeric > 0. Default is 365 for daily annual seasonality.
alpha_1: FOI mixing exponent applied to the infectious term (I/N) (numeric in (0, 1]; 1 = well-mixed contacts). Dual-mode (laser-cholera v0.16.0+): a scalar applied uniformly across patches, or a per-location vector of length length(location_name).
alpha_2: Exponent on N_jt in the FOI denominator (numeric in [0, 1]). alpha_2 = 1 is frequency-dependent transmission (FOI proportional to I/N); alpha_2 = 0 is density-dependent (FOI proportional to I). A single global scalar: the engine rejects a per-location vector.

Force of Infection (environment-to-human)

Environmental suitability, its calibration parameters, shedding rates, and V. cholerae decay parameters for environment-to-human transmission.
beta_j0_env: Baseline environment-to-human transmission rate (numeric vector of length(location_name)). If beta_j0_tot and p_beta are provided, this will be validated against beta_j0_tot * (1 - p_beta).
theta_j: Proportion with adequate WASH (numeric vector of length(location_name) in [0, 1]).
psi_jt: Matrix of environmental suitability values (matrix with rows = length(location_name) and columns equal to the daily sequence from date_start to date_stop).
psi_star_a: Shape/gain parameter for logit calibration of psi_jt (numeric vector of length(location_name) > 0). Values > 1 sharpen peaks, values < 1 flatten peaks. Default 1.0 (no transformation).
psi_star_b: Scale/offset parameter for logit calibration of psi_jt (numeric vector of length(location_name)). Shifts baseline up/down on logit scale. Default 0.0 (no offset).
psi_star_z: Smoothing weight for causal EWMA of calibrated psi_jt (numeric vector of length(location_name) in (0,1]). 1.0 = no smoothing, < 1.0 = apply smoothing. Default 1.0 (no smoothing).
psi_star_k: Time offset in days for psi_jt calibration (numeric vector of length(location_name)). Positive values = forward/delay, negative values = backward/advance. Default 0.0 (no offset).
zeta_1: Shedding rate (numeric > 0).
zeta_2: Asymptomatic shedding rate (numeric > 0). Derived by sample_parameters() as zeta_1 / zeta_ratio.
kappa: Concentration required for 50% infection (numeric > 0).
decay_days_short: Time constant (in days) for short-term survival of V. cholerae in the environment. Must be > 0 and < decay_days_long.
decay_days_long: Time constant (in days) for long-term survival of V. cholerae in the environment. Must be > 0 and > decay_days_short.
decay_shape_1: First shape parameter for beta distribution controlling how environmental suitability maps to the decay rate of V. cholerae in the environment. Must be numeric > 0.
decay_shape_2: Second shape parameter for beta distribution controlling how environmental suitability maps to the decay rate of V. cholerae in the environment. Must be numeric > 0.

Reported data

Observed surveillance series and epidemic-peak metadata used by the likelihood.
reported_cases: Matrix of daily reported cholera cases. Must be integer. NA allowed. nrow=length(location_name), ncol=length(t).
reported_deaths: Matrix of daily reported cholera deaths. Must be integer. NA allowed. nrow=length(location_name), ncol=length(t).
epidemic_peaks: Optional data.frame of observed epidemic peaks consumed by the peak-timing / peak-magnitude shape terms in calc_model_likelihood() (R and the Python port in laser-cholera). Must contain two character columns: iso_code (matching entries in location_name) and peak_date (ISO YYYY-MM-DD strings parseable by as.Date). NULL allowed; when NULL the peak shape terms contribute 0 to the likelihood.
sigfigs: Ignored; retained for backward compatibility. No rounding is applied, and supplying it raises a warning.

Value

The validated list of parameters (invisibly when output_file_path is provided, after the parameters are written to a file in the format determined by the file extension).

Examples

if (FALSE) { # \dontrun{
make_simulation_config(
     output_file_path = "parameters.json",
     seed = 123,
     date_start = "2024-12-01",
     date_stop = "2024-12-31",
     location_name = c("Location A", "Location B"),
     N_j_initial = c("Location A" = 1000, "Location B" = 1000),
     S_j_initial = c("Location A" = 900, "Location B" = 900),
     E_j_initial = c("Location A" = 0, "Location B" = 0),
     I_j_initial = c("Location A" = 50, "Location B" = 50),
     R_j_initial = c("Location A" = 50, "Location B" = 50),
     V1_j_initial = c("Location A" = 0, "Location B" = 0),
     V2_j_initial = c("Location A" = 0, "Location B" = 0),
     b_jt = matrix(data = 0.0015, nrow = 2, ncol = 366),
     d_jt = matrix(data = 0.001, nrow = 2, ncol = 366),
     nu_1_jt = matrix(data = 0, nrow = 2, ncol = 366),
     nu_2_jt = matrix(data = 0, nrow = 2, ncol = 366),
     phi_1 = 0.8,
     phi_2 = 0.85,
     omega_1 = 0.1,
     omega_2 = 0.12,
     iota = 1.4,
     gamma_1 = 0.2,
     gamma_2 = 0.25,
     epsilon = 0.05,
     mu_jt = c(0.02, 0.015),
     rho = 0.9,
     sigma = 0.5,
     beta_j0_hum = c(0.05, 0.03),
     a_1_j = c(0.02, 0.02),
     a_2_j = c(0.01, 0.01),
     b_1_j = c(0.03, 0.03),
     b_2_j = c(0.01, 0.01),
     p     = 365,
     longitude = c(36.8, 37.0),
     latitude = c(-1.3, -1.2),
     mobility_omega = 1.0,
     mobility_gamma = 2.0,
     tau_i = c(0.1, 0.2),
     alpha_1 = 0.95,
     alpha_2 = 1,
     beta_j0_env = c(0.02, 0.04),
     theta_j = c(0.6, 0.7),
     psi_jt = matrix(data = 0, nrow = 2, ncol = 366),
     zeta_1 = 0.5,
     zeta_2 = 0.4,
     kappa = 10^5,
     decay_days_short  = 3,
     decay_days_long   = 90,
     decay_shape_1     = 1,
     decay_shape_2     = 1,
     reported_cases    = matrix(NA, nrow=2, ncol=366),
     reported_deaths   = matrix(NA, nrow=2, ncol=366)
)
} # }

Usage

Arguments

Initialization

Demographics

Vaccination

Infection dynamics

Observation Processes

Spatial model

Force of Infection (human-to-human)

Force of Infection (environment-to-human)

Reported data

Value

Examples