R: STERGM wrappers for TERGM simulation

simulate.network {tergm} | R Documentation

## STERGM wrappers for TERGM simulation

### Description

The `simulate.network` and `simulate.networkDynamic` wrappers are provided for backwards compatibility. It is recommended that new code make use of the `simulate_formula.network` and `simulate_formula.networkDynamic` functions instead. See `simulate.tergm` for details on these new functions.

### Usage

    ## S3 method for class 'network'
    simulate(
      object,
      nsim = 1,
      seed = NULL,
      formation,
      dissolution,
      coef.form,
      coef.diss,
      constraints = ~.,
      monitor = NULL,
      time.slices = 1,
      time.start = NULL,
      time.burnin = 0,
      time.interval = 1,
      time.offset = 1,
      control = control.simulate.network(),
      output = c("networkDynamic", "stats", "changes", "final", "ergm_state"),
      stats.form = FALSE,
      stats.diss = FALSE,
      verbose = FALSE,
      ...
    )

    ## S3 method for class 'networkDynamic'
    simulate(
      object,
      nsim = 1,
      seed = NULL,
      formation,
      dissolution,
      coef.form = attr(object, "coef.form"),
      coef.diss = attr(object, "coef.diss"),
      constraints = ~.,
      monitor = NULL,
      time.slices = 1,
      time.start = NULL,
      time.burnin = 0,
      time.interval = 1,
      time.offset = 1,
      control = control.simulate.network(),
      output = c("networkDynamic", "stats", "changes", "final", "ergm_state"),
      stats.form = FALSE,
      stats.diss = FALSE,
      verbose = FALSE,
      ...
    )

### Arguments

`object` | an object of type `network` or `networkDynamic`
`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`.
`formation, dissolution` | One-sided `ergm`-style formulas for the formation and dissolution models, respectively. The dissolution model is parameterized in terms of tie persistence.
`coef.form` | Parameters for the formation model.
`coef.diss` | Parameters for the dissolution (persistence) model.
`constraints` | A one-sided formula specifying one or more constraints on the support of the distribution of the networks being modeled, using syntax similar to the `formula` argument. 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.
`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.
`control` | A list of control parameters for algorithm tuning, constructed using `control.simulate.network`. These are mapped to `control.simulate.formula.tergm` controls by assigning: `MCMC.prop.form` to `MCMC.prop`, `MCMC.prop.args.form` to `MCMC.prop.args`, and `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.
`stats.form, stats.diss` | Logical: Whether to return formation/dissolution model statistics. This is not the recommended method: use the `monitor` argument instead. Note that if either `stats.form` or `stats.diss` is `TRUE`, all generative model statistics will be returned.
`verbose` | Logical: If `TRUE`, extra information is printed as the Markov chain progresses.
`...` | Further arguments passed to or used by methods.

### Details

Note that return values may be structured differently than in past versions.

Remember that in `stergm`, the dissolution formula is parameterized in terms of tie persistence: negative coefficients imply lower rates of persistence and postive coefficients imply higher rates. The dissolution effects are simply the negation of these coefficients.

Because the old `dissolution` formula in `stergm` represents tie persistence, it maps to the new `Persist()` operator in the `tergm` function, NOT the `Diss()` operator

### Value

Depends on the `output` argument. See `simulate.tergm` for details. Note that some formation/dissolution separated information is also attached to the return value for calls made through `simulate.network` and `simulate.networkDynamic` in an attempt to increase backwards compatibility.

### Examples

    logit<-function(p)log(p/(1-p))
    coef.form.f<-function(coef.diss,density) -log(((1+exp(coef.diss))/(density/(1-density)))-1)

    # Construct a network with 20 nodes and 20 edges
    n<-20
    target.stats<-edges<-20
    g0<-network.initialize(n,dir=TRUE)
    g1<-san(g0~edges,target.stats=target.stats,verbose=TRUE)

    S<-10

    # To get an average duration of 10...
    duration<-10
    coef.diss<-logit(1-1/duration)

    # To get an average of 20 edges...
    dyads<-network.dyadcount(g1)
    density<-edges/dyads
    coef.form<-coef.form.f(coef.diss,density)

    # ... coefficients.
    print(coef.form)
    print(coef.diss)

    # Simulate a networkDynamic
    dynsim<-simulate(g1,formation=~edges,dissolution=~edges,
                     coef.form=coef.form,coef.diss=coef.diss,
                     time.slices=S,verbose=TRUE)

    # "Resume" the simulation.
    dynsim2<-simulate(dynsim,formation=~edges,dissolution=~edges,time.slices=S,verbose=TRUE)

[Package tergm version 4.0.2 Index]