---
title: Conversions for `tergm` version 4.0
output: rmarkdown::html_vignette
vignette: >
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
%\VignetteIndexEntry{Conversions for tergm version 4.0}
---
```{r, echo=FALSE, cache=FALSE, eval=TRUE}
library(knitr)
library(rmarkdown)
options(rmarkdown.html_vignette.check_title = FALSE)
opts_chunk$set(echo=TRUE)
options(width=80)
```
# Introduction #
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 #
Estimation calls in `tergm` 3.x might look something like
```
data(samplk)
samp <- list(samplk1, samplk2, samplk3)
samp.fit <- 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.fit.1 <- 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.
- Replace the function name `stergm` with `tergm` (in 4.0, the tergms need not
be separable, hence we drop the s).
- Combine the network (or network list), formation, and dissolution formulas
into a single formula, schematically of the form
```
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.
- The control argument (if present), previously of class `control.stergm`,
should be replaced by one of class `control.tergm`. This can be accomplished
by replacing `control.stergm()` with `control.tergm()`, `snctrl()`, or
`list()`, and updating arguments as follows. Arguments to `control.stergm()`
occurring in pairs with `.form` and `.diss` in their names have been
collapsed to single, correspondingly named arguments to `control.tergm()`
without `.form` or `.diss`. Additionally, the arguments `CMLE.control.form` and
`CMLE.control.diss` to `control.stergm()` correspond to the `CMLE.ergm`
argument to `control.tergm()` (and have been renamed as the `CMLE.form.ergm`
and `CMLE.diss.ergm` control arguments to `control.stergm()`).
Furthermore, the arguments `MCMC.init.maxedges`
and `MCMC.init.maxchanges` to `control.stergm()` have been replaced by the
`MCMC.maxedges` and `MCMC.maxchanges` arguments to `control.tergm()`; these
arguments have also been replaced in `control.stergm()`, so code continuing
to use the old interface will still need to change from using
`MCMC.init.maxedges` and `MCMC.init.maxchanges` to using `MCMC.maxedges` and
`MCMC.maxchanges`.
Our discussion of initial coefficient values below will also include the
necessary control argument changes for our examples above.
- The initial coefficient specifications for the formation and dissolution
models, if passed, should be combined into a specification of initial
coefficients for the combined model. This can be done through the `tergm`
function's `offset.coef`, `control$init`, and/or `control$CMLE.ergm$init`
arguments (the final one applying only to the CMLE case). If `offset.coef`
is passed, it should have length equal to the number of offset thetas in the
combined model, and if `control$init` or `control$CMLE.ergm$init` is passed,
it should have length equal to the total number of thetas in the combined
model. (`NA`s may be used in `control$init` or `control$CMLE.ergm$init` to
indicate that initial values for those (non-offset) thetas are not being
passed.) Here `control` refers to the `control.tergm` class control
discussed in the previous bullet point.
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))
```
instead.
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
```
data(samplk)
samp <- list(samplk1, samplk2, samplk3)
samp.fit <- tergm(samp ~ Form(~edges+mutual+cyclicalties+transitiveties) +
Persist(~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.fit.1 <- tergm(flobusiness ~ Form(~edges+gwesp(0,fixed=T)) +
Persist(~offset(edges)),
targets = "formation",
offset.coef = log(9),
estimate = "EGMME",
control = control.tergm(SA.plot.progress=TRUE))
```
for EGMME.
# Simulation #
## 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(stergm.fit.1,
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.
- Replace the `coef.form` and `coef.diss` arguments (which will default to the
coefficients of the fitted `stergm`) with the `coef` argument (which will
default to the coefficients of the fitted `tergm`), which is schematically of
the form `coef = c(coef.form, coef.diss)`, assuming the combined formula used
when estimating the `tergm` was of the form described in the Estimation
section (with `Form(formation formula)` preceding
`Persist(dissolution formula)`).
These arguments are not passed in the example
above, so no corresponding changes are needed in that example.
- Replace the `stats.form` and `stats.diss` arguments (if passed) with the
`stats` argument, which will give all generative model statistics if set to
`TRUE`.
In the example above, we pass `stats.form = TRUE`, so in
the 4.0 version of the call, we will set `stats = TRUE`.
- The control argument (if passed), previously of class
`control.simulate.stergm`, should be replaced by one of class
`control.simulate.tergm`. This can be accomplished by replacing
`control.simulate.stergm()` with `control.simulate.tergm()`, `snctrl()`, or
`list()`, and updating arguments as follows. Arguments to
`control.simulate.stergm()` occurring in pairs with `.form` and `.diss` in
their names have been collapsed to single, correspondingly named arguments to
`control.simulate.tergm()` without `.form` or `.diss`. Additionally, the
arguments `MCMC.init.maxedges` and `MCMC.init.maxchanges` to
`control.simulate.stergm()` have been replaced by the `MCMC.maxedges` and
`MCMC.maxchanges` arguments to `control.simulate.tergm()`; these arguments
have also been replaced in `control.simulate.stergm()`, so code continuing
to use `control.simulate.stergm()` will still need to change from using
`MCMC.init.maxedges` and `MCMC.init.maxchanges` to using `MCMC.maxedges` and
`MCMC.maxchanges`.
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(tergm.fit.1,
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.
- Combine the network, formation, and dissolution formulas into a single
formula, schematically of the form
```
network ~ Form(formation formula) +
Persist(dissolution formula)
```
as for estimation.
- Combine the `coef.form` and `coef.diss` arguments into a single `coef`
argument, schematically of the form `coef = c(coef.form, coef.diss)`,
assuming the combined formula is specified as in the previous bullet point
(with `Form(formation formula)` preceding `Persist(dissolution formula)`).
- The control argument (if passed), previously of class
`control.simulate.network`, should be replaced by one of class
`control.simulate.formula.tergm`. This can be accomplished by replacing
`control.simulate.network()` with `control.simulate.formula.tergm()`,
`snctrl()`, or `list()`, and updating arguments as when simulating from a
fitted `tergm`.
- Combine the `stats.form` and `stats.diss` arguments (if passed) into a
single `stats` argument.
- Pass `dynamic = TRUE` to indicate that you want dynamic `tergm` simulation.
Thus, we obtain the 4.0 simulation call
```
tergm.sim.2 <- simulate(flobusiness ~ Form(~edges+gwesp(0,fixed=T)) +
Persist(~edges),
monitor = "formation",
coef = c(-7.981749, 1.575780, log(99)),
time.slices = 50000,
dynamic = TRUE)
```
<!-- # Some Technical Points # -->
<!-- perhaps to be added later -->