R: Separable Temporal Exponential Family Random Graph Models

stergm {tergm} | R Documentation

## 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

    stergm(
      nw,
      formation,
      dissolution,
      constraints = ~.,
      estimate,
      times = NULL,
      offset.coef.form = NULL,
      offset.coef.diss = NULL,
      targets = NULL,
      target.stats = NULL,
      eval.loglik = NVL(getOption("tergm.eval.loglik"), getOption("ergm.eval.loglik")),
      control = control.stergm(),
      verbose = FALSE,
      ...,
      SAN.offsets = NULL
    )

### Arguments

`nw` | A `network` object (for EGMME); or `networkDynamic` object, a `network.list` object, or a `list` containing networks (for CMLE and CMPLE). `stergm` understands the `lasttoggle` "API".
`formation, dissolution` | One-sided `ergm`-style formulas for the formation and dissolution models, respectively. 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.
`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.
`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. Note that at this time, the selected time points will be treated as temporally adjacent. Irregularly spaced time series are not supported at this time.
`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. Any offset terms are used only during the preliminary SAN run; they are removed automatically for the EGMME proper. If `targets` is specified as a character (one of `"formation"` and `"dissolution"`) then the function `.extract.fd.formulae` is used to determine the corresponding formula; the user should be aware of its behavior and limitations.
`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. Can be set globally via `option(tergm.eval.loglik=...)`, falling back to `getOption("ergm.eval.loglik")` if not set.
`control` | A list of control parameters for algorithm tuning. Constructed using `control.stergm`. Remapped to `control.tergm`.
`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.
`SAN.offsets` | Offset coefficients (if any) to use during the SAN run.

### Details

This function is included for backwards compatibility, and users are encouraged to use the new `tergm` family of functions instead.

The `stergm` function uses a pair of formulas, `formation` and `dissolution` to model tie-dynamics. The dissolution formula, however, 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, but the discrepancy between the terminology and interpretation has always been unfortunate, and we have fixed this in the new `tergm` function.

If you are making the transition from old `stergm` to new `tergm`, note that the `dissolution` formula in `stergm` maps to the new `Persist()` operator in the `tergm` function, NOT the `Diss()` operator.

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

- For a brief demonstration, please see the tergm package vignette: `browseVignettes(package='tergm')`

- A more detailed tutorial is available on the statnet wiki: https://statnet.org/Workshops/tergm/tergm_tutorial.html

### Value

`stergm` returns an object of class `tergm`; see `tergm()` for details and methods.

### References

Krivitsky P.N. and Handcock M.S. (2014) A Separable Model for Dynamic Networks. Journal of the Royal Statistical Society, Series B, 76(1): 29-46. doi: 10.1111/rssb.12014

Krivitsky, P.N. (2012). Modeling of Dynamic Networks based on Egocentric Data with Durational Information. Pennsylvania State University Department of Statistics Technical Report, 2012(2012-01). https://web.archive.org/web/20170830053722/https://stat.psu.edu/research/technical-report-files/2012-technical-reports/TR1201A.pdf

### See Also

ergm, network, \

### Examples

    ## Not run:
    # 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)

    ## End(Not run)

    # 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)

[Package tergm version 4.0.2 Index]