Package 'fergm' reference manual

Title:	Estimation and Fit Assessment of Frailty Exponential Random Graph Models
Description:	Frailty Exponential Random Graph Models estimated through pseudo likelihood with frailty terms estimated using 'Stan' as per Box-Steffensmeier et. al (2017) <doi:10.7910/DVN/K3D1M2>. Goodness of fit for Frailty Exponential Random Graph Models is also available, with easy visualizations for comparison to fit Exponential Random Graph Models.
Authors:	Jason W. Morgan [aut], Benjamin W. Campbell [aut, cre], Dino P. Christenson [aut], Janet M. Box-Steffensmeier [aut]
Maintainer:	Benjamin W. Campbell <[email protected]>
License:	GPL-3
Version:	1.1.5
Built:	2024-10-27 04:05:39 UTC
Source:	https://github.com/benjamin-w-campbell/fergm

Clean posterior description of FERGM.

Description

This function takes a stan object and return a clean summary of the posterior distribution.

Usage

clean_summary(fergm.fit = NULL, custom_var_names = NULL)
clean_summary(fergm.fit = NULL, custom_var_names = NULL)

Arguments

`fergm.fit`	A model object returned by the `fergm` function. Must be specified.
`custom_var_names`	A vector of custom variable names used in presentation that match the order of the `form` object passed to `fergm`. If not provided, defaults to names inherited by `fergm.fit`.

Value

This function returns a matrix summarizing the posterior distribution, including variable names, posterior means, and 95

References

Stan Development Team (2016). RStan: the R interface to Stan. R package version 2.14.1. http://mc-stan.org/.

Examples

## Not run: 
# The fergm.fit$stan.fit object is of class stanfit.
   # We keep it this way such that users can rely upon
   # conventional stan functions for interpretation
   # getting posterior distributions from the fergm

   # Conventional rstan summary call

 # load example data
data("ergm.fit")
data("fergm.fit")
data("mesa")
stan.smry <- summary(fergm.fit$stan.fit)$summary
beta_df <- stan.smry[grep("beta", rownames(stan.smry)),]
est <- round(beta_df[,c(1,4,8)], 3)

  # We have a built in function to do this simply
est <- clean_summary(fergm.fit)
est <- clean_summary(fergm.fit,
custom_var_names = c("Edges", "Sex Homophily", "Grade Homophily",
"Race Homophily", "GWESP", "Alternating K-Stars"))

## End(Not run)
## Not run: 
# The fergm.fit$stan.fit object is of class stanfit.
   # We keep it this way such that users can rely upon
   # conventional stan functions for interpretation
   # getting posterior distributions from the fergm

   # Conventional rstan summary call

 # load example data
data("ergm.fit")
data("fergm.fit")
data("mesa")
stan.smry <- summary(fergm.fit$stan.fit)$summary
beta_df <- stan.smry[grep("beta", rownames(stan.smry)),]
est <- round(beta_df[,c(1,4,8)], 3)

  # We have a built in function to do this simply
est <- clean_summary(fergm.fit)
est <- clean_summary(fergm.fit,
custom_var_names = c("Edges", "Sex Homophily", "Grade Homophily",
"Race Homophily", "GWESP", "Alternating K-Stars"))

## End(Not run)

Plots the coefficients of FERGM and ERGM objects.

Description

This function allows the users to visualize FERGM estimates or to compare the coefficients of ERGMs and FERGMs.

Usage

coef_plot(fergm.fit = NULL, ergm.fit = NULL, custom_var_names = NULL)
coef_plot(fergm.fit = NULL, ergm.fit = NULL, custom_var_names = NULL)

Arguments

`fergm.fit`	A model object returned by the `fergm` function. Must be specified.
`ergm.fit`	A model object returned by the `ergm` function. May be specified when comparing ERGM and FERGM coefficients.
`custom_var_names`	A vector of custom variable names used in presentation that match the order of the `form` object passed to `fergm`. If not provided, defaults to names inherited by `fergm.fit`.

Value

