Parse an ERGM Model Object

Extracts terms, coefficients, standard errors, p-values, and term metadata from a fitted ergm object. Returns a standardized data frame for use in publication-ready tables.

Usage

parse_ergm_model(
  object,
  override = NULL,
  override.title = NULL,
  override.desc = NULL,
  override.math = NULL,
  override.figure = NULL,
  override.citation = NULL
)

Arguments

object: A fitted ergm object.
override: A named list keyed by term name, each element a named list of fields to replace, e.g. list(edges = list(title = "Density", citation = "doi:10.1234/x")). Valid fields are title, description (or desc), math, figure, and citation.
override.title, override.desc, override.math, override.figure: Named character vectors keyed by term name, e.g. override.title = c(edges = "Density"). These take precedence over override.
override.citation: A named list keyed by term name whose elements are citation specifications in the same form the YAML citation: field accepts: a bare key ("hunter2007"), a prefixed identifier ("doi:10.1016/j.socnet.2006.08.002"), a single entry list (list(key = "hunter2007", doi = "10.1016/j.socnet.2006.08.002")), or a list of such entries.

Value

A data frame with columns:

term: Character. The canonical ERGM term name.
coef_name: Character. The full coefficient name from the model.
attribute: Character or NA. The attribute(s) used in the term, comma-separated when multiple.
estimate: Numeric. The coefficient estimate.
se: Numeric. The standard error.
pvalue: Numeric. The p-value.
title: Character or NA. Short one-line label for the term.
description: Character or NA. Prose description of the term.
math: Character or NA. The LaTeX definition of the statistic.
figure: Character or NA. Path to the rendered term figure.
citation: Character or NA. Citation key(s) for the term, comma-separated when several. The corresponding bibliography is attached to the data frame as the "tabulergm_citations" attribute.

Details

The coefficient names produced by ergm (which may expand terms into multiple rows, e.g., nodefactor.race.Black) are mapped back to the canonical term names from the formula.

Metadata sources

Each metadata field is resolved from three sources, in increasing order of precedence: the ergm term database (via ergm::search.ergmTerms(), which supplies title and description), the YAML term database shipped in inst/terms/ (which may supply title, description, math, figure, and citation), and the override* arguments documented below.

Override names are matched against the term column first and against coef_name second, so an expanded coefficient such as nodefactor.race.Black can be targeted individually. Names matching no row produce a warning.

Examples

library(ergm)
fit <- readRDS(system.file("fits", "fit_nodematch.rds", package = "tabulergm"))
parse_ergm_model(fit)
#> Warning: This object was fit with ‘ergm’ version 4.9.0 or earlier. Summarizing it with version 4.10 or later may return incorrect results or fail.
#>        term       coef_name attribute   estimate        se    pvalue
#> 1     edges           edges      <NA> -0.5753641 0.4166666 0.1673176
#> 2 nodematch nodematch.group     group -0.2719337 0.6416426 0.6717053
#>               title
#> 1   Number of edges
#> 2 Uniform homophily
#>                                                                                                                                                                                                   description
#> 1                                                                       Counts the ties present in the network. Acts as the baseline density term, playing the role an intercept plays in a regression model.
#> 2 Counts the ties joining nodes that share the same value of a categorical attribute, the standard measure of homophily. Setting diff = TRUE adds one statistic per attribute value (differential homophily).
#>                                        math
#> 1                        \\sum_{i<j} y_{ij}
#> 2 \\sum_{i<j} y_{ij} \\mathbf{1}(x_i = x_j)
#>                                                                                                         figure
#> 1 /tmp/RtmpQpSy5d/tabulergm-83bf88159c17a513202a912d589a0254-b6f3c9a3a81099857159db04549de0da-0-undirected.png
#> 2 /tmp/RtmpQpSy5d/tabulergm-a673ab51cffbb0c78cac452d4b806b45-b6f3c9a3a81099857159db04549de0da-0-undirected.png
#>        citation
#> 1          <NA>
#> 2 mcpherson2001

# Replace the title and description of a single term
parse_ergm_model(
  fit,
  override.title = c(edges = "Density"),
  override.desc  = c(edges = "Baseline propensity to form ties.")
)
#> Warning: This object was fit with ‘ergm’ version 4.9.0 or earlier. Summarizing it with version 4.10 or later may return incorrect results or fail.
#>        term       coef_name attribute   estimate        se    pvalue
#> 1     edges           edges      <NA> -0.5753641 0.4166666 0.1673176
#> 2 nodematch nodematch.group     group -0.2719337 0.6416426 0.6717053
#>               title
#> 1           Density
#> 2 Uniform homophily
#>                                                                                                                                                                                                   description
#> 1                                                                                                                                                                           Baseline propensity to form ties.
#> 2 Counts the ties joining nodes that share the same value of a categorical attribute, the standard measure of homophily. Setting diff = TRUE adds one statistic per attribute value (differential homophily).
#>                                        math
#> 1                        \\sum_{i<j} y_{ij}
#> 2 \\sum_{i<j} y_{ij} \\mathbf{1}(x_i = x_j)
#>                                                                                                         figure
#> 1 /tmp/RtmpQpSy5d/tabulergm-83bf88159c17a513202a912d589a0254-b6f3c9a3a81099857159db04549de0da-0-undirected.png
#> 2 /tmp/RtmpQpSy5d/tabulergm-a673ab51cffbb0c78cac452d4b806b45-b6f3c9a3a81099857159db04549de0da-0-undirected.png
#>        citation
#> 1          <NA>
#> 2 mcpherson2001