simulate.network {tergm}

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

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.

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)