This function produces a coefficient rope-ladder plot containing 95% confidence intervals using ggplot2. The function either takes fergm model output or fergm and ergm model output. The former is effective in summarizing fergm model output while the latter is effective in comparing FERGM and ERGM estimates.

References

Box-Steffensmeier, Janet M., Dino P. Christenson, and Jason W. Morgan. 2018. “Modeling Unobserved Heterogeneity in Social Networks with the Frailty Exponential Random Graph Model." Political Analysis. (26)1:3-19.references Box-Steffensmeier, Janet M., Dino P. Christenson, and Jason W. Morgan. 2017. “Modeling Unobserved Heterogeneity in Social Networks with the Frailty Exponential Random Graph Model." Political Analysis.

Stan Development Team (2016). RStan: the R interface to Stan. R package version 2.14.1. http://mc-stan.org/.

Examples

# load example data
data("ergm.fit")
data("fergm.fit")
data("mesa")
# Compare substantive implications via coef plot, these are with 95% credible intervals
coef_plot(fergm.fit = fergm.fit, ergm.fit = ergm.fit,
custom_var_names =  c("Edges", "Sex Homophily", "Grade Homophily",
"Race Homophily", "GWESP", "Alternating K-Stars"))
coef_plot(fergm.fit = fergm.fit,
custom_var_names =  c("Edges", "Sex Homophily", "Grade Homophily",
"Race Homophily", "GWESP", "Alternating K-Stars"))
# load example data
data("ergm.fit")
data("fergm.fit")
data("mesa")
# Compare substantive implications via coef plot, these are with 95% credible intervals
coef_plot(fergm.fit = fergm.fit, ergm.fit = ergm.fit,
custom_var_names =  c("Edges", "Sex Homophily", "Grade Homophily",
"Race Homophily", "GWESP", "Alternating K-Stars"))
coef_plot(fergm.fit = fergm.fit,
custom_var_names =  c("Edges", "Sex Homophily", "Grade Homophily",
"Race Homophily", "GWESP", "Alternating K-Stars"))

Plots the posterior density for FERGM model terms.

Description

This function allows the users to examine the posterior density of FERGM model terms.

Usage

coef_posterior_density(fergm.fit = NULL, custom_var_names = NULL)
coef_posterior_density(fergm.fit = NULL, custom_var_names = NULL)

Arguments

`fergm.fit`	A model object returned by the `fergm` function. Must be specified.
`custom_var_names`	A vector of custom variable names used in presentation that match the order of the `form` object passed to `fergm`. If not provided, defaults to names inherited by `fergm.fit`.

Value

This prints a list of posterior density plots produced using ggplot2.

References

Stan Development Team (2016). RStan: the R interface to Stan. R package version 2.14.1. http://mc-stan.org/.

Examples

# load example data
data("ergm.fit")
data("fergm.fit")
data("mesa")

# rstan functions
# Histogram of the posterior
rstan::stan_hist(fergm.fit$stan.fit, par = "beta")
# Density of the posteriors
rstan::stan_dens(fergm.fit$stan.fit, par = "beta")

# We have a cleaner function to look at the posterior densities
densities <- coef_posterior_density(fergm.fit = fergm.fit,
custom_var_names = c("Edges", "Sex Homophily", "Grade Homophily", "Race Homophily",
"GWESP", "Alternating K-Stars"))
densities[[1]]
densities[[2]]
# load example data
data("ergm.fit")
data("fergm.fit")
data("mesa")

# rstan functions
# Histogram of the posterior
rstan::stan_hist(fergm.fit$stan.fit, par = "beta")
# Density of the posteriors
rstan::stan_dens(fergm.fit$stan.fit, par = "beta")

# We have a cleaner function to look at the posterior densities
densities <- coef_posterior_density(fergm.fit = fergm.fit,
custom_var_names = c("Edges", "Sex Homophily", "Grade Homophily", "Race Homophily",
"GWESP", "Alternating K-Stars"))
densities[[1]]
densities[[2]]

Compare predictions of ERGM to FERGM.

Description

This function allows you to assess the importance of the frailty term in prediction by comparing the predictive accuracy of an ERGM to an FERGM. Note: Prior to estimating this function, ensure the network object of interest is saved to the global environment and named "net."

