Skip to content

Parameter reference

Every top-level field in default_parameters.json is documented on one of the ten parameter group pages. Each parameter has a definition, shape, dtype, valid range, a link to the model section that consumes it, and — most importantly — the value that turns the feature it gates off. The grouped table below lets you skim a feature area (vaccination, mobility, environmental transmission, ...) and jump straight to the entries on that page; the alphabetical table at the bottom is the lookup index for "I have a parameter name, where is it?".

Every parameter listed below is exercised by the coverage test tests/test_docs_param_coverage.py, which fails if a default_parameters.json key is undocumented or appears on more than one group page. The test is the source of truth for completeness; this index is the source of truth for navigation.

Grouped tables

Run identity and calendar

Anchors the run: PRNG seed, calendar window, and the ordered patch labels that define npatches and every per-patch vector's element order.

Parameter One-line description
date_start Calendar date of simulation tick 0; together with date_stop it defines the run length (nticks = (date_stop - date_start).days + 1).
date_stop Calendar date of the final simulation tick; with date_start it bounds the run window and sets nticks.
location_name Ordered list of patch/admin-unit labels; its length defines npatches and its order defines every per-patch vector's element ordering.
seed Integer seed for the model's pseudo-random number generator; setting it pins all stochastic draws to a reproducible sequence.

Initial populations

Per-patch seed counts (and unused proportions) for the seven live compartments at tick 0.

Parameter One-line description
E_j_initial Per-patch initial number of exposed (latent, not yet infectious) people seeded into the E compartment at tick 0.
I_j_initial Per-patch initial number of infectious people; split by sigma into symptomatic (Isym) and asymptomatic (Iasym) at tick 0.
N_j_initial Total initial population per patch (used as the gravity-model destination mass when reconstructing the mobility matrix, though the live code now sums the per-compartment initials instead).
R_j_initial Per-patch initial number of recovered (immune) people seeded into the R compartment at tick 0.
S_j_initial Per-patch initial number of susceptible people seeded into the S compartment at tick 0.
V1_j_initial Per-patch initial number of one-dose-vaccinated people seeded into the V1 compartment at tick 0.
V2_j_initial Per-patch initial number of two-dose-vaccinated people seeded into the V2 compartment at tick 0.
prop_E_initial Per-patch initial fraction of population in the E compartment (informational / upstream-MOSAIC artifact; not read by the model).
prop_I_initial Per-patch initial fraction of population in the I compartment (informational / upstream-MOSAIC artifact; not read by the model).
prop_R_initial Per-patch initial fraction of population in the R compartment (informational / upstream-MOSAIC artifact; not read by the model).
prop_S_initial Per-patch initial fraction of population in the S compartment (informational / upstream-MOSAIC artifact; not read by the model itself).
prop_V1_initial Per-patch initial fraction of population in the V1 compartment (informational / upstream-MOSAIC artifact; not read by the model).
prop_V2_initial Per-patch initial fraction of population in the V2 compartment (informational / upstream-MOSAIC artifact; not read by the model).

Vital dynamics

Per-tick birth, non-disease mortality, and disease-mortality rates applied to the live compartments.

Parameter One-line description
b_jt Per-patch, per-tick crude birth rate; the Poisson mean for new susceptibles each day is N * b_jt[tick].
d_jt Per-patch, per-tick non-disease (background) mortality rate applied to every live compartment (S, E, Isym, Iasym, R, V1, V2).
mu_j_baseline Per-patch baseline disease (cholera) mortality rate applied to symptomatic infectious; the multiplicative anchor of the mu_jt = mu_baseline * (1 + slope*t) * (1 + epidemic_factor*flag) formula.
mu_j_epidemic_factor Per-patch multiplicative boost on disease mortality when the patch is flagged as being in an epidemic regime (reported symptomatic infectious exceeds epidemic_threshold * N).
mu_j_slope Per-patch linear time-trend on disease mortality; mu_jt is scaled by (1 + mu_j_slope * tick/nticks) so positive values ramp mortality up over the run and negative values ramp it down.
mu_jt Disease mortality time-series stored on the parameter set for diagnostic plotting only — the simulation loop computes its own per-tick mu_jt from baseline/slope/epidemic_factor and ignores this array.

