Repository files navigation

Explore a range of infectious disease models in a consistent framework.The primary aim ofidmodelr is to provide a library of infectiousdisease models for researchers, students, and other interestedindividuals. These models can be used to understand the underlyingdynamics and as a reference point when developing models for research.idmodelr also provides a range of utilities. These include: plottingfunctionality; a simulation wrapper; scenario analysis tooling; aninteractive dashboard; tools for handling mult-dimensional models; andboth model and parameter look up tables. Unlike other modelling packagessuch aspomp,libbi andEpiModel,idmodelr serves primarily as an educational resource. It is mostcomparable toepirecipes butprovides a more consistent framework, anR based workflow, andadditional utility tooling. After users have explored model dynamicswithidmodelr they may then implement their model using one of thesepackages in order to utilise the model fitting tools they provide. Fornewer modellers, this package reduces the barrier to entry by containingmultiple infectious disease models, providing a consistent framework forsimulation and visualisation, andsignpostingtowards other, more research, focussed resources.

Install the CRAN version:

install.packages("idmodelr")

Alternatively install the development version from GitHub:

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

In this quick start guide we are going to be defining, simulating andplotting a Susceptible-Infected-Recovered deterministic compartmentalmodel with simple population demographics (births = deaths). The firststep is to load theidmodelr package.

library(idmodelr)

The next step is to find the model of interest amongst those implementedinidmodelr.model_details lists all of the models implemented inidmodelr and can be search usingdplyr, base R, or other dataframetools.

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, unionmodel_details %>%dplyr::filter(model_family%in%"SIR") %>%knitr::kable()

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 usingrequired_parameters.This returns a table containing all the parameters that must be definedin order to use the model as well as descriptive information for eachparameter.

parameters<- required_parameters("SIR_demographics_ode")knitr::kable(parameters)

Parameterise the model.

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

Check the initial conditions required by looking at the start of themodel 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. willrequire 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 odeinits=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()

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 thensimulate the updated model.

parameters_up<-parametersparameters_up[["mu"]]<-1/20traj_up<- simulate_model(model=SIR_demographics_ode,sim_fn=solve_ode,inits,parameters_up,times)

Plot the original trajectory and the updated trajectory. What has theimpact of increasing mortality been?

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

See the package vignettes for more help getting started and someadditional ideas for exploring infectious disease model dynamics.

A shiny application has been developed that showcases some of thefunctionality of theidmodelr package. This application allows theparameter spaces of a range of models built intoidmodelr to beexplored in an interactive session. It is designed to be used as ateaching aid when introducing people to the concepts behind infectiousdisease models without requiring them to interact with the underlyingcode. The code for the dashboard can be foundhere. It can be run locallyusing the following (Note: this will install required packages to yoursystem),

#install.packages("shiny")shiny::runGitHub("exploreidmodels","seabbs")

Additional models are extremely welcome!

To add models in the same family as those already implemented (i.eSIR_ode)please follow the implemented coding style closely (alternatively openanissue explaining whythis style needs updating). Models should be named using theircompartments in capitals followed by lower case model details, andfinally the model type. An example of this is theSIR_demographics_odemodel. For highly complex models only the most major model detailsshould be listed (aim for less than 40 characters). An entry formodel_details is also required (seemodel_details.R).If new parameters have been used then a description must be added toparameter_details (seeparameter_details.R).Please consider also adding to the testing suite for your new model (orflagging the lack of tests). Models can either be added via a pullrequest or via an issue.

To add a new family of models (i.e stochastic models) please open anissue outlining yourproposed approach. A new family of models is likely to require at leastits ownsolve_ (equivalent tosolve_ode)function and may also require other package changes. Models implementedin other languages (i.e C) are also very welcome.

File an issuehere if thereis any other feature, that you think is missing from the package, orbetter yet submit a pull request!

Please note that theidmodelr project is released with aContributorCode ofConduct.By contributing to this project, you agree to abide by its terms.

This packge was developed in a docker container based on thetidyverse docker image. Torun the docker image run:

docker run -d -p 8787:8787 --name idmodelr -e USER=seabbs -e PASSWORD=seabbs seabbs/idmodelr

The rstudio client can be found on port:8787 at your local machinesip. The default username:password is seabbs:seabbs, set the user with-e USER=username, and the password with- e PASSWORD=newpasswordhere. The default is to save the analysisfiles into the user directory. Alternatively, access the developmentenvironment viabinder.