get_epi: Get and Set Epidemic Outputs in Network Models

In EpiModel: Mathematical Modeling of Infectious Disease Dynamics

Get and Set Epidemic Outputs in Network Models

Description

Retrieve, create, and edit the epidemic outputs of the main netsim_dat object of network models, from inside module functions. Each epidemic output is a vector with one value per time step, which becomes a column of the data frame returned by as.data.frame.netsim() after the simulation.

• get_epi() returns one output, for all time steps or for the time steps in at. get_epi_list() returns several outputs as a named list.

• set_epi() records value at one time step, the current one by default, and creates the output if it does not exist. add_epi() creates an output set to NA at every time step.

Unlike the other set_ functions, set_epi() takes a time step at, which comes last and must be passed by name.

See net-accessor for an overview of the accessors.

Usage

get_epi(dat, item, at = NULL, override.null.error = FALSE)

get_epi_list(dat, item = NULL)

set_epi(dat, item, value, ..., at = NULL)

add_epi(dat, item)

Arguments

dat	Main netsim_dat object containing a networkDynamic object and other initialization information passed from netsim().
item	Name of the epidemic output. For get_epi_list(), a character vector of names, or NULL (default) for all outputs.
at	For get_epi(), the time steps at which to return the output, with NULL (default) for all time steps. For set_epi(), the time step at which to record value, which defaults to the current time step (get_current_timestep()) when NULL.
override.null.error	If TRUE, return NULL instead of an error when item does not exist (default = FALSE).
value	Value of the output at time step at.
...	Must be empty. It makes at a named-only argument of set_epi(), so that calls written for the set_epi(dat, item, at, value) signature of EpiModel 2.6 and earlier error instead of silently swapping at and value.

Value

For get_epi(), the output vector, or its values at the time steps in at; for get_epi_list(), a named list of output vectors. The other functions return the updated netsim_dat object.

Intended Usage

These accessors operate on the live netsim_dat object that EpiModel constructs internally when a simulation starts and passes through each module at every time step. The expected calling context is inside a user-supplied module function (e.g., a custom infection.FUN, recovery.FUN, or arrivals/departures module) registered with control.net().

They are not a general-purpose tool for editing the user-facing input or output objects of netsim():

• Calling them on a param.net(), init.net(), or control.net() object before a run will appear to succeed (those objects are also list-like) but produces an object that is not a valid simulation input.

• Calling them on the object returned by netsim() modifies only the saved input slot, not anything that would change the result of a re-run. Note also that netsim() strips the ⁠*.FUN⁠ entries from its returned control slot, so feeding that slot back into a new simulation will fail.

For modifications outside a running simulation, use the following instead:

• Editing parameters before a run: update_params() for a param.net object, or direct list assignment (e.g., p$inf.prob <- 0.5).

• Editing init or control before a run: direct list assignment (e.g., ctrl$nsteps <- 1000), or rebuild with a fresh call to the init.net() / control.net() constructor.

• Scheduled mid-simulation changes: the .param.updater.list argument to param.net() and the .control.updater.list argument to control.net(). See the "model-parameters" vignette for the underlying updater module and the scenario API built on top of it.

Mutability

The set_, append_, and add_ functions DO NOT modify the netsim_dat object in place. The result must be assigned back to dat in order to be registered: ⁠dat <- set_*(dat, item, value)⁠.

See Also

net-accessor for an overview of the accessors, and get_attr() and get_param() for the other groups; epi_trackers() for outputs computed by tracker functions at each time step; mutate_epi() for outputs derived after the simulation.

Examples

dat <- create_dat_object(control = list(nsteps = 5))
dat <- set_current_timestep(dat, 1)

dat <- add_epi(dat, "i.num")
dat <- set_epi(dat, "i.num", 10)
dat <- set_epi(dat, "s.num", 90)
get_epi_list(dat)

# Record at a time step other than the current one
dat <- set_epi(dat, "i.num", 12, at = 2)
get_epi_list(dat, c("i.num", "s.num"))
get_epi(dat, "i.num")
get_epi(dat, "i.num", at = c(1, 2))

EpiModel documentation built on Oct. 16, 2026, 5:07 p.m.