EpiModel (version 0.95)

epiNet.est: Stochastic Network Estimation with STERGM

Description

Estimates and diagnoses a statistical network model using the exponential random graph modeling (ERGM) framework with extensions for dynamic/temporal models (STERGM)

Usage

epiNet.est(nw, formation, dissolution, target.stats, coef.diss, constraints,
  edapprox = TRUE, save.stats = TRUE, stats.formula, stats.start = 1,
  stats.end = 1000, verbose = TRUE, ...)

Arguments

nw

an object of class network.

formation

a right-hand sided STERGM formation formula in the form ~ edges + ..., where ... are additional network statistics.

dissolution

a right-hand sided STERGM dissolution formula in the form ~ offset(edges) + ..., where ... are additional network statistics.

target.stats

a vector of target statistics for formation model, with one number for each network statistic in the model (see stergm).

coef.diss

an object of class dissolution.coefs that is calculated with the function of that name containing the target coefficients to target.

constraints

a right-hand sided formula specifying contraints for the modeled network, in the form ~..., where ... are constraint terms described in stergm. By default, no constraints ar

edapprox

if TRUE, use the indirect edges dissolution approximation method for dynamic modeling fitting rather than the more time-intensive full STERGM estimation (available with FALSE). For this to function, the coef.diss

save.stats

if TRUE, run simulation-based model diagnostics for the formation and dissolution processes.

stats.formula

a right-hand sided ERGM formula that includes network statistics of interest, with the default to the formation formula terms.

stats.start

starting timestep for calculating the summary measure diagnostics.

stats.end

ending timestep for calculating the summary measure diagnostics.

verbose

if TRUE, print simulation progress to the console.

...

additional arguments to pass to ergm or stergm.

Details

This function is a wrapper function around ergm and stergm to facilitate estimating a dynamic/temporal ERGM from target statistics. This framework is suggested for parameterizing a stochastic network epidemic model from empirical partnership formation and dissolution data collected in an egocentric format (i.e., study subjects asked about their recent partners, including questions on partnership duration).

Additional functionality here includes time-varying diagnostics for a temporal simulation from the fitted model, to ensure that target statistics are approximated by the network simulation. This is available through the save.stats argument, with the stats.formula argument allowing flexibility in network statistics of interest outside those in the formation formula. The diagnostics are available by printing and plotting the fitted epiNet.est object.

With a fitted and diagnosed network model, one may proceed to epiNet.simNet for simulating a series of networks for use in an independent stochastic network epidemic model, or straight to the epidemic model function epiNet.simTrans if there are dependencies between the network model and the disease model. See Section 4 of ../doc/Tutorial.pdf{EpiModel Tutorial} for further clarification.

References

Krivitsky PN, Handcock MS (2010). A Separable Model for Dynamic Networks. http://arxiv.org/abs/1011.1937.

See Also

stergm, epiNet.simNet, epiNet.simTrans

Examples

# Initialize an empty network of 500 nodes divided equally into two races
nw <- network.initialize(n=500, directed=F)
nw <- set.vertex.attribute(nw, "race", value = rep(0:1, each=250))

# Set formation and dissolution formulas
formation <- ~ edges + nodematch("race") + degree(0) + concurrent
dissolution <- ~ offset(edges)

# Set target statistics for formation
target.stats <- c(225, 187, 180, 90)

# Set a vector of durations (here in months, but timestep units are arbitrary)
#  Then use the dissolution.coefs functions to obtain the offset coefficients
durations <- 20
coef.diss <- dissolution.coefs(dissolution, durations)
coef.diss

# Set the stats.formula to include more degree tergms than the formation formula
dx.stats <- ~edges + nodematch("race") + degree(0:5)

# Estimate the STERGM with all the parameters set above with diagnostic
#  simulations through 2000 timesteps, using the edges dissolution approximation
est <- epiNet.est(
  nw,
  formation,
  dissolution,
  target.stats,
  coef.diss,
  edapprox = TRUE,
  stats.formula = dx.stats,
  dx.end = 2000)

# Estimate the STERGM directly and use the default for model statistics
est2 <- epiNet.est(
  nw,
  formation,
  dissolution,
  target.stats,
  coef.diss,
  edapprox = FALSE)
est2

# Print and plot summaries
est
plot(est)
plot(est, type="duration")