Learn R Programming

A flexible and efficient framework for data-driven stochastic disease spread simulations

SimInf

The package provides an efficient and very flexible framework to conduct data-driven epidemiological modeling in realistic large scale disease spread simulations. The framework integrates infection dynamics in subpopulations as continuous-time Markov chains using the Gillespie stochastic simulation algorithm and incorporates available data such as births, deaths and movements as scheduled events at predefined time-points. Using C code for the numerical solvers and 'OpenMP' (if available) to divide work over multiple processors ensures high performance when simulating a sample outcome. One of our design goals was to make the package extendable and enable usage of the numerical solvers from other R extension packages in order to facilitate complex epidemiological research. The package contains template models and can be extended with user-defined models.

Getting started

You can use one of the predefined compartment models in SimInf, for example, SEIR. But you can also define a custom model 'on the fly' using the model parser method mparse. The method takes a character vector of transitions in the form of X -> propensity -> Y and automatically generates the C and R code for the model. The left hand side of the first arrow (->) is the initial state, the right hand side of the last arrow (->) is the final state, and the propensity is written between the two arrows. The flexibility of the mparse approach allows for quick prototyping of new models or features. To illustrate the mparse functionality, let us consider the SIR model in a closed population i.e., no births or deaths. Let beta denote the transmission rate of spread between a susceptible individual and an infectious individual and gamma the recovery rate from infection (gamma = 1 / average duration of infection). It is also possible to define variables which can then be used in calculations of propensities or in calculations of other variables. A variable is defined by the operator <-. Using a variable for the size of the population, the SIR model can be described as:

library(SimInf)

transitions <- c("S -> beta*S*I/N -> I",
                 "I -> gamma*I -> R",
                 "N <- S+I+R")
compartments <- c("S", "I", "R")

The transitions and compartments variables together with the constants beta and gamma can now be used to generate a model with mparse. The model also needs to be initialised with the initial condition u0 and tspan, a vector of time points where the state of the system is to be returned. Let us create a model that consists of 1000 replicates of a population, denoted a node in SimInf, that each starts with 99 susceptibles, 5 infected and 0 recovered individuals.

n <- 1000
u0 <- data.frame(S = rep(99, n), I = rep(5, n), R = rep(0, n))

model <- mparse(transitions = transitions,
                compartments = compartments,
                gdata = c(beta = 0.16, gamma = 0.077),
                u0 = u0,
                tspan = 1:150)

To generate data from the model and then print some basic information about the outcome, run the following commands:

result <- run(model)
result
#> Model: SimInf_model
#> Number of nodes: 1000
#> Number of transitions: 2
#> Number of scheduled events: 0
#> 
#> Global data
#> -----------
#>  Parameter Value
#>  beta      0.160
#>  gamma     0.077
#> 
#> Compartments
#> ------------
#>      Min. 1st Qu. Median   Mean 3rd Qu.   Max.
#>  S   1.00   19.00  30.00  40.74   60.00  99.00
#>  I   0.00    0.00   4.00   6.87   11.00  47.00
#>  R   0.00   28.00  67.00  56.39   83.00 103.00

There are several functions in SimInf to facilitate analysis and post-processing of simulated data, for example, trajectory, prevalence and plot. The default plot will display the median count in each compartment across nodes as a colored line together with the inter-quartile range using the same color, but with transparency.

plot(result)

Most modeling and simulation studies require custom data analysis once the simulation data has been generated. To support this, SimInf provides the trajectory method to obtain a data.frame with the number of individuals in each compartment at the time points specified in tspan. Below is the first 10 lines of the data.frame with simulated data.

trajectory(result)
#>    node time  S I R
#> 1     1    1 98 6 0
#> 2     2    1 98 6 0
#> 3     3    1 98 6 0
#> 4     4    1 99 5 0
#> 5     5    1 97 7 0
#> 6     6    1 98 5 1
#> 7     7    1 99 5 0
#> 8     8    1 99 5 0
#> 9     9    1 97 7 0
#> 10   10    1 97 6 1
...

Finally, let us use the prevalence method to explore the proportion of infected individuals across all nodes. It takes a model object and a formula specification, where the left hand side of the formula specifies the compartments representing cases i.e., have an attribute or a disease and the right hand side of the formula specifies the compartments at risk. Below is the first 10 lines of the data.frame.

