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)

Arguments

Value

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

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.

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)

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)

Arguments

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"))

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)

Arguments

Value

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

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.

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]]

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)

Arguments

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

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.

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)

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)

Arguments

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

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.

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)

Arguments

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)

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)

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)

Arguments

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

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.

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)

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)

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).

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)

Arguments

Value

This prints a ggplot2 traceplot for the effects of interest.

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.

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"))

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)

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).