simulate.ergm: Draw from the distribution of an Exponential Family Random Graph Model

Description

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.

Usage

# S3 method for formula
simulate(object, nsim = 1, seed = NULL, coef,
  response = NULL, reference = ~Bernoulli, constraints = ~.,
  monitor = NULL, basis = NULL, statsonly = FALSE, esteq = FALSE,
  sequential = TRUE, control = control.simulate.formula(),
  verbose = FALSE, ...)
# S3 method for ergm
simulate(object, nsim = 1, seed = NULL,
  coef = object$coef, response = object$response,
  reference = object$reference, constraints = object$constraints,
  monitor = NULL, statsonly = FALSE, esteq = FALSE,
  sequential = TRUE, control = control.simulate.ergm(),
  verbose = FALSE, ...)

Arguments

object

Either a formula or an ergm object. The formula should be of the form y ~ <model terms>, where y is a network object or a matrix that can be coerced to a network object. For the details on the possible <model terms>, see ergm-terms. To create a network object in , use the network() function, then add nodal attributes to it using the %v% operator if necessary.

nsim

Number of networks to be randomly drawn from the given distribution on the set of all networks, returned by the Metropolis-Hastings algorithm.

seed

Seed value (integer) for the random number generator. See set.seed.

coef

Vector of parameter values for the model from which the sample is to be drawn. If object is of class ergm, the default value is the vector of estimated coefficients.

response

Name of the edge attribute whose value is to be modeled in the valued ERGM framework. Defaults to NULL for simple presence or absence, modeled via a binary ERGM.

reference

A one-sided formula specifying the reference measure ($h(y)$) to be used. (Defaults to ~Bernoulli.) See help for ERGM reference measures implemented in the ergm package.

constraints

A one-sided formula specifying one or more constraints on the support of the distribution of the networks being simulated. See the documentation for a similar argument for ergm and see list of implemented constraints for more information. For simulate.formula, defaults to no constraints. For simulate.ergm, defaults to using the same constraints as those with which object was fitted.

monitor

A one-sided formula specifying one or more terms whose value is to be monitored. These terms are appeneded to the model, along with a coefficient of 0, so their statistics are returned. An ergm_model objectcan be passed as well.

basis

An optional network object to start the Markov chain. If omitted, the default is the left-hand-side of the formula. If neither a left-hand-side nor a basis is present, an error results because the characteristics of the network (e.g., size and directedness) must be specified.

statsonly

Logical: If TRUE, return only the network statistics, not the network(s) themselves.

esteq

Logical: If TRUE, compute the sample estimating equations of an ERGM: if the model is non-curved, all non-offset 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.

sequential

Logical: If FALSE, each of the nsim simulated Markov chains begins at the initial network. If TRUE, the end of one simulation is used as the start of the next. Irrelevant when nsim=1.

control

A list of control parameters for algorithm tuning. Constructed using control.simulate.ergm or control.simulate.formula, which have different defaults.

verbose

Logical: If TRUE, extra information is printed as the Markov chain progresses.

…

Further arguments passed to or used by methods.

Value

If statsonly==TRUE a matrix containing the simulated network statistics. If control$parallel>0, the statistics from each Markov chain are stacked.

Otherwise, 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 following attr-style attributes on the list:

formula

The formula used to generate the sample.

stats

The $\code{nsim}\times p$ matrix of network statistics, where $p$ is the number of network statistics specified in the model.

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.

If statsonly==FALSE && control$parallel>0 the returned networks are "interleaved", in the sense that for y[i,j] is the jth network from MCMC chain i, the sequence returned if control$parallel==2 is list(y[1,1], y[2,1], y[1,2], y[2,2], y[1,3], y[2,3], ...). This is different from the behavior when statsonly==TRUE. This detail may change in the future.

This object has summary and print methods.

Details

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.

Examples

Run this code

# NOT RUN {
#
# 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 2-star 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 2-star model using the ergm function
#
gest <- ergm(flomarriage ~ edges + kstar(2))
summary(gest)
#
# Draw from the fitted model (satatistics only), and observe the number
# of triangles as well.
#
g.sim <- simulate(gest, nsim=10, 
            monitor=~triangles, statsonly=TRUE,
            control=control.simulate.ergm(MCMC.burnin=1000, MCMC.interval=100))
g.sim
# }