Environmental transmission¶
These parameters control the second of the model's two transmission pathways: the indirect, water-borne route where infectious individuals shed Vibrio cholerae into a per-patch environmental reservoir W and susceptibles re-encounter that reservoir through a saturating force of infection. Together they govern the baseline reservoir-to-human rate (beta_j0_env), the seasonal modulation of that rate and of the reservoir's decay (psi_jt, decay_*), the WASH attenuation that reduces both transmission and shedding (theta_j), the per-compartment shedding rates (zeta_1, zeta_2), and the saturation half-constant (kappa). A handful of additional psi_star_*, zeta_ratio, and decay_days_spread keys are MOSAIC-side metadata that travel with the parameter set but are not read by any laser-cholera component.
To turn the entire environmental pathway off, set beta_j0_env = np.zeros(npatches) (and, if you also want the reservoir to stop accumulating, zeta_1 = zeta_2 = 0). See Explanation › Transmission for how these parameters compose into the environmental force of infection.
Quick reference¶
| Parameter | Shape | Dtype | Range | Off-value |
|---|---|---|---|---|
beta_j0_env |
(npatches, 1) |
float32 |
>= 0 |
np.zeros(npatches) |
theta_j |
(npatches,) |
float32 |
[0, 1] |
np.zeros(npatches) |
psi_jt |
(nticks, npatches) |
float32 |
shape-only | psi_jt = 1.0 everywhere |
psi_star_a |
(npatches,) |
float32 |
unconstrained | n/a (not consumed) |
psi_star_b |
(npatches,) |
float32 |
unconstrained | n/a (not consumed) |
psi_star_z |
(npatches,) |
float32 |
unconstrained | n/a (not consumed) |
psi_star_k |
(npatches,) |
float32 |
unconstrained | n/a (not consumed) |
zeta_1 |
scalar | float32 |
>= 0 |
0.0 |
zeta_2 |
scalar | float32 |
>= 0 |
0.0 |
zeta_ratio |
scalar | Python float |
unconstrained | n/a (not consumed) |
kappa |
scalar | float32 |
>= 0 |
n/a (tuning, not a toggle) |
decay_days_short |
scalar | float32 |
> 0 and <= decay_days_long |
n/a (tuning, not a toggle) |
decay_days_long |
scalar | float32 |
>= decay_days_short |
n/a (tuning, not a toggle) |
decay_days_spread |
scalar | Python int |
unconstrained | n/a (not consumed) |
decay_shape_1 |
scalar | float32 |
unconstrained (scipy needs > 0) |
n/a (tuning, not a toggle) |
decay_shape_2 |
scalar | float32 |
unconstrained (scipy needs > 0) |
n/a (tuning, not a toggle) |
Parameters¶
beta_j0_env¶
- What it controls: Per-patch baseline environmental-reservoir-to-human transmission rate; multiplier on the
W / (kappa + W)saturation term in the environmental force of infection. - Shape:
(npatches, 1)— coerced 1-D vector reshaped to(-1, 1)bydict_to_propertysetexfor broadcast. - Dtype:
float32 - Range:
>= 0(validator:"beta_j0_env values must be >= 0"); the validator also checkslen(beta_j0_env) == npatches. - Off-value:
np.zeros(npatches)—beta_jt_envis then identically zero, so no S to E environmental infections occur and the environmental pathway is fully off. - Consumer code:
src/laser/cholera/metapop/envtohuman.py,src/laser/cholera/metapop/params.py - Related parameters:
psi_jt,theta_j,kappa,beta_j0_hum - Notes: Unusual shape —
dict_to_propertysetexreshapes the 1-Das_ndarrayresult to(npatches, 1), and the consumer usesbeta_j0_env.Tso that broadcasting against the(nticks, npatches)psi-modulation works out. Withbeta_j0_env = 0everywhere,beta_jt_envis identically zero,Psi = 0, and no S to E environmental infections occur.
theta_j¶
- What it controls: Per-patch WASH (water, sanitation, and hygiene) coverage fraction;
(1 - theta_j)attenuates both environmental transmission to humans and infectious shedding into the reservoir. - Shape:
(npatches,) - Dtype:
float32 - Range:
[0, 1]per element (validator:"theta_j values must be in the range [0, 1]"). - Off-value:
np.zeros(npatches)— disables WASH protection, so the(1 - theta_j)multiplier becomes 1 and environmental transmission and shedding run at their unattenuated rates. Note this maximises the environmental pathway rather than disabling it; to actually disable environmental transmission setbeta_j0_envto zero (and optionallyzeta_1andzeta_2to zero as well). - Consumer code:
src/laser/cholera/metapop/envtohuman.py,src/laser/cholera/metapop/environmental.py,src/laser/cholera/metapop/params.py - Related parameters:
beta_j0_env,zeta_1,zeta_2
psi_jt¶
- What it controls: Per-tick, per-patch environmental suitability time series; modulates seasonal environmental transmission around its temporal mean and drives the suitability-to-decay map for the reservoir.
- Shape:
(nticks, npatches)— auto-transposed from(npatches, nticks)input if needed. - Dtype:
float32 - Range: Shape-only check (validator:
"Shape of psi_jt ... does not match (nticks, npatches)"); no numeric range is enforced (aTODO - TBDcomment sits invalidate_parameters). - Off-value:
psi_jt = 1.0everywhere —beta_jt_env = beta_j0_env.T * (1 + (psi - psi_bar) / psi_bar)collapses tobeta_j0_envanddelta_jtbecomes time-invariant per patch. Any positive constant achieves the same effect sincepsi - psi_bar = 0, butpsi_jtmust not be zero (psi_baris in the denominator); constant1is the safe canonical choice. - Consumer code:
src/laser/cholera/metapop/envtohuman.py,src/laser/cholera/metapop/environmental.py,src/laser/cholera/metapop/params.py - Related parameters:
beta_j0_env,decay_days_short,decay_days_long,decay_shape_1,decay_shape_2
psi_star_a¶
- What it controls: Per-patch upstream-MOSAIC parameter for the suitability curve; carried in the parameter set but NOT consumed by any laser-cholera simulation code.
- Shape:
(npatches,)effectively — coerced vianp.arraybut no validator shape check. - Dtype:
float32 - Range: unconstrained (validator does not check it).
- Off-value: n/a — not a feature toggle; the value is irrelevant in laser-cholera as long as
psi_jtis provided directly. - Consumer code:
src/laser/cholera/metapop/params.py,src/laser/cholera/metapop/utils.py - Related parameters:
psi_jt,psi_star_b,psi_star_z,psi_star_k - Notes: Dead parameter w.r.t. dynamics:
dict_to_propertysetexcoerces it to afloat32ndarray andoverride_helperaccepts it as a CLI-unsupported key (vectors are not CLI-overridable), but nothing reads it during simulation. Likely a MOSAIC-side artefact retained for round-tripping.
psi_star_b¶
- What it controls: Per-patch upstream-MOSAIC parameter for the suitability curve; carried in the parameter set but NOT consumed by any laser-cholera simulation code.
- Shape:
(npatches,)effectively — coerced vianp.arraybut no validator shape check. - Dtype:
float32 - Range: unconstrained (validator does not check it).
- Off-value: n/a — not a feature toggle; inert within laser-cholera.
- Consumer code:
src/laser/cholera/metapop/params.py,src/laser/cholera/metapop/utils.py - Related parameters:
psi_jt,psi_star_a,psi_star_z,psi_star_k - Notes: Same status as
psi_star_a— coerced but never read by any simulation component.
psi_star_z¶
- What it controls: Per-patch upstream-MOSAIC parameter for the suitability curve; carried in the parameter set but NOT consumed by any laser-cholera simulation code.
- Shape:
(npatches,)effectively — coerced vianp.arraybut no validator shape check. - Dtype:
float32 - Range: unconstrained (validator does not check it).
- Off-value: n/a — not a feature toggle; inert within laser-cholera.
- Consumer code:
src/laser/cholera/metapop/params.py,src/laser/cholera/metapop/utils.py - Related parameters:
psi_jt,psi_star_a,psi_star_b,psi_star_k - Notes: Same status as
psi_star_a— coerced but never read.
psi_star_k¶
- What it controls: Per-patch upstream-MOSAIC parameter for the suitability curve; carried in the parameter set but NOT consumed by any laser-cholera simulation code.
- Shape:
(npatches,)effectively — coerced vianp.arraybut no validator shape check. - Dtype:
float32 - Range: unconstrained (validator does not check it).
- Off-value: n/a — not a feature toggle; inert within laser-cholera.
- Consumer code:
src/laser/cholera/metapop/params.py,src/laser/cholera/metapop/utils.py - Related parameters:
psi_jt,psi_star_a,psi_star_b,psi_star_z - Notes: Same status as
psi_star_a— coerced but never read.
zeta_1¶
- What it controls: Per-infectious-symptomatic-person shedding rate into the environmental reservoir
Wper tick (Poisson rate). - Shape: scalar
- Dtype:
float32 - Range:
>= 0(validator:"zeta_1 value must be >= 0"). - Off-value:
0.0— symptomatic individuals stop contributing to the reservoir; combined withzeta_2= 0the entire shedding source disappears. - Consumer code:
src/laser/cholera/metapop/environmental.py,src/laser/cholera/metapop/params.py - Related parameters:
zeta_2,zeta_ratio,theta_j - Notes:
environmental.pyshedding line:shedding_sym = Poisson(zeta_1 * Isym). Thezeta_*family is not listed as a stand-alone toggle in plan §4 — disabling environmental transmission viabeta_j0_env= 0already breaks the reservoir-to-human link; zeroing bothzeta_*additionally breaks the human-to-reservoir link.
zeta_2¶
- What it controls: Per-infectious-asymptomatic-person shedding rate into the environmental reservoir
Wper tick (Poisson rate). - Shape: scalar
- Dtype:
float32 - Range:
>= 0(validator:"zeta_2 value must be >= 0"). - Off-value:
0.0— asymptomatic individuals stop contributing to the reservoir. - Consumer code:
src/laser/cholera/metapop/environmental.py,src/laser/cholera/metapop/params.py - Related parameters:
zeta_1,zeta_ratio,theta_j - Notes:
environmental.pyshedding line:shedding_asym = Poisson(zeta_2 * Iasym). Same logic aszeta_1.
zeta_ratio¶
- What it controls: MOSAIC-side ratio used to derive
zeta_1/zeta_2upstream; carried into the parameter set but NOT consumed by any laser-cholera simulation code. - Shape: scalar (passed through unchanged; no coercion entry in
dict_to_propertysetex). - Dtype: Python
floatas loaded from JSON; never cast tofloat32. - Range: unconstrained (no validator entry; no coercion entry).
- Off-value: n/a — not a feature toggle.
- Consumer code:
src/laser/cholera/metapop/utils.py - Related parameters:
zeta_1,zeta_2 - Notes: Truly inert: not in the scalars/arrays coercion lists in
params.py, not asserted byvalidate_parameters, and not read by any component. Listed only inoverride_helper's mapping so CLI overrides will not reject it. Pure metadata.
kappa¶
- What it controls: Half-saturation constant in the environmental force of infection
W / (kappa + W); largerkappameans more reservoir is needed before transmission saturates. - Shape: scalar
- Dtype:
float32 - Range:
>= 0(validator:"kappa value must be >= 0"). - Off-value: n/a — this is a tuning constant, not a toggle. To disable environmental transmission set
beta_j0_envto zero rather than touchingkappa. - Consumer code:
src/laser/cholera/metapop/envtohuman.py,src/laser/cholera/metapop/params.py - Related parameters:
beta_j0_env,theta_j,psi_jt - Notes: Caveat —
kappa = 0does not raise (the validator allows>= 0) but changes semantics:W / (0 + W) = 1whereverW > 0and0 / 0(NaN) atW = 0. Usebeta_j0_env= 0to disable the pathway;kappabecomes irrelevant oncebeta_jt_env = 0zeroes the whole numerator.
decay_days_short¶
- What it controls: Shortest reservoir half-life (in days) at the high end of the suitability-to-decay map;
1 / decay_days_shortis the maximum decay rate. - Shape: scalar
- Dtype:
float32 - Range:
> 0(validator:"decay_days_short value must be > 0"); additionallydecay_days_short <= decay_days_long. - Off-value: n/a — this is a tuning constant, not a toggle.
- Consumer code:
src/laser/cholera/metapop/environmental.py,src/laser/cholera/metapop/params.py - Related parameters:
decay_days_long,decay_shape_1,decay_shape_2,psi_jt - Notes: Tunes the
delta_jtrange. Settingdecay_days_short == decay_days_longcollapses the suitability-to-decay map to a constant — effectively "no psi modulation of decay". The validator forbidsdecay_days_short == 0.
decay_days_long¶
- What it controls: Longest reservoir half-life (in days) at the low end of the suitability-to-decay map;
1 / decay_days_longis the minimum decay rate. - Shape: scalar
- Dtype:
float32 - Range:
>= decay_days_short(validator:"decay_days_short ... value must be <= decay_days_long"); no explicit> 0check but inherits> 0transitively viadecay_days_short. - Off-value: n/a — this is a tuning constant, not a toggle.
- Consumer code:
src/laser/cholera/metapop/environmental.py,src/laser/cholera/metapop/params.py - Related parameters:
decay_days_short,decay_shape_1,decay_shape_2,psi_jt - Notes: Paired with
decay_days_short. To make decay psi-independent, setdecay_days_short == decay_days_long.
decay_days_spread¶
- What it controls: MOSAIC-side scratch parameter describing the spread between fast and slow decay (in days); carried in the parameter set but NOT consumed by any laser-cholera simulation code.
- Shape: scalar (passed through unchanged; no coercion entry).
- Dtype: Python
intfrom JSON; never cast. - Range: unconstrained (no validator entry; no coercion entry).
- Off-value: n/a — not a feature toggle.
- Consumer code:
src/laser/cholera/metapop/utils.py - Related parameters:
decay_days_short,decay_days_long - Notes: Truly inert in laser-cholera. Listed in
override_helper's mapping only so CLI overrides will not reject it. Decay times are controlled bydecay_days_shortanddecay_days_long;decay_days_spreadis metadata.
decay_shape_1¶
- What it controls: Alpha shape parameter of the Beta CDF used to map
psi_jtin[0, 1]onto the[decay_days_short, decay_days_long]interval. - Shape: scalar
- Dtype:
float32 - Range: unconstrained by
validate_parameters(no assert);scipy.stats.beta.cdfrequires> 0at use time. - Off-value: n/a — this is a tuning constant, not a toggle.
- Consumer code:
src/laser/cholera/metapop/environmental.py,src/laser/cholera/metapop/params.py - Related parameters:
decay_shape_2,decay_days_short,decay_days_long,psi_jt - Notes: Coerced to
float32butvalidate_parametersdoes not range-check it; misuse surfaces insidescipy.stats.beta.cdfat run time rather than at validation time.
decay_shape_2¶
- What it controls: Beta shape parameter of the Beta CDF used to map
psi_jtin[0, 1]onto the[decay_days_short, decay_days_long]interval. - Shape: scalar
- Dtype:
float32 - Range: unconstrained by
validate_parameters(no assert);scipy.stats.beta.cdfrequires> 0at use time. - Off-value: n/a — this is a tuning constant, not a toggle.
- Consumer code:
src/laser/cholera/metapop/environmental.py,src/laser/cholera/metapop/params.py - Related parameters:
decay_shape_1,decay_days_short,decay_days_long,psi_jt - Notes: Same caveat as
decay_shape_1— coerced but not range-validated; misuse surfaces in scipy at run time.