Vital dynamics¶
This group controls the demographic and disease-mortality processes layered on top of the SEIR core: how many new susceptibles are born into each patch per tick, how aggressively a constant non-disease (background) hazard culls every live compartment, and how cholera-specific case fatality is built up from a baseline, an optional linear time-trend, and an epidemic-regime multiplier. Together these parameters decide whether the simulated population is closed (zero births, zero non-disease deaths, zero case fatality) or open with realistic demographics, and they shape the long-term replenishment of the susceptible pool that drives multi-year endemicity.
Quick reference¶
| Parameter | Shape | Dtype | Range | Off-value |
|---|---|---|---|---|
b_jt |
(nticks, npatches) |
np.float32 |
>= 0 |
0 (entire array) |
d_jt |
(nticks, npatches) |
np.float32 |
>= 0 |
0 (entire array) |
mu_j_baseline |
(npatches,) |
np.float32 |
>= 0 |
0 (vector of zeros) |
mu_j_slope |
(npatches,) |
np.float32 |
unconstrained | 0 (vector of zeros) |
mu_j_epidemic_factor |
(npatches,) |
np.float32 |
>= 0 |
0 (vector of zeros) |
mu_jt |
(nticks, npatches) |
np.float32 |
unconstrained | n/a (diagnostic only) |
b_jt¶
- What it controls: Per-patch, per-tick crude birth rate; the Poisson mean for new susceptibles each day is
N * b_jt[tick]. - Shape:
(nticks, npatches) - Dtype:
np.float32 - Range:
>= 0(validator-enforced viaassert np.all(params.b_jt >= 0.0); the assert message says "b_jt rate values must be positive" but the check admits zero). - Off-value:
0(entire(nticks, npatches)array) — with the per-tick rate at zero the Poisson mean for new births is zero, so no new susceptibles are ever drawn into the population. - Consumer code:
src/laser/cholera/metapop/susceptible.py,src/laser/cholera/metapop/params.py - Related parameters:
d_jt,N_j_initial - Notes: Stored as
(nticks, npatches)after a transpose indict_to_propertysetex— if the JSON ships it as(num_nodes, num_ticks)it is auto-transposed. The validator's assert message says "must be positive" but the implementation is>= 0, so zero is legal (which is what enables the closed-population off-switch). Births at ticktare drawn asPoisson(N * b_jt[tick])insusceptible.py; withb_jt = 0the mean is0and zero births are drawn.
d_jt¶
- What it controls: Per-patch, per-tick non-disease (background) mortality rate applied to every live compartment (S, E, Isym, Iasym, R, V1, V2).
- Shape:
(nticks, npatches) - Dtype:
np.float32 - Range:
>= 0(validator-enforced viaassert np.all(params.d_jt >= 0.0); the assert message says "d_jt rate values must be positive" but the check admits zero). - Off-value:
0(entire(nticks, npatches)array) — every compartment caches1 - exp(-d_jt)and drawsBinomial(X, p)non-disease deaths; with the rate at zero the probability is zero and the population is closed against background mortality. - Consumer code:
src/laser/cholera/metapop/susceptible.py,src/laser/cholera/metapop/exposed.py,src/laser/cholera/metapop/infectious.py,src/laser/cholera/metapop/recovered.py,src/laser/cholera/metapop/vaccinated.py,src/laser/cholera/metapop/params.py - Related parameters:
b_jt,mu_j_baseline,mu_j_slope,mu_j_epidemic_factor - Notes: Auto-transposed from
(num_nodes, num_ticks)to(nticks, npatches)if needed. Each compartment cachesmodel.patches.non_disease_death_prob_jt = 1 - exp(-d_jt)once atcheck()time and indexes by tick at runtime; withd_jt = 0the cache is all zeros andBinomial(X, 0) = 0, so non-disease deaths vanish in every compartment. Note the asymmetry with disease mortality, which is themu_*family and lives only ininfectious.py.
mu_j_baseline¶
- What it controls: Per-patch baseline disease (cholera) mortality rate applied to the symptomatic infectious compartment; the multiplicative anchor of
mu_jt = mu_j_baseline * (1 + mu_j_slope * t/nticks) * (1 + mu_j_epidemic_factor * epidemic_flag). - Shape:
(npatches,) - Dtype:
np.float32 - Range:
>= 0(validator-enforced viaassert np.all(params.mu_j_baseline >= 0)). - Off-value:
0(vector of zeros) — with the baseline at zero the productmu_jtis zero regardless of slope or epidemic factor, so symptomatic disease deaths are drawn fromBinomial(Isym, 0) = 0and disappear entirely. - Consumer code:
src/laser/cholera/metapop/infectious.py - Related parameters:
mu_j_slope,mu_j_epidemic_factor,epidemic_threshold,delta_reporting_cases - Notes: The plan's §4 does not enumerate a disease-mortality off-switch; this off-value is inferred from the multiplicative form in
infectious.py. Withmu_j_baseline = 0, the productmu_jt = 0, sodisease_deaths = Binomial(Isym, 1 - exp(0)) = 0regardless of slope or epidemic factor. Only applies to symptomatic infectious (Isym), not asymptomatic (Iasym).
mu_j_slope¶
- What it controls: Per-patch linear time-trend on disease mortality;
mu_jtis scaled by(1 + mu_j_slope * tick/nticks)so positive values ramp mortality up over the run and negative values ramp it down. - Shape:
(npatches,) - Dtype:
np.float32 - Range: unconstrained — only the shape is checked; the validator's comment notes "no range constraints on mu_j_slope".
- Off-value:
0(vector of zeros) — with slope zero the time factor collapses to1and the simulatedmu_jtreduces tomu_j_baseline * (1 + mu_j_epidemic_factor * epidemic_flag), removing any drift over the run. - Consumer code:
src/laser/cholera/metapop/infectious.py - Related parameters:
mu_j_baseline,mu_j_epidemic_factor - Notes: This is the only parameter in this group without a non-negativity guard — a slope of
-1would drivemu_jtnegative at the end of the run, which would break thenp.expm1(-mu_jt)semantics used to convert a rate into a per-tick probability. Withslope = 0the time factor collapses to1exactly andmu_jtreduces tomu_j_baseline * (1 + mu_j_epidemic_factor * epidemic_flag).
mu_j_epidemic_factor¶
- What it controls: 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). - Shape:
(npatches,) - Dtype:
np.float32 - Range:
>= 0(validator-enforced viaassert np.all(params.mu_j_epidemic_factor >= 0)). - Off-value:
0(vector of zeros) — with the factor at zero the epidemic bracket collapses to1.0regardless of the regime flag, so disease mortality stays at the endemic level even during a declared outbreak. - Consumer code:
src/laser/cholera/metapop/infectious.py - Related parameters:
mu_j_baseline,mu_j_slope,epidemic_threshold,delta_reporting_cases,chi_endemic,chi_epidemic - Notes: With
factor = 0the second multiplicative bracket collapses to1.0regardless ofepidemic_flag, so the epidemic regime does not amplify disease mortality. The epidemic flag is still computed usingepidemic_thresholdand the reported (lagged)Isymvalue, but its product with the factor is zero so the regime-switch has no effect on mortality.
mu_jt¶
- What it controls: Disease-mortality time-series stored on the parameter set for diagnostic plotting only — the simulation loop computes its own per-tick
mu_jtfrom baseline / slope / epidemic-factor and ignores this array. - Shape:
(nticks, npatches)as stored (never validated or transposed). - Dtype:
np.float32 - Range: unconstrained — the validator does not check this field at all.
- Off-value: n/a — this is a diagnostic display copy, not a feature toggle; zeroing it has no effect on the simulation.
- Consumer code:
src/laser/cholera/metapop/params.py - Related parameters:
mu_j_baseline,mu_j_slope,mu_j_epidemic_factor - Notes: Surprising:
mu_jtis the only parameter in this group that is loaded bydict_to_propertysetexbut has zero presence invalidate_parameters— no shape check, no range check, no auto-transpose. It is read at exactly one site,Parameters.plot(), which callsimshow(self.model.params.mu_jt.T, ...). The simulation's effective disease-mortality field is recomputed inline ininfectious.pyfrommu_j_baseline,mu_j_slope, andmu_j_epidemic_factor; the storedmu_jtarray is purely a precomputed display copy and can drift from the actual simulated values.