Geography & mobility¶
This group defines where each patch sits on the globe and how strongly its inhabitants mix with the other patches. The two coordinate vectors (longitude, latitude) feed the great-circle distance kernel that — together with the gravity exponents mobility_omega and mobility_gamma — builds the per-patch coupling matrix pi_ij. The per-patch coupling strength tau_i is the master switch: it scales how much of a patch's infectious (and, for the environmental pathway, susceptible) fraction is treated as moving out of its home patch each tick. Set tau_i to zeros and the spatial-mixing terms drop out of the dynamics; the other four parameters still have to be present for validation to pass, but they no longer influence the run.
Quick reference¶
| Parameter | Shape | Dtype | Range | Off-value |
|---|---|---|---|---|
longitude |
(npatches,) |
float32 |
shape-only check | n/a |
latitude |
(npatches,) |
float32 |
shape-only check | n/a |
tau_i |
(npatches,) |
float32 |
[0, 1] per element |
np.zeros(npatches) |
mobility_omega |
scalar | float32 |
unconstrained | n/a |
mobility_gamma |
scalar | float32 |
unconstrained | n/a |
longitude¶
- What it controls: Per-patch longitude coordinate; used together with
latitudeto compute great-circle distances that feed the gravity-model mobility matrix. - Shape:
(npatches,) - Dtype:
float32 - Range: shape-only check —
validate_parametersassertslen(params.longitude) == npatchesand nothing else. - Off-value:
n/a—longitudeis geographic input, not a feature toggle; it cannot be "switched off". The mobility dynamics are disabled by zeroingtau_i, not by zeroing the coordinates. - Consumer code:
src/laser/cholera/metapop/utils.py - Related parameters:
latitude,tau_i,mobility_omega,mobility_gamma - Notes: Read inside
utils.py'sdistance(...)helper when assemblingpi_ij. Whentau_i = 0the coordinates are still required by the validator, but the resultingpi_ijis never multiplied into a non-zero term so the values do not influence the dynamics.
latitude¶
- What it controls: Per-patch latitude coordinate; combined with
longitudefor inter-patch distance in the gravity-mobility kernel (and used to order patches in one plot). - Shape:
(npatches,) - Dtype:
float32 - Range: shape-only check —
validate_parametersassertslen(params.latitude) == npatchesand nothing else. - Off-value:
n/a— geographic input, not a feature toggle. Seetau_ifor the inert setting that removes spatial mixing from the dynamics. - Consumer code:
src/laser/cholera/metapop/utils.py,src/laser/cholera/metapop/humantohuman.py - Related parameters:
longitude,tau_i,mobility_omega,mobility_gamma - Notes:
humantohuman.pyuseslatitudeonly to sort patches for a diagnostic plot; the dynamics consume it only through thedistance(...)call inutils.py.
tau_i¶
- What it controls: Per-patch fraction of infectious (and, for environmental exposure, susceptible) individuals that move out of their home patch; the master switch for spatial mixing.
- Shape:
(npatches,) - Dtype:
float32 - Range:
[0, 1]per element —validate_parametersassertsnp.all((params.tau_i >= 0.0) & (params.tau_i <= 1.0)). The same range assertion is repeated indict_to_propertysetex(line 554) andvalidate_parameters(line 746) inparams.py. - Off-value:
np.zeros(npatches)— withtau_i = 0,humantohuman.pysetslocal_frac = 1and the immigrating term(0 * total_i) * pi_ij.Tcollapses to zero, so the force of infection uses only the local infected count andpi_ijdrops out. Inenvtohuman.pylocal_frac = 1 - tau_i = 1, so every susceptible is exposed locally and patches do not exchange environmental exposure. - Consumer code:
src/laser/cholera/metapop/humantohuman.py,src/laser/cholera/metapop/envtohuman.py,src/laser/cholera/metapop/derivedvalues.py,src/laser/cholera/metapop/utils.py,src/laser/cholera/metapop/params.py - Related parameters:
mobility_omega,mobility_gamma,longitude,latitude,pi_ij - Notes:
tau_iis the only parameter in this group with a validator-enforced numeric range; the coordinates and the gravity exponents are validated for presence/shape only. Treattau_ias the canonical knob for turning spatial mixing on or off — do not try to disable mobility by, for example, settingmobility_omega = 0or zeroing the coordinates.
mobility_omega¶
- What it controls: 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. - Shape: scalar
- Dtype:
float32 - Range: unconstrained —
validate_parametersonly checks"mobility_omega" in params. Any float passes validation. - Off-value:
n/a—mobility_omegais a kernel shape parameter, not a feature toggle. It is validator-required even whentau_iis zero:pi_ijis still constructed insideutils.pyusingmobility_omega, but every term it contributes to is multiplied bytau_i = 0inhumantohuman.pyand so it has no effect on the dynamics. The right way to disable spatial mixing is to settau_ito zeros while leavingmobility_omegaat any valid float. - Consumer code:
src/laser/cholera/metapop/utils.py - Related parameters:
mobility_gamma,tau_i,longitude,latitude
mobility_gamma¶
- What it controls: Exponent on inter-patch distance (with sign reversed) in the gravity model; larger values penalize long-distance movement more strongly when building
pi_ij. - Shape: scalar
- Dtype:
float32 - Range: unconstrained —
validate_parametersonly checks"mobility_gamma" in params. Any float passes validation. - Off-value:
n/a— kernel shape parameter, not a feature toggle. It is validator-required even whentau_iis zero:pi_ijis still assembled withmobility_gammain the distance term, but the resulting matrix is zeroed out of the dynamics by thetau_i = 0multiplication inhumantohuman.py. Disable spatial mixing by zeroingtau_i, not by adjustingmobility_gamma. - Consumer code:
src/laser/cholera/metapop/utils.py - Related parameters:
mobility_omega,tau_i,longitude,latitude