ergm: gof – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

gof

Conduct Goodness-of-Fit Diagnostics on a Exponential Family Random Graph Model

Description

gof calculates p-values for geodesic distance, degree, and reachability summaries to diagnose the goodness-of-fit of exponential family random graph models. See ergm for more information on these models.

Usage

gof(object, ...)

## S3 method for class 'ergm'
gof(
  object,
  ...,
  coef = NULL,
  GOF = NULL,
  constraints = NULL,
  control = control.gof.ergm(),
  verbose = FALSE
)

## S3 method for class 'formula'
gof(
  object,
  ...,
  coef = NULL,
  GOF = NULL,
  constraints = ~.,
  control = NULL,
  unconditional = TRUE,
  verbose = FALSE
)

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

## S3 method for class 'gof'
plot(
  x,
  ...,
  cex.axis = 0.7,
  plotlogodds = FALSE,
  main = "Goodness-of-fit diagnostics",
  normalize.reachability = FALSE,
  verbose = FALSE
)

Arguments

`object`	Either a formula or an `ergm` object. See documentation for `ergm`.
`...`	Additional arguments, to be passed to lower-level functions.
`coef`	When given either a formula or an object of class ergm, `coef` are the parameters from which the sample is drawn. By default set to a vector of 0.
`GOF`	formula; an formula object, of the form `~ <model terms>` specifying the statistics to use to diagnosis the goodness-of-fit of the model. They do not need to be in the model formula specified in `formula`, and typically are not. Currently supported terms are the degree distribution (“degree” for undirected graphs, or “idegree” and/or “odegree” for directed graphs), geodesic distances (“distance”), shared partner distributions (“espartners” and “dspartners”), the triad census (“triadcensus”), and the terms of the original model (“model”). The default formula for undirected networks is `~ degree + espartners + distance + model`, and the default formula for directed networks is `~ idegree + odegree + espartners + distance + model`. By default a “model” term is added to the formula. It is a very useful overall validity check and a reminder of the statistical variation in the estimates of the mean value parameters. To omit the “model” term, add “- model” to the formula.
`constraints`	A one-sided formula specifying one or more constraints on the support of the distribution of the networks being modeled. See the help for similarly-named argument in `ergm` for more information. For `gof.formula`, defaults to unconstrained. For `gof.ergm`, defaults to the constraints with which `object` was fitted.
`control`	A list to control parameters, constructed using `control.gof.formula` or `control.gof.ergm` (which have different defaults).
`verbose`	Provide verbose information on the progress of the simulation.
`unconditional`	logical; if `TRUE`, the simulation is unconditional on the observed dyads. if not `TRUE`, the simulation is conditional on the observed dyads. This is primarily used internally when the network has missing data and a conditional GoF is produced.
`x`	an object of class `gof` for printing or plotting.
`cex.axis`	Character expansion of the axis labels relative to that for the plot.
`plotlogodds`	Plot the odds of a dyad having given characteristics (e.g., reachability, minimum geodesic distance, shared partners). This is an alternative to the probability of a dyad having the same property.
`main`	Title for the goodness-of-fit plots.
`normalize.reachability`	Should the reachability proportion be normalized to make it more comparable with the other geodesic distance proportions.

Details

A sample of graphs is randomly drawn from the specified model. The first argument is typically the output of a call to ergm and the model used for that call is the one fit.

For GOF = ~model, the model's observed sufficient statistics are plotted as quantiles of the simulated sample. In a good fit, the observed statistics should be near the sample median (0.5).

By default, the sample consists of 100 simulated networks, but this sample size (and many other settings) can be changed using the control argument described above.

Value

gof, gof.ergm, and gof.formula return an object of class gof.ergm, which inherits from class gof. This is a list of the tables of statistics and p-values. This is typically plotted using plot.gof.

Methods (by class)

ergm: Perform simulation to evaluate goodness-of-fit for a specific ergm() fit.
formula: Perform simulation to evaluate goodness-of-fit for a model configuration specified by a formula, coefficient, constraints, and other settings.
gof: print.gof summaries the diagnostics such as the degree distribution, geodesic distances, shared partner distributions, and reachability for the goodness-of-fit of exponential family random graph models. See ergm for more information on these models. (summary.gof is a deprecated alias that may be repurposed in the future.)
gof: plot.gof plots diagnostics such as the degree distribution, geodesic distances, shared partner distributions, and reachability for the goodness-of-fit of exponential family random graph models. See ergm for more information on these models.

Note

For gof.ergm and gof.formula, default behavior depends on the directedness of the network involved; if undirected then degree, espartners, and distance are used as default properties to examine. If the network in question is directed, “degree” in the above is replaced by idegree and odegree.

Examples

data(florentine)
gest <- ergm(flomarriage ~ edges + kstar(2))
gest
summary(gest)

# test the gof.ergm function
gofflo <- gof(gest)
gofflo

# Plot all three on the same page
# with nice margins
par(mfrow=c(1,3))
par(oma=c(0.5,2,1,0.5))
plot(gofflo)

# And now the log-odds
plot(gofflo, plotlogodds=TRUE)

# Use the formula version of gof
gofflo2 <-gof(flomarriage ~ edges + kstar(2), coef=c(-1.6339, 0.0049))
plot(gofflo2)

ergm

Fit, Simulate and Diagnose Exponential-Family Models for Networks

v3.11.0

GPL-3 + file LICENSE

Authors

Mark S. Handcock [aut], David R. Hunter [aut], Carter T. Butts [aut], Steven M. Goodreau [aut], Pavel N. Krivitsky [aut, cre] (<https://orcid.org/0000-0002-9101-3362>), Martina Morris [aut], Li Wang [ctb], Kirk Li [ctb], Skye Bender-deMoll [ctb], Chad Klumb [ctb], Michał Bojanowski [ctb], Ben Bolker [ctb]

Initial release

2020-10-14

gof