Usage

compare_predictions(ergm.fit = NULL, fergm.fit = NULL, seed = NULL,
  replications = 500)
compare_predictions(ergm.fit = NULL, fergm.fit = NULL, seed = NULL,
  replications = 500)

Arguments

`ergm.fit`	A model object returned by the `ergm` function. Must be specified.
`fergm.fit`	A model object returned by the `fergm` function. Must be specified.
`seed`	An integer that sets the seed for the random number generator to assist in replication. Defaults to a null value for no seed setting.
`replications`	The number of networks to be simulated to assess predictions. Defaults to 500.

Value

The compare_predictions function returns a matrix reflecting the number of correctly predicted ties for the ERGM and FERGM for each network simulated.

References

Stan Development Team (2016). RStan: the R interface to Stan. R package version 2.14.1. http://mc-stan.org/.

Examples

# load example data
library(fergm)
data("ergm.fit")
data("fergm.fit")

# Use built in compare_predictions function to compare predictions of ERGM and FERGM,
# few replications due to example
# Make sure "net" is an object defined in the global environment.
net <- ergm.fit$network
predict_out <- compare_predictions(ergm.fit = ergm.fit, fergm.fit = fergm.fit,
                                   replications = 10, seed=12345)

# Use the built in compare_predictions_plot function to examine the densities of
#  correctly predicted ties from the compare_predictions simulations
compare_predictions_plot(predict_out)

# We can also conduct a KS test to determine if the FERGM fit
     # it statistically disginguishable from the ERGM fit
compare_predictions_test(predict_out)
# load example data
library(fergm)
data("ergm.fit")
data("fergm.fit")

# Use built in compare_predictions function to compare predictions of ERGM and FERGM,
# few replications due to example
# Make sure "net" is an object defined in the global environment.
net <- ergm.fit$network
predict_out <- compare_predictions(ergm.fit = ergm.fit, fergm.fit = fergm.fit,
                                   replications = 10, seed=12345)

# Use the built in compare_predictions_plot function to examine the densities of
#  correctly predicted ties from the compare_predictions simulations
compare_predictions_plot(predict_out)

# We can also conduct a KS test to determine if the FERGM fit
     # it statistically disginguishable from the ERGM fit
compare_predictions_test(predict_out)

Compare FERGM to ERGM predictions via plot. This is a plot function to compare the distributions of predictions from `ergm` and `fergm` objects.

Description

Compare FERGM to ERGM predictions via plot. This is a plot function to compare the distributions of predictions from ergm and fergm objects.

Usage

compare_predictions_plot(compare_predictions_out = NULL)
compare_predictions_plot(compare_predictions_out = NULL)

Arguments

compare_predictions_out

Matrix of correctly predicted ties produced by the compare_predictions function.

Value

The compare_predictions_plot function returns a ggplot2 plot of the density of the percent of correctly predicted ties simulated by the compare_predictions function.

References

Stan Development Team (2016). RStan: the R interface to Stan. R package version 2.14.1. http://mc-stan.org/.

KS Test for Difference in Predictive Performance

Description

This is a plot function to determine whether the distributions of predictions from ERGM and FERGM objects differ. It does so by using a Kolmogorov-Smirnov Test.

Usage

compare_predictions_test(compare_predictions_out = NULL, alpha_level = 0.05)
compare_predictions_test(compare_predictions_out = NULL, alpha_level = 0.05)

Arguments

`compare_predictions_out`	Matrix of correctly predicted ties produced by the `compare_predictions` function.
`alpha_level`	The significance level that should be used for the test.

Value

Returns ks.test output to determine if the percent of correctly predicted ERGM ties are less than those of the FERGM and prints a message to assist with interpretation

Examples

# load example data
data("ergm.fit")
data("fergm.fit")
data("mesa")
# Use built in compare_predictions function to compare predictions of ERGM and FERGM,
# few replications due to example
 net <- ergm.fit$network
predict_out <- compare_predictions(ergm.fit = ergm.fit, fergm.fit = fergm.fit,
                                   replications = 10, seed = 12345)

