<!-- README.md is generated from README.Rmd. Please edit that file -->

Infectious disease model library and utilities <img src="man/figures/logo.png" align="right" alt="" width="120" />

Explore a range of infectious disease models in a consistent framework. The primary aim of idmodelr is to provide a library of infectious disease models for researchers, students, and other interested individuals. These models can be used to understand the underlying dynamics and as a reference point when developing models for research. idmodelr also provides a range of utilities. These include: plotting functionality; a simulation wrapper; scenario analysis tooling; an interactive dashboard; tools for handling mult-dimensional models; and both model and parameter look up tables. Unlike other modelling packages such as pomp, libbi and EpiModel, idmodelr serves primarily as an educational resource. It is most comparable to epirecipes but provides a more consistent framework, an R based workflow, and additional utility tooling. After users have explored model dynamics with idmodelr they may then implement their model using one of these packages in order to utilise the model fitting tools they provide. For newer modellers, this package reduces the barrier to entry by containing multiple infectious disease models, providing a consistent framework for simulation and visualisation, and signposting towards other, more research, focussed resources.

Installation

Install the CRAN version:

install.packages("idmodelr")

Alternatively install the development version from GitHub:

# install.packages("devtools")
devtools::install_github("seabbs/idmodelr")

Documentation

Testing

Quick start

In this quick start guide we are going to be defining, simulating and plotting a Susceptible-Infected-Recovered deterministic compartmental model with simple population demographics (births = deaths). The first step is to load the idmodelr package.

library(idmodelr)

The next step is to find the model of interest amongst those implemented in idmodelr. model_details lists all of the models implemented in idmodelr and can be search using dplyr, base R, or other dataframe tools.

library(dplyr)
#> 
#> Attaching package: 'dplyr'
#> The following objects are masked from 'package:stats':
#> 
#>     filter, lag
#> The following objects are masked from 'package:base':
#> 
#>     intersect, setdiff, setequal, union

model_details %>% 
  dplyr::filter(model_family %in% "SIR") %>% 
  knitr::kable()

| model | model_family | time | type | recovered | exposed | treated | susceptible | risk_stratified | non_exponential | simple_demographics | vaccination | disease_example | language | parameters | |:---------------------------------|:-------------|:-----------|:--------------|:----------|:--------|:--------|:------------|:----------------|:----------------|:--------------------|:------------|:----------------|:---------|:--------------------------------| | SIR_ode | SIR | continuous | deterministic | no | no | no | no | no | no | no | no | none | R | beta, tau | | SIR_demographics_ode | SIR | continuous | deterministic | no | no | no | no | no | no | yes | no | none | R | beta, tau , mu | | SIR_vaccination_ode | SIR | continuous | deterministic | no | no | no | no | no | no | no | yes | none | R | beta , tau , lambda | | SIR_vaccination_demographics_ode | SIR | continuous | deterministic | no | no | no | no | no | no | yes | yes | none | R | beta , tau , lambda, alpha , mu |

Now look at the model and the model help file (?SIR_demographics_ode) to get an understanding of how the model is constructed.

SIR_demographics_ode
#> function (t, x, params) 
#> {
#>     S <- x[1]
#>     I <- x[2]
#>     R <- x[3]
#>     with(as.list(params), {
#>         N = S + I + R
#>         dS = -beta * S * I/N - mu * S + mu * N
#>         dI = beta * S * I/N - tau * I - mu * I
#>         dR = tau * I - mu * R
#>         derivatives <- c(dS, dI, dR)
#>         list(derivatives)
#>     })
#> }
#> <bytecode: 0x7fb5c4a7da08>
#> <environment: namespace:idmodelr>

Check the parameters required by the model using required_parameters. This returns a table containing all the parameters that must be defined in order to use the model as well as descriptive information for each parameter.

parameters <- required_parameters("SIR_demographics_ode")

knitr::kable(parameters)

| parameter | parameter_family | description | type | risk_stratified | non_exponential | |:----------|:-----------------|:--------------------------------------------------------------------------------------------------------------------------|:-----|:----------------|:----------------| | beta | transmission | Transmission rate = the transmission probability per contact * the number of contacts each individual has. | rate | no | no | | tau | recovery | Recovery rate. The reciprocal of the time infectious. | rate | no | no | | mu | demographics | The natural mortality rate. The reciprocal of the average lifespan. (for simple demographics this is also the birth rate. | rate | no | no |

Parameterise the model.

parameters <- data.frame(
  beta = 3, ##Transmission rate = contact rate * transmission probablity
  tau = 0.5, ## Rate recovcery = 1 / duration of infection
  mu = 1/81 ## Natural birth/death rate = 1 / average lifespan
)

Check the initial conditions required by looking at the start of the model function. In most cases this should match up to the model name (i.e S, I and R for an SIR model) but risk stratification etc. will require additional compartments.

inits <- data.frame(
  S = 999,
  I = 1,
  R = 0
  )

Specify the timespan over which to run the model.

times <- seq(0, 50, 0.1)

Simulate the model.

traj <- simulate_model(model = SIR_demographics_ode,
                       sim_fn = solve_ode, ##as solving an ode
                       inits = inits,
                       params = parameters,
                       times = times)


traj
#> # A tibble: 501 × 4
#>     time     S     I      R
#>    <dbl> <dbl> <dbl>  <dbl>
#>  1   0    999   1    0     
#>  2   0.1  999.  1.28 0.0567
#>  3   0.2  998.  1.64 0.129 
#>  4   0.3  998.  2.11 0.222 
#>  5   0.4  997.  2.70 0.342 
#>  6   0.5  996.  3.46 0.494 
#>  7   0.6  995.  4.43 0.690 
#>  8   0.7  993.  5.67 0.940 
#>  9   0.8  991.  7.25 1.26  
#> 10   0.9  989.  9.28 1.67  
#> # … with 491 more rows
#> # ℹ Use `print(n = ...)` to see more rows

Summarise the model.

summarise_model(traj) %>% 
  knitr::kable()

| Final size: S | Final size: I | Final size: R | Epidemic peak time | Epidemic peak | Epidemic duration | |--------------:|--------------:|--------------:|-------------------:|--------------:|------------------:| | 136 | 31 | 833 | 3.5 | 533 | Inf |

Plot the model trajectory.

plot_model(traj, facet = FALSE)
#> Warning: `guides(<scale> = FALSE)` is deprecated. Please use `guides(<scale> =
#> "none")` instead.

<!-- -->

Vary the model parameters, by increasing the mortality rate, and then simulate the updated model.

param