prevalence(result, I ~ S + I + R)
#>    time prevalence
#> 1     1 0.05196154
#> 2     2 0.05605769
#> 3     3 0.06059615
#> 4     4 0.06516346
#> 5     5 0.06977885
#> 6     6 0.07390385
#> 7     7 0.07856731
#> 8     8 0.08311538
#> 9     9 0.08794231
#> 10   10 0.09321154
...

Learn more

See the vignette to learn more about special features that the SimInf R package provides, for example, how to:

  • use continuous state variables

  • use the SimInf framework from another R package

  • incorporate available data such as births, deaths and movements as scheduled events at predefined time-points.

Installation

You can install the released version of SimInf from CRAN

install.packages("SimInf")

or use the remotes package to install the development version from GitHub

library(remotes)
install_github("stewid/SimInf")

We refer to section 3.1 in the vignette for detailed installation instructions.

Authors

In alphabetical order: Pavol Bauer , Robin Eriksson , Stefan Engblom , and Stefan Widgren (Maintainer)

Any suggestions, bug reports, forks and pull requests are appreciated. Get in touch.

Citation

If you use SimInf in your research, please cite:

Widgren S, Bauer P, Eriksson R, Engblom S (2019). SimInf: An R Package for Data-Driven Stochastic Disease Spread Simulations. Journal of Statistical Software, 91(12), 1–42. https://doi.org/10.18637/jss.v091.i12

Bauer P, Engblom S, Widgren S (2016). Fast event-based epidemiological simulations on national scales. International Journal of High Performance Computing Applications, 30(4), 438–453. https://doi.org/10.1177/1094342016635723

Acknowledgments

This software has been made possible by support from the Swedish Research Council within the UPMARC Linnaeus center of Excellence (Pavol Bauer, Robin Eriksson, and Stefan Engblom), the Swedish Research Council Formas (Stefan Engblom and Stefan Widgren), the Swedish Board of Agriculture (Stefan Widgren), the Swedish strategic research program eSSENCE (Stefan Widgren), and in the framework of the Full Force project, supported by funding from the European Union’s Horizon 2020 Research and Innovation programme under grant agreement No 773830: One Health European Joint Programme (Stefan Widgren).

Versioning

The SimInf package uses semantic versioning.

License

The SimInf package is licensed under the GPLv3.

Copy Link

Version

Install

install.packages('SimInf')

Monthly Downloads

1,223

Version

10.0.0

License

GPL-3

Issues

1

Pull Requests

0

Stars

36

Forks

16

Maintainer

Stefan Widgren

Last Published

November 13th, 2025

Functions in SimInf (10.0.0)

SISe_sp

Create a SISe_sp model
SimInf_individual_events-class

Class "SimInf_individual_events"
SISe3_sp-class

Definition of the ‘SISe3_sp’ model
SimInf

A Framework for Data-Driven Stochastic Disease Spread Simulations
SISe3_sp

Create an SISe3_sp model
SimInf_events-class

Class "SimInf_events"
SISe_sp-class

Definition of the SISe_sp model
SimInf_events

Create a SimInf_events object
SISe3

Create a SISe3 model
SimInf_abc-class

Class "SimInf_abc"
abc

Approximate Bayesian computation
as.data.frame.SimInf_events

Coerce events to a data frame
SimInf_pmcmc-class

Class "SimInf_pmcmc"
add_spatial_coupling_to_ldata

Add information about spatial coupling between nodes to 'ldata'
as.data.frame.SimInf_individual_events

Coerce to data frame
as.data.frame.SimInf_pmcmc

Coerce to data frame
SimInf_model-class

Class "SimInf_model"
SimInf_model

Create a SimInf_model
as.data.frame.SimInf_abc

Coerce to data frame
SimInf_pfilter-class

Class "SimInf_pfilter"
events_SISe

Example data to initialize events for the ‘SISe’ model
events

Extract the events from a SimInf_model object
events_SIS

Example data to initialize events for the ‘SIS’ model
edge_properties_to_matrix

Convert an edge list with properties to a matrix
continue_pmcmc

Run more iterations of PMCMC
continue_abc

Run more generations of ABC SMC
boxplot,SimInf_model-method

Box plot of number of individuals in each compartment
events_SIR

Example data to initialize events for the ‘SIR’ model
events_SEIR

Example data to initialize events for the ‘SEIR’ model
distance_matrix

Create a distance matrix between nodes for spatial models
individual_events

Individual events
indegree