# We can also conduct a KS test to determine if the FERGM fit it statistically
 # distinguishable from the ERGM fit
compare_predictions_test(predict_out)
# load example data
data("ergm.fit")
data("fergm.fit")
data("mesa")
# Use built in compare_predictions function to compare predictions of ERGM and FERGM,
# few replications due to example
 net <- ergm.fit$network
predict_out <- compare_predictions(ergm.fit = ergm.fit, fergm.fit = fergm.fit,
                                   replications = 10, seed = 12345)

# We can also conduct a KS test to determine if the FERGM fit it statistically
 # distinguishable from the ERGM fit
compare_predictions_test(predict_out)

Output from an Exponential Random Graph Model fit on the Mesa High Network (Hunter et. al, 2008).

Description

This is the output of a call to the ergm function fit with with an edge term, sex, grade, and race homophily, GWESP, and alternating k-stars. Fit according to the vignette "mesaHighVignette".

Usage

data(ergm.fit)
data(ergm.fit)

Format

An object of class "ergm"

References

Hunter et al. (2008) ergm: A package to fit, simulate and diagnose exponential-family models for networks. Journal of Statistical Software 24(3).

Estimation of Frailty Exponential Random Graph Model (FERGM) via MPLE using Stan

Description

This function estimates a FERGM

Usage

fergm(net = NULL, form = NULL, seed = 12345, chains = 4, warmup = 100,
  iter = 600, cores = 1)
fergm(net = NULL, form = NULL, seed = 12345, chains = 4, warmup = 100,
  iter = 600, cores = 1)

Arguments

`net`	A network object that is to be explained using the right_hand_vars argument.
`form`	A character string specified as "ergm.term1 + ergm.term2", must be terms supported for ERGMs.
`seed`	An integer that sets the seed for the random number generator to assist in replication. Defaults to 12345. Set to null to prevent internal seed setting.
`chains`	An integer that sets the number of Markov chains that should be used by Stan.
`warmup`	The number of warm up or burn-in iterations that should be used before posterior draws are taken. Defaults to 100.
`iter`	The number of total number of samples that should be taken including warm ups Defaults to 600 total iterations, leading to a posterior sample size of 500.
`cores`	The number of cores to used should parallel processing be desired. Defaults to 1.

Value

This function returns a list that includes the Stan output (stan.fit), the data object passed to Stan (stan.dta), and the original formula (form).

References

Stan Development Team (2016). RStan: the R interface to Stan. R package version 2.14.1. http://mc-stan.org/.

Examples

## Not run: 
set.seed(1)

data("faux.mesa.high")

mesa <- faux.mesa.high

mesa.fit <- ergm::ergm(mesa ~ edges +
                  nodematch('Sex') +
                  nodematch('Grade', diff = FALSE) +
                  nodematch('Race', diff = FALSE) +
                  gwesp(decay = 0.2, fixed = TRUE) +
                  altkstar(lambda = 0.6, fixed = TRUE))

