mlergm: Multilevel Exponential-Family Random Graph Models
In mlergm: Multilevel Exponential-Family Random Graph Models

compute_CI

R Documentation

Multilevel Exponential-Family Random Graph Models

Description

This function estimates an exponential-family random graph model for multilevel network data. At present, mlergm covers network data where the set of nodes is nested within known blocks (see, e.g., Schweinberger and Handcock, 2015). An example is groups of students nested within classrooms, which is covered in the classes data set. It is assumed that the node membership, that to which block each node is associated, is known (or has been previously estimated).

Usage

compute_CI(object, alpha)

mlergm(
  form,
  node_memb,
  parameterization = "standard",
  options = set_options(),
  theta_init = NULL,
  verbose = 0,
  eval_loglik = TRUE,
  seed = NULL
)

## S3 method for class 'mlergm'
print(x, ...)

## S3 method for class 'mlergm'
summary(object, ...)

## S3 method for class 'mlergm'
vcov(object, ...)

Arguments

`object`	An object of class `mlergm`, probably produced by `mlergm`.
`alpha`	Desired significance level for the confidence interval.
`form`	Formula of the form: `network ~ term1 + term2 + ...`; allowable model terms are a subset of those in R package ergm, see `ergm.terms`.
`node_memb`	Vector (length equal to the number of nodes in the network) indicating to which block or group the nodes belong. If the network provided in `form` is an object of class `mlnet`, then `node_memb` can be exctracted directly from the network and need not be provided.
`parameterization`	Parameterization options include 'standard', 'offset', or 'size'. 'standard' : Does not adjust the individual block parameters for size. 'offset' : The offset parameterization uses edge and mutual offsets along the lines of Krivitsky, Handcock, and Morris (2011) and Krivitsky and Kolaczyk (2015). The edge parameter is offset by `-log n(k)` and the mutual parameter is offset by `+log n(k)`, where `n(k)` is the size of the kth block. 'size' : Multiplies the block parameters by `log n(k)`, where `n(k)` is the size of the kth block.
`options`	See `set_options` for details.
`theta_init`	Parameter vector of initial estimates for theta to be used.
`verbose`	Controls the level of output. A value of `0` corresponds to no output, except for warnings; a value of `1` corresponds to minimal output, and a value of `2` corresponds to full output.
`eval_loglik`	(Logical `TRUE` or `FALSE`) If set to `TRUE`, the bridge estimation procedure of Hunter and Handcock (2006) is used to estimate the loglikelihood for BIC calculations, otherwise the loglikelihood and therefore the BIC is not estimated.
`seed`	For reproducibility, an integer-valued seed may be specified.
`x`	An object of class `mlergm`, probably produced by `mlergm`.
`...`	Additional arguments to be passed if necessary.

Details

The estimation procedures performs Monte-Carlo maximum likelihood for the specified ERGM using a version of the Fisher scoring method detailed by Hunter and Handcock (2006). Settings governing the MCMC procedure (such as burnin, interval, and sample_size) as well as more general settings for the estimation procedure can be adjusted through set_options. The estimation procedure uses the the stepping algorithm of Hummel, et al., (2012) for added stability.

Value

mlergm returns an object of class mlergm which is a list containing:

`theta`	Estimated parameter vector of the exponential-family random graph model.
`between_theta`	Estimated parameter vector of the between group model.
`se`	Standard error vector for theta.
`vcovmat`	Variance-covariance matrix of the sufficient statistics of the model. Also the Fisher Information matrix.
`between_se`	Standard error vector for between_theta.
`pvalue`	A vector of p-values for the estimated parameter vector.
`between_pvalue`	A vector of p-values for the estimated parameter vector.
`logLikval`	The loglikelihood for at the estimated MLE.
`bic`	The BIC for the estimated model.
`mcmc_chain`	The MCMC sample used in the final estimation step, which can be used to diagnose non-convergence.
`estimation_status`	Indicator of whether the estimation procedure had `succcess` or `failed`.
`parameterization`	The model parameterization (either `standard` or `offset`).
`etamap`	Object defining the evaluation of the canonical parameters. See `eta` for more details.
`formula`	The model formula.
`network`	The network for which the model is estimated.
`node_memb`	Vector indicating to which group or block the nodes belong.
`size_quantiles`	The quantiles of the block sizes.

