ergm (version 3.1.3)

ergm: Exponential Family Random Graph Models

Description

ergm is used to fit linear exponential random graph models (ERGMs), in which the probability of a given network, $y$, on a set of nodes is $h(y) \exp{\eta(\theta) \cdot g(y)}/c(\theta)$, where $h(y)$ is the reference measure (usually $h(y)=1$), $g(y)$ is a vector of network statistics for $y$, $\eta(\theta)$ is a natural parameter vector of the same length (with $\eta(\theta)=\theta$ for most terms), and $c(\theta)$ is the normalizing constant for the distribution. ergm can return either a maximum pseudo-likelihood estimate or an approximate maximum likelihood estimator based on a Monte Carlo scheme.

Usage

ergm (formula,
      response=NULL,
      reference=~Bernoulli,
      constraints=~.,
      offset.coef=NULL,
      target.stats=NULL,
      eval.loglik=TRUE,
      estimate=c("MLE", "MPLE"),
      control=control.ergm(),
      verbose=FALSE,
      ...)

Arguments

formula

An Rformula object, of the form y ~ , where y is a network object or a matrix that can be coerced t

response

EXPERIMENTAL. Name of the edge attribute whose value is to be modeled. Defaults to NULL for simple presence or absence, modeled via binary ERGM terms. Passing anything but NULL uses valued ERGM terms.

reference

EXPERIMENTAL. A one-sided formula specifying the reference measure ($h(y)$) to be used. (Defaults to ~Bernoulli.) See help for ERGM reference measures implem

constraints

A one-sided formula specifying one or more constraints on the support of the distribution of the networks being modeled, using syntax similar to the formula argument. Multiple constraints may be given, separated by +

offset.coef

A vector of coefficients for the offset terms.

target.stats

vector of "observed network statistics," if these statistics are for some reason different than the actual statistics of the network on the left-hand side of formula. Equivalently, this vector is the mean-value parameter valu

eval.loglik

Logical: For dyad-dependent models, if TRUE, use bridge sampling to evaluate the log-likelihoood associated with the fit. Has no effect for dyad-independent models. Since bridge sampling takes additional time, setting to FALSE may speed p

estimate

If "MPLE," then the maximum pseudolikelihood estimator is returned. If "MLE" (the default), then an approximate maximum likelihood estimator is returned. For certain models, the MPLE and MLE are equivalent, in which case this argument is ign

control

A list of control parameters for algorithm tuning. Constructed using control.ergm.

verbose

logical; if this is TRUE, the program will print out additional information, including goodness of fit statistics.

...

Additional arguments, to be passed to lower-level functions.

Value

• ergm returns an object of class ergm that is a list consisting of the following elements:
• coef
  The Monte Carlo maximum likelihood estimate of $\theta$, the vector of coefficients for the model parameters.
• sample
  The $n\times p$ matrix of network statistics, where $n$ is the sample size and $p$ is the number of network statistics specified in the model, that is used in the maximum likelihood estimation routine.
• sample.obs
  As sample, but for the constrained sample.
• iterations
  The number of Newton-Raphson iterations required before convergence.
• MCMCtheta
  The value of $\theta$ used to produce the Markov chain Monte Carlo sample. As long as the Markov chain mixes sufficiently well, sample is roughly a random sample from the distribution of network statistics specified by the model with the parameter equal to MCMCtheta. If estimate="MPLE" then MCMCtheta equals the MPLE.
• loglikelihood
  The approximate change in log-likelihood in the last iteration. The value is only approximate because it is estimated based on the MCMC random sample.
• gradient
  The value of the gradient vector of the approximated loglikelihood function, evaluated at the maximizer. This vector should be very close to zero.
• covar
  Approximate covariance matrix for the MLE, based on the inverse Hessian of the approximated loglikelihood evaluated at the maximizer.
• failure
  Logical: Did the MCMC estimation fail?
• mc.se
  MCMC standard error estimates
• newnetwork
  The final network at the end of the MCMC simulation
• network
  Original network
• coef.init
  The initial value of $\theta$.
• initial
  The MPLE fit as a glm object.