Determine in-degree for each node in a model
lambertW0

Lambert W0 function
ldata

Extract local data from a node
gdata

Extract global data from a SimInf_model object
get_individuals

Extract individuals from SimInf_individual_events
length,SimInf_pmcmc-method

Length of the MCMC chain
logLik,SimInf_pfilter-method

Log likelihood
events_SISe3

Example data to initialize events for the ‘SISe3’ model
gdata<-

Set a global data parameter for a SimInf_model object
mparse

Model parser to define new models to run in SimInf
package_skeleton

Create a package skeleton from a SimInf_model
n_generations

Determine the number of generations
n_nodes

Determine the number of nodes in a model
n_replicates

Determine the number of replicates in a model
nodes

Example data with spatial distribution of nodes
pairs,SimInf_model-method

Scatterplot of number of individuals in each compartment
outdegree

Determine out-degree for each node in a model
node_events

Transform individual events to node events for a model
n_compartments

Determine the number of compartments in a model
prevalence,SimInf_model-method

Calculate prevalence from a model object with trajectory data
plot,SimInf_events-method

Display the distribution of scheduled events over time
plot,SimInf_pmcmc-method

Display the PMCMC posterior distribution
plot,SimInf_individual_events-method

Display the distribution of individual events over time
plot,SimInf_abc-method

Display the ABC posterior distribution
pmcmc

Particle Markov chain Monte Carlo (PMCMC) algorithm
plot,SimInf_model-method

Display the outcome from a simulated trajectory
plot,SimInf_pfilter-method

Diagnostic plot of a particle filter object
prevalence,SimInf_pfilter-method

Extract prevalence from running a particle filter
pfilter

Bootstrap particle filter
prevalence

Generic function to calculate prevalence from trajectory data
select_matrix<-

Set the select matrix for a SimInf_model object
shift_matrix

Extract the shift matrix from a SimInf_model object
set_num_threads

Specify the number of threads that SimInf should use
show,SimInf_abc-method

Print summary of a SimInf_abc object
shift_matrix<-

Set the shift matrix for a SimInf_model object
punchcard<-

Set a template for where to record result during a simulation
prevalence,SimInf_pmcmc-method

Extract prevalence from fitting a PMCMC algorithm
select_matrix

Extract the select matrix from a SimInf_model object
run

Run the SimInf stochastic simulation algorithm
show,SimInf_pfilter-method

Brief summary of a SimInf_pfilter object
show,SimInf_model-method

Brief summary of SimInf_model
summary,SimInf_pfilter-method

Detailed summary of a SimInf_pfilter object
show,SimInf_events-method

Brief summary of SimInf_events
summary,SimInf_model-method

Detailed summary of a SimInf_model object
show,SimInf_individual_events-method

Print summary of a SimInf_individual_events object
show,SimInf_pmcmc-method

Brief summary of a SimInf_pmcmc object
summary,SimInf_events-method

Detailed summary of a SimInf_events object
summary,SimInf_abc-method

Detailed summary of a SimInf_abc object
summary,SimInf_individual_events-method

Detailed summary of a SimInf_individual_events object
trajectory,SimInf_pfilter-method

Extract filtered trajectory from running a particle filter
u0_SIR

Example data to initialize the ‘SIR’ model
trajectory,SimInf_pmcmc-method

Extract filtered trajectories from fitting a PMCMC algorithm
u0_SEIR

Example data to initialize the ‘SEIR’ model
u0

Get the initial compartment state
u0_SIS

Example data to initialize the ‘SIS’ model
trajectory

Generic function to extract data from a simulated trajectory
trajectory,SimInf_model-method

Extract data from a simulated trajectory
summary,SimInf_pmcmc-method

Detailed summary of a SimInf_pmcmc object
u0<-

Update the initial compartment state u0 in each node
u0_SISe3

Example data to initialize the ‘SISe3’ model
u0_SISe

Example data to initialize the ‘SISe’ model
v0<-

Update the initial continuous state v0 in each node
SIR

Create an SIR model
SIR-class

Definition of the SIR model
SISe

Create a SISe model
C_code

Extract the C code from a SimInf_model object
SIS-class

Definition of the SIS model
SEIR-class

Definition of the ‘SEIR’ model
SISe3-class

Definition of the ‘SISe3’ model
SEIR

Create an SEIR model
SISe-class

Definition of the SISe model
SIS

Create an SIS model