Methods (by generic)

print(mlergm): Print method for objects of class mlergm. Indicates whether the model was succesfully estimated, as well as the model formula provided.
summary(mlergm): Prints a summary of the estimated mlergm model.
vcov(mlergm): Extracts the estimated Fisher information matrix of the model from an estimated mlergm model. When the model is a canonical exponential family (i.e., no curved terms such as gwesp or gwdegree), this is equal to the variance-covariance matrix of the canonical statistics. In the case that specified model is a curved exponential family, the Fisher information matrix is a transformation of the variance-covariance matrix of the exponential family and is given by Equation (3.2) of Hunter & Handcock (Journal of Computational and Graphical Statistics, 2006, DOI: 10.1198/106186006X133069).

Functions

compute_CI(): Constructs a confidence interval at a desird significance level for an estimated parameter vector.

References

Schweinberger, M. and Stewart, J. (2019) Concentration and consistency results for canonical and curved exponential-family random graphs. The Annals of Statistics, to appear.

Schweinberger, M. and Handcock, M. S. (2015). Local dependence in random graph models: characterization, properties and statistical inference. Journal of the Royal Statistical Society: Series B (Statistical Methodology), 77(3), 647-676.

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

Hummel, R. M., Hunter, D. R., and Handcock, M. S. (2012). Improving simulation-based algorithms for fitting ERGMs. Journal of Computational and Graphical Statistics, 21(4), 920-939.

Krivitsky, P. N., Handcock, M. S., & Morris, M. (2011). Adjusting for network size and composition effects in exponential-family random graph models. Statistical methodology, 8(4), 319-339.

Krivitsky, P.N, and Kolaczyk, E. D. (2015). On the question of effective sample size in network modeling: An asymptotic inquiry. Statistical science: a review journal of the Institute of Mathematical Statistics, 30(2), 184.

Hunter D., Handcock M., Butts C., Goodreau S., and Morris M. (2008). ergm: A Package to Fit, Simulate and Diagnose Exponential-Family Models for Networks. Journal of Statistical Software, 24(3), 1-29.

Butts, C. (2016). sna: Tools for Social Network Analysis. R package version 2.4. https://CRAN.R-project.org/package=sna.

Butts, C. (2008). network: a Package for Managing Relational Data in R. Journal of Statistical Software, 24(2).

Stewart, J., Schweinberger, M., Bojanowski, M., and M. Morris (2019). Multilevel network data facilitate statistical inference for curved ERGMs with geometrically weighted terms. Social Networks, 59, 98-119.

Schweinberger, M., Krivitsky, P. N., Butts, C.T. and J. Stewart (2018). Exponential-family models of random graphs: Inference in finite-, super-, and infinite-population scenarios. https://arxiv.org/abs/1707.04800

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

Examples


### Load the school classes data-set 
data(classes) 

# Estimate a curved multilevel ergm model with offset parameter 
# Approximate run time (2 cores): 1.29m, Run time (5 cores): 1.01m
model_est <- mlergm(classes ~ edges + mutual + nodematch("sex") +  gwesp(fixed = FALSE), 
                    seed = 123, 
                    options = set_options(number_cores = 2))

# To access a summary of the fitted model, call the 'summary' function 
summary(model_est)

# Goodness-of-fit can be run by calling the 'gof.mlergm' method 
# Approximate run time (2 cores): 32.7s, Run time (5 cores): 18.4s  
gof_res <- gof(model_est, options = set_options(number_cores = 2))
plot(gof_res, cutoff = 15)

# Additional information can be obtained by setting verbose = 1,2. 
# Approximate run time (2 cores): 6.7s, Run time (5 cores): 5.6s 
model_est <- mlergm(classes ~ edges + mutual + nodematch("sex"), 
                    seed = 123, 
                    verbose = 2, 
                    options = set_options(number_cores = 2))

mlergm documentation built on June 8, 2025, 9:41 p.m.