Add forced EIR feature

[pwinskill]

Summary

Adds an option to bypass the simulated mosquito component and drive infectious bites directly from a user-supplied, time-varying EIR, while preserving the overdispersed distribution of bites among individuals (age biting psi × individual heterogeneity zeta).

Useful when transmission intensity is a known/prescribed input (fitting to an observed EIR series, forcing counterfactual scenarios) rather than an emergent property of vector dynamics.

API

• set_forced_eir(parameters, timesteps, eir) — new exported helper. EIR is a step function in infectious bites per adult person per year, the same per-adult convention as set_equilibrium()'s default init_EIR, so forcing EIR = X reproduces a set_equilibrium(init_EIR = X) run. Split across species by biting proportion. Emits a warning that the EIR is applied directly.

How it works

• simulate_bites() overrides the per-species species_eir via forced_species_eir() and wraps the mosquito-only work (infectious counts, FOIM, mu, ODE/individual-mosquito updates) in a !force_EIR guard. The existing rpois + fast_weighted_sample(lambda) machinery is reused unchanged, so overdispersion is preserved.
• The vector ODE stepping, mosquito emergence, and mosquito-state renderers are disabled under a forced EIR, so EIR_*, n_bitten and all human outputs remain while E/L/P/Sm/Pm/Im counts, total_M, FOIM_* and mu_* are omitted.

Interactions

• Interventions are permitted (with a warning): direct-on-human interventions (drugs, vaccines) act as usual; bednets/spraying still redistribute the fixed bites (double-counting caveat — supply the pre-intervention EIR); vector-only interventions (set_carrying_capacity) are inert.
• Not supported for metapopulation simulations (errors early).
• No entomological lag; seasonality must be supplied directly as a fine-grained EIR series.

Testing

• New tests/testthat/test-forced-eir.R (53 assertions): unit tests for the helper/lookup/conversion, a low-EIR consistency check against a matched equilibrium run (validates the per-adult unit convention), multi-species split, vivax, individual-mosquitoes gating, warning behaviour, and process wiring.
• Full suite green locally (0 failures).
• New vignettes/Forced-EIR.Rmd.

Notes for reviewers

Reviewed by independent code-correctness and epidemiology passes; the key finding (per-adult vs population-average unit convention) was fixed by aligning forced_species_eir() with set_equilibrium's calculate_population_to_adult_EIR_scalar.

🤖 Generated with Claude Code