Skip to content

Mozambique admin-2 (157 districts)

This configuration scales the parameter set up to a real country, broken down to admin-2. It covers the 157 districts of Mozambique on a daily tick from 2020-01-01 through 2024-12-31 (1827 ticks), with mobility, seasonality, and both transmission pathways enabled. It is intended for readers who want to see how the per-patch vectors and (nticks, npatches) matrices grow when J is no longer one, and what an end-to-end "country-level admin-2" configuration looks like when its geography and demography are sourced from laser-init rather than hand-authored. The output is a single gzipped JSON file (~64 KB on disk, ~22 MB raw) that get_parameters can read directly.

This is a worked example, not a calibrated fit. Per-patch transmission and reporting values are broadcast from the MOZ row of default_parameters.json; they are not tuned against district-level data.

What's in this configuration

Features ON:

  • Mobility (gravity-model coupling) — tau_i is the bundled non-zero MOZ vector broadcast to all 157 districts; mobility_omega and mobility_gamma are the scalar MOZ defaults. With J = 157, pi_ij is a non-trivial 157 by 157 coupling matrix.
  • Seasonality — all four amplitudes (a_1_j, a_2_j, b_1_j, b_2_j) and the period p are the MOZ defaults broadcast 157 times.
  • Human-to-human transmission — beta_j0_hum is the MOZ scalar broadcast to all 157 districts.
  • Environmental transmission — beta_j0_env, theta_j, kappa, decay_days_*, decay_shape_*, zeta_*, and the four psi_star_* are the MOZ defaults. psi_jt is a (1827, 157) ones matrix (constant suitability).
  • Vital dynamics — b_jt and d_jt are derived from the country-level CBR / CDR series in cxr.csv (per-1000 per-year converted to per-person per-day) and broadcast across all 157 patches.

Features OFF (justification for each off-value follows the §4 inert-values table in the docs plan):

  • Vaccination — nu_1_jt and nu_2_jt are zero matrices of shape (1827, 157); V1_j_initial = V2_j_initial = 0. With zero dose deliveries, phi_* and omega_* have no effect.
  • Regime switching — disabled by the corrected two-parameter partnership: chi_endemic == chi_epidemic == 1.0 and mu_j_epidemic_factor is a zero vector of length 157. Zeroing the threshold alone would not have disabled the feature; setting both partners makes epidemic_threshold inert.
  • Likelihood scoring — reported_cases and reported_deaths are NaN matrices, so likelihood is undefined; runs should not request a score against them.
  • Excess mortality — mu_jt is a zero matrix.

Files

Path Purpose
docs/configurations/code/multi-admin.json.gz The frozen parameter set, gzipped (~64 KB). This is what get_parameters reads.
docs/configurations/code/multi-admin.metadata.txt Records the laser-init invocation, the source files, the date pulled, and the upstream notes. The contract for reproducibility.
tmp/laser-init/mozambique-adm2/ Upstream extract directory (gitignored). Contains MOZ_admin2.gpkg, cxr.csv, provenance.json. Regenerated by re-running laser-init.
misc/build_multi_admin.py The reproducible build script that turns the laser-init extract into multi-admin.json.gz.

Running it

From the project root, with the package installed in the active environment, run:

metapop --params docs/configurations/code/multi-admin.json.gz --seed 20240930

From Python:

from pathlib import Path

from laser.cholera.metapop.model import run_model

params_path = Path("docs/configurations/code/multi-admin.json.gz")
model = run_model(params_path, seed=20240930)

get_parameters transparently decompresses the gzipped JSON; the loaded parameter set on model.params exposes model.params.nticks == 1827 and len(model.params.location_name) == 157.

To regenerate the extract from scratch (different country, different admin level, or a refreshed pull) re-run laser-init with the desired arguments:

uvx --with git+https://github.com/laser-base/laser-init laser-init MOZ 2 2000 2025

This drops a fresh extract under tmp/laser-init/; then re-run misc/build_multi_admin.py to produce a new multi-admin.json.gz. The CLI signature is laser-init <ISO3> <admin-level> <start-year> <end-year>; substitute as needed.

What to expect

With mobility, seasonality, and both transmission pathways on, a single seeded outbreak (the build script places 100 infected individuals in the single most-populous district) will not stay there. The gravity coupling redistributes force-of-infection across neighbours weighted by population and distance, so neighbouring districts pick up infection over the first few weeks. The seasonal multiplier on the transmission rate gives the trajectories a yearly rhythm across the five-year window. Because the per-patch parameters are broadcast — every district sees the same beta_j0_hum, beta_j0_env, theta_j — heterogeneity in outcomes comes from differences in initial population, district position in the gravity matrix, and the country-level birth / death broadcast, not from per-district calibration. Treat the trajectories as qualitatively plausible "country-shaped" output, not as a forecast for Mozambique.

Where this fits