Skip to contents

Generate a Publication-Ready Table from an ERGM Object

Source: R/tabulergm_table.R
tabulergm_table.Rd

S3 generic that dispatches to methods for fitted ergm objects or plain formula objects, calling the internal parsing engine and returning a formatted table.

Usage

tabulergm_table(object, ...)

# S3 method for class 'ergm'
tabulergm_table(
  object,
  include_description = FALSE,
  include_math = FALSE,
  include_attribute = FALSE,
  include_title = FALSE,
  digits = 2L,
  format = c("data.frame", "html", "markdown"),
  figures_dir = NULL,
  override = NULL,
  override.title = NULL,
  override.desc = NULL,
  override.math = NULL,
  override.figure = NULL,
  override.citation = NULL,
  ...
)

# S3 method for class 'formula'
tabulergm_table(
  object,
  format = c("data.frame", "html", "markdown"),
  figures_dir = NULL,
  directed = NULL,
  include_title = FALSE,
  include_description = TRUE,
  override = NULL,
  override.title = NULL,
  override.desc = NULL,
  override.math = NULL,
  override.figure = NULL,
  override.citation = NULL,
  ...
)

Arguments

object

A fitted ergm object or an ERGM formula.

...

Additional arguments passed to methods.

include_description

Logical. Include the term description column? Default FALSE.

include_math

Logical. Include the mathematical notation column? Default FALSE.

include_attribute

Logical. Include the attribute column? Default FALSE.

include_title

Logical. Include the short term-title column? Default FALSE.

digits

Non-negative whole number of decimal places used to display every numeric column of a fitted-model table (estimates, standard errors, and p-values; p-values below 10^-digits display as "<0.01"-style bounds). Default 2. Use NULL to retain full precision. Parsed model data always retain full precision.

format

Character. Output format: "data.frame" (default), "html", or "markdown". HTML and Markdown output require the knitr package.

figures_dir

Optional directory for figure assets when format = "markdown". When NULL, figures are copied automatically to the active knitr/Quarto/R Markdown figure path during non-interactive document rendering.

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.005"), a single entry list (list(key = "hunter2007", doi = "10.1016/j.socnet.2006.08.005")), or a list of such entries.

directed

Logical or NULL. Whether the network is directed. Passed to parse_ergm_formula(); when NULL (the default), directedness is inferred from the network on the left-hand side of the formula when possible.

Value

A data.frame (default), or a knitr_kable object when format is "html" or "markdown"; these additionally inherit from internal tabulergm_table and tabulergm_kable classes so styles can be safely applied after rendering. When the term figures use drawing conventions (orange for focal attributes, orange/teal for mixing, squares/circles for bipartite modes), an explanatory note is appended below "html" and "markdown" tables. Terms carrying a citation get a (key) marker next to their description, and the matching [key] identifier lines are appended below the table.

Methods (by class)

  • tabulergm_table(ergm): Method for fitted ergm objects.

    Calls parse_ergm_model() and returns a table with default columns term, figure, estimate, se, and pvalue. Optional columns (title, description, math, attribute) can be included via logical arguments. The title column, when included, is placed immediately after term. Estimates and standard errors are rounded for display according to digits, and p-values are formatted as strings with the same number of decimal places, showing values below the display precision as an upper bound (e.g. "<0.01"). The attached table specification retains the full-precision values.

  • tabulergm_table(formula): Method for formula objects.

    Calls parse_ergm_formula() and returns a table with columns term, figure, math, and, by default, description. Coefficient statistics are excluded because no fitted model is available.

See also

tabulergm_table.ergm(), tabulergm_table.formula()

Examples

library(ergm)
fit <- readRDS(system.file("fits", "fit_edges.rds", package = "tabulergm"))
tabulergm_table(fit)
#>                  term
#> 1 edges (holland1981)
#>                                                                                                         figure
#> 1 /tmp/RtmpRs97L3/tabulergm-4ec940654adcc485b27f39ca7dd20ef2-b6f3c9a3a81099857159db04549de0da-4-undirected.png
#>   estimate   se pvalue
#> 1    -0.69 0.32   0.03
tabulergm_table(fit, include_description = TRUE)
#>    term
#> 1 edges
#>                                                                                                         figure
#> 1 /tmp/RtmpRs97L3/tabulergm-4ec940654adcc485b27f39ca7dd20ef2-b6f3c9a3a81099857159db04549de0da-4-undirected.png
#>   estimate   se pvalue
#> 1    -0.69 0.32   0.03
#>                                                                                                                                           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. (holland1981)
tabulergm_table(fit, format = "markdown")
#> 
#> 
#> |term                |figure                                                                                                                        | estimate|   se| pvalue|
#> |:-------------------|:-----------------------------------------------------------------------------------------------------------------------------|--------:|----:|------:|
#> |edges (holland1981) |![](/tmp/RtmpRs97L3/tabulergm-4ec940654adcc485b27f39ca7dd20ef2-b6f3c9a3a81099857159db04549de0da-4-undirected.png){width=80px} |    -0.69| 0.32|   0.03|
#> 
#> *\[holland1981\] [doi:10.1080/01621459.1981.10477598](https://doi.org/10.1080/01621459.1981.10477598)*

# Replace the shipped title and description for one term
tabulergm_table(
  fit,
  include_title = TRUE,
  include_description = TRUE,
  override.title = c(edges = "Density"),
  override.desc  = c(edges = "Baseline propensity to form ties.")
)
#>    term   title
#> 1 edges Density
#>                                                                                                         figure
#> 1 /tmp/RtmpRs97L3/tabulergm-4ec940654adcc485b27f39ca7dd20ef2-b6f3c9a3a81099857159db04549de0da-4-undirected.png
#>   estimate   se pvalue                                     description
#> 1    -0.69 0.32   0.03 Baseline propensity to form ties. (holland1981)
library(ergm)
tabulergm_table(network ~ edges + nodematch("gender"))
#>        term
#> 1     edges
#> 2 nodematch
#>                                                                                                         figure
#> 1 /tmp/RtmpRs97L3/tabulergm-4ec940654adcc485b27f39ca7dd20ef2-b6f3c9a3a81099857159db04549de0da-4-undirected.png
#> 2 /tmp/RtmpRs97L3/tabulergm-fec42f2f331ba7659bcb83ab4e0b3511-b6f3c9a3a81099857159db04549de0da-4-undirected.png
#>                                        math
#> 1                        \\sum_{i<j} y_{ij}
#> 2 \\sum_{i<j} y_{ij} \\mathbf{1}(x_i = x_j)
#>                                                                                                                                                                                                                                  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. (holland1981)
#> 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). (wasserman1996; mcpherson2001)