Defining epidemic scenarios and comparisons • scenarios

This is a bare-bones vignette showing the basic functionality of scenarios. This package is a work in progress, and more functionality and documentation, including updates to this vignette, will be added in the near future.

New to epidemic modelling in R? It may help to read The Epidemiologist R Handbook for a primer on scenario modelling.

Use case

To compare the outcomes of epidemic scenario models, such as the proportion of the population infected at a stage of the outbreak. Current use cases focus on comparing the cumulative proportion of individuals infected over the course of an epidemic wave, called the ‘final size’ of the epidemic.

What you need

An epidemic model R function that produces data frames as outputs,
Parameters to the epidemic model, which are typically arguments to the model function.

What we assume

That the epidemic scenarios are broadly comparable on a conceptual level.

Code

library(scenarios)

Components of an epidemic scenario model

The scenarios package is intended to help with the comparison of epidemic model scenarios. The scenarios package defines the scenario class, which is an epidemic model definition with or without its associated data. Each scenario is expected to have:

A model function,
The model parameters in the form of named function arguments, and
The number of replicates to run.

Defining scenarios for the final size of an epidemic

This example considers the definition of scenario specifications for the outbreak of an epidemic in the U.K. population, and uses demography and social contact data from the POLYMOD survey (Mossong et al. 2008). These are conveniently provided in the finalsize package, and can be obtained for other coutries (and other surveys) from the socialmixr package.

First define epidemic scenarios.

Code

# get inbuilt parameters using a convenience function
parameters_finalsize_low_r0 <- make_parameters_finalsize_UK(r0 = 1.5)
age_groups <- rownames(parameters_finalsize_low_r0$contact_matrix)

# define a low R0 scenario comparable to pandemic influenza
low_r0 <- scenario(
  name = "pandemic_flu",
  model_function = "finalsize::final_size",
  parameters = parameters_finalsize_low_r0,
  extra_info = list(
    age_groups = age_groups
  ),
  replicates = 1L
)

# define a higher R0 scenario comparable to Covid-19
# note no age group information is added yet
high_r0 <- scenario(
  name = "covid19",
  model_function = "finalsize::final_size",
  parameters = make_parameters_finalsize_UK(r0 = 5.0),
  replicates = 1L
)

Code

# print scenarios to examine information
low_r0
#> Epidemic scenario object
#>  Scenario name: "pandemic_flu"
#>  Model function: finalsize::final_size
#>  Extra information on: "age_groups"
#>  Scenario replicates: 1
#>  Scenario outcomes are not prepared
high_r0
#> Epidemic scenario object
#>  Scenario name: "covid19"
#>  Model function: finalsize::final_size
#>  Extra information on: 
#>  Scenario replicates: 1
#>  Scenario outcomes are not prepared

Getting scenario parameters

Scenario objects can be queried for their information using sce_get_information(). This function searches the scenario’s parameters and extra_info lists for named elements and returns them if found.

Code

# get information on the model parameter r0
sce_get_information(low_r0, which = "r0")
#> $r0
#> [1] 1.5

# get information on the demography groups
sce_get_information(low_r0, which = c("r0", "age_groups"))
#> $r0
#> [1] 1.5
#> 
#> $age_groups
#> [1] "[0,20)"  "[20,40)" "40+"

sce_get_information(low_r0, which = "contact_matrix")
#> $contact_matrix
#>                  
#> contact.age.group         [,1]         [,2]         [,3]
#>           [0,20)  4.514575e-08 1.600071e-08 8.965770e-09
#>           [20,40) 1.600071e-08 2.489595e-08 1.346051e-08
#>           40+     8.965770e-09 1.346051e-08 1.464763e-08

When the scenario does not have this information, an informative error message is returned.

Code

# no data found
sce_get_information(high_r0, which = "age_groups")
#> Error in sce_get_information(high_r0, which = "age_groups"): 'age_groups' not found among scenario model parameters or extra information

Adding information to scenarios

Information can be added to scenarios using sce_add_info(), with the information passed as an element of a named list. This function checks whether the list names are already present in the extra_info list, and adds them if they are not present, erroring otherwise.

Code

# add age group size information
high_r0 <- sce_add_info(
  high_r0, list(age_groups = age_groups)
)

# print to check that data are added
high_r0
#> Epidemic scenario object
#>  Scenario name: "covid19"
#>  Model function: finalsize::final_size
#>  Extra information on: "age_groups"
#>  Scenario replicates: 1
#>  Scenario outcomes are not prepared

