mparse: Model parser to define new models to run in 'SimInf'

In SimInf: A Framework for Data-Driven Stochastic Disease Spread Simulations

Model parser to define new models to run in SimInf

Description

Describe your model in a logical way in R. mparse creates a SimInf_model object with your model definition that is ready to run.

Usage

mparse(
  transitions = NULL,
  compartments = NULL,
  ldata = NULL,
  gdata = NULL,
  u0 = NULL,
  v0 = NULL,
  tspan = NULL,
  events = NULL,
  E = NULL,
  N = NULL,
  pts_fun = NULL,
  use_enum = FALSE
)

Arguments

transitions	character vector containing transitions on the form "X -> ... -> Y". The left (right) side is the initial (final) state and the propensity is written in between the ->-signs. The special symbol @ is reserved for the empty set. For example, transitions = c("S -> beta*S*I/(S+I+R) -> I", "I -> gamma*I -> R") expresses the SIR model. 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 instead be written transitions = c("S -> beta*S*I/N -> I", "I -> gamma*I -> R", "N <- S+I+R"). By default, the type of a variable is defined as a double in the generated C code, but it is possible to also define it as an integer by writing (int) before the variable name. For example, for the SIR model, the population size can be defined as "(int)N <- S+I+R". It is also possible to explicitly use (double) in front of the variable name, but it is not needed because it is the default. Note that the order of propensities and variables does not matter.
compartments	contains the names of the involved compartments, for example, compartments = c("S", "I", "R").
ldata	optional data for the nodes. Can be specified as a data.frame with one row per node, as a numeric matrix where column ldata[, j] contains the local data vector for the node j, or as a as a named vector when the model only contains one node. If ldata is specified as a data.frame, each column is one parameter. If v0 is specified as a matrix, it must have row names to identify the parameters in the transitions. If v0 is specified as a named vector, the names identify the parameters. The local data vector is passed as an argument to the transition rate functions and the post time step function.
gdata	optional data that are common to all nodes in the model. Can be specified either as a optionally named numeric vector or as as a one-row data.frame. The names are used to identify the parameters in the transitions. When gdata is specified as a vector, it is possible to have parameters without names, however, these parameters will not be automatically identified by mparse but need to be identified in the code by the user. The global data vector is passed as an argument to the transition rate functions and the post time step function.
u0	A data.frame with the initial state in each node, i.e., the number of individuals in each compartment in each node when the simulation starts (see ‘Details’). The parameter u0 can also be an object that can be coerced to a data.frame, e.g., a named numeric vector will be coerced to a one row data.frame.
v0	optional data with the initial continuous state in each node. v0 can be specified as a data.frame with one row per node, as a numeric matrix where column v0[, j] contains the initial state vector for the node j, or as a named vector when the model only contains one node. If v0 is specified as a data.frame, each column is one parameter. If v0 is specified as a matrix, the row names identify the parameters. If v0 is specified as a named vector, the names identify the parameters. The ‘v’ vector is passed as an argument to the transition rate functions and the post time step function. The continuous state can be updated in the post time step function.
tspan	A vector (length >= 1) of increasing time points where the state of each node is to be returned. Can be either an integer or a Date vector. A Date vector is coerced to a numeric vector as days, where tspan[1] becomes the day of the year of the first year of tspan. The dates are added as names to the numeric vector.
events	A data.frame with the scheduled events. Default is NULL i.e. no scheduled events in the model.
E	matrix to handle scheduled events, see SimInf_events. Default is NULL i.e. no scheduled events in the model.
N	matrix to handle scheduled events, see SimInf_events. Default is NULL i.e. no scheduled events in the model.
pts_fun	optional character vector with C code for the post time step function. The C code should contain only the body of the function i.e. the code between the opening and closing curly brackets.
use_enum	generate enumeration constants for the indices to each parameter in the 'u', 'v', 'ldata', and 'gdata' vectors in the generated C code. The name of each enumeration constant will be transformed to the upper-case name of the corresponding parameter, for example, a parameter 'beta' will become 'BETA'. The enumeration constants 'N_COMPARTMENTS_U' and 'N_COMPARTMENTS_V' will be automatically added to facilitate indexing 'u' and 'v' in the C code. These two enumeration constants cannot be used as a compartment or variable name. Using enumeration constants can make it easier to modify the C code afterwards, or when writing C code for the pts_fun parameter. Default is FALSE, i.e., the parameters are specified by using integer indices for the parameters.

Value

a SimInf_model object

Examples

## Not run: 
## Use the model parser to create a 'SimInf_model' object that
## expresses the SIR model, where 'beta' is the transmission rate
## and 'gamma' is the recovery rate.
model  <- mparse(transitions = c("S -> beta*S*I/N -> I",
                                 "I -> gamma*I -> R",
                                 "N <- S+I+R"),
                 compartments = c("S", "I", "R"),
                 gdata = c(beta = 0.16, gamma = 0.077),
                 u0 = data.frame(S = 100, I = 1, R = 0),
                 tspan = 1:100)

## Run and plot the result
set.seed(22)
result <- run(model)
plot(result)

## End(Not run)

SimInf documentation built on Nov. 18, 2025, 1:08 a.m.