SimInfDescribe your model using a simple string syntax in
R. mparse parses this description, generates model-specific
C code, and returns a SimInf_model object
ready for simulation.
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,
pre_code = NULL,
replicates = NULL
)a SimInf_model object
Character vector defining the state
transitions. Each element follows the format
"Source -> Propensity -> Target".
Syntax: "X -> rate_expr -> Y" moves
individuals from compartment X to Y with
rate rate_expr.
Empty Set: Use @ for the empty set
(e.g., "I -> mu*I -> @" for death, or
"@ -> lambda -> S" for birth).
Variables: Define intermediate variables
using <-. Example:
"N <- S + I + R". Variables can be used in
propensity expressions. Order does not matter.
Types: By default, variables are
double. Use (int) to force integer type
(e.g., "(int)N <- S+I+R").
Example: c("S -> beta*S*I/N -> I", "I -> gamma*I -> R",
"N <- S+I+R").
Character vector of compartment names (e.g.,
c("S", "I", "R")).
Optional local data (node-specific parameters). Can be:
A data.frame with one row per node (columns =
parameters).
A numeric matrix where columns are nodes and row names are parameters.
A named vector (for single-node models).
Optional global data (common to all nodes). Can be:
A named numeric vector (names identify parameters).
A one-row data.frame.
Unnamed parameters in a vector must be referenced by index in the transitions.
Initial state vector. Can be a data.frame,
matrix, or named vector. See
SimInf_model for details.
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.
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.
If integer: Represents the specific time points
(e.g., days, hours) at which to record the state.
If Date: Coerced to a numeric vector
representing the day of the year (1–366) relative
to the first date in the vector. The original Date
objects are preserved as names for the numeric vector,
facilitating time-series plotting.
A data.frame with the scheduled
events. Default is NULL i.e. no scheduled events in the
model.
Optional select matrix for events. Can be a matrix
or data.frame. Defines which compartments are affected
by events and their sampling weights. See
SimInf_events for detailed logic on
data.frame columns (compartment, select,
value). Default is NULL (no events).
Optional shift matrix for events. Can be a matrix
or data.frame. Defines how individuals are moved
between compartments during events. See
SimInf_events for detailed logic on
data.frame columns (compartment, shift,
value). Default is NULL (no events).
Optional character vector with C code for the post-time-step function. Should contain only the function body (code between curly brackets).
Logical. If TRUE, generates C enumeration
constants for parameters found in the u, v,
gdata, and ldata vectors to facilitate manual C
code modification or use in pts_fun. The name of each
enumeration constant is the upper-case version of the
corresponding parameter name (e.g., beta becomes
BETA). Additionally, the following constants are
automatically generated:
N_COMPARTMENTS_U: The number of discrete
compartments.
N_COMPARTMENTS_V: The number of continuous
state variables.
These constants facilitate indexing of the u and
v vectors in C code. Note that N_COMPARTMENTS_U
and N_COMPARTMENTS_V cannot be used as compartment or
variable names. Default is FALSE (parameters accessed
by integer indices).
Optional character vector with C code to be
inserted into the generated model code, after the enumeration
constants and before the transition rate functions. This
allows users to define helper functions or include statements
that can be referenced from transition propensity
expressions. Include statements, if needed, should be placed
at the beginning of the vector. Default is NULL, i.e.,
no additional code is inserted.
Number of model replicates to simulate (default
NULL, treated as 1L). When replicates >
1L, each replicate is simulated independently using its own
initial state (from u0), but shares the same parameters
(gdata, ldata), scheduled events, and structure
(transitions, compartments).
The u0 argument must contain initial states for all
replicates. Each replicate requires n nodes, where
n is the number of nodes in the model. Thus, u0
must have replicates * n nodes total. Nodes are grouped
by replicate: the first n nodes belong to replicate 1,
the next n to replicate 2, and so on. This allows
different starting conditions per replicate if desired.
ldata remains unchanged: its data per node is shared
across all replicates. Scheduled events are also shared—the
same event schedule applies to each replicate.
Use this when you need multiple independent stochastic
trajectories from the same model in a single simulation run.
For identical starting conditions across replicates, simply
repeat the same node pattern in u0.
SimInf_model for the class definition of the
returned model object. SIR, SEIR,
SIS, SISe for high-level model
constructors that use predefined structures. Vignette
"Getting started with mparse" for a comprehensive
tutorial on defining custom models, including syntax, variables,
and event handling. package_skeleton for creating
an installable R package from a mparse model.
## Create an SIR model with a defined population size variable.
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
)
## Running a model defined with 'mparse' compiles model-specific C
## code and requires a C compiler on the system. See the vignette
## "Getting started with mparse" for a complete walkthrough
## including running and plotting.
Run the code above in your browser using DataLab