Prepare scenario data

The scenario objects created thus far do not have any data, and this is because the model_function has not been called with the parameters to populate the data list.

The scenario outcome data can be added to the scenario by running the scenario using run_scenario().

Code

# add outcome data to scenarios
# assigning to different object for clarity
low_r0_data <- run_scenario(low_r0)
high_r0_data <- run_scenario(high_r0)

Code

# print scenario to check information
low_r0_data
#> Epidemic scenario object
#>  Scenario name: "pandemic_flu"
#>  Model function: finalsize::final_size
#>  Extra information on: "age_groups"
#>  Scenario replicates: 1
#>  Scenario outcomes are prepared

Getting scenario data

The scenario data can be accessed (so long as they are data frames) using sce_get_outcomes(), which returns a data.table of outcomes, with an additional column to indicate the replicate number.

Code

# peeking at data to examine column names
sce_peek_outcomes(low_r0_data, view_rows = FALSE)
#>       demo_grp       susc_grp susceptibility     p_infected      replicate 
#>    "character"    "character"      "numeric"      "numeric"      "integer"

# get full outcome data as data.table
sce_get_outcomes(low_r0_data)
#>    demo_grp   susc_grp susceptibility p_infected replicate
#>      <char>     <char>          <num>      <num>     <int>
#> 1:   [0,20) susc_grp_1              1  0.6544866         1
#> 2:  [20,40) susc_grp_1              1  0.5750030         1
#> 3:      40+ susc_grp_1              1  0.4588871         1

Check whether scenarios are comparable

Code

# comparing scenarios while expecting an identical match
# this is less useful when comparing scenarios that obviously
# differ on an important parameter such as R0
sce_are_comparable(
  baseline = low_r0_data,
  compare = high_r0_data,
  match_variables = "r0",
  comparison_variables = "p_infected"
)
#> Scenario parameters do not match, scenarios are not comparable.
#> These parameters do not match: 'r0'
#> [1] FALSE

# match variables must be *identical*
sce_are_comparable(
  baseline = low_r0_data,
  compare = high_r0_data,
  match_variables = "age_groups",
  comparison_variables = "p_infected"
)
#> [1] TRUE

Creating a comparison object

Scenarios can be wrapped into a comparison object. This is a convenient and structured way of holding numerous scenarios. A brief introduction is given here.

Code

# create object, passing prepared scenarios with some names
outbreak_comparison <- comparison(
  low_r0_data, high_r0_data,
  baseline = "pandemic_flu"
)

# check the scenario names in this comparison
sce_get_scenario_names(outbreak_comparison)
#> [1] "pandemic_flu" "covid19"

# print to examine output
outbreak_comparison
#> Scenario comparison object
#>  Number of scenarios: 2
#>  Baseline scenario: "pandemic_flu"
#>  All scenario data are prepared, use `sce_get_outcomes()` to get data
#>  Scenario matching variables:
#>   No matching variables specified yet.
#>  Scenario comparison variables:
#>   No comparison variables specified yet.
#>  Model functions found:
#>   finalsize::final_size

The data from individual scenarios can be accessed as a single data table using the sce_get_outcomes() function.

Code

# scenario output can be accessed from a comparison object as well
# using multiple dispatch on the sce_get_outcomes function
sce_get_outcomes(outbreak_comparison)
#>    demo_grp   susc_grp susceptibility p_infected replicate scenario_name
#>      <char>     <char>          <num>      <num>     <int>        <char>
#> 1:   [0,20) susc_grp_1              1  0.6544866         1  pandemic_flu
#> 2:  [20,40) susc_grp_1              1  0.5750030         1  pandemic_flu
#> 3:      40+ susc_grp_1              1  0.4588871         1  pandemic_flu
#> 4:   [0,20) susc_grp_1              1  0.9973053         1       covid19
#> 5:  [20,40) susc_grp_1              1  0.9941026         1       covid19
#> 6:      40+ susc_grp_1              1  0.9785699         1       covid19

References

Mossong, Joël, Niel Hens, Mark Jit, Philippe Beutels, Kari Auranen, Rafael Mikolajczyk, Marco Massari, et al. 2008. “Social Contacts and Mixing Patterns Relevant to the Spread of Infectious Diseases.” PLOS Medicine 5 (3): e74. https://doi.org/10.1371/journal.pmed.0050074.