R: Draw from the distribution of a Temporal Exponential Family...

simulate.tergm {tergm} | R Documentation

## Draw from the distribution of a Temporal Exponential Family Random Graph Model

### Description

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

### Usage

    ## S3 method for class 'tergm'
    simulate(
      object,
      nsim = 1,
      seed = NULL,
      coef = coefficients(object),
      constraints = object$constraints,
      monitor = object$targets,
      time.slices = 1,
      time.start = NULL,
      time.burnin = 0,
      time.interval = 1,
      control = control.simulate.tergm(),
      output = c("networkDynamic", "stats", "changes", "final", "ergm_state"),
      nw.start = NULL,
      stats = FALSE,
      verbose = FALSE,
      ...
    )

    ## S3 method for class 'network'
    simulate_formula(
      object,
      nsim = 1,
      seed = NULL,
      coef = NULL,
      constraints = ~.,
      monitor = NULL,
      time.slices = 1,
      time.start = NULL,
      time.burnin = 0,
      time.interval = 1,
      time.offset = 1,
      control = control.simulate.formula.tergm(),
      output = c("networkDynamic", "stats", "changes", "final", "ergm_state"),
      stats = FALSE,
      verbose = FALSE,
      ...,
      basis = ergm.getnetwork(object),
      dynamic = FALSE
    )

    ## S3 method for class 'networkDynamic'
    simulate_formula(
      object,
      nsim = 1,
      seed = NULL,
      coef = attr(basis, "coef"),
      constraints = ~.,
      monitor = NULL,
      time.slices = 1,
      time.start = NULL,
      time.burnin = 0,
      time.interval = 1,
      time.offset = 1,
      control = control.simulate.formula.tergm(),
      output = c("networkDynamic", "stats", "changes", "final", "ergm_state"),
      stats = FALSE,
      verbose = FALSE,
      ...,
      basis = eval_lhs.formula(object),
      dynamic = FALSE
    )

### Arguments

`object` | for `simulate.tergm`, an object of type `tergm` giving a model fit; for `simulate_formula.network` and `simulate_formula.networkDynamic`, a formula specifying the model `simulate_formula.network` understands the `lasttoggle` "API".
`nsim` | Number of replications (separate chains of networks) of the process to run and return. The `networkDynamic` method only supports `nsim=1`.
`seed` | Random number integer seed. See `set.seed`.
`coef` | Parameters for the model.
`constraints` | A one-sided formula specifying one or more constraints on the support of the distribution of the networks being modeled. Multiple constraints may be given, separated by “+” operators. Together with the model terms in the formula and the reference measure, the constraints define the distribution of networks being modeled. The default is `~.`, for an unconstrained model. See the ERGM constraints documentation for the constraints implemented in the ergm package. Other packages may add their own constraints. Note that not all possible combinations of constraints are supported.
`monitor` | A one-sided formula specifying one or more terms whose value is to be monitored. If `monitor` is specified as a character (one of `"formation"`, `"dissolution"`, and `"all"`) then the function `.extract.fd.formulae` is used to determine the corresponding formula; the user should be aware of its behavior and limitations.
`time.slices` | Number of time slices (or statistics) to return from each replication of the dynamic process. See below for return types. Defaults to 1, which, if `time.burnin==0` and `time.interval==1` (the defaults), advances the process one time step.
`time.start` | An optional argument specifying the time point at which the simulation is to start. See Details for further information.
`time.burnin` | Number of time steps to discard before starting to collect network statistics.
`time.interval` | Number of time steps between successive recordings of network statistics.
`control` | A list of control parameters for algorithm tuning. Constructed using `control.simulate.tergm` or `control.simulate.formula.tergm`. For backwards compatibility, control lists from `control.simulate.stergm` and `control.simulate.network` are allowed in calls to `simulate.tergm`; they are mapped to `control.simulate.tergm` by assigning: `MCMC.prop.form` to `MCMC.prop`, `MCMC.prop.args.form` to `MCMC.prop.args`, `MCMC.prop.weights.form` to `MCMC.prop.weights`.
`output` | A character vector specifying output type: one of `"networkDynamic"` (the default), `"stats"`, `"changes"`, `"final"`, and `"ergm_state"`, with partial matching allowed. See Value section for details.
`nw.start` | A specification for the starting network to be used by `simulate.tergm`, optional for EGMME fits, but required for CMLE and CMPLE fits: a numeric index `i` use `i`th time-point's network, where the first network in the series used to fit the model is defined to be at the first time point; `"first"` or `"last"` the first or last time point used in fitting the model; or `network` specify the network directly. `networkDynamic`s cannot be used as starting networks for `simulate.tergm` at this time. (They can be used as starting networks for `simulate_formula.networkDynamic`, of course.)
`stats` | Logical: Whether to return model statistics. This is not the recommended method: use `monitor` argument instead.
`verbose` | Logical: If TRUE, extra information is printed as the Markov chain progresses.
`...` | Further arguments passed to or used by methods.
`time.offset` | Argument specifying the offset between the point when the state of the network is sampled (`time.start`) and the the beginning of the spell that should be recorded for the newly simulated network state.
`basis` | For the `network` and `networkDynamic` methods, the network to start the simulation from. (If `basis` is missing, the default is the left hand side of the `object` argument.)
`dynamic` | Logical; if `TRUE`, dynamic simulation is performed in `tergm`; if `FALSE` (the default), ordinary `ergm` simulation is performed instead. Note that when `dynamic=FALSE`, default argument values for `ergm`'s `simulate` methods are used.

