simulate.ergm  R Documentation 
simulate
is used to draw from exponential
family random network models. See ergm()
for more
information on these models.
The method for ergm
objects inherits the model,
the coefficients, the response attribute, the reference, the
constraints, and most simulation parameters from the model fit,
unless overridden by passing them explicitly. Unless overridden,
the simulation is initialized with either a random draw from near
the fitted model saved by ergm()
or, if unavailable, the
network to which the ERGM was fit.
## S3 method for class 'formula_lhs_network'
simulate(object, nsim = 1, seed = NULL, ...)
simulate_formula(object, ..., basis = eval_lhs.formula(object))
## S3 method for class 'network'
simulate_formula(
object,
nsim = 1,
seed = NULL,
coef,
response = NULL,
reference = ~Bernoulli,
constraints = ~.,
observational = FALSE,
monitor = NULL,
statsonly = FALSE,
esteq = FALSE,
output = c("network", "stats", "edgelist", "ergm_state"),
simplify = TRUE,
sequential = TRUE,
control = control.simulate.formula(),
verbose = FALSE,
...,
basis = ergm.getnetwork(object),
do.sim = NULL,
return.args = NULL
)
## S3 method for class 'ergm_state'
simulate_formula(
object,
nsim = 1,
seed = NULL,
coef,
response = NULL,
reference = ~Bernoulli,
constraints = ~.,
observational = FALSE,
monitor = NULL,
statsonly = FALSE,
esteq = FALSE,
output = c("network", "stats", "edgelist", "ergm_state"),
simplify = TRUE,
sequential = TRUE,
control = control.simulate.formula(),
verbose = FALSE,
...,
basis = ergm.getnetwork(object),
do.sim = NULL,
return.args = NULL
)
## S3 method for class 'ergm_model'
simulate(
object,
nsim = 1,
seed = NULL,
coef,
reference = if (is(constraints, "ergm_proposal")) NULL else trim_env(~Bernoulli),
constraints = trim_env(~.),
observational = FALSE,
monitor = NULL,
basis = NULL,
esteq = FALSE,
output = c("network", "stats", "edgelist", "ergm_state"),
simplify = TRUE,
sequential = TRUE,
control = control.simulate.formula(),
verbose = FALSE,
...,
do.sim = NULL,
return.args = NULL
)
## S3 method for class 'ergm_state_full'
simulate(
object,
nsim = 1,
seed = NULL,
coef,
esteq = FALSE,
output = c("network", "stats", "edgelist", "ergm_state"),
simplify = TRUE,
sequential = TRUE,
control = control.simulate.formula(),
verbose = FALSE,
...,
return.args = NULL
)
## S3 method for class 'ergm'
simulate(
object,
nsim = 1,
seed = NULL,
coef = coefficients(object),
response = object$network %ergmlhs% "response",
reference = object$reference,
constraints = list(object$constraints, object$obs.constraints),
observational = FALSE,
monitor = NULL,
basis = if (observational) object$network else NVL(object$newnetwork, object$network),
statsonly = FALSE,
esteq = FALSE,
output = c("network", "stats", "edgelist", "ergm_state"),
simplify = TRUE,
sequential = TRUE,
control = control.simulate.ergm(),
verbose = FALSE,
...,
return.args = NULL
)
object 
Either a 
nsim 
Number of networks to be randomly drawn from the given distribution on the set of all networks, returned by the MetropolisHastings algorithm. 
seed 
Seed value (integer) for the random number generator. See