Vaccination

First- and second-dose campaigns: delivery counts, dose effectiveness, waning, and the source-compartment list.

Parameter One-line description
nu_1_jt Number of first-dose vaccinations to deliver per tick and per patch.
nu_2_jt Number of second-dose vaccinations to deliver per tick and per patch (moves V1 to V2).
nu_jt_sources List of compartment names from which first-dose vaccinations are drawn (proportional sampling across the listed compartments).
omega_1 Daily waning rate from V1 back to S; converted to a per-tick probability via 1 - exp(-omega_1).
omega_2 Daily waning rate from V2 back to S; converted to a per-tick probability via 1 - exp(-omega_2).
phi_1 Effectiveness (take fraction) of a first dose: only this fraction of delivered doses moves the recipient into V1.
phi_2 Effectiveness (take fraction) of a second dose: only this fraction of V1 recipients moves into V2.

Disease progression

Per-day rates for the SEIR backbone: latency, recovery, waning natural immunity, and the symptomatic/asymptomatic split.

Parameter One-line description
epsilon Per-day rate at which natural immunity wanes (R -> S).
gamma_1 Per-day recovery rate for symptomatic infectious individuals (I_sym -> R).
gamma_2 Per-day recovery rate for asymptomatic infectious individuals (I_asym -> R).
iota Per-day rate at which exposed (E) individuals progress to becoming infectious (I_sym or I_asym).
sigma Fraction of new infections that become symptomatic (the rest go to the asymptomatic compartment).

Reporting

Observed-data inputs (case / death series) and the under-reporting + lag knobs that turn modeled cases into reported cases.

Parameter One-line description
delta_reporting_cases Integer tick lag between when a new symptomatic case occurs and when it is added to reported_cases.
delta_reporting_deaths Integer tick lag between when a disease death occurs and when it is added to reported_deaths.
reported_cases Observed per-patch-per-time-step case counts used as the target series when computing the model likelihood.
reported_deaths Observed per-patch-per-time-step death counts used as the target series when computing the model likelihood.
rho Per-case reporting probability for symptomatic cases — fraction of new symptomatic infections that show up in the reported_cases series.
rho_deaths Per-death reporting probability — fraction of disease deaths that show up in the reported_deaths series.

Regime switching

Endemic-vs-epidemic regime: threshold, reporting-rate divisors per regime, and the observed peak dates the likelihood scorer uses.

Parameter One-line description
chi_endemic Reporting-rate divisor used when local symptomatic-infected fraction is below epidemic_threshold (endemic regime); inflates estimated cases via division.
chi_epidemic Reporting-rate divisor used when local symptomatic-infected fraction is at or above epidemic_threshold (epidemic regime); inflates estimated cases via division.
epidemic_peaks Observed epidemic peak dates per ISO code used by the likelihood scorer to evaluate peak-timing and peak-magnitude shape terms; not consumed by the simulation dynamics.
epidemic_threshold Per-patch (or global) symptomatic-infected fraction above which the patch is treated as in an epidemic regime, switching both the disease-mortality multiplier and the reporting-rate divisor.

Geography and mobility

Per-patch coordinates, the master spatial-mixing fraction tau_i, and the gravity-model exponents that build pi_ij.

Parameter One-line description
latitude Per-patch latitude coordinate; combined with longitude for inter-patch distance in the gravity-mobility kernel (and used to order patches in one plot).
longitude Per-patch longitude coordinate; used together with latitude to compute great-circle distances that feed the gravity-model mobility matrix.
mobility_gamma Exponent on inter-patch distance (with sign reversed) in the gravity model; larger values penalize long-distance movement more strongly when building pi_ij.
mobility_omega Exponent on the destination population in the gravity model that builds the patch-to-patch coupling matrix pi_ij; larger values pull more flow toward larger patches.
tau_i Per-patch fraction of infectious (and, for environmental exposure, susceptible) individuals that move out of their home patch; the master switch for spatial mixing.