### Details

The dynamic process is run forward and the results are returned. For the method for `networkDynamic`, the simulation is resumed from the last generated time point of `basis` (or the left hand side of `object` if `basis` is missing), by default with the same model and parameters.

The starting network for the `tergm` object method (`simulate.tergm`) is determined by the `nw.start` argument.

- If `time.start` is specified, it is used as the initial time index of the simulation.

- If `time.start` is not specified (is `NULL`), then if the `object` carries a time stamp from which to start or resume the simulation, either in the form of a `"time"` network attribute (for the `network` method — see the `lasttoggle` "API") or in the form of an `net.obs.period` network attribute (for the `networkDynamic` method), this attribute will be used. (If specified, `time.start` will override it with a warning.)

- Othewise, the simulation starts at 0.

### Value

Depends on the `output` argument:

`"stats"` | If `stats == FALSE`, an `mcmc` matrix with monitored statistics, and if `stats == TRUE`, a list containing elements `stats` for statistics specified in the `monitor` argument, and `stats.gen` for the model statistics. If `stats == FALSE` and no monitored statistics are specified, an empty list is returned, with a warning. When `nsim>1`, an `mcmc.list` (or list of them) of the statistics is returned instead.
`"networkDynamic"` | A `networkDynamic` object representing the simulated process, with ties present in the initial network having onset `-Inf` and ties present at the end of the simulation having terminus `+Inf`. The method for `networkDynamic` returns the initial `networkDynamic` with simulated changes applied to it. The `net.obs.period` network attribute is updated (or added if not existing) to reflect the time period that was simulated. If the network does not have any `persistent.ids` defined for vertices, a vertex.pid will be attached in a vertex attribute named `'tergm_pid'` to facilitate 'bookkeeping' between the networkDynamic argument and the simulated network time step. Additionally, attributes (`attr`, not network attributes) are attached as follows: `formula`, `monitor`: Model and monitoring formulas used in the simulation, respectively. `stats`, `stats.gen`: Network statistics as above. `coef`: Coefficients used in the simulation. `changes`: A four-column matrix summarizing the changes in the `"changes"` output. (This may be removed in the future.) When `nsim>1`, a `network.list` of these `networkDynamic`s is returned.
`"changes"` | An integer matrix with four columns (`time`, `tail`, `head`, and `to`), giving the time-stamped changes relative to the current network. `to` is `1` if a tie was formed and `0` if a tie was dissolved. The convention for `time` is that it gives the time point during which the change is effective. For example, a row `c(5,2,3,1)` indicates that between time 4 and 5, a tie from node 2 to node 3 was formed, so that it was absent at time point 4 and present at time point 5; while a row `c(5,2,3,0)` indicates that in that time, that tie was dissolved, so that it is was present at time point 4 and absent at time point 5. Additionally, the same attributes (`attr`, not network attributes) as with `output=="networkDynamic"` are attached. When `nsim>1`, a list of these change matrices is returned.
`"final"` | A `network` object representing the last network in the series generated. `lasttoggle` and `time` attributes are also included. Additionally, the same attributes (`attr`, not network attributes) as with `output=="networkDynamic"` are attached. When `nsim>1`, a `network.list` of these `network`s is returned.
`"ergm_state"` | The `ergm_state` object resulting from the simulation. Attributes are attached as for other output types.

Note that when using `simulate_formula.networkDynamic` with either `"final"` or `"ergm_state"` for `output`, the nodes included in these objects are those produced by `network.collapse` at the start time.

### Examples

    data(samplk)

    # Fit a transition from Time 1 to Time 2
    samplk12 <- tergm(list(samplk1, samplk2)~
                      Form(~edges+mutual+transitiveties+cyclicalties)+
                      Diss(~edges+mutual+transitiveties+cyclicalties),
                      estimate="CMLE")

    # direct simulation from tergm object
    sim1 <- simulate(samplk12, nw.start="last")

    # equivalent simulation from formula with network LHS;
    # must pass dynamic=TRUE for tergm simulation
    sim2 <- simulate(samplk2 ~ Form(~edges+mutual+transitiveties+cyclicalties) +
                               Diss(~edges+mutual+transitiveties+cyclicalties),
                               coef = coef(samplk12),
                               dynamic=TRUE)

    # the default simulate output is a networkDynamic, and we can simulate
    # with a networkDynamic LHS as well
    sim3 <- simulate(sim2 ~ Form(~edges+mutual+transitiveties+cyclicalties) +
                            Diss(~edges+mutual+transitiveties+cyclicalties),
                            coef = coef(samplk12),
                            dynamic=TRUE)

[Package tergm version 4.0.2 Index]