simulate() is used to draw from temporal
exponential family random network models in their natural parameterizations.
See tergm() for more information on these models.
# S3 method for tergm
simulate(
object,
nsim = 1,
seed = NULL,
coef = coefficients(object),
constraints = object$constraints,
monitor = object$targets,
time.slices = 1,
time.start = NULL,
time.burnin = 0,
time.interval = 1,
control = control.simulate.tergm(),
output = c("networkDynamic", "stats", "changes", "final", "ergm_state"),
nw.start = NULL,
stats = FALSE,
verbose = FALSE,
...
)# S3 method for network
simulate_formula(
object,
nsim = 1,
seed = NULL,
coef = NULL,
constraints = ~.,
monitor = NULL,
time.slices = 1,
time.start = NULL,
time.burnin = 0,
time.interval = 1,
time.offset = 1,
control = control.simulate.formula.tergm(),
output = c("networkDynamic", "stats", "changes", "final", "ergm_state"),
stats = FALSE,
verbose = FALSE,
...,
basis = ergm.getnetwork(object),
dynamic = FALSE
)
# S3 method for networkDynamic
simulate_formula(
object,
nsim = 1,
seed = NULL,
coef = attr(basis, "coef"),
constraints = ~.,
monitor = NULL,
time.slices = 1,
time.start = NULL,
time.burnin = 0,
time.interval = 1,
time.offset = 1,
control = control.simulate.formula.tergm(),
output = c("networkDynamic", "stats", "changes", "final", "ergm_state"),
stats = FALSE,
verbose = FALSE,
...,
basis = eval_lhs.formula(object),
dynamic = FALSE
)
Depends on the output argument:
If stats == FALSE, an mcmc matrix with
monitored statistics, and if stats == TRUE, a
list containing elements stats for statistics specified in the
monitor argument, and stats.gen for the model statistics.
If stats == FALSE and no monitored statistics are specified,
an empty list is returned, with a warning.
When nsim>1, an mcmc.list (or list of them) of
the statistics is returned instead.
A networkDynamic
object representing the simulated process, with ties present in the
initial network having onset -Inf and ties present at the end
of the simulation having terminus +Inf. The method for
networkDynamic returns the initial
networkDynamic with simulated changes
applied to it. The net.obs.period network attribute is
updated (or added if not existing) to reflect the time period that was
simulated. If the network does not have any persistent.ids
defined for vertices, a vertex.pid will be attached in a vertex attribute
named 'tergm_pid' to facilitate 'bookkeeping' between the networkDynamic
argument and the simulated network time step.
Additionally, attributes (attr(), not network
attributes) are attached as follows:
formula, monitor:Model and monitoring formulas used in the simulation, respectively.
stats, stats.gen:Network statistics as above.
coef:Coefficients used in the simulation.
changes:A four-column matrix summarizing the changes in the
"changes" output. (This may be removed in the future.)
When nsim>1, a network.list of these
networkDynamics is returned.
An integer matrix with four columns (time,
tail, head, and to), giving the time-stamped
changes relative to the current network. to is 1 if
a tie was formed and 0 if a tie was dissolved. The
convention for time is that it gives the time point during
which the change is effective. For example, a row
c(5,2,3,1) indicates that between time \(4\) and \(5\),
a tie from node \(2\) to node \(3\) was formed, so that it was
absent at time point \(4\) and present at time point \(5\);
while a row c(5,2,3,0) indicates that in that time, that
tie was dissolved, so that it is was present at time point \(4\)
and absent at time point \(5\).
Additionally, the same attributes (attr(), not network
attributes) as with output=="networkDynamic" are attached.
When nsim>1, a list of these change matrices is returned.
A network
object representing the last network in the series generated.
lasttoggle and time attributes are also included.
Additionally, the same attributes (attr(), not network
attributes) as with output=="networkDynamic" are attached.
When nsim>1, a network.list of these
networks is returned.
The ergm_state object resulting
from the simulation. Attributes are attached as for other output types.
Note that when using simulate_formula.networkDynamic with either
"final" or "ergm_state" for output, the nodes
included in these objects are those produced by network.collapse
at the start time.
for simulate.tergm, an object of type tergm giving a model fit;
for simulate_formula.network and simulate_formula.networkDynamic, a formula specifying
the model
simulate_formula.network understands the lasttoggle "API".
Number of replications (separate chains of networks) of the
process to run and return. The networkDynamic method only
supports nsim=1.
Seed value (integer) for the random number generator. See
set.seed().
Parameters for the model.
A formula specifying one or more constraints
on the support of the distribution of the networks being modeled. Multiple constraints
may be given, separated by “+” and “-” operators. See
ergmConstraint for the detailed explanation of
their semantics and also for an indexed list of the constraints visible to the ergm package.
The default is to have no constraints except those provided through
the ergmlhs API.
Together with the model terms in the formula and the reference measure, the constraints define the distribution of networks being modeled.
It is also possible to specify a proposal function directly either
by passing a string with the function's name (in which case,
arguments to the proposal should be specified through the
MCMC.prop.args argument to the relevant control function, or
by giving it on the LHS of the hints formula to MCMC.prop
argument to the control function. This will override
the one chosen automatically.
Note that not all possible combinations of constraints and reference measures are supported. However, for relatively simple constraints (i.e., those that simply permit or forbid specific dyads or sets of dyads from changing), arbitrary combinations should be possible.
A one-sided formula specifying one or more terms whose
value is to be monitored. If monitor is specified as a character
(one of "formation", "dissolution", and "all") then
the function .extract.fd.formulae() is used to determine the
corresponding formula; the user should be aware of its behavior and limitations.
Number of time slices (or statistics) to return from each
replication of the dynamic process. See below for return types. Defaults to
1, which, if time.burnin==0 and time.interval==1 (the
defaults), advances the process one time step.
An optional argument specifying the time point at which the simulation is to start. See Details for further information.
Number of time steps to discard before starting to collect network statistics.
Number of time steps between successive recordings of network statistics.
A list of control parameters for algorithm tuning.
Constructed using control.simulate.tergm() or
control.simulate.formula.tergm(). For backwards compatibility,
control lists from control.simulate.stergm() and
control.simulate.network() are allowed in calls to
simulate.tergm; they are mapped to control.simulate.tergm
by assigning:
MCMC.prop.form to MCMC.prop,
MCMC.prop.args.form to MCMC.prop.args,
MCMC.prop.weights.form to MCMC.prop.weights.
A character vector specifying output type: one of
"networkDynamic" (the default), "stats", "changes", "final", and
"ergm_state", with partial matching allowed. See Value section for details.
A specification for the starting network to be used by
simulate.tergm, optional for EGMME fits, but required for CMLE and
CMPLE fits:
iuse ith time-point's
network, where the first network in the series used to fit the model is
defined to be at the first time point;
"first" or "last"the first or last time point used in fitting the model; or
networkspecify the network directly.
networkDynamics
cannot be used as starting networks for simulate.tergm at this time.
(They can be used as starting networks for simulate_formula.networkDynamic,
of course.)
Logical: Whether to return
model statistics. This is not the recommended method:
use monitor argument instead.
A logical or an integer to control the amount of
progress and diagnostic information to be printed. FALSE/0
produces minimal output, with higher values producing more
detail. Note that very high values (5+) may significantly slow
down processing.
Further arguments passed to or used by methods.
Argument specifying the offset between the point when the
state of the network is sampled (time.start) and the the beginning of
the spell that should be recorded for the newly simulated network state.
For the network and networkDynamic methods,
the network to start the simulation from. (If basis is missing,
the default is the left hand side of the object argument.)
Logical; if TRUE, dynamic simulation is performed in
tergm; if FALSE (the default), ordinary ergm
simulation is performed instead. Note that when dynamic=FALSE,
default argument values for ergm's simulate methods
are used.
The dynamic process is run forward and the results are returned. For the
method for networkDynamic, the simulation is resumed from the
last generated time point of basis (or the left hand side of object
if basis is missing), by default with the same model
and parameters.
The starting network for the tergm object method
(simulate.tergm) is determined by the nw.start argument.
If time.start is specified, it is used as the initial
time index of the simulation.
If time.start is not specified (is NULL), then
if the object carries a time stamp from which to start
or resume the simulation, either in the form
of a "time" network attribute (for the
network method --- see the
lasttoggle "API") or
in the form of an net.obs.period network attribute (for the
networkDynamic method), this attribute will be used. (If
specified, time.start will override it with a warning.)
Othewise, the simulation starts at 0.
# \donttest{
data(samplk)
# Fit a transition from Time 1 to Time 2
samplk12 <- tergm(list(samplk1, samplk2)~
Form(~edges+mutual+transitiveties+cyclicalties)+
Diss(~edges+mutual+transitiveties+cyclicalties),
estimate="CMLE")
# direct simulation from tergm object
sim1 <- simulate(samplk12, nw.start="last")
# equivalent simulation from formula with network LHS;
# must pass dynamic=TRUE for tergm simulation
sim2 <- simulate(samplk2 ~ Form(~edges+mutual+transitiveties+cyclicalties) +
Diss(~edges+mutual+transitiveties+cyclicalties),
coef = coef(samplk12),
dynamic=TRUE)
# the default simulate output is a networkDynamic, and we can simulate
# with a networkDynamic LHS as well
sim3 <- simulate(sim2 ~ Form(~edges+mutual+transitiveties+cyclicalties) +
Diss(~edges+mutual+transitiveties+cyclicalties),
coef = coef(samplk12),
dynamic=TRUE)
# }
Run the code above in your browser using DataLab