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. 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 a random draw from the fitted model, saved by `ergm()`.

### 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,
      output = c("network", "stats", "edgelist", "pending_update_network"),
      simplify = TRUE, sequential = TRUE,
      control = control.simulate.formula(), verbose = FALSE, ...,
      do.sim = TRUE)

    ## S3 method for class 'ergm_model'
    simulate(object, nsim = 1, seed = NULL, coef,
      response = NULL, reference = ~Bernoulli, constraints = ~.,
      monitor = NULL, basis = NULL, esteq = FALSE,
      output = c("network", "stats", "edgelist", "pending_update_network"),
      simplify = TRUE, 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, basis = object$newnetwork, statsonly = FALSE,
      esteq = FALSE, output = c("network", "stats", "edgelist",
      "pending_update_network"), simplify = TRUE, 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. Deprecated in favor of `output=`.
`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.
`output` | Character, one of `"network"` (default), `"stats"`, `"edgelist"`, or `"pending_update_network"`: determines the output format. Partial matching is performed.
`simplify` | Logical: If `TRUE` the output is "simplified": sampled networks are returned in a single list, statistics from multiple parallel chains are stacked, etc.. This makes it consistent with behavior prior to `ergm` 3.10.
`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.
`do.sim` | Logical: If `FALSE`, do not proceed to the simulation but rather return a list of arguments that would have been passed to `simulate.ergm_model()`. This can be useful if, for example, one wants to run several simulations with varying coefficients and did not want to reinitialize the model and the proposal ever time.

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

### Value

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 above-listed additional attributes.

`"edgelist"`

  An `edgelist` representation of the network, or a list thereof, depending on `nsim`.

`"pending_update_network"`

  A semi-internal 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.

### Note

`simulate.ergm_model()` is a lower-level 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.

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

[Package ergm version 3.10.4 Index]