Overview
laser.cholera.metapop
¶
laser.cholera.metapop — metapopulation cholera simulation pipeline.
Re-exports the canonical component classes and get_parameters /
scenario helpers as a flat namespace, so user code can write
from laser.cholera.metapop import Susceptible, Exposed, ... instead
of importing from each submodule. Importing this package also
triggers logsetup which configures
the laser.cholera logger and reserves a timestamped log file path.
The default component pipeline (Susceptible -> Exposed ->
Recovered -> Infectious -> Vaccinated -> Census ->
HumanToHuman -> EnvToHuman -> Environmental -> DerivedValues ->
Analyzer -> Recorder -> Parameters) is wired up by
run_model.
__all__
module-attribute
¶
__all__ = [
"Analyzer",
"Census",
"DerivedValues",
"EnvToHuman",
"Environmental",
"Exposed",
"HumanToHuman",
"Infectious",
"Parameters",
"Recorder",
"Recovered",
"Susceptible",
"Vaccinated",
"get_parameters",
"scenario",
]
Analyzer
¶
Final-tick likelihood evaluator for calibration / scoring workflows.
Attributes:
| Name | Type | Description |
|---|---|---|
model |
The parent |
Source code in src/laser/cholera/metapop/analyzer.py
27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 | |
__init__
¶
Register the analyzer on the model (no state is allocated).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
Model
|
The |
required |
check
¶
No-op: Analyzer has no prerequisites that need pre-tick validation.
The likelihood call validates its own inputs on the final tick.
__call__
¶
Calculate log likelihood on the final tick.
Source code in src/laser/cholera/metapop/analyzer.py
plot
¶
Yield one Matplotlib figure overlaying every SEIRV channel for the largest patch.
Pulls the R-transposed series from model.results (so channels
are indexed [patch, tick]) and plots all of S, Isym,
Iasym, R, V1, V2 for the single largest-by-initial-S
patch.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fig
|
Figure
|
Optional existing Matplotlib |
None
|
Yields:
| Type | Description |
|---|---|
str
|
The string label |
Source code in src/laser/cholera/metapop/analyzer.py
Census
¶
Population-census component: maintains patches.N as the sum of all SEIRV compartments.
Attributes:
| Name | Type | Description |
|---|---|---|
model |
The parent |
Source code in src/laser/cholera/metapop/census.py
__init__
¶
Allocate the N per-patch population vector.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
Model
|
The |
required |
Raises:
| Type | Description |
|---|---|
AttributeError
|
When |
Source code in src/laser/cholera/metapop/census.py
check
¶
Seed N[0] by running __call__ with tick=-1.
Slightly hacky: __call__ writes into N[tick + 1], so
tick=-1 ends up writing the initial population from the
compartments that have already been seeded by their own
__init__ methods. Avoids duplicating the sum logic.
Source code in src/laser/cholera/metapop/census.py
__call__
¶
Sum the SEIRV compartments at tick + 1 into patches.N[tick + 1].
Compartments that are not present on model.people (e.g.
V1 / V2 if Vaccinated was excluded) are silently skipped,
making the component robust to alternative pipelines.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
Model
|
The parent |
required |
tick
|
int
|
Current simulation tick. |
required |
Raises:
| Type | Description |
|---|---|
AssertionError
|
When the resulting per-patch total is negative (indicates an upstream compartment underflowed). |
Source code in src/laser/cholera/metapop/census.py
plot
¶
Yield one Matplotlib figure of N(t) for the ten largest patches.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fig
|
Figure
|
Optional existing Matplotlib |
None
|
Yields:
| Type | Description |
|---|---|
str
|
The string label |
Source code in src/laser/cholera/metapop/census.py
DerivedValues
¶
Computes end-of-run diagnostics: spatial hazard and coupling matrix.
Attributes:
| Name | Type | Description |
|---|---|---|
model |
The parent |
Source code in src/laser/cholera/metapop/derivedvalues.py
36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 | |
__init__
¶
Allocate spatial_hazard and coupling arrays on model.patches.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
Model
|
The |
required |
Raises:
| Type | Description |
|---|---|
AttributeError
|
When |
Source code in src/laser/cholera/metapop/derivedvalues.py
check
¶
Validate every upstream attribute and parameter the final-tick math needs.
Verifies model.people has S/Isym/Iasym; model.patches
has N/beta_jt_human/pi_ij; and params provides
beta_j0_hum, p, and tau_i. These are populated by
Susceptible,
Infectious,
Census, and
HumanToHuman
earlier in the pipeline.
Raises:
| Type | Description |
|---|---|
AttributeError
|
When |
ValueError
|
When |
Source code in src/laser/cholera/metapop/derivedvalues.py
__call__
¶
Calculate derived values for the model.
Spatial hazard and coupling are calculated at the end of the simulation.
Spatial hazard per location and tick:
Prevalence fraction and its time-average per location:
Inter-location coupling — Pearson correlation between prevalence fractions:
Equivalently:
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
Model
|
The parent |
required |
tick
|
int
|
Current simulation tick. The computation is a no-op
for every tick except the last
( |
required |
Source code in src/laser/cholera/metapop/derivedvalues.py
plot
¶
Yield one Matplotlib heatmap of spatial_hazard (patch × tick).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fig
|
Figure | None
|
Optional existing Matplotlib |
None
|
Yields:
| Type | Description |
|---|---|
str
|
The string label |
Source code in src/laser/cholera/metapop/derivedvalues.py
Environmental
¶
Environmental-reservoir component: maintains patches.W per tick.
Attributes:
| Name | Type | Description |
|---|---|---|
model |
The parent |
Source code in src/laser/cholera/metapop/environmental.py
33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 | |
__init__
¶
Allocate W / delta_jt and pre-compute the suitability-to-decay map.
delta_jt is built once from params.psi_jt via
map_suitability_to_decay
(a Beta-CDF interpolator between decay_days_short and
decay_days_long).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
Model
|
The |
required |
Raises:
| Type | Description |
|---|---|
AttributeError
|
When |
ValueError
|
When any of |
Source code in src/laser/cholera/metapop/environmental.py
check
¶
Validate Isym / Iasym are available and shedding parameters are present.
Raises:
| Type | Description |
|---|---|
AttributeError
|
When |
ValueError
|
When |
Source code in src/laser/cholera/metapop/environmental.py
__call__
¶
Advance W one tick: carry forward, decay, then shed from infectious cohorts.
Decay is clamped not to exceed W so the reservoir never goes
negative even on extreme Poisson draws. WASH coverage
(1 - theta_j) attenuates the shed amount entering the reservoir.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
Model
|
The parent |
required |
tick
|
int
|
Current simulation tick. |
required |
Source code in src/laser/cholera/metapop/environmental.py
plot
¶
Yield three Matplotlib figures: reservoir trajectory, decay heatmap, suitability map.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fig
|
Figure
|
Optional existing Matplotlib |
None
|
Yields:
| Type | Description |
|---|---|
str
|
Three labels in order: |
str
|
|
Source code in src/laser/cholera/metapop/environmental.py
EnvToHuman
¶
Environmental transmission component: turns reservoir W into new S -> E infections.
Attributes:
| Name | Type | Description |
|---|---|---|
model |
The parent |
Source code in src/laser/cholera/metapop/envtohuman.py
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 | |
__init__
¶
Allocate Psi and bake the beta_jt_env seasonality matrix.
beta_jt_env is computed once at construction time from
params.psi_jt (deviation-from-mean suitability) and
params.beta_j0_env (baseline) and is constant across the run.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
Model
|
The |
required |
Raises:
| Type | Description |
|---|---|
AttributeError
|
When |
ValueError
|
When |
AssertionError
|
When the allocated |
Source code in src/laser/cholera/metapop/envtohuman.py
check
¶
Validate the consumer-side state and transmission parameters.
Asserts that model.people.S and .E exist, that
model.patches.W exists (allocated by Environmental), and
that params provides tau_i, theta_j, and kappa.
Raises:
| Type | Description |
|---|---|
AttributeError
|
When |
ValueError
|
When |
Source code in src/laser/cholera/metapop/envtohuman.py
__call__
¶
Compute environmental force-of-infection Psi and convert S -> E.
Psi[tick + 1] = beta_jt_env[tick] * (1 - theta_j) * W /
(kappa + W). New infections drawn from Binomial(S_next,
1 - exp(-Psi)), where S_next is the susceptible count after
natural mortality and any human-to-human force-of-infection has
already been applied earlier in the tick.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
Model
|
The parent |
required |
tick
|
int
|
Current simulation tick. |
required |
Raises:
| Type | Description |
|---|---|
AssertionError
|
When the post-infection susceptible population goes negative. |
Source code in src/laser/cholera/metapop/envtohuman.py
plot
¶
Yield one Matplotlib figure of Psi(t) for the ten largest patches.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fig
|
Figure
|
Optional existing Matplotlib |
None
|
Yields:
| Type | Description |
|---|---|
str
|
The string label |
Source code in src/laser/cholera/metapop/envtohuman.py
Exposed
¶
Exposed compartment: tracks E_j(t) and bleeds off non-disease deaths each tick.
Attributes:
| Name | Type | Description |
|---|---|---|
model |
The parent |
Source code in src/laser/cholera/metapop/exposed.py
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 | |
__init__
¶
Allocate the E state vector and seed it from E_j_initial.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
Model
|
The |
required |
Raises:
| Type | Description |
|---|---|
AttributeError
|
When |
ValueError
|
When |
Source code in src/laser/cholera/metapop/exposed.py
check
¶
Validate the iota progression-rate parameter and ensure shared bookkeeping is allocated.
Raises:
| Type | Description |
|---|---|
ValueError
|
When |
Source code in src/laser/cholera/metapop/exposed.py
__call__
¶
Advance E from tick to tick + 1: carry forward, then remove non-disease deaths.
Progression E -> Isym / Iasym (governed by iota and sigma)
is handled by Infectious;
this method only applies natural mortality from d_jt.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
Model
|
The parent |
required |
tick
|
int
|
Current simulation tick. |
required |
Source code in src/laser/cholera/metapop/exposed.py
plot
¶
Yield a single Matplotlib figure of E(t) for the ten largest patches.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fig
|
Figure | None
|
Optional existing Matplotlib |
None
|
Yields:
| Type | Description |
|---|---|
str
|
The string label |
Source code in src/laser/cholera/metapop/exposed.py
HumanToHuman
¶
Direct (human-to-human) transmission component for the metapop pipeline.
Owns the per-patch force-of-infection vector patches.Lambda, the
spatial-connectivity matrix patches.pi_ij, and the seasonality
matrix patches.beta_jt_human.
Attributes:
| Name | Type | Description |
|---|---|---|
model |
The parent |
Source code in src/laser/cholera/metapop/humantohuman.py
33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 | |
__init__
¶
Allocate Lambda, build pi_ij from lat/long, and bake the seasonality matrix.
pi_ij is computed once via
get_pi_from_lat_long
(gravity model), and beta_jt_human once via
get_daily_seasonality
(Fourier sum) — neither changes during the run.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
Model
|
The |
required |
Raises:
| Type | Description |
|---|---|
AttributeError
|
When |
ValueError
|
When any of the seasonality / mobility parameters
( |
Source code in src/laser/cholera/metapop/humantohuman.py
check
¶
Validate the consumer-side compartments and transmission parameters.
Asserts that model.people has Isym, Iasym, S, E;
model.patches.N exists; and params provides tau_i,
beta_j0_hum, alpha_1, and alpha_2.
Raises:
| Type | Description |
|---|---|
AttributeError
|
When |
ValueError
|
When |
Source code in src/laser/cholera/metapop/humantohuman.py
__call__
¶
Calculate the current human-to-human transmission rate per patch.
Source code in src/laser/cholera/metapop/humantohuman.py
plot
¶
Yield three Matplotlib figures: transmission rate, pi_ij heatmap, seasonality heatmap.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fig
|
Figure
|
Optional existing Matplotlib |
None
|
Yields:
| Type | Description |
|---|---|
str
|
Three labels in order: |
str
|
|
str
|
|
str
|
|
Source code in src/laser/cholera/metapop/humantohuman.py
Infectious
¶
Infectious compartment: tracks Isym(t), Iasym(t), disease deaths, and reported cases.
Attributes:
| Name | Type | Description |
|---|---|---|
model |
The parent |
Source code in src/laser/cholera/metapop/infectious.py
46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 | |
__init__
¶
Allocate Isym / Iasym and the disease-deaths / reporting bookkeeping vectors.
Splits params.I_j_initial into symptomatic and asymptomatic
seed populations using the symptomatic fraction params.sigma.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
Model
|
The |
required |
Raises:
| Type | Description |
|---|---|
AttributeError
|
When |
ValueError
|
When a required |
Source code in src/laser/cholera/metapop/infectious.py
check
¶
Validate every parameter and prerequisite attribute used by __call__.
Asserts that model.people.R exists (so recovery can route into
it) and that params contains d_jt, mu_j_baseline,
mu_j_slope, mu_j_epidemic_factor, epidemic_threshold,
gamma_1, gamma_2, iota, sigma, rho, and rho_deaths.
Raises:
| Type | Description |
|---|---|
AttributeError
|
When |
ValueError
|
When any of the required |
Source code in src/laser/cholera/metapop/infectious.py
__call__
¶
Advance Isym / Iasym one tick: deaths, recoveries, then E -> I progression.
For each patch and within each of Isym and Iasym:
- Carry forward; subtract non-disease deaths (
d_jt). - For
Isymonly: computemu_jt = mu_baseline * (1 + slope * t_factor) * (1 + epidemic_factor * epidemic_flag), sample disease deaths fromBinomial(Isym, 1 - exp(-mu_jt)), and updatepatches.disease_deathsand laggedreported_deaths. - Sample recoveries (
gamma_1for symptomatic,gamma_2for asymptomatic) and add toR[tick + 1]. - Sample
E -> Iprogression fromBinomial(E_next, 1 - exp(-iota)), split bysigma, and add intoIsym/Iasym. - Update lagged
reported_casesusingrhoand thechi_endemic/chi_epidemichealthcare-access modifier.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
Model
|
The parent |
required |
tick
|
int
|
Current simulation tick. |
required |
Raises:
| Type | Description |
|---|---|
AssertionError
|
When any compartment goes negative after a draw (indicates the implementation's invariants have regressed). |
Source code in src/laser/cholera/metapop/infectious.py
147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 | |
plot
¶
Yield four Matplotlib figures: symptomatic, asymptomatic, total, and reported-vs-actual cases.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fig
|
Figure | None
|
Optional existing Matplotlib |
None
|
Yields:
| Type | Description |
|---|---|
str
|
Four labels in order: |
str
|
|
str
|
|
Source code in src/laser/cholera/metapop/infectious.py
Parameters
¶
Pipeline component whose only job is to render an extensive parameter overview.
Has no per-tick work — __call__ is a no-op. The
plot generator
yields nine figures (initial populations, four rate heatmaps,
emigration/WASH scatters, mortality and suitability heatmaps) that
surface the input parameters for human review.
Attributes:
| Name | Type | Description |
|---|---|---|
model |
The parent |
Source code in src/laser/cholera/metapop/params.py
843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 | |
__init__
¶
Register the component on model (no state is allocated).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
Model
|
The |
required |
check
¶
Validate that model.params is attached.
Raises:
| Type | Description |
|---|---|
AssertionError
|
When |
Source code in src/laser/cholera/metapop/params.py
__call__
¶
plot
¶
Yield nine Matplotlib figures summarizing the input parameters.
Generates (in order): initial-population stacked bar; b_jt /
d_jt / nu_1_jt / nu_2_jt / mu_jt per-patch-per-tick
heatmaps; tau_i and theta_j per-patch scatter; psi_jt
suitability heatmap.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fig
|
Figure
|
Optional existing Matplotlib |
None
|
Yields:
| Type | Description |
|---|---|
str
|
Nine labels in order: |
str
|
|
str
|
|
str
|
|
str
|
|
str
|
|
str
|
|
str
|
|
str
|
|
Source code in src/laser/cholera/metapop/params.py
881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 | |
Recorder
¶
Pipeline component that dumps a configurable HDF5 snapshot on the final tick.
No per-tick work until the last tick; gated by params.hdf5_output
and the params.return property whitelist.
Attributes:
| Name | Type | Description |
|---|---|---|
model |
The parent |
Source code in src/laser/cholera/metapop/recorder.py
__init__
¶
Register the component on model (no state is allocated).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
Model
|
The |
required |
check
¶
Warn (but do not fail) if expected people / patches frames are missing.
Uses warnings.warn rather than assert so a recorder
configured against an unusual minimal model still lets the
run complete; the final-tick dump will then simply have no
groups to write.
Source code in src/laser/cholera/metapop/recorder.py
__call__
¶
On the final tick, write whitelisted state to HDF5 if hdf5_output is set.
Quietly returns (with an info-level log explaining which gate
was unmet) when either params.hdf5_output is false or
params.return is unset / empty. When both are present and
truthy, dispatches to
save_hdf5_parameters
or
save_compressed_hdf5_parameters
based on params.compress.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
Model
|
The parent |
required |
tick
|
int
|
Current simulation tick. |
required |
Source code in src/laser/cholera/metapop/recorder.py
Recovered
¶
Recovered compartment: tracks R_j(t) and lets natural immunity wane back to S.
Attributes:
| Name | Type | Description |
|---|---|---|
model |
The parent |
Source code in src/laser/cholera/metapop/recovered.py
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 | |
__init__
¶
Allocate the R state vector and seed it from R_j_initial.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
Model
|
The |
required |
Raises:
| Type | Description |
|---|---|
AttributeError
|
When |
ValueError
|
When |
Source code in src/laser/cholera/metapop/recovered.py
check
¶
Validate that S (waning destination), d_jt, and epsilon are available.
Raises:
| Type | Description |
|---|---|
AttributeError
|
When |
ValueError
|
When |
Source code in src/laser/cholera/metapop/recovered.py
__call__
¶
Advance R from tick to tick + 1: carry forward, subtract deaths, wane to S.
Waning is computed against the post-deaths cohort so dying-then- waning individuals are not counted twice.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
Model
|
The parent |
required |
tick
|
int
|
Current simulation tick. |
required |
Raises:
| Type | Description |
|---|---|
AssertionError
|
When the post-deaths-and-waning recovered population goes negative. |
Source code in src/laser/cholera/metapop/recovered.py
plot
¶
Yield one Matplotlib figure of R(t) for the ten largest patches.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fig
|
Figure
|
Optional existing Matplotlib |
None
|
Yields:
| Type | Description |
|---|---|
str
|
The string label |
Source code in src/laser/cholera/metapop/recovered.py
Susceptible
¶
Bases: Component
Susceptible compartment: tracks S_j(t) and runs births / non-disease deaths each tick.
Attributes:
| Name | Type | Description |
|---|---|---|
model |
The parent |
Source code in src/laser/cholera/metapop/susceptible.py
37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 | |
__init__
¶
Allocate the S state vector and seed it from S_j_initial.
Adds model.people.S (shape (nticks + 1, npatches)) and
model.patches.births (per-tick birth counts) as int32 vector
properties, then writes the initial susceptible counts from
params.S_j_initial into S[0].
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
Model
|
The |
required |
Raises:
| Type | Description |
|---|---|
AttributeError
|
When |
ValueError
|
When |
Source code in src/laser/cholera/metapop/susceptible.py
check
¶
Validate prerequisites that other components are expected to set up.
Confirms model.patches.N (population census, set up by
Census) and
params.b_jt / params.d_jt (birth / non-disease-mortality
matrices) are present. Lazily allocates
model.patches.non_disease_deaths if no earlier component has
already done so.
Raises:
| Type | Description |
|---|---|
AttributeError
|
When |
ValueError
|
When |
Source code in src/laser/cholera/metapop/susceptible.py
__call__
¶
Advance S from tick to tick + 1: carry forward, kill, then birth.
For each patch:
S[tick + 1] := S[tick](carry forward).- Sample non-disease deaths from
Binomial(S, 1 - exp(-d_jt))and subtract; bank intopatches.non_disease_deaths[tick]. - Sample births from
Poisson(N * b_jt[tick])(whereNis the current total patch population fromCensus) and add; record intopatches.births[tick].
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
Model
|
The parent |
required |
tick
|
int
|
Current simulation tick (0-indexed); |
required |
Raises:
| Type | Description |
|---|---|
AssertionError
|
When the post-deaths susceptible population
goes negative (indicates a draw exceeded the population,
which should be impossible for a |
Source code in src/laser/cholera/metapop/susceptible.py
plot
¶
Yield one Matplotlib figure showing S(t) for the ten largest patches.
Patches are ranked by params.S_j_initial so the largest
initial-susceptible populations are surfaced. Used by
Model.visualize to
generate the per-component PDF / on-screen plots.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fig
|
Figure
|
Optional existing Matplotlib |
None
|
Yields:
| Type | Description |
|---|---|
str
|
The string label |
str
|
the figure title / PDF section heading). |
Source code in src/laser/cholera/metapop/susceptible.py
Vaccinated
¶
Vaccinated compartment: tracks V1(t) / V2(t) and the per-tick dose flows.
Attributes:
| Name | Type | Description |
|---|---|---|
model |
The parent |
|
sources |
Names of |
Source code in src/laser/cholera/metapop/vaccinated.py
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 | |
sources
instance-attribute
¶
__init__
¶
Allocate V1 / V2 and the dose-bookkeeping vectors; seed from V*_j_initial.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
Model
|
The |
required |
Raises:
| Type | Description |
|---|---|
AttributeError
|
When |
ValueError
|
When |
Source code in src/laser/cholera/metapop/vaccinated.py
check
¶
Validate dose-related parameters and the source compartments.
Asserts that model.people.S and model.people.E exist and
that params provides phi_1, phi_2, omega_1, omega_2,
nu_1_jt, nu_2_jt, and d_jt.
Raises:
| Type | Description |
|---|---|
AttributeError
|
When |
ValueError
|
When any of |
Source code in src/laser/cholera/metapop/vaccinated.py
__call__
¶
Advance V1 / V2 one tick: deaths, waning, then dose deliveries.
Doses scheduled for this tick are clamped against the available
donor population (warning logged at DEBUG if the schedule
exceeds capacity). Only the phi_*-effective fraction transits
to the vaccinated compartment; ineffective doses leave the
recipient in their original compartment.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
Model
|
The parent |
required |
tick
|
int
|
Current simulation tick. |
required |
Source code in src/laser/cholera/metapop/vaccinated.py
131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 | |
plot
¶
Yield two Matplotlib figures: V1(t) and V2(t) for the ten largest patches.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fig
|
Figure | None
|
Optional existing Matplotlib |
None
|
Yields:
| Type | Description |
|---|---|
str
|
Two labels in order: |
str
|
|
Source code in src/laser/cholera/metapop/vaccinated.py
get_parameters
¶
get_parameters(
paramsource: str | Path | dict | None = None,
do_validation: bool = True,
mods: dict | None = None,
) -> PropertySetEx
Load parameters from disk or memory and return a typed PropertySetEx.
The canonical entry point for assembling a simulation parameter set. Accepts a parameter source in any of four forms:
None→ loadssrc/laser/cholera/metapop/data/default_parameters.json(the bundled defaults).strorpathlib.Path→ loaded from that filesystem path. Supported suffixes are.jsonand.json.gz; HDF5 sources are no longer supported.dict→ ingested in-memory viadict_to_propertysetex.
Any of those is then optionally merged with caller-supplied mods:
overrides of existing keys are applied first (logged at INFO level),
additions of new keys follow. After merge, validate_parameters is
called unless do_validation=False. Finally, default values for
the visualization/output flags (visualize, pdf, quiet)
are filled in if absent so downstream code can read them
unconditionally.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
paramsource
|
str | Path | dict | None
|
|
None
|
do_validation
|
bool
|
When True (default), run
|
True
|
mods
|
dict | None
|
Optional dict of overrides/additions to merge after loading
the base parameters. Typed via
|
None
|
Returns:
| Type | Description |
|---|---|
PropertySetEx
|
A populated |
PropertySetEx
|
with all known fields coerced to their working dtypes and |
PropertySetEx
|
(when |
PropertySetEx
|
invariants. |
Raises:
| Type | Description |
|---|---|
KeyError
|
If |
ValueError
|
If |
ValueError
|
From |
Example
Load the bundled defaults with a one-month simulation window:
from laser.cholera.metapop.params import get_parameters from laser.cholera.utils import sim_duration from datetime import datetime params = get_parameters(mods=sim_duration(datetime(2024, 1, 1), datetime(2024, 1, 31))) params.nticks 31
Source code in src/laser/cholera/metapop/params.py
132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 | |