net-accessor: Functions to Access and Edit the Main netsim_dat Object in...

In EpiModel: Mathematical Modeling of Infectious Disease Dynamics

Functions to Access and Edit the Main netsim_dat Object in Network Models

Description

These get_, set_, append_, and add_ functions allow a safe and efficient way to retrieve and mutate the main netsim_dat class object of network models (typical variable name dat). They are intended for use inside module functions that run during a netsim() simulation, not for editing the user-facing param.net, init.net, or control.net inputs before a run or the output object returned by netsim(). See the Intended Usage section below for details and alternatives.

This function returns an exhaustive named list of the attributes managed by EpiModel itself. It can be used to check the validity of an attributes list and of its types.

Usage

get_attr_list(dat, item = NULL)

get_attr(dat, item, posit_ids = NULL, override.null.error = FALSE)

add_attr(dat, item)

set_attr(dat, item, value, posit_ids = NULL, override.length.check = FALSE)

append_attr(dat, item, value, n.new)

remove_node_attr(dat, posit_ids)

get_epi_list(dat, item = NULL)

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

add_epi(dat, item)

set_epi(dat, item, at, value)

get_param_list(dat, item = NULL)

get_param(dat, item, override.null.error = FALSE)

add_param(dat, item)

set_param(dat, item, value)

get_control_list(dat, item = NULL)

get_control(dat, item, override.null.error = FALSE)

get_network_control(dat, network, item, override.null.error = FALSE)

add_control(dat, item)

set_control(dat, item, value)

get_init_list(dat, item = NULL)

get_init(dat, item, override.null.error = FALSE)

add_init(dat, item)

set_init(dat, item, value)

get_core_attributes()

append_core_attr(dat, at, n.new)

Arguments

dat	Main netsim_dat object containing a networkDynamic object and other initialization information passed from netsim().
item	A character vector containing the name of the element to access (for get_ functions), create (for add_ functions), or edit (for set_ and append_ functions). Can be of length greater than 1 for ⁠get_*_list⁠ functions.
posit_ids	For set_attr and get_attr, a numeric vector of posit_ids to subset the desired item.
override.null.error	If TRUE, get_ will return NULL if the item does not exist instead of throwing an error. (default = FALSE).
value	New value to be attributed in the set_ and append_ functions.
override.length.check	If TRUE, set_attr allows the modification of the item size. (default = FALSE).
n.new	For append_core_attr, the number of new nodes to initiate with core attributes; for append_attr, the number of new elements to append at the end of item.
at	For get_epi, the timestep at which to access the specified item; for set_epi, the timestep at which to add the new value for the epi output item; for append_core_attr, the current time step.
network	index of network for which to get control

Value

A vector or a list of vectors for get_ functions; the main list object for set_, append_, and add_ functions.

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.

Core Attribute

The append_core_attr function initializes the attributes necessary for EpiModel to work (the four core attributes are: "active", "unique_id", "entrTime", and "exitTime"). These attributes are used in the initialization phase of the simulation, to create the nodes (see initialize.net()); and also used when adding nodes during the simulation (see arrivals.net()).

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)⁠.

set_ and append_ vs add_

The set_ and append_ functions edit a pre-existing element or create a new one if it does not exist already by calling the add_ functions internally.

See Also

update_params() for editing a param.net object outside a simulation; param.net(), init.net(), control.net() for input constructors; netsim() for running a simulation.

Examples

dat <- create_dat_object(control = list(nsteps = 150))
dat <- append_core_attr(dat, 1, 100)

dat <- add_attr(dat, "age")
dat <- set_attr(dat, "age", runif(100))
dat <- set_attr(dat, "status", rbinom(100, 1, 0.9))
dat <- append_attr(dat, "status", 1, 10)
dat <- append_attr(dat, "age", NA, 10)
get_attr_list(dat)
get_attr_list(dat, c("age", "active"))
get_attr(dat, "status")
get_attr(dat, "status", c(1, 4))

dat <- add_epi(dat, "i.num")
dat <- set_epi(dat, "i.num", 150, 10)
dat <- set_epi(dat, "s.num", 150, 90)
get_epi_list(dat)
get_epi_list(dat, c("i.num", "s.num"))
get_epi(dat, "i.num")
get_epi(dat, "i.num", c(1, 4))

dat <- add_param(dat, "x")
dat <- set_param(dat, "x", 0.4)
dat <- set_param(dat, "y", 0.8)
get_param_list(dat)
get_param_list(dat, c("x", "y"))
get_param(dat, "x")

dat <- add_init(dat, "x")
dat <- set_init(dat, "x", 0.4)
dat <- set_init(dat, "y", 0.8)
get_init_list(dat)
get_init_list(dat, c("x", "y"))
get_init(dat, "x")

dat <- add_control(dat, "x")
dat <- set_control(dat, "x", 0.4)
dat <- set_control(dat, "y", 0.8)
get_control_list(dat)
get_control_list(dat, c("x", "y"))
get_control(dat, "x")

EpiModel documentation built on May 13, 2026, 9:08 a.m.