simulate.ergm {ergm}R Documentation

Draw from the distribution of an Exponential Family Random Graph Model

Description

simulate is used to draw from exponential family random network models in their natural parameterizations. See ergm for more information on these models.

Usage

## S3 method for class 'formula'
simulate(object, nsim=1, seed=NULL, theta0,
                          burnin=1000, interval=1000,
                          basis=NULL,
                          statsonly=FALSE,
                          sequential=TRUE,
                          constraints = ~.,
                          control = control.simulate.formula(),
                          verbose=FALSE, ...)
## S3 method for class 'ergm'
simulate(object, nsim=1, seed=NULL, theta0=object$coef,
                       burnin=1000, interval=1000, 
                       statsonly=FALSE,
                       sequential=TRUE,
                       constraints = NULL,
                       control = control.simulate.ergm(),
                       verbose=FALSE, ...)

Arguments

object

an R 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 R, 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

Random number integer seed. The default is sample(10000000, size=1).

theta0

Vector of parameters 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.

burnin

The number of proposals before any MCMC sampling is done. If NULL in simulate.ergm, the value of object$burnin is used.

interval

The number of proposals between sampled statistics. If NULL in simulate.ergm, the value of object$interval is used. The program prints a warning if too few proposals are being accepted (if the number of proposals between sampled observations ever equals an integral multiple of 100(1+the number of proposals accepted)).

basis

An optional network object to start the MCMC algorithm from. This overrides 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.

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

control

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

statsonly

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

sequential

If FALSE, each new simulation (of nsim) is always started at the initial network. If TRUE, the end of one simulation is used as the start of the next. Irrelevant when nsim=1.

verbose

If this is TRUE, we will print out more information as we run the program, including (currently) some goodness of fit statistics.

...

further arguments passed to or used by 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 theta0 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 theta0.

Note that the first network is sampled after burnin + interval 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.

Value

If nsim==1, simulate.ergm returns an object of class network. If nsim>1, it returns an object of class network.series that is a list with the following elements:

formula

The formula used to generate the sample.

networks

A list of the generated networks.

stats

The n\times p matrix of network change statistics, where n is the sample size and p is the number of network change statistics specified in the model.

See Also

ergm, network, print.network

Examples

#
# Let's draw from a Bernoulli model with 16 nodes
# and density 0.5 (i.e., theta0 = c(0,0))
#
g.sim <- simulate(network(16) ~ edges + mutual)
#
# What are the statistics like?
#
summary(g.sim ~ edges + mutual)
#
# Now simulate a network with higher mutuality
#
g.sim <- simulate(network(16) ~ edges + mutual, theta0=c(0,2))
#
# How do the statistics like?
#
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 5 realizations
# of a edges and 2-star network
#
g.sim <- simulate(~edges+kstar(2),nsim=5,theta0=c(-1.8,0.03),
               basis=g.use,
               burnin=100000,interval=1000)
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
#
g.sim <- simulate(gest,nsim=100,burnin=1000,interval=1000)
g.sim

[Package ergm version 2.4-3 Index]