simulate.stergm: Draw from the distribution of an Separable Temporal Exponential Family Random Graph Model

Description

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

Usage

## S3 method for class 'stergm':
simulate(object, nsim=1, seed=NULL,
  coef.form = object$formation.fit$coef,
  coef.diss = object$dissolution.fit$coef,
  constraints = object$constraints,
  monitor = object$targets,
  time.slices=1, time.start=NULL, time.burnin=0, time.interval=1,
  control=control.simulate.stergm(),
  statsonly=NULL,
  output=c("networkDynamic", "stats", "changes", "final"),
  nw.start = NULL,
  stats.form = FALSE,
  stats.diss = FALSE,
  duration.dependent = NULL,
  verbose=FALSE, 
  ...)
## 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(),
  statsonly=NULL,
  output=c("networkDynamic", "stats", "changes", "final"),
  stats.form = FALSE,
  stats.diss = FALSE,
  duration.dependent = NULL,
  verbose=FALSE,
  ...)
## S3 method for class 'networkDynamic':
simulate(object, nsim=1, seed=NULL,
   formation = attr(object, "formation"),
   dissolution = attr(object, "dissolution"),
   coef.form = attr(object, "coef.form"),
   coef.diss = attr(object, "coef.diss"),
   constraints = NVL(attr(object, "constraints"), ~.),
   monitor = attr(object, "monitor"),
   time.slices=1, time.start=NULL, time.burnin=0, time.interval=1, time.offset=1,
   control=control.simulate.network(),
   statsonly=NULL,
   output=c("networkDynamic", "stats", "changes"),
   stats.form = FALSE,
   stats.diss = FALSE,
   duration.dependent = NULL,
   verbose=FALSE,
   ...)

Arguments

object

an Robject of type stergm giving a model fit or of type network giving the initial network.

simulate.network understands the

formation, dissolution

One-sided ergm-style formulas for the formation and dissolution models, respectively.

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.form

Parameters for the model from which the post-formation network is drawn.

coef.diss

As coef.form, but for the post-dissolution network.

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 +

monitor

Either a one-sided formula specifying one or more terms whose value is to be monitored, or a string containing "formation" or "dissolution", to monitor their respective terms, or "all" to monitor distinct

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 o

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. Actual network will only be returned if time.burnin==0.

time.interval

Number of time steps between successive recordings of network statistics. Actual network will only be returned if time.interval==1.

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.stergm or control.simulate.network

statsonly

Deprecated in favor of output.

output

A character vector specifying output type: one of "networkDynamic" (the default), "stats", and "changes", with partial matching allowed. See Value section for details.

nw.start

A specification for the starting network to be used by simulate.stergm, optional for EGMME fits, but required for CMLE and CMPLE fits: [object Object],[object Object],[object Object]

stats.form, stats.diss

Logical: Whether to return formation/dissolution model statistics. This is not the recommended method: use monitor argument instead.

duration.dependent

Logical: Whether the model terms in formula or model are duration dependent. E.g., if a duration-dependent term is used in estimation/simulation model, the probability of forming or dissolving a tie may dependent on the age the dyad status.

verbose

Logical: If TRUE, extra information is printed as the Markov chain progresses.

...

Further arguments passed to or used by methods.

Value

Depends on the output argument:
"stats"If stats.form==FALSE and stats.diss==FALSE, an mcmc matrix with monitored statistics, and if either of them is TRUE, a list containing elements stats for statistics specified in the monitor argument, and stats.form and stats.diss for the respective formation and dissolution statistics.
If stats.form==FALSE and stats.diss==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: [object Object],[object Object],[object Object],[object Object]
When nsim>1, a network.list of these networkDynamics 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, 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. This is not implemented in the method for networkDynamic.
lasttoggle attributes are also included.
Additionally, attributes (attr, not network attributes) are attached as follows: [object Object],[object Object],[object Object],[object Object]
When nsim>1, a network.list of these networks is returned.

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 object, by default with the same model and parameters.

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

The time index of the start of the simulation is determined as follows:

Iftime.startis 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.

Examples

Run this code

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,time.slices=S,verbose=TRUE)

Run the code above in your browser using DataLab