• null.deviance
  Deviance of the null model. Valid only for unconstrained models.
• mle.lik
  The approximate log-likelihood for the MLE. The value is only approximate because it is estimated based on the MCMC random sample.
• etamap
  The set of functions mapping the true parameter theta to the canonical parameter eta (irrelevant except in a curved exponential family model)
• degeneracy.value
  Score calculated to assess the degree of degeneracy in the model.
• degeneracy.type
  Supporting output for degeneracy.value. Mainly for internal use.
• formula
  The original formula entered into the ergm function.
• constraints
  Constraints used by original ergm call
• control
  The control list passed to the call.
• offset
  vector of logical telling which model parameters are to be set at a fixed value (i.e., not estimated).
• drop
  If control$drop=TRUE, a numeric vector indicating which terms were dropped due to to extreme values of the corresponding statistics on the observed network, and how: [object Object],[object Object],[object Object]
• coef.hist, stats.hist, stats.obs.hist
  For the MCMLE method, the history of coefficients and resulting average statistics.
• estimable
  A logical vector indicating which terms could not be estimated due to a constraints constraint fixing that term at a constant value.
• See the method print.ergm for details on how an ergm object is printed. Note that the method summary.ergm returns a summary of the relevant parts of the ergm object in concise summary format.

Notes on model specification

Although each of the statistics in a given model is a summary statistic for the entire network, it is rarely necessary to calculate statistics for an entire network in a proposed Metropolis-Hastings step.Thus, for example, if the triangle term is included in the model, a census of all triangles in the observed network is never taken; instead, only the change in the number of triangles is recorded for each edge toggle.

In the implementation of ergm, the model is initialized in R, then all the model information is passed to a C program that generates the sample of network statistics using MCMC. This sample is then returned to R, which implements a simple Newton-Raphson algorithm to approximate the MLE. An alternative style of maximum likelihood estimation is to use a stochastic approximation algorithm. This can be chosen with the control.ergm(style="Robbins-Monro") option. The mechanism for proposing new networks for the MCMC sampling scheme, which is a Metropolis-Hastings algorithm, depends on two things: The constraints, which define the set of possible networks that could be proposed in a particular Markov chain step, and the weights placed on these possible steps by the proposal distribution. The former may be controlled using the constraints argument described above. The latter may be controlled using the prop.weights argument to the control.ergm function.

The package is designed so that the user could conceivably add additional proposal types.

References

Admiraal R, Handcock MS (2007). networksis: Simulate bipartite graphs with fixed marginals through sequential importance sampling. Statnet Project, Seattle, WA. Version 1. statnet.org.

Bender-deMoll S, Morris M, Moody J (2008). Prototype Packages for Managing and Animating Longitudinal Network Data: dynamicnetwork and rSoNIA. Journal of Statistical Software, 24(7). http://www.jstatsoft.org/v24/i07/.

Butts CT (2006). netperm: Permutation Models for Relational Data. Version 0.2, http://erzuli.ss.uci.edu/R.stuff.

Butts CT (2007). sna: Tools for Social Network Analysis. Version 1.5, http://erzuli.ss.uci.edu/R.stuff.

Butts CT (2008). network: A Package for Managing Relational Data in R. Journal of Statistical Software, 24(2). http://www.jstatsoft.org/v24/i02/.

Butts CT, with help~from David~Hunter, Handcock MS (2007). network: Classes for Relational Data. Version 1.2, http://erzuli.ss.uci.edu/R.stuff.

Goodreau SM, Handcock MS, Hunter DR, Butts CT, Morris M (2008a). A statnet Tutorial. Journal of Statistical Software, 24(8). http://www.jstatsoft.org/v24/i08/.

Goodreau SM, Kitts J, Morris M (2008b). Birds of a Feather, or Friend of a Friend? Using Exponential Random Graph Models to Investigate Adolescent Social Networks. Demography, 45, in press.

Handcock, M. S. (2003) Assessing Degeneracy in Statistical Models of Social Networks, Working Paper #39, Center for Statistics and the Social Sciences, University of Washington. www.csss.washington.edu/Papers/wp39.pdf

