tutorial3 – malariaverse

Part 3 - Tailoring Model Inputs to Local Contexts

In this section, we’ll focus on tailoring the inputs needed to run malariasimulation for a specific geography or context. We’ll discuss how the site package and its associated country site files can provide a systematic starting point for context-specific malaria modelling runs. By the end of this section, you’ll be able to:

Understand how country site files collate essential data for all malaria-endemic countries.
Identify the data inputs required for malaria simulations and where they come from.
Use the site package to convert country information into malariasimulation parameters.
Run a model for a single site
Understand why a simulation must cover the full time period, plus a burn-in.
Understand the limitations of using global datasets.

Systematically Collating Data into Country Site Files

Running malariasimulation for a specific context requires diverse data inputs, including historical interventions, seasonality, population demography, and mosquito population characteristics. Collecting this information systematically across all malaria-endemic countries is no small task. To address this, the country site files consolidate these inputs for each country using globally available datasets.

The site files aim to provide a comprehensive overview of relevant data for each malaria-endemic country. This includes ecological, demographic, and intervention-specific information, which serves as a starting point for simulations. But please note:

A starting point, not a finished input

It is essential to review these data critically before applying them to your specific context.
If using a site file, it is important that you correctly reference each data input - referencing the site package alone isn’t enough!

To explore the full range of inputs included in the country site files, see the detailed documentation on the site website.

Introducing the site Package

The site package provides tools to access and utilise the country site files for malaria modelling. This R package simplifies the process of tailoring your modelling inputs by:

Accessing the Country Site Files

You can sign up for access to the site files and download them directly. Detailed instructions on how to do this, along with an example, are available here.

Converting Country Information into Simulation Parameters

Once downloaded, the site package allows you to convert the collated country-specific data into the input parameters required by malariasimulation. This includes calibrating baseline transmission, seasonal patterns, and intervention histories to the context of your chosen geography.

Limitations of the Country Site Files

While the site files offer a valuable starting point for malaria modelling, there are some important caveats to keep in mind:

Data coarseness

The site files are based on globally available datasets, and some inputs are only available at the country level. This means that the spatial and temporal resolution of the data may be too coarse for detailed local analyses. If you are using a site file for context-specific modelling, it is highly recommended to review and incorporate any additional local data that may be available to refine and recalibrate the inputs.

Data source identification

If using site files for research, it is crucial to identify and properly cite the underlying datasets. Each section of the site file includes relevant data sources, which must be reviewed and included in your research citations. Simply citing the site package is not sufficient.

With these limitations in mind, let’s proceed to run a single site simulation and see how the site files can be applied in practice.

Example: Running a Single Site Simulation

Using the site package, we’ll demonstrate how to set up and run a simulation for a single site.

Always simulate the full time period, including a burn-in

It is tempting to run only the years you are interested in - for example setting start_year = 2019 and end_year = 2025 for an analysis covering 2019 to 2025. This will give you the wrong answer.

malariasimulation is a dynamic model with a memory: what happens at any point in time depends on everything that came before it. In particular:

Acquired immunity builds up and wanes over a lifetime, and depends on an individual’s full history of exposure.
Intervention history persists. Nets distributed in previous years are still in use (and still decaying), and past treatment, chemoprevention and vaccination have shaped current infection and immunity.
Mosquito populations respond to rainfall and vector control with a lag.
The age structure of the population, and the age pattern of immunity within it, take time to establish.

On top of this, the baseline transmission (EIR) in a site file is calibrated over the full historical period, given the observed historical scale-up of interventions (see Recalibration below). Truncating the simulation period invalidates that calibration.

A run that starts in 2019 therefore begins from a population that has never experienced the historical scale-up of interventions, and the 2019 to 2025 output will be biased. Nothing in the output will tell you that this has happened.

Always run from before the start of the site file data, including a burn-in, through to your end year - then subset the output afterwards. Site file data typically begin around the year 2000, so the start_year = 1980 below gives a 20 year burn-in. Check the earliest year in the intervention and demography tables of your own site file. Years before the site file data start are simulated with zero intervention coverage and the earliest available demography profile.

