simulate.stergm function

STERGM wrappers for TERGM simulation

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.

## 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: Seed value (integer) for the random number generator. 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 formula specifying one or more constraints on the support of the distribution of the networks being modeled. Multiple constraints may be given, separated by + and - operators. See ergmConstraint for the detailed explanation of their semantics and also for an indexed list of the constraints visible to the ergm package.

  The default is to have no constraints except those provided through the ergmlhs API.

  Together with the model terms in the formula and the reference measure, the constraints define the distribution of networks being modeled.

  It is also possible to specify a proposal function directly either by passing a string with the function's name (in which case, arguments to the proposal should be specified through the MCMC.prop.args argument to the relevant control function, or by giving it on the LHS of the hints formula to MCMC.prop

  argument to the control function. This will override the one chosen automatically.

  Note that not all possible combinations of constraints and reference measures are supported. However, for relatively simple constraints (i.e., those that simply permit or forbid specific dyads or sets of dyads from changing), arbitrary combinations should be possible.

• 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: A logical or an integer to control the amount of progress and diagnostic information to be printed. FALSE/0

  produces minimal output, with higher values producing more detail. Note that very high values (5+) may significantly slow down processing.

• ...: Further arguments passed to or used by methods.

Returns

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.

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

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)