tergm
version
4.0Version 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
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.
tergm
objectA 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))
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)