Separable Temporal Exponential Family Random Graph Models

Description

stergm is used for finding Separable Temporal ERGMs' (STERGMs) Conditional MLE (CMLE) (Krivitsky and Handcock, 2010) and Equilibrium Generalized Method of Moments Estimator (EGMME) (Krivitsky, 2009).

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
  stergm (nw, 
          formation, 
          dissolution,
          constraints = ~.,
          estimate, 
          times=NULL, 
          offset.coef.form=NULL, 
          offset.coef.diss=NULL,
          targets=NULL, 
          target.stats=NULL,
          eval.loglik=TRUE,
          control=control.stergm(),
          verbose=FALSE, 
          ...)

Arguments

nw

A network object (for EGMME); or networkDynamic object, a network.list object, or a list containing networks (for CMLE and CMPLE).

simulate.network understands the lasttoggle "API".

formation, dissolution

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

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.

It is also possible to specify a proposal function directly by passing a string with the function's name. In that case, arguments to the proposal should be specified through the prop.args argument to control.ergm.

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.

For STERGMs in particular, the constraints apply to the post-formation and the post-dissolution network, rather than the final network. This means, for example, that if the degree of all vertices is constrained to be less than or equal to three, and a vertex begins a time step with three edges, then, even if one of its edges is dissolved during its time step, it won't be able to form another edge until the next time step. This behavior may change in the future.

Note that not all possible combinations of constraints are supported.

estimate

One of "EGMME" for Equilibrium Generalized Method of Moments Estimation, based on a single network with some temporal information and making an assumption that it is a product of a STERGM process running to its stationary (equilibrium) distribution; "CMLE" for Conditional Maximum Likelihood Estimation, modeling a transition between two networks, or "CMPLE" for Conditional Maximum PseudoLikelihood Estimation, using MPLE instead of MLE. CMPLE is extremely inaccurate at this time.

times

For CMLE and CMPLE estimation, times or indexes at which the networks whose transition is to be modeled are observed. Default to c(0,1) if nw is a networkDynamic and to 1:length(nw) (all transitions) if nw is a network.list or a list. Unused for EGMME.

offset.coef.form

Numeric vector to specify offset formation parameters.

offset.coef.diss

Numeric vector to specify offset dissolution parameters.

targets

One-sided ergm-style formula specifying statistics whose moments are used for the EGMME. Unused for CMLE and CMPLE. Targets is required for EGMME estimation. It may contain any valid ergm terms. If specified as "formation" or "dissolution", it copies the formula from the respective model. Any offset terms are removed automatically.

target.stats

A vector specifying the values of the targets statistics that EGMME will try to match. Defaults to the statistics of nw. Unused for CMLE and CMPLE.

eval.loglik

Whether or not to calculate the log-likelihood of a CMLE STERGM fit. See ergm for details.

control

A list of control parameters for algorithm tuning. Constructed using control.stergm.

verbose

logical or integer; if TRUE or positive, the program will print out progress information. Higher values result in more output.

...

Additional arguments, to be passed to lower-level functions.

Details

Model Terms See ergm and ergm-terms for details. At this time, only linear ERGM terms are allowed.

Value

stergm returns an object of class stergm that is a list consisting of the following elements:

formation, dissolution

Formation and dissolution formulas, respectively.

targets

The targets formula.

target.stats

The target statistics.

estimate

The type of estimate.

opt.history

A matrix containing the full trace of the EGMME optimization process: coefficients tried and target statistics simulated.

sample

An mcmc object containing target statistics sampled at the estimate.

covar

The full estimated variance-covariance matrix of the parameter estimates for EGMME. (Note that although the CMLE formation parameter estimates are independent of the dissolution parameter estimates due to the separability assumption, this is not necessarily the case for EGMME.)

formation.fit, dissolution.fit

For CMLE and CMPLE, ergm objects from fitting formation and dissolution, respectively. For EGMME, stripped down ergm-like lists.

network

For estimate=="EGMME", the original network; for estimate=="CMLE" or estimate=="CMPLE", a network.list (a discrete series of networks) to which the model was fit.

control

The control parameters used to fit the model.

See the method print.stergm for details on how an stergm object is printed. Note that the method summary.stergm returns a summary of the relevant parts of the stergm object in concise summary format.

References

See Also

ergm, network, %v%, %n%, ergm-terms

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
# EGMME Example
par(ask=FALSE)
n<-30
g0<-network.initialize(n,dir=FALSE)

#                     edges, degree(1), mean.age
target.stats<-c(      n*1/2,    n*0.6,        20)

dynfit<-stergm(g0,formation = ~edges+degree(1), dissolution = ~edges,
               targets = ~edges+degree(1)+mean.age,
               target.stats=target.stats, estimate="EGMME",
               control=control.stergm(SA.plot.progress=TRUE))

par(ask=TRUE)
mcmc.diagnostics(dynfit)
summary(dynfit)

# CMLE Example
data(samplk)

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

mcmc.diagnostics(samplk12)
summary(samplk12)

# Fit a transition from Time 1 to Time 2 and from Time 2 to Time 3 jointly
samplk123 <- stergm(list(samplk1, samplk2, samplk3),
                    formation=~edges+mutual+transitiveties+cyclicalties,
                    dissolution=~edges+mutual+transitiveties+cyclicalties,
                    estimate="CMLE")

mcmc.diagnostics(samplk123)
summary(samplk123)