Regime switching¶
The regime-switching parameters let the model behave differently depending on whether a patch is in an endemic or epidemic state. A per-patch symptomatic-infected fraction is compared to a threshold; patches above the threshold are treated as in an epidemic regime, which alters both the reporting-rate divisor (chi_endemic vs. chi_epidemic) and — via the partner parameter mu_j_epidemic_factor — the disease-mortality multiplier. The optional epidemic_peaks table is not consumed by the simulation dynamics; it carries observed peak dates per location that are scored by the likelihood machinery.
Quick reference¶
| Parameter | Shape | Dtype | Range | Off-value |
|---|---|---|---|---|
chi_endemic |
scalar | np.float32 |
unconstrained | chi_endemic == chi_epidemic (e.g. both 1.0) |
chi_epidemic |
scalar | np.float32 |
unconstrained | chi_epidemic == chi_endemic (e.g. both 1.0) |
epidemic_threshold |
scalar or (npatches,) |
np.float32 |
>= 0 |
set chi_endemic == chi_epidemic and mu_j_epidemic_factor == 0 |
epidemic_peaks |
(num_peaks, 3) DataFrame |
pandas (object / int) | columns iso_code, peak_date required if field present |
omit the field entirely |
Parameters¶
chi_endemic¶
- What it controls: Reporting-rate divisor used when the local symptomatic-infected fraction is below
epidemic_threshold(endemic regime); inflates estimated cases via division. - Shape:
scalar - Dtype:
np.float32 - Range: unconstrained (cast to
np.float32indict_to_propertysetex; no validator-enforced bound invalidate_parameters). - Off-value:
chi_endemic == chi_epidemic(e.g. both1.0) — collapses the regime switch so the reporting branch is a no-op regardless ofepidemic_threshold; an additional value of1.0also makes the reporting divisor itself a no-op. - Consumer code:
src/laser/cholera/metapop/infectious.py,src/laser/cholera/metapop/params.py,src/laser/cholera/metapop/utils.py - Related parameters:
chi_epidemic,epidemic_threshold,rho,delta_reporting_cases - Notes: Consumed in
infectious.pyasnp.where(infected_fraction < epidemic_threshold, chi_endemic, chi_epidemic), thenreported_cases += round(binomial(new_symptomatic, rho) / chi_eff). The bundled default value0.5inflates reported cases by1 / 0.5 = 2xin the endemic regime.
chi_epidemic¶
- What it controls: Reporting-rate divisor used when the local symptomatic-infected fraction is at or above
epidemic_threshold(epidemic regime); inflates estimated cases via division. - Shape:
scalar - Dtype:
np.float32 - Range: unconstrained (cast to
np.float32indict_to_propertysetex; no validator-enforced bound invalidate_parameters). - Off-value:
chi_epidemic == chi_endemic(e.g. both1.0) — collapses the regime switch so the reporting branch is a no-op regardless ofepidemic_threshold; an additional value of1.0also makes the reporting divisor itself a no-op. - Consumer code:
src/laser/cholera/metapop/infectious.py,src/laser/cholera/metapop/params.py,src/laser/cholera/metapop/utils.py - Related parameters:
chi_endemic,epidemic_threshold,rho,delta_reporting_cases - Notes: Bundled default value
0.75(higher reporting under epidemic awareness than the endemic default of0.5). Settingchi_epidemic == chi_endemicmakes the regime branch ininfectious.pya no-op regardless ofepidemic_threshold.
epidemic_threshold¶
- What it controls: 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.
- Shape:
scalaror(npatches,) - Dtype:
np.float32(scalarnp.float32if scalar input;np.ndarrayofnp.float32if list / array input). - Range:
>= 0(scalar branch assertsparams.epidemic_threshold >= 0; array branch assertsnp.all(params.epidemic_threshold >= 0)andparams.epidemic_threshold.shape == (npatches,); raisesRuntimeErrorif the value is neither a scalar nor annp.ndarray). The array form is shape-checked at both ingestion (dict_to_propertysetex) and validation time, so a wrong-length array fails atget_parametersrather than silently broadcasting insidenp.where. - Off-value: Verified off-value (corrects plan §4): set
chi_endemic == chi_epidemicandmu_j_epidemic_factor== 0to fully collapse both regime effects; anyepidemic_thresholdvalue then has no effect. The plan's "epidemic_threshold = 0(or large)" is not sufficient on its own: withepidemic_threshold = 0and any positiveIreported, the epidemic flag isTrueeverywhere andmu_jtpicks up the fullmu_j_epidemic_factorinflation; with a very large threshold the flag isFalseeverywhere (always endemic) butchi_endemicstill applies. The plan's parentheticalchi_endemic = chi_epidemic = 1.0is the necessary half of the fix, and note thatmu_j_epidemic_factorlives in the vital-dynamics group, not in regime-switching. - Consumer code:
src/laser/cholera/metapop/infectious.py,src/laser/cholera/metapop/params.py,src/laser/cholera/metapop/utils.py - Related parameters:
chi_endemic,chi_epidemic,mu_j_epidemic_factor,delta_reporting_cases - Notes: Two distinct uses with different threshold operands: (1)
infectious.py:198comparesIreported(count) toepidemic_threshold * N, so the threshold is interpreted as a fraction of population for the mortality switch; (2)infectious.py:265comparesinfected_fraction = Isym / N(fraction) toepidemic_thresholddirectly for the reporting-rate switch. The two checks use the same threshold value but with different left-hand-side scalings (Ireportedvs.Ireported / N) — functionally consistent because both reduce to comparingIsym / Nagainst the threshold. The field is commented out of the scalars and arrays tables indict_to_propertysetex(lines 466 and 499) and handled in a dedicated branch (lines 545–552).
epidemic_peaks¶
- What it controls: 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.
- Shape:
(num_peaks, 3)DataFrame with columnsiso_code,peak_date,loc_idx(theloc_idxcolumn is added indict_to_propertysetexby looking upiso_codeinlocation_name). - Dtype: pandas DataFrame (
iso_code: object / str;peak_date: object / str — not parsed todatetimehere;loc_idx: int). - Range: shape-only check — the validator only requires the field to be convertible to a DataFrame and to contain
iso_codeandpeak_datecolumns;dict_to_propertysetexadditionally asserts everyiso_codeis present inlocation_name. - Off-value:
omit the field entirely— the validator branch is gated onif "epidemic_peaks" in params, so dropping the key skips all checks; equivalently, settingweight_peak_timing=weight_peak_magnitude= 0skips the peak-shape branch insidecalc_model_likelihood. - Consumer code:
src/laser/cholera/metapop/params.py,src/laser/cholera/metapop/utils.py,src/laser/cholera/metapop/analyzer.py,src/laser/cholera/calc_model_likelihood.py - Related parameters:
weight_peak_timing,weight_peak_magnitude,sigma_peak_time,sigma_peak_log,reported_cases,date_start,date_stop - Notes: Optional field. Not consumed in the simulation dynamics at all — only flows through
analyzer.py(line 74) intocalc_model_likelihoodvia the analyzer's likelihood-computation path.dict_to_propertysetexaugments the DataFrame with aloc_idxcolumn (line 565) for downstream consumers, butvalidate_parametersonly checks theiso_code/peak_datecolumns. The R upstream's in-window peak filter is applied insidecalc_model_likelihood(post-port semantics, commitf8e3b38).