Conversions for `tergm` version 4.0

options(rmarkdown.html_vignette.check_title = FALSE)


Version 4.0 of the tergm package introduces new user interfaces for specifying tergm models. While an effort has been made to maintain a high degree of backwards compatibility, there are some points of backwards incompatibility, and some users may wish to convert their code to use the new interfaces anyway, so this document describes how to go about doing that. The examples given here are somewhat artificial so as to better illustrate the range of possible changes needed; they may not be typical or even plausible in every detail, but are intended to exhibit the types of updates that users may need to make.


Estimation calls in tergm 3.x might look something like

samp <- list(samplk1, samplk2, samplk3) <- stergm(samp,
                   formation = ~edges+mutual+cyclicalties+transitiveties,
                   dissolution = ~edges+mutual+cyclicalties+transitiveties,
                   estimate = "CMLE",
                   times = 1:3,
                   control = control.stergm(CMLE.control.form = control.ergm(init = c(-3.5,2,0,NA)),
                                            CMLE.control.diss = control.ergm(init = c(0,1,0,1/2))))

for CMLE, and

data(florentine) <- stergm(flobusiness,
                       formation = ~edges+gwesp(0,fixed=T),
                       dissolution = ~offset(edges),
                       targets = "formation",
                       offset.coef.diss = log(9),
                       estimate = "EGMME",
                       control = control.stergm(SA.plot.progress=TRUE))

for EGMME.

To convert these to the new 4.0 user interface, we make the following changes.

network ~ Form(formation formula) + Persist(dissolution formula)

where Form and Persist are operator terms defined in tergm 4.0.

For the CMLE example, this results in the formula

samp ~ Form(~edges+mutual+cyclicalties+transitiveties) + Persist(~edges+mutual+cyclicalties+transitiveties)

and for the EGMME example, it results in the formula

flobusiness ~ Form(~edges+gwesp(0,fixed=T)) + Persist(~offset(edges))

These formulas will be our first arguments to the tergm function.

Our discussion of initial coefficient values below will also include the necessary control argument changes for our examples above.

In our examples, the CMLE call specifies initial coefficient values through control$CMLE.control.*$init. We can combine these into control$CMLE.ergm$init as

control = control.tergm(CMLE.ergm = control.ergm(init = c(-3.5,2,0,NA,0,1,0,1/2)))

noting that we also replaced control.stergm() with control.tergm(). We can simplify this further by exploiting new control list flattening features, writing

control = snctrl(init = c(-3.5,2,0,NA,0,1,0,1/2))


The EGMME call specifies only a single dissolution offset, which we can specify through offset.coef as

offset.coef = log(9)

Overall, this produces the new-style calls

samp <- list(samplk1, samplk2, samplk3) <- tergm(samp ~ Form(~edges+mutual+cyclicalties+transitiveties) + 
                  estimate = "CMLE",
                  times = 1:3,
                  control = snctrl(init = c(-3.5,2,0,NA,0,1,0,1/2)))

for CMLE, and

data(florentine) <- tergm(flobusiness ~ Form(~edges+gwesp(0,fixed=T)) + 
                     targets = "formation",
                     offset.coef = log(9),
                     estimate = "EGMME",
                     control = control.tergm(SA.plot.progress=TRUE))

for EGMME.


From a fitted tergm object

A call in tergm 3.x for simulating from a fitted stergm might look something like

stergm.sim.1 <- simulate(, 
                         stats.form = TRUE,
                         nsim = 1,
                         time.slices = 1000,
                         control = control.simulate.stergm(MCMC.init.maxchanges = 10000))

There is no simulate.stergm function in tergm 4.0, only a simulate.tergm function, so the changes described in this section are generally mandatory, with the exception of the control list class, which can be left as control.simulate.stergm if desired (although this is not recommended). Even if one calls the old stergm() function to estimate the model, calling simulate on the returned object will dispatch to the simulate.tergm function described here.

To convert from simulating a fitted stergm in tergm 3.x to simulating a fitted tergm in tergm 4.0, we make the following changes.

These arguments are not passed in the example above, so no corresponding changes are needed in that example.

In the example above, we pass stats.form = TRUE, so in the 4.0 version of the call, we will set stats = TRUE.

In the example above, we passed MCMC.init.maxchanges = 10000; since this is enough to accomodate all expected changes throughout the entire simulation, we will pass

control = snctrl(MCMC.maxchanges = 10000)

in the 4.0 version of the call.

Thus, dropping the s from the object names for consistency, we obtain the 4.0 style call

tergm.sim.1 <- simulate(, 
                        stats = TRUE,
                        nsim = 1,
                        time.slices = 1000,
                        control = snctrl(MCMC.maxchanges = 10000))

From a network (or networkDynamic)

A call in tergm 3.x for simulating based on a starting network (or networkDynamic), along with specified formation and dissolution formulas and coefficients, might look something like

stergm.sim.2 <- simulate(flobusiness, 
                         formation = ~edges+gwesp(0,fixed=T),
                         dissolution = ~edges, 
                         monitor = "formation",
                         coef.form = c(-7.981749, 1.575780), 
                         coef.diss = log(99),
                         time.slices = 50000)

To convert from simulating based on a starting network in tergm 3.x to simulating based on a starting network in tergm 4.0, we make the following changes.

network ~ Form(formation formula) + Persist(dissolution formula)

as for estimation.

Thus, we obtain the 4.0 simulation call

tergm.sim.2 <- simulate(flobusiness ~ Form(~edges+gwesp(0,fixed=T)) +
                        monitor = "formation",
                        coef = c(-7.981749, 1.575780, log(99)), 
                        time.slices = 50000,
                        dynamic = TRUE)

Try the tergm package in your browser

Any scripts or data that you put into this service are public.

tergm documentation built on May 31, 2023, 8:29 p.m.