R: Draw from the distribution of an Exponential Family Random...

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,
                               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 class '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` | 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. 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` | EXPERIMENTAL. Name of the edge attribute whose value is to be modeled. Defaults to `NULL` for simple presence or absence, modeled via binary ERGM terms. Passing anything but `NULL` uses valued ERGM terms.
`reference` | EXPERIMENTAL. 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.
`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.

### 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` + `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 `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 `j`th 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.

### See Also

`ergm`, `network`

### Examples

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

[Package ergm version 3.8.0 Index]