Human-to-human transmission

Per-patch baseline transmission, the two-harmonic seasonal envelope, and the mixing-nonlinearity exponents.

Parameter One-line description
a_1_j Per-patch amplitude of the first (annual) cosine term of the seasonal-transmission harmonic.
a_2_j Per-patch amplitude of the second (semi-annual) cosine term of the seasonal-transmission harmonic.
alpha_1 Exponent on the effective-infected count in the human-to-human force-of-infection (mixing nonlinearity in the numerator).
alpha_2 Exponent on the patch population in the FOI denominator; alpha_2=1 = frequency-dependent mixing, alpha_2=0 = density-dependent.
b_1_j Per-patch amplitude of the first (annual) sine term of the seasonal-transmission harmonic.
b_2_j Per-patch amplitude of the second (semi-annual) sine term of the seasonal-transmission harmonic.
beta_j0_hum Per-patch baseline human-to-human transmission rate; multiplied by the seasonal harmonic to produce the per-tick, per-patch transmission envelope.
beta_j0_tot Per-patch combined baseline transmission rate (legacy / metadata field carried from upstream MOSAIC R config; not consumed by the Python simulation loop).
p Period (in ticks/days) of the seasonal-transmission harmonic; typically 365 for an annual cycle.
p_beta Per-patch split fraction between human-to-human and environmental transmission in the upstream R model (legacy metadata; not consumed by the Python simulation loop).

Environmental transmission

Environmental-reservoir transmission to humans, WASH coverage, shedding rates, suitability forcing, and reservoir decay.

Parameter One-line description
beta_j0_env Per-patch baseline environmental-reservoir-to-human transmission rate; multiplier on the W/(kappa+W) saturation term in the env force of infection.
decay_days_long Longest reservoir half-life (in days) at the low end of the suitability-to-decay map; 1/decay_days_long is the minimum decay rate.
decay_days_short Shortest reservoir half-life (in days) at the high end of the suitability-to-decay map; 1/decay_days_short is the maximum decay rate.
decay_days_spread MOSAIC-side scratch parameter describing the spread between fast and slow decay (days); carried in the parameter set but NOT consumed by any laser-cholera simulation code.
decay_shape_1 Alpha shape parameter of the Beta CDF used to map psi_jt in [0, 1] onto the [decay_days_short, decay_days_long] interval.
decay_shape_2 Beta shape parameter of the Beta CDF used to map psi_jt in [0, 1] onto the [decay_days_short, decay_days_long] interval.
kappa Half-saturation constant in the env force-of-infection W / (kappa + W); larger kappa means more reservoir is needed before transmission saturates.
psi_jt Per-tick, per-patch environmental suitability time series; modulates seasonal env transmission rate around its mean and drives the suitability-to-decay map for the reservoir.
psi_star_a Per-patch upstream-MOSAIC parameter for the suitability curve; carried in the parameter set but NOT consumed by any laser-cholera simulation code.
psi_star_b Per-patch upstream-MOSAIC parameter for the suitability curve; carried in the parameter set but NOT consumed by any laser-cholera simulation code.
psi_star_k Per-patch upstream-MOSAIC parameter for the suitability curve; carried in the parameter set but NOT consumed by any laser-cholera simulation code.
psi_star_z Per-patch upstream-MOSAIC parameter for the suitability curve; carried in the parameter set but NOT consumed by any laser-cholera simulation code.
theta_j Per-patch WASH (water/sanitation/hygiene) coverage fraction; (1 - theta_j) attenuates both env transmission to humans and infectious shedding into the reservoir.
zeta_1 Per-infectious-symptomatic-person shedding rate into the environmental reservoir W per tick (Poisson rate).
zeta_2 Per-infectious-asymptomatic-person shedding rate into the environmental reservoir W per tick (Poisson rate).
zeta_ratio MOSAIC-side ratio used to derive zeta_1/zeta_2 upstream; carried into the parameter set but NOT consumed by any laser-cholera simulation code.