library(fergm)
form <- c("edges + nodematch('Sex') + nodematch('Grade', diff = FALSE) +
          nodematch('Race', diff = FALSE) +
          gwesp(decay = 0.2, fixed = TRUE) + altkstar(lambda = 0.6, fixed = TRUE)")

fergm.fit <- fergm(net = mesa, form = form, chains = 2)

## End(Not run)
## Not run: 
set.seed(1)

data("faux.mesa.high")

mesa <- faux.mesa.high

mesa.fit <- ergm::ergm(mesa ~ edges +
                  nodematch('Sex') +
                  nodematch('Grade', diff = FALSE) +
                  nodematch('Race', diff = FALSE) +
                  gwesp(decay = 0.2, fixed = TRUE) +
                  altkstar(lambda = 0.6, fixed = TRUE))

library(fergm)
form <- c("edges + nodematch('Sex') + nodematch('Grade', diff = FALSE) +
          nodematch('Race', diff = FALSE) +
          gwesp(decay = 0.2, fixed = TRUE) + altkstar(lambda = 0.6, fixed = TRUE)")

fergm.fit <- fergm(net = mesa, form = form, chains = 2)

## End(Not run)

Plot traceplots for model terms.

Description

This function takes a fergm object and plots the time series of each chain per model term using ggplot2.

Usage

fergm_beta_traceplot(fergm.fit = NULL, custom_var_names = NULL)
fergm_beta_traceplot(fergm.fit = NULL, custom_var_names = NULL)

Arguments

`fergm.fit`	A model object returned by the `fergm` function. Must be specified.
`custom_var_names`	A vector of custom variable names used in presentation that match the order of the `form` object passed to `fergm`. If not provided, defaults to names inherited by `fergm.fit`.

Value

This prints a ggplot2 traceplot for the effects of interest.

References

Stan Development Team (2016). RStan: the R interface to Stan. R package version 2.14.1. http://mc-stan.org/.

Examples

# load example data
data("ergm.fit")
data("fergm.fit")
data("mesa")
# Use rstan's built in traceplot function
trace <- rstan::traceplot(fergm.fit$stan.fit, pars = "beta")
trace

# We have our own version that includes variable names and tidies it up a bit
fergm_beta_traceplot(fergm.fit,
                    custom_var_names =  c("Edges", "Sex Homophily",
                    "Grade Homophily", "Race Homophily", "GWESP", "Alternating K-Stars"))
# load example data
data("ergm.fit")
data("fergm.fit")
data("mesa")
# Use rstan's built in traceplot function
trace <- rstan::traceplot(fergm.fit$stan.fit, pars = "beta")
trace

# We have our own version that includes variable names and tidies it up a bit
fergm_beta_traceplot(fergm.fit,
                    custom_var_names =  c("Edges", "Sex Homophily",
                    "Grade Homophily", "Race Homophily", "GWESP", "Alternating K-Stars"))

Output from a Frailty Exponential Random Graph Model fit on the Mesa High Network (Hunter et. al, 2008)

Description

This is the output of a call to the ergm function fit with with an edge term, sex, grade, and race homophily, GWESP, and alternating k-stars. Fit according to "mesaHighVignette".

Usage

data(fergm.fit)
data(fergm.fit)

Format

A list containing an object of class "stan.fit"

References

Hunter et al. (2008) ergm: A package to fit, simulate and diagnose exponential-family models for networks. Journal of Statistical Software 24(3).

Mesa High Network (Hunter et. al, 2008).

Description

This is a network included in Hunter et al. (2008) that represents a simulated in-school friendship network.

Usage

data(mesa)
data(mesa)

Format

An object of class "network"

References

Hunter et al. (2008) ergm: A package to fit, simulate and diagnose exponential-family models for networks. Journal of Statistical Software 24(3).

Package 'fergm'

Help Index

Clean posterior description of FERGM.

Description

Usage

Arguments

Value

References

Examples

Plots the coefficients of FERGM and ERGM objects.

Description

Usage

Arguments

Value

References

Examples

Plots the posterior density for FERGM model terms.

Description

Usage

Arguments

Value

References

Examples

Compare predictions of ERGM to FERGM.

Description

Usage

Arguments

Value

References

Examples

Compare FERGM to ERGM predictions via plot. This is a plot function to compare the distributions of predictions from ergm and fergm objects.

Description

Usage

Arguments

Value

References

KS Test for Difference in Predictive Performance

Description

Usage

Arguments

Value

Examples

Output from an Exponential Random Graph Model fit on the Mesa High Network (Hunter et. al, 2008).

Description

Usage

Format

References

Estimation of Frailty Exponential Random Graph Model (FERGM) via MPLE using Stan

Description

Usage

Arguments

Value

References

Examples

Plot traceplots for model terms.

Description

Usage

Arguments

Value

References

Examples

Output from a Frailty Exponential Random Graph Model fit on the Mesa High Network (Hunter et. al, 2008)

Description

Usage

Format

References

Mesa High Network (Hunter et. al, 2008).

Description

Usage

Format

References

Compare FERGM to ERGM predictions via plot. This is a plot function to compare the distributions of predictions from `ergm` and `fergm` objects.