... 
Further arguments passed to or used by methods. 
basis 
a value (usually a 
coef 
Vector of parameter values for the model from which the
sample is to be drawn. If 
response 
Either a character string, a formula, or

reference 
A onesided formula specifying
the reference measure ( 
constraints 
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
The default is to have no constraints except those provided through
the 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
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. 
observational 
Inherit observational constraints rather than model constraints. 
monitor 
A onesided formula specifying one or more terms
whose value is to be monitored. These terms are appended to the
model, along with a coefficient of 0, so their statistics are
returned. An 
statsonly 
Logical: If TRUE, return only the network statistics, not
the network(s) themselves. Deprecated in favor of 
esteq 
Logical: If TRUE, compute the sample estimating equations of an ERGM: if the model is noncurved, all nonoffset statistics are returned either way, but if the model is curved, the score estimating function values (3.1) by Hunter and Handcock (2006) are returned instead. 
output 
Normally character, one of Alternatively, a function with prototype

simplify 
Logical: If 
sequential 
Logical: If FALSE, each of the 
control 
A list of control parameters for algorithm tuning,
typically constructed with 
verbose 
A logical or an integer to control the amount of
progress and diagnostic information to be printed. 
do.sim 
Logical; a deprecated interface superseded by 
return.args 
Character; if not 
A sample of networks is randomly drawn from the specified model. The model
is specified by the first argument of the function. If the first argument
is a formula
then this defines the model. If the first
argument is the output of a call to ergm()
then the model used
for that call is the one fit – and unless coef
is specified, the
sample is from the MLE of the parameters. If neither of those are given as
the first argument then a Bernoulli network is generated with the
probability of ties defined by prob
or coef
.
Note that the first network is sampled after burnin
steps,
and any subsequent networks are sampled each interval
steps
after the first.
More information can be found by looking at the documentation of
ergm()
.
If output=="stats"
an mcmc
object containing the
simulated network statistics. If control$parallel>0
, an
mcmc.list
object. If simplify=TRUE
(the default), these
would then be "stacked" and converted to a standard matrix
. A
logical vector indicating whether or not the term had come from
the monitor=
formula is stored in attr()
style attribute
"monitored"
.
Otherwise, a representation of the simulated network is returned,
in the form specified by output
. In addition to a network
representation or a list thereof, they have the following
attr()
style attributes:
formula
The formula
used to generate the
sample.
stats
An mcmc
or mcmc.list
object as above.
control
Control parameters used to generate the sample.
constraints
Constraints used to generate the sample.
reference
The reference measure for the sample.
monitor
The monitoring formula.
response
The edge attribute used as a response.
The following are the permitted network formats:
"network"
If nsim==1
, an object of class
network
. If nsim>1
, it returns an object of class
network.list
(a list of networks) with the
abovelisted additional attributes.
"edgelist"
An edgelist
representation of the network,
or a list thereof, depending on nsim
.
"ergm_state"
A semiinternal representation of
a network consisting of a network
object emptied of edges, with
an attached edgelist matrix, or a list thereof, depending on
nsim
.
If simplify==FALSE
, the networks are returned as a nested list,
with outer list being the parallel chain (including 1 for no
parallelism) and inner list being the samples within that chains
(including 1, if one network per chain). If TRUE
, they are
concatenated, and if a total of one network had been simulated, the
network itself will be returned.
simulate(ergm_state_full)
: a lowlevel function to simulate from an ergm_state
object.
The actual network
method for simulate_formula()
is
actually called .simulate_formula.network()
and is also
exported as an object. This allows it to be overridden by
extension packages, such as tergm
, but also accessed directly
when needed.
simulate.ergm_model()
is a lowerlevel interface, providing
a simulate()
method for ergm_model
class. The basis
argument is required; monitor
, if passed, must be an
ergm_model
as well; and constraints
can be an
ergm_proposal
object instead.
ergm()
, network
,
ergm_MCMC_sample()
for a demonstration of return.args=
.
#
# Let's draw from a Bernoulli model with 16 nodes
# and density 0.5 (i.e., coef = c(0,0))
#
g.sim < simulate(network(16) ~ edges + mutual, coef=c(0, 0))
#
# What are the statistics like?
#
summary(g.sim ~ edges + mutual)
#
# Now simulate a network with higher mutuality
#
g.sim < simulate(network(16) ~ edges + mutual, coef=c(0,2))
#
# How do the statistics look?
#
summary(g.sim ~ edges + mutual)
#
# Let's draw from a Bernoulli model with 16 nodes
# and tie probability 0.1
#
g.use < network(16,density=0.1,directed=FALSE)
#
# Starting from this network let's draw 3 realizations
# of a edges and 2star network
#
g.sim < simulate(~edges+kstar(2), nsim=3, coef=c(1.8,0.03),
basis=g.use, control=control.simulate(
MCMC.burnin=1000,
MCMC.interval=100))
g.sim
summary(g.sim)
#
# attach the Florentine Marriage data
#
data(florentine)
#
# fit an edges and 2star model using the ergm function
#
gest < ergm(flomarriage ~ edges + kstar(2))
summary(gest)
#
# Draw from the fitted model (statistics only), and observe the number
# of triangles as well.
#
g.sim < simulate(gest, nsim=10,
monitor=~triangles, output="stats",
control=control.simulate.ergm(MCMC.burnin=1000, MCMC.interval=100))
g.sim
# Custom output: store the edgecount (computed in R), iteration index, and chain index.
output.f < function(x, iter, chain, ...){
list(nedges = network.edgecount(as.network(x)),
chain = chain, iter = iter)
}
g.sim < simulate(gest, nsim=3,
output=output.f, simplify=FALSE,
control=control.simulate.ergm(MCMC.burnin=1000, MCMC.interval=100))
unclass(g.sim)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.