Alphabetical table

Every top-level field in default_parameters.json, sorted alphabetically. The "Group" column links to the section above; the parameter name links to its detailed entry.

Parameter Group One-line description
E_j_initial Initial populations Per-patch initial number of exposed (latent, not yet infectious) people seeded into the E compartment at tick 0.
I_j_initial Initial populations Per-patch initial number of infectious people; split by sigma into symptomatic (Isym) and asymptomatic (Iasym) at tick 0.
N_j_initial Initial populations Total initial population per patch (used as the gravity-model destination mass when reconstructing the mobility matrix, though the live code now sums the per-compartment initials instead).
R_j_initial Initial populations Per-patch initial number of recovered (immune) people seeded into the R compartment at tick 0.
S_j_initial Initial populations Per-patch initial number of susceptible people seeded into the S compartment at tick 0.
V1_j_initial Initial populations Per-patch initial number of one-dose-vaccinated people seeded into the V1 compartment at tick 0.
V2_j_initial Initial populations Per-patch initial number of two-dose-vaccinated people seeded into the V2 compartment at tick 0.
a_1_j Human-to-human transmission Per-patch amplitude of the first (annual) cosine term of the seasonal-transmission harmonic.
a_2_j Human-to-human transmission Per-patch amplitude of the second (semi-annual) cosine term of the seasonal-transmission harmonic.
alpha_1 Human-to-human transmission Exponent on the effective-infected count in the human-to-human force-of-infection (mixing nonlinearity in the numerator).
alpha_2 Human-to-human transmission Exponent on the patch population in the FOI denominator; alpha_2=1 = frequency-dependent mixing, alpha_2=0 = density-dependent.
b_1_j Human-to-human transmission Per-patch amplitude of the first (annual) sine term of the seasonal-transmission harmonic.
b_2_j Human-to-human transmission Per-patch amplitude of the second (semi-annual) sine term of the seasonal-transmission harmonic.
b_jt Vital dynamics Per-patch, per-tick crude birth rate; the Poisson mean for new susceptibles each day is N * b_jt[tick].
beta_j0_env Environmental transmission Per-patch baseline environmental-reservoir-to-human transmission rate; multiplier on the W/(kappa+W) saturation term in the env force of infection.
beta_j0_hum Human-to-human transmission Per-patch baseline human-to-human transmission rate; multiplied by the seasonal harmonic to produce the per-tick, per-patch transmission envelope.
beta_j0_tot Human-to-human transmission Per-patch combined baseline transmission rate (legacy / metadata field carried from upstream MOSAIC R config; not consumed by the Python simulation loop).
chi_endemic Regime switching Reporting-rate divisor used when local symptomatic-infected fraction is below epidemic_threshold (endemic regime); inflates estimated cases via division.
chi_epidemic Regime switching Reporting-rate divisor used when local symptomatic-infected fraction is at or above epidemic_threshold (epidemic regime); inflates estimated cases via division.
d_jt Vital dynamics Per-patch, per-tick non-disease (background) mortality rate applied to every live compartment (S, E, Isym, Iasym, R, V1, V2).
date_start Run identity and calendar Calendar date of simulation tick 0; together with date_stop it defines the run length (nticks = (date_stop - date_start).days + 1).
date_stop Run identity and calendar Calendar date of the final simulation tick; with date_start it bounds the run window and sets nticks.
decay_days_long Environmental transmission Longest reservoir half-life (in days) at the low end of the suitability-to-decay map; 1/decay_days_long is the minimum decay rate.
decay_days_short Environmental transmission Shortest reservoir half-life (in days) at the high end of the suitability-to-decay map; 1/decay_days_short is the maximum decay rate.
decay_days_spread Environmental transmission MOSAIC-side scratch parameter describing the spread between fast and slow decay (days); carried in the parameter set but NOT consumed by any laser-cholera simulation code.
decay_shape_1 Environmental transmission Alpha shape parameter of the Beta CDF used to map psi_jt in [0, 1] onto the [decay_days_short, decay_days_long] interval.
decay_shape_2 Environmental transmission Beta shape parameter of the Beta CDF used to map psi_jt in [0, 1] onto the [decay_days_short, decay_days_long] interval.
delta_reporting_cases Reporting Integer tick lag between when a new symptomatic case occurs and when it is added to reported_cases.
delta_reporting_deaths Reporting Integer tick lag between when a disease death occurs and when it is added to reported_deaths.
epidemic_peaks Regime switching Observed epidemic peak dates per ISO code used by the likelihood scorer to evaluate peak-timing and peak-magnitude shape terms; not consumed by the simulation dynamics.
epidemic_threshold Regime switching Per-patch (or global) symptomatic-infected fraction above which the patch is treated as in an epidemic regime, switching both the disease-mortality multiplier and the reporting-rate divisor.
epsilon Disease progression Per-day rate at which natural immunity wanes (R -> S).
gamma_1 Disease progression Per-day recovery rate for symptomatic infectious individuals (I_sym -> R).
gamma_2 Disease progression Per-day recovery rate for asymptomatic infectious individuals (I_asym -> R).
iota Disease progression Per-day rate at which exposed (E) individuals progress to becoming infectious (I_sym or I_asym).
kappa Environmental transmission Half-saturation constant in the env force-of-infection W / (kappa + W); larger kappa means more reservoir is needed before transmission saturates.
latitude Geography and mobility Per-patch latitude coordinate; combined with longitude for inter-patch distance in the gravity-mobility kernel (and used to order patches in one plot).
location_name Run identity and calendar Ordered list of patch/admin-unit labels; its length defines npatches and its order defines every per-patch vector's element ordering.
longitude Geography and mobility Per-patch longitude coordinate; used together with latitude to compute great-circle distances that feed the gravity-model mobility matrix.
mobility_gamma Geography and mobility Exponent on inter-patch distance (with sign reversed) in the gravity model; larger values penalize long-distance movement more strongly when building pi_ij.
mobility_omega Geography and mobility Exponent on the destination population in the gravity model that builds the patch-to-patch coupling matrix pi_ij; larger values pull more flow toward larger patches.
mu_j_baseline Vital dynamics Per-patch baseline disease (cholera) mortality rate applied to symptomatic infectious; the multiplicative anchor of the mu_jt = mu_baseline * (1 + slope*t) * (1 + epidemic_factor*flag) formula.
mu_j_epidemic_factor Vital dynamics Per-patch multiplicative boost on disease mortality when the patch is flagged as being in an epidemic regime (reported symptomatic infectious exceeds epidemic_threshold * N).
mu_j_slope Vital dynamics Per-patch linear time-trend on disease mortality; mu_jt is scaled by (1 + mu_j_slope * tick/nticks) so positive values ramp mortality up over the run and negative values ramp it down.
mu_jt Vital dynamics Disease mortality time-series stored on the parameter set for diagnostic plotting only — the simulation loop computes its own per-tick mu_jt from baseline/slope/epidemic_factor and ignores this array.
nu_1_jt Vaccination Number of first-dose vaccinations to deliver per tick and per patch.
nu_2_jt Vaccination Number of second-dose vaccinations to deliver per tick and per patch (moves V1 to V2).
nu_jt_sources Vaccination List of compartment names from which first-dose vaccinations are drawn (proportional sampling across the listed compartments).
omega_1 Vaccination Daily waning rate from V1 back to S; converted to a per-tick probability via 1 - exp(-omega_1).
omega_2 Vaccination Daily waning rate from V2 back to S; converted to a per-tick probability via 1 - exp(-omega_2).
p Human-to-human transmission Period (in ticks/days) of the seasonal-transmission harmonic; typically 365 for an annual cycle.
p_beta Human-to-human transmission Per-patch split fraction between human-to-human and environmental transmission in the upstream R model (legacy metadata; not consumed by the Python simulation loop).
phi_1 Vaccination Effectiveness (take fraction) of a first dose: only this fraction of delivered doses moves the recipient into V1.
phi_2 Vaccination Effectiveness (take fraction) of a second dose: only this fraction of V1 recipients moves into V2.
prop_E_initial Initial populations Per-patch initial fraction of population in the E compartment (informational / upstream-MOSAIC artifact; not read by the model).
prop_I_initial Initial populations Per-patch initial fraction of population in the I compartment (informational / upstream-MOSAIC artifact; not read by the model).
prop_R_initial Initial populations Per-patch initial fraction of population in the R compartment (informational / upstream-MOSAIC artifact; not read by the model).
prop_S_initial Initial populations Per-patch initial fraction of population in the S compartment (informational / upstream-MOSAIC artifact; not read by the model itself).
prop_V1_initial Initial populations Per-patch initial fraction of population in the V1 compartment (informational / upstream-MOSAIC artifact; not read by the model).
prop_V2_initial Initial populations Per-patch initial fraction of population in the V2 compartment (informational / upstream-MOSAIC artifact; not read by the model).
psi_jt Environmental transmission Per-tick, per-patch environmental suitability time series; modulates seasonal env transmission rate around its mean and drives the suitability-to-decay map for the reservoir.
psi_star_a Environmental transmission Per-patch upstream-MOSAIC parameter for the suitability curve; carried in the parameter set but NOT consumed by any laser-cholera simulation code.
psi_star_b Environmental transmission Per-patch upstream-MOSAIC parameter for the suitability curve; carried in the parameter set but NOT consumed by any laser-cholera simulation code.
psi_star_k Environmental transmission Per-patch upstream-MOSAIC parameter for the suitability curve; carried in the parameter set but NOT consumed by any laser-cholera simulation code.
psi_star_z Environmental transmission Per-patch upstream-MOSAIC parameter for the suitability curve; carried in the parameter set but NOT consumed by any laser-cholera simulation code.
reported_cases Reporting Observed per-patch-per-time-step case counts used as the target series when computing the model likelihood.
reported_deaths Reporting Observed per-patch-per-time-step death counts used as the target series when computing the model likelihood.
rho Reporting Per-case reporting probability for symptomatic cases — fraction of new symptomatic infections that show up in the reported_cases series.
rho_deaths Reporting Per-death reporting probability — fraction of disease deaths that show up in the reported_deaths series.
seed Run identity and calendar Integer seed for the model's pseudo-random number generator; setting it pins all stochastic draws to a reproducible sequence.
sigma Disease progression Fraction of new infections that become symptomatic (the rest go to the asymptomatic compartment).
tau_i Geography and mobility Per-patch fraction of infectious (and, for environmental exposure, susceptible) individuals that move out of their home patch; the master switch for spatial mixing.
theta_j Environmental transmission Per-patch WASH (water/sanitation/hygiene) coverage fraction; (1 - theta_j) attenuates both env transmission to humans and infectious shedding into the reservoir.
zeta_1 Environmental transmission Per-infectious-symptomatic-person shedding rate into the environmental reservoir W per tick (Poisson rate).
zeta_2 Environmental transmission Per-infectious-asymptomatic-person shedding rate into the environmental reservoir W per tick (Poisson rate).
zeta_ratio Environmental transmission MOSAIC-side ratio used to derive zeta_1/zeta_2 upstream; carried into the parameter set but NOT consumed by any laser-cholera simulation code.