Future scenario

library(scene)

Using a site file in the malariaverse, we can define a future scenario by extending and populating the $interventions section to include future years. Scene provides a small set of generic helpers that operate on any single intervention implementation data.frame (for example site$interventions$itn$use or site$interventions$smc$implementation). The typical pattern is: pull out an implementation data.frame, modify it with the scene helpers, then assign it back.

In the current site file structure, $interventions is a nested list, with one entry per intervention type. ITN usage, for instance, lives in example_site$interventions$itn$use:

country	iso3c	name_1	urban_rural	year	itn_use	usage_day_of_year
Example	EXP	North	rural	2016	0.0	180
Example	EXP	North	rural	2017	0.1	180
Example	EXP	North	rural	2018	0.2	180
Example	EXP	North	rural	2019	0.4	180
Example	EXP	North	rural	2020	0.4	180
Example	EXP	South	rural	2016	0.0	180
Example	EXP	South	rural	2017	0.1	180
Example	EXP	South	rural	2018	0.2	180
Example	EXP	South	rural	2019	0.4	180
Example	EXP	South	rural	2020	0.4	180

Let’s start by creating a new site file for our scenario, and defining the grouping variable(s) that identify each site:

new_scenario <- example_site
group_var <- names(new_scenario$sites)
group_var
#> [1] "country"     "iso3c"       "name_1"      "urban_rural"

We work on one implementation data.frame at a time. Here we extend ITN usage to some future years with expand_years():

itn_use <- new_scenario$interventions$itn$use |>
  expand_years(max_year = 2025, group_var = group_var)

We can now add target change points. Add a target ITN usage of 60% in all sites by 2024:

itn_use <- itn_use |>
  set_change_point(sites = new_scenario$sites, var = "itn_use", year = 2024, target = 0.6)

Changes can be restricted to specific sites. For example, target 80% usage only in the “North” site:

to_change <- new_scenario$sites[new_scenario$sites$name_1 == "North", ]
itn_use <- itn_use |>
  set_change_point(sites = to_change, var = "itn_use", year = 2025, target = 0.8)

We can also pick sites based on their history. ever_used() and last_used() return the grouping columns for sites that have ever (or most recently) used an intervention - handy as the sites argument to set_change_point(). For example, target SMC only in sites that have used it before:

smc <- new_scenario$interventions$smc$implementation |>
  expand_years(max_year = 2025, group_var = group_var)

ever_smc <- ever_used(
  x = new_scenario$interventions$smc$implementation,
  var = "smc_cov",
  group_var = group_var
)
ever_smc
#> # A tibble: 1 × 4
#>   country iso3c name_1 urban_rural
#>   <chr>   <chr> <chr>  <chr>      
#> 1 Example EXP   South  rural

smc <- smc |>
  set_change_point(sites = ever_smc, var = "smc_cov", year = 2025, target = 0.5)

Now we fill the remaining missing values. We can scale linearly up to a target with linear_interpolate():

itn_use <- itn_use |>
  linear_interpolate(vars = "itn_use", group_var = group_var)
smc <- smc |>
  linear_interpolate(vars = "smc_cov", group_var = group_var)

And carry the last value forward (or any other columns we want to extrapolate) with fill_extrapolate():

itn_use <- itn_use |>
  fill_extrapolate(group_var = group_var)
smc <- smc |>
  fill_extrapolate(group_var = group_var)

Finally, assign the modified data.frames back into the site file:

new_scenario$interventions$itn$use <- itn_use
new_scenario$interventions$smc$implementation <- smc

country	iso3c	name_1	urban_rural	year	itn_use	usage_day_of_year
Example	EXP	North	rural	2016	0.00	180
Example	EXP	North	rural	2017	0.10	180
Example	EXP	North	rural	2018	0.20	180
Example	EXP	North	rural	2019	0.40	180
Example	EXP	North	rural	2020	0.40	180
Example	EXP	North	rural	2021	0.45	180
Example	EXP	North	rural	2022	0.50	180
Example	EXP	North	rural	2023	0.55	180
Example	EXP	North	rural	2024	0.60	180
Example	EXP	North	rural	2025	0.80	180
Example	EXP	South	rural	2016	0.00	180
Example	EXP	South	rural	2017	0.10	180
Example	EXP	South	rural	2018	0.20	180
Example	EXP	South	rural	2019	0.40	180
Example	EXP	South	rural	2020	0.40	180
Example	EXP	South	rural	2021	0.45	180
Example	EXP	South	rural	2022	0.50	180
Example	EXP	South	rural	2023	0.55	180
Example	EXP	South	rural	2024	0.60	180
Example	EXP	South	rural	2025	0.60	180

Note that the order of operations matters: you can’t linear_interpolate() a variable after you’ve already fill_extrapolate()d it, as there will be no gaps left to interpolate.

Net distribution

Future ITN usage on its own is not enough to run the model - it needs to be converted into the model input net distribution (itn_input_dist). This conversion now lives in the site package, which wraps the netz net-loss model. After expanding site$interventions$itn$implementation to the same future years, estimate the input distribution from your future usage with site::site_usage_to_model_distribution():

itn_impl <- new_scenario$interventions$itn$implementation |>
  expand_years(max_year = 2025, group_var = group_var)

itn_impl$itn_input_dist <- site::site_usage_to_model_distribution(
  usage = new_scenario$interventions$itn$use$itn_use,
  usage_year = new_scenario$interventions$itn$use$year,
  usage_day_of_year = new_scenario$interventions$itn$use$usage_day_of_year,
  distribution_year = itn_impl$year,
  distribution_day_of_year = itn_impl$distribution_day_of_year
)

new_scenario$interventions$itn$implementation <- itn_impl

Inspecting the scenario

The site package provides plotting functions to inspect a site file, for example:

site::plot_site_interventions(new_scenario)
site::plot_site_diagnostic(new_scenario)

We now have a fully populated new scenario. In reality there is more complexity in site file interventions than shown here (multiple rounds, vaccine doses, etc.), but the same principles apply: extract the relevant implementation data.frame, modify it with the scene helpers, and assign it back.