Handcock MS (2003b). degreenet: Models for Skewed Count Distributions Relevant to Networks. Statnet Project, Seattle, WA. Version 1.0, statnet.org.

Handcock MS, Hunter DR, Butts CT, Goodreau SM, Morris M (2003a). ergm: A Package to Fit, Simulate and Diagnose Exponential-Family Models for Networks. Statnet Project, Seattle, WA. Version 2, statnet.org.

Handcock MS, Hunter DR, Butts CT, Goodreau SM, Morris M (2003b). statnet: Software Tools for the Statistical Modeling of Network Data. Statnet Project, Seattle, WA. Version 2, statnet.org.

Hunter, D. R. and Handcock, M. S. (2006) Inference in curved exponential family models for networks, Journal of Computational and Graphical Statistics.

Hunter DR, Handcock MS, Butts CT, Goodreau SM, Morris M (2008b). ergm: A Package to Fit, Simulate and Diagnose Exponential-Family Models for Networks. Journal of Statistical Software, 24(3). http://www.jstatsoft.org/v24/i03/.

Krivitsky PN (2012). Exponential-Family Random Graph Models for Valued Networks. Electronic Journal of Statistics, 2012, 6, 1100-1128. http://dx.doi.org/10.1214/12-EJS696{doi:10.1214/12-EJS696} Morris M, Handcock MS, Hunter DR (2008). Specification of Exponential-Family Random Graph Models: Terms and Computational Aspects. Journal of Statistical Software, 24(4). http://www.jstatsoft.org/v24/i04/. Snijders, T.A.B. (2002), Markov Chain Monte Carlo Estimation of Exponential Random Graph Models. Journal of Social Structure. Available from http://www.cmu.edu/joss/content/articles/volume3/Snijders.pdf.

See Also

network, %v%, %n%, ergm-terms, ergmMPLE, summary.ergm, print.ergm

Examples

#
# load the Florentine marriage data matrix
#
data(flo)
#
# attach the sociomatrix for the Florentine marriage data
# This is not yet a network object.
#
flo
#
# Create a network object out of the adjacency matrix
#
flomarriage <- network(flo,directed=FALSE)
flomarriage
#
# print out the sociomatrix for the Florentine marriage data
#
flomarriage[,]
#
# create a vector indicating the wealth of each family (in thousands of lira) 
# and add it as a covariate to the network object
#
flomarriage %v% "wealth" <- c(10,36,27,146,55,44,20,8,42,103,48,49,10,48,32,3)
flomarriage
#
# create a plot of the social network
#
plot(flomarriage)
#
# now make the vertex size proportional to their wealth
#
plot(flomarriage, vertex.cex=flomarriage %v% "wealth" / 20, main="Marriage Ties")
#
# Use 'data(package = "ergm")' to list the data sets in a
#
data(package="ergm")
#
# Load a network object of the Florentine data
#
data(florentine)
#
# Fit a model where the propensity to form ties between
# families depends on the absolute difference in wealth
#
gest <- ergm(flomarriage ~ edges + absdiff("wealth"))
summary(gest)
#
# add terms for the propensity to form 2-stars and triangles
# of families 
#
gest <- ergm(flomarriage ~ kstar(1:2) + absdiff("wealth") + triangle)
summary(gest)

# import synthetic network that looks like a molecule
data(molecule)
# Add a attribute to it to mimic the atomic type
molecule %v% "atomic type" <- c(1,1,1,1,1,1,2,2,2,2,2,2,2,3,3,3,3,3,3,3)
#
# create a plot of the social network
# colored by atomic type
#
plot(molecule, vertex.col="atomic type",vertex.cex=3)

# measure tendency to match within each atomic type
gest <- ergm(molecule ~ edges + kstar(2) + triangle + nodematch("atomic type"),
  control=control.ergm(MCMC.samplesize=10000))
summary(gest)

# compare it to differential homophily by atomic type
gest <- ergm(molecule ~ edges + kstar(2) + triangle
                              + nodematch("atomic type",diff=TRUE),
  control=control.ergm(MCMC.samplesize=10000))
summary(gest)