tergm: tergm.godfather – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

tergm.godfather

A function to apply a given series of changes to a network.

Description

Gives the network a series of timed proposals it can't refuse. Returns the statistics of the network, and, optionally, the final network.

Usage

tergm.godfather(
  formula,
  changes = NULL,
  toggles = changes[, -4, drop = FALSE],
  start = NULL,
  end = NULL,
  end.network = FALSE,
  stats.start = FALSE,
  verbose = FALSE,
  control = control.tergm.godfather()
)

Arguments

`formula`	An `summary.formula`-style formula, with either a `network` or a `networkDynamic` as the LHS and statistics to be computed on the RHS. If LHS is a `networkDynamic`, it will be used to derive the changes to the network whose statistics are wanted. Otherwise, either `changes` or `toggles` must be specified, and the LHS `network` will be used as the starting network.
`changes`	A matrix with four columns: time, tail, head, and new value, describing the changes to be made. Can only be used if LHS of `formula` is not a `networkDynamic`.
`toggles`	A matrix with three columns: time, tail, and head, giving the dyads which had changed. Can only be used if LHS of `formula` is not a `networkDynamic`.
`start`	Time from which to start applying changes. Note that the first set of changes will take effect at `start+1`. Defaults to the time point 1 before the earliest change passed.
`end`	Time from which to finish applying changes. Defaults to the last time point at which a change occurs.
`end.network`	Whether to return a network that results. Defaults to `FALSE`.
`stats.start`	Whether to return the network statistics at `start` (before any changes are applied) as the first row of the statistics matrix. Defaults to `FALSE`, to produce output similar to that of `simulate` for STERGMs when `output="stats"`, where initial network's statistics are not returned.
`verbose`	Whether to print progress messages.
`control`	A control list generated by `control.tergm.godfather`.

Value

If end.network==FALSE (the default), an mcmc object with the requested network statistics associed with the network series produced by applying the specified changes. Its mcmc attributes encode the timing information: so start(out) gives the time point associated with the first row returned, and end(out) out the last. The "thinning interval" is always 1.

If end.network==TRUE, return a network object with lasttoggle "extension", representing the final network, with a matrix of statistics described in the previous paragraph attached to it as an attr-style attribute "stats".

Examples

g1 <- network.initialize(10, dir=FALSE)
g1[1,2] <- 1
g1[3,4] <- 1
g1 %n% "time" <- 0
g1 %n% "lasttoggle" <- -1-rgeom(network.dyadcount(g1),1/4)

dc <- matrix(rnorm(100),10,10); dc <- dc+t(dc)

# Simulate a network, tracking its statistics.
simnet <- simulate(g1, formation=~edges, dissolution=~edges, coef.form=-1, coef.diss=1,
                   time.slices=50, monitor=~degree(1)+mean.age+degree.mean.age(1)+
                                            mean.age(log=TRUE)+degree.mean.age(1,log=TRUE)+
                                            degrange(1,3)+mean.age+degrange.mean.age(1,3)+
                                            mean.age(log=TRUE)+degrange.mean.age(1,3,log=TRUE)+
                                            edge.ages+edgecov(dc)+edgecov.ages(dc),
                   output="networkDynamic")

sim.stats <- attr(simnet, "stats")

print(head(sim.stats))
sim.stats <- as.matrix(sim.stats)

# Replay the simulation using a networkDynamic, monitoring a potentially different set of
# statistics (but same in this case).
gf1.stats <- tergm.godfather(simnet~degree(1)+mean.age+degree.mean.age(1)+
                                    mean.age(log=TRUE)+degree.mean.age(1,log=TRUE)+
                                    degrange(1,3)+mean.age+degrange.mean.age(1,3)+
                                    mean.age(log=TRUE)+degrange.mean.age(1,3,log=TRUE)+
                                    edge.ages+edgecov(dc)+edgecov.ages(dc),
                             start=0, end=50)

print(head(gf1.stats))
gf1.stats <- as.matrix(gf1.stats)

# Replay the simulation using the initial network + list of changes.

gf2.stats <- tergm.godfather(g1~degree(1)+mean.age+degree.mean.age(1)+
                                mean.age(log=TRUE)+degree.mean.age(1,log=TRUE)+
                                degrange(1,3)+mean.age+degrange.mean.age(1,3)+
                                mean.age(log=TRUE)+degrange.mean.age(1,3,log=TRUE)+
                                edge.ages+edgecov(dc)+edgecov.ages(dc),
                             start=0, end=50, changes=attr(simnet,"changes"))

print(head(gf2.stats))
gf2.stats <- as.matrix(gf2.stats)

# We can also compare them to the network statistics summarized.
summ.stats <- summary(simnet~degree(1)+mean.age+degree.mean.age(1)+
                             mean.age(log=TRUE)+degree.mean.age(1,log=TRUE)+
                             degrange(1,3)+mean.age+degrange.mean.age(1,3)+
                             mean.age(log=TRUE)+degrange.mean.age(1,3,log=TRUE)+
                             edge.ages+edgecov(dc)+edgecov.ages(dc), at=1:50)

print(head(summ.stats))

tol <- sqrt(.Machine$double.eps)
# If they aren't all identical, we are in trouble.
stopifnot(all.equal(sim.stats,gf1.stats),
          all.equal(sim.stats,gf2.stats),
          all.equal(sim.stats,summ.stats))

tergm

Fit, Simulate and Diagnose Models for Network Evolution Based on Exponential-Family Random Graph Models

v3.7.0

GPL-3 + file LICENSE

Authors

Pavel N. Krivitsky [aut, cre] (<https://orcid.org/0000-0002-9101-3362>), Mark S. Handcock [aut, ths], David R. Hunter [ctb], Steven M. Goodreau [ctb, ths], Martina Morris [ctb, ths], Nicole Bohme Carnegie [ctb], Carter T. Butts [ctb], Ayn Leslie-Cook [ctb], Skye Bender-deMoll [ctb], Li Wang [ctb], Kirk Li [ctb], Chad Klumb [ctb]

Initial release

2020-10-15