library(site)
library(malariasimulation)

# Download the latest site file for Nigeria
nigeria <- fetch_site(
  iso3c = "NGA"
)

# Pull out data for a single site from the site file.
print(nigeria$sites[1,])
site <- subset_site(
  site = nigeria,
  site_filter = nigeria$sites[1,]
)

# Add in model net distributions
site$interventions$itn$implementation$itn_input_dist <- site::site_usage_to_model_distribution(
  usage = site$interventions$itn$use$itn_use,
  usage_year = site$interventions$itn$use$year,
  usage_day_of_year = site$interventions$itn$use$usage_day_of_year,
  distribution_year = site$interventions$itn$implementation$year,
  distribution_day_of_year = site$interventions$itn$implementation$distribution_day_of_year,
  distribution_lower = site$interventions$itn$implementation$distribution_lower,
  distribution_upper = site$interventions$itn$implementation$distribution_upper,
  net_loss_function = netz::net_loss_map,
  half_life = site$interventions$itn$retention_half_life
)

# Convert to malariasimulation parameters
parameters <- site_parameters(
  interventions = site$interventions,
  demography = site$demography,
  vectors = site$vectors,
  seasonality = site$seasonality,
  start_year = 1980,
  end_year = 2025
)

# Run the simulation
simulation <- run_simulation(
  timesteps = parameters$timesteps,
  parameters = parameters
)

Subsetting the output to the years of interest

Because we always run the full time period, the raw output contains the burn-in and all of the historical years, not just the period we want to report on. We deal with that after the simulation has run, by dropping the burn-in and then filtering to the years of interest:

library(postie)
library(dplyr)

# Drop the 20 year burn-in (1980 - 1999) from the raw output
simulation <- drop_burnin(
  x = simulation,
  burnin = 20 * 365
)

# Process the output. The simulation now starts in the year 2000
prevalence <- get_prevalence(
  x = simulation,
  baseline_year = 2000
)

# Keep only the period we are reporting on
prevalence_2019_2025 <- prevalence |>
  filter(year >= 2019, year <= 2025)

Note the difference: the simulation still ran from 1980, we have simply chosen not to look at the early years. If instead you had set start_year = 2019, the model itself would never have seen 1980 - 2018 and the output for 2019 onwards would be wrong.

Future scenarios

Often, we would like to model future scenarios. To do this we can modify a version of the site, adding future rows (years) to the interventions data.frame.

Interventions do not continue by themselves

If you set an end_year beyond the last year of data in the site file, the future is not a continuation of the present. Site file interventions are only scheduled at the years that appear in its intervention tables, so beyond the final year of data:

Event-based interventions - net distributions, IRS, SMC, PMC and vaccination - simply stop happening. Nets already in use continue to decay, so net coverage falls away towards zero.
Continuous coverages, such as treatment, hold at their last specified value.

The result is a future that nobody intended: vector control abandoned, treatment carrying on. If you want to model the future, specify it explicitly by adding future years to the intervention data.frames - which is exactly what the scene package is for.

For a full exploration of designing and specifying future scenarios, please see the documentation for the scene package.

Recalibration

The baseline transmission for each site has been calibrated such that given the observed historical scale-up of interventions we best match prevalence estimates. This is a very important step as the level of baseline transmission is very influential, impacting the malaria burden and how well interventions may be able to control malaria in your simulation.

This calibration is contingent on the historical scale up of interventions and other aspects of the site file which determine dynamics in the past, and it assumes the simulation is run over the full time period (which is why shortening the run period, as described above, breaks it).

Change the history, recalibrate the baseline

Any change you make to the historical inputs of a site will necessitate re-calibrating the baseline transmission. This could be, for example, updating the historical scale up of bed nets with improved, site-specific data, or changing the assumptions of which vector species are present at a site. The EIR that came with the site file was fitted to the original history - it is no longer the right EIR once you have changed that history.

For an in depth explainer and additional functionality to help with re-calibration please see the information in the cali package