Basic Usage
We begin by loading in some example network data. In our case, these data are (logged) aggregate public and private lending volumes between 17 large countries from 2005. The data are included in the GERGM package and were used in the Wilson et. al. study listed at the beginning of this vignette. In addition to the network (a square matrix) we are also going to load in some node-level covariate data, and a network covariate: the normalized net exports between these countries in 2005. WE will make use of this data in fitting our example GERGM model.
The GERGM package provides a plot_network() function, which we can use to visualize the network as follows:
library(GERGM)
set.seed(12345)
data("lending_2005")
data("covariate_data_2005")
data("net_exports_2005")
plot_network(lending_2005) 
Alternatively, if we prefer a white background, and no legend, we can select options for this as well. Typing ?plot_network into the console will pull up a manual for this function.
Having plotted the raw network data, we can now proceed to model it using the gergm() function. Detailed documentation for this function (along with a large number of advanced options) can be accessed by typing ?gergm into the console. We are going to focus on a simpler version of the application from the Wilson et. al. paper, that will highlight creating a formula object with node and network level covariates, as well as endogenous (network) effects. While this model will not provide a perfect fit to the data, it serves to illustrate a number of key concepts. If we look at the first couple of rows of the covariate_data_2005 object, we can see that it include information about each country’s log GDP and whether it was a member of the G8.
head(covariate_data_2005)## GDP log_GDP G8
## ARG 2.229108e+11 26.13004 No
## AUS 6.933386e+11 27.26478 No
## BRA 8.921068e+11 27.51685 No
## CAN 1.164144e+12 27.78301 Yes
## PRC 2.268594e+12 28.45018 No
## FRA 2.203679e+12 28.42115 YesTo model this network, we are gong to include an edges term, which functions similarly to an intercept term in a regression model and parameterizes the density of the network. We are also going to include sender and receiver effects for a country’s GDP. These effects are designed to capture the effects of having a large economy on the amount of lending a borrowing a country does. We are also going to include a Nodemix term to capture the propensity for members and non-members of the G8 to lend to each other, compared to the base case of non-G8 to non-G8 member lending. The final covariate effect we are going to include in the model is a netcov, or network covariate term, capturing the effect of the structure of the international trade network on the international lending network. Finally, we are going to include one endogenous statistic in the model, to capture the degree of reciprocal lending in the network. For this endogenous statistic, we are also going to include an exponential down-weight. this means that when the value of the network statistic is calculated, it will then be raised to the power of (in this case) 0.8. This will have the effect of reducing its value, but more importantly of smoothing out statistic values as the GERGM parameter controlling the propensity for mutual dyads in the network carries. Practically, this can make it easier to get starting values for the mutual dyads parameter that are in the right ball park, aiding in the estimation process. The formula object is defined below:
formula <- lending_2005 ~ edges + mutual(alpha = 0.8) + sender("log_GDP") +
receiver("log_GDP") + nodemix("G8", base = "No") + netcov(net_exports_2005) Note that the terms used in GERGM formulas are analogous to those used in the ergm package, and are documented in greater detail in the ?gergm help file.
If you are interested in experimenting, try setting alpha = 1 and rerunning the model. You will see lots of error messages, and output indicating that your parameter estimates have zoomed off to infinity. If you are familiar with ERGMs (for binary network data), you may have heard of an issue these models can run into called “degeneracy”, which can make certain models impossible to estimate. In this particular example, as with all GERGM specifications we have tried so far, the GERGM does not seem to suffer from this issue. However, as the experiment described above can attest, GERGMs can still be difficult to estimate. This is primarily due to challenges in getting good starting values for our model parameters. The current implementation of the GERGM software does so using maximum pseudo likelihood (MPLE), which does a pretty good job in many cases. However, in some cases, such as the example here, it can be enough off the mark that the initial parameter guesses from MPLE simulate networks that look a lot different from the observed network. This can cause the optimizer in R (which is used to update our estimates of the model parameters) to zoom off to infinity.
If this happens to you, do not (immediately) panic! This usually means you are dealing with a tricky network, or a tricky specification (typically one with lots of endogenous statistics included). The first thing to do is try to use alpha weighting. A good rule of thumb is to set alpha = 0.8 for all of the endogenous statistics included in the model. Note that these currently include: out2stars, in2stars, ctriads, mutual, and ttriads (or just twostars and ttriads if your network is undirected). If this does not work, you can try cranking down the weights to around 0.5. If this still does not work, you will need to explore the theta_grid_optimization_list option in the gergm documentation, which should always work if given enough time (although this could be weeks, depending on how complex your model is). A fuller example is provided at the end of this vignette.
Having addressed the challenges that come with estimating a GERGM model, lets try and example!
test <- gergm(formula,
covariate_data = covariate_data_2005,
number_of_networks_to_simulate = 40000,
thin = 1/100,
proposal_variance = 0.05,
MCMC_burnin = 10000,
seed = 456,
convergence_tolerance = 0.5)
The output displayed in this vignette only includes diagnostic plots, and not all of the information that would be spit out by the gergm() function if you were to run this code on your computer. All of that output is meant to help you track the estimation process (which can take days or weeks for larger networks), and diagnose issues with the estimation. Note that if you wish to tweak some of the parameters in the diagnostic and estimate plots, you may do so and regenerate the plots after estimation is complete using the following functions:
# Generate Estimate Plot
Estimate_Plot(test)
# Generate GOF Plot
GOF(test)
# Generate Trace Plot
Trace_Plot(test)In particular, we might want to make a nicer looking estimate plot. We can do this using the following block of code, where we leave out the intercept estimate, and provide a custom list of parameter names to produce a publication quality plot:
Estimate_Plot(test,
coefficients_to_plot = "both",
coefficient_names = c("Mutual Dyads",
"log(GDP) Sender",
"log(GDP) Receiver",
"Non-G8 Sender, G8 Receiver",
"G8 Sender, Non-G8 Receiver",
"G8 Sender, G8 Receiver",
"intercept",
"Normalized Net Exports",
"Dispersion Parameter"),
leave_out_coefficients = "intercept")
In order to verify the claim made earlier in this vignette that the current model is not degenerate, just hard to fit, we can generate a hysteresis plot for this model using the hysteresis() function. This function simulates large numbers of networks at parameter values around the estimated parameter values and plots the mean network density at each of these values to examine whether the model becomes degenerate due to small deviations in the parameter estimates. See the following reference for details:
- Snijders, Tom AB, et al. “New specifications for exponential random graph models.” Sociological methodology 36.1 (2006): 99-153.
So long as we see a smooth upward sloping series of points, we have strong evidence that the specification is not degenerate.
# Generate Hysteresis plots for all structural parameter estimates
hysteresis_results <- hysteresis(test,
networks_to_simulate = 1000,
burnin = 300,
range = 8,
steps = 20,
simulation_method = "Metropolis",
proposal_variance = 0.05)
As we can see this specification does not display signs of degeneracy, even though we needed to use exponential down-weighting in order to fit the model.
Edge Prediction
Following on from the example above, we can also predict individual edge values, conditioning on the rest of the observed edges and estimated parameters. We can then calculate the mean edgewise mean squared error (MSE) for these predictions, and compare it against the MSE from a null model with no parameters included. First we generate the conditional edge predictions:
test2 <- conditional_edge_prediction(
GERGM_Object = test,
number_of_networks_to_simulate = 100,
thin = 1,
proposal_variance = 0.05,
MCMC_burnin = 100,
seed = 123)Next we can calculate the MSE of these predictions and compare it to the null model predictions.
MSE_results <- conditional_edge_prediction_MSE(test2)## Mean MSE for Predicted Edge Values: 8099.79
## Mean MSE for Max Ent Predicted Edge Values: 42927.12
## This represents a 81.13 percent reduction in the average edgewise MSE when using the GERGM model.As we can see, this model does significantly better in terms of conditional edgewise predictive performance than the null model.
Correlation Matrix Estimation Functionality
The GERGM development team has recently added functionality to estimate GERGMs on correlation matrices, as well as simulation functionality. The GERGM can therefore be used both to assess the structural properties of correlation matrices, but also as an infinitely flexible prior for correlation matrices. To access the this functionality, set the optional argument beta_correlation_model = TRUE. Covariate effects are modeled using a Beta regression and then the correlation matrix is transformed onto an unconstrained space of matrices on [0,1], where stadard GERGM modeling takes place. The resulting simulated networks can then be transformed back onto the correlation space. Correlation matrix estimation functionality is the same as with other undirected networks. More information on this model will be made available in mid 2017 with the publication of a paper that is now under review. Please contact the package maintainer with further questions.
set.seed(12345)
# Function to generating a random positive-definite matrix with user-specified
# positive eigenvalues. If eigenvalues are not specified, they are generated
# from a uniform distribution.
Posdef <- function (n, ev = runif(n, 0, 10)) {
Z <- matrix(ncol=n, rnorm(n^2))
decomp <- qr(Z)
Q <- qr.Q(decomp)
R <- qr.R(decomp)
d <- diag(R)
ph <- d / abs(d)
O <- Q %*% diag(ph)
Z <- t(O) %*% diag(ev) %*% O
return(Z)
}
# Generate eignevalues
x <- rnorm(10)
# generate a positive definite matrix
pdmat <- Posdef(n = 10)
# transform to correlations
correlations <- pdmat / max(abs(pdmat))
diag(correlations) <- 1
net <- (correlations + t(correlations)) / 2
# add in node names
colnames(net) <- rownames(net) <- letters[1:10]
# correlation GERGM specification
formula <- net ~ edges + ttriads
# model should run in under a minute
test <- gergm(formula,
estimation_method = "Metropolis",
number_of_networks_to_simulate = 100000,
thin = 1/100,
proposal_variance = 0.2,
MCMC_burnin = 100000,
seed = 456,
convergence_tolerance = 0.5,
beta_correlation_model = TRUE)