Package {tabulergm}

Title:	Publication-Ready Tables and Summaries for Exponential-Family Random Graph Models
Version:	0.1.0
Description:	Creates publication-ready tables documenting exponential-family random graph models (ERGMs), a class of statistical models for social networks (Robins et al., 2007, <doi:10.1016/j.socnet.2006.08.002>). Tables describe model terms through their definitions, mathematical representations, and graphical representations, and can be generated from ERGM formulas or from models fitted with the 'ergm' package (Hunter et al., 2008, <doi:10.18637/jss.v024.i03>). Resulting tables can be integrated into 'quarto' and 'rmarkdown' documents.
License:	MIT + file LICENSE
Encoding:	UTF-8
Depends:	R (≥ 4.2)
Imports:	base64enc, ergm (≥ 4.0), netplot (≥ 0.4-0), network, yaml
Suggests:	knitr, rmarkdown, rstudioapi, tinytest
URL:	https://gvegayon.github.io/tabulergm/, https://github.com/gvegayon/tabulergm
BugReports:	https://github.com/gvegayon/tabulergm/issues
Config/roxygen2/version:	8.0.0
RoxygenNote:	7.3.3
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2026-08-20 02:21:33 UTC; runner
Author:	George Vega Yon [aut, cre]
Maintainer:	George Vega Yon <g.vegayon@gmail.com>
Repository:	CRAN
Date/Publication:	2026-08-21 13:50:02 UTC

tabulergm: Publication-Ready Tables and Summaries for ERGM Models

Description

tabulergm translates models estimated with the ergm framework into publication-ready tables and explanatory summaries.

Author(s)

Maintainer: George Vega Yon g.vegayon@gmail.com (ORCID)

Authors:

• George Vega Yon g.vegayon@gmail.com (ORCID)

See Also

Useful links:

• https://gvegayon.github.io/tabulergm/

• https://github.com/gvegayon/tabulergm

• Report bugs at https://github.com/gvegayon/tabulergm/issues

Parse an ERGM Formula

Description

Extracts ERGM term names and attributes from a formula. No fitted model is required. Returns a standardized data frame with metadata from the ERGM term database where available.

Usage

parse_ergm_formula(
  formula,
  directed = NULL,
  override = NULL,
  override.title = NULL,
  override.desc = NULL,
  override.math = NULL,
  override.figure = NULL,
  override.citation = NULL
)

Arguments

Details

Metadata is resolved from the same three sources, and with the same precedence, as parse_ergm_model(); see its “Metadata sources” section.

Value

A data frame with columns:

term

Character. The canonical ERGM term name.

attribute

Character or NA. The attribute(s) used in the term, comma-separated when multiple.

estimate

Numeric. Always NA for formula-only parsing.

se

Numeric. Always NA for formula-only parsing.

pvalue

Numeric. Always NA for formula-only parsing.

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.

See Also

parse_ergm_model() for parsing fitted models, ergm::search.ergmTerms() for the underlying term database.

Examples

library(ergm)
parse_ergm_formula(network ~ edges + nodematch("gender"))

# Directedness can be stated explicitly when the formula has no
# network on its left-hand side
parse_ergm_formula(~ edges + mutual, directed = TRUE)

# Attach a citation to a term that has none in the term dictionary
parse_ergm_formula(
  ~ edges + kstar(2),
  directed = FALSE,
  override.citation = list(
    kstar = list(key = "frank1986", doi = "10.1080/0022250X.1986.9990013")
  )
)

Parse an ERGM Model Object

Description

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

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.

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.

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.

See Also

parse_ergm_formula() for formula-only parsing, ergm::search.ergmTerms() for the underlying term database.

Examples

library(ergm)
fit <- readRDS(system.file("fits", "fit_nodematch.rds", package = "tabulergm"))
parse_ergm_model(fit)

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

Notation and Drawing Standards for Term Definitions

Description

Reference for the conventions used in the YAML term database under ⁠inst/terms/⁠. Follow these standards when adding or editing term definitions so that the math and figures stay consistent across the term dictionary.

Files

Each term lives in ⁠inst/terms/<term>.<directed|undirected>.yml⁠, where ⁠<term>⁠ is the canonical ergm term name as written in a model formula (e.g., gwesp, b1nodematch). Terms available for both directed and undirected networks get one file per variant; bipartite terms use undirected. A file has up to five top-level entries: title and description (text, both optional), citation (optional, see below), plot (the network drawing specification), and math (a LaTeX expression). No parser changes are needed for new terms: files are looked up by term name.

Titles, descriptions, and citations

title is a short label, capitalized like a heading and without a trailing period (e.g. ⁠Uniform homophily⁠). description is one to three sentences of prose saying what the statistic counts and why a modeler would include it; write it as a folded block scalar (⁠>-⁠) so the source stays readable. Both fields are optional: when absent, tabulergm falls back to the title and description recorded in the ergm term database, which are accurate but often too long, too technical, or full of raw LaTeX for a table cell. Prefer writing them here.

citation records the source(s) that introduced the term. Each entry carries a key (the marker shown in the table, conventionally lastnameYEAR) and, where one exists, a machine-readable identifier so readers can pull the full reference into their own bibliography:

citation:
  - key: hunter2007
    doi: 10.1016/j.socnet.2006.08.005

Accepted identifier fields are doi, arxiv, pmid, and url; an entry may also carry free-text text, which is the right choice when no stable identifier can be verified. Always resolve an identifier before committing it (for a DOI, ⁠https://doi.org/<id>⁠); an identifier that points at the wrong paper is worse than none.

tabulergm_table() renders a (key) marker next to the term's description and a matching ⁠[key] identifier⁠ line below the table. Users can replace any of these fields per table through the override arguments of tabulergm_table() without editing the YAML.

Math notation

• y_{ij}: tie indicator. Undirected statistics sum over i<j; directed statistics sum over i \neq j.

• x_i: vertex attribute value of node i; x_{ij}: dyadic covariate value (e.g., edgecov).

• \mathbf{1}(\cdot): indicator function (⁠\mathbf{1}⁠ in LaTeX).

• Attribute levels: k for a single level (factor terms), (k, l) for mixing pairs, and (p, q) for center/leaf values in star-mixing terms.

• Bipartite modes: B_1 (first mode) and B_2 (second mode); n_{B_1} and n_{B_2} for the mode sizes.

• Geometrically weighted terms follow the Hunter (2007) parameterization, e.g. \exp(\tau) \sum_i [1 - (1 - e^{-\tau})^i] EP_i(y), where the exponent is the summation index and EP_i, DP_i, and D_i are the edgewise shared partner, dyadwise shared partner, and degree counts.

• Directed shared-partner terms carry the two-path type as a superscript, e.g. EP^{\mathrm{OTP}}_i, because ergm counts outgoing two-paths (OTP) by default and gwesp/gwdsp take a type argument that changes which two-paths are counted.

Always verify a new formula against the ergm term manual (see ergm::ergmTerm and ergm::search.ergmTerms()) and the source literature. When the manual is ambiguous, compare the formula numerically against summary(nw ~ term) on a small test network.

Drawing conventions

The plot entry supports edgelist, vcolor, vshape, vsize, ecolor, elinetype, and layout (with x and y coordinates). Edgelists are chains like "0->1->2, 0->3": each consecutive pair is one edge. Per-vertex vectors follow the node order obtained from the parsed edgelist (unique node ids, all tail nodes first, then head nodes); render the figure to double-check the mapping.

• Vertex color: black marks the focal structure of a term; gray marks non-focal context, both attribute-irrelevant nodes and structurally non-focal nodes (e.g., the shared partners in gwesp/gwdsp); orange marks nodes whose attribute enters the statistic (matched pairs share orange); mixing terms use orange vs. teal ("#008080", quoted in the YAML) for the two attribute categories, a colorblind-friendly pairing. These colors drive the explanatory notes appended below rendered tables, so use them consistently.

• Vertex shape: square marks first-mode (B_1) nodes and circle marks second-mode (B_2) nodes in bipartite drawings. One-mode drawings use circles only.

• Layout: bipartite drawings place the first mode on the left and the second mode on the right.

• Vertex size: 1.0 for focal or attribute-relevant nodes, .5 for context nodes.

• Edges: solid black for focal ties; gray for context ties (e.g., the two-paths in shared-partner terms); dashed (elinetype: 2) for match/covariate annotations; orange when the edge itself carries the covariate (e.g., edgecov).

• Directedness comes from the file name; arrows are drawn automatically for .directed.yml terms.

Checklist for a new term

1. Add the YAML file(s) following the standards above, including a title and description, and a citation when the term has an identifiable source.

2. Add tinytest coverage in inst/tinytest/test_term_db.R (file lookup, math/figure reading, and formula integration).

3. Add the term to the dictionary tables in README.qmd and vignettes/ergm-with-tabulergm.Rmd; both contain a hidden coverage-check chunk that fails the render if a term is missing.

4. Re-render the README, and run the tests and devtools::check().

References

Hunter, D. R. (2007). Curved exponential family models for social networks. Social Networks, 29(2), 216–230. doi:10.1016/j.socnet.2006.08.005

Bomiriya, R. P., Bansal, S., & Hunter, D. R. (2014). Modeling homophily in ERGMs for bipartite networks. (No stable identifier verified; the arXiv id previously given here, 1412.1151, belongs to an unrelated paper.)

Default Plot Function for Term Figures

Description

Draws a network figure using netplot::nplot(). This is the default plot function used by tabulergm when generating term figures.

Usage

tabulergm_default_plotfun(
  netobj,
  layout,
  vcolor,
  vshape,
  vrotation,
  ecolor,
  directed,
  vsize,
  elinetype,
  ...
)

Arguments

Details

A plot function must accept the arguments netobj, layout, vcolor, ecolor, directed, and ..., and draw on the current graphics device.

Value

Called for its side-effect of drawing a plot on the current graphics device. Returns invisibly.

See Also

tabulergm_set_plotfun(), tabulergm_get_plotfun()

Examples

# See the default implementation
tabulergm_default_plotfun

# Use a custom plot function
my_plotfun <- function(netobj, layout, vcolor, ecolor, directed, vshape, vrotation, vsize, ...) {
  netplot::nplot(netobj, vertex.color = vcolor, edge.color = ecolor,
                 layout = layout)
}
old <- tabulergm_get_plotfun()
tabulergm_set_plotfun(my_plotfun)
# Restore the previous plot function
tabulergm_set_plotfun(old)

Get the Current Plot Function

Description

Returns the function currently used to draw term figures. If no custom function has been set, returns tabulergm_default_plotfun().

Usage

tabulergm_get_plotfun()

Value

A function (the active plot function).

See Also

tabulergm_default_plotfun(), tabulergm_set_plotfun()

Save a tabulergm Table and Figure Assets

Description

Saves the table code produced by tabulergm and copies the generated term figures out of the temporary cache into a user-controlled directory. The exported table references the copied image files with relative paths, making the result easier to reuse in another document or project.

Usage

tabulergm_save(object, path, ...)

## S3 method for class 'ergm'
tabulergm_save(
  object,
  path,
  format = c("markdown", "latex"),
  filename = "tabulergm-table",
  images_dir = "figures",
  overwrite = TRUE,
  latex_image_width = "0.7in",
  ...
)

## S3 method for class 'formula'
tabulergm_save(
  object,
  path,
  format = c("markdown", "latex"),
  filename = "tabulergm-table",
  images_dir = "figures",
  overwrite = TRUE,
  latex_image_width = "0.7in",
  ...
)

## S3 method for class 'data.frame'
tabulergm_save(
  object,
  path,
  format = c("markdown", "latex"),
  filename = "tabulergm-table",
  images_dir = "figures",
  overwrite = TRUE,
  latex_image_width = "0.7in",
  ...
)

Arguments

Value

Invisibly returns a list with:

path

The normalized export directory.

files

Named character vector of written table code files.

figures

Named character vector of copied figure files, where names are the relative paths used in the table.

table

The data frame used for export, with figure paths rewritten to the copied relative paths.

Methods (by class)

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

• tabulergm_save(formula): Method for formula objects.

• tabulergm_save(data.frame): Method for data frames returned by tabulergm_table().

See Also

tabulergm_table()

Examples

if (requireNamespace("knitr", quietly = TRUE)) {
  fit <- readRDS(system.file("fits", "fit_edges.rds", package = "tabulergm"))
  out_dir <- tempfile("tabulergm-export-")
  tabulergm_save(fit, out_dir, include_math = TRUE)
}

Set the Plot Function for Term Figures

Description

Replaces the current plot function used when drawing term figures. The function must accept netobj, layout, vcolor, ecolor, directed, and .... Setting a plot function invalidates previously cached term figures, so subsequent renders use the new function.

Usage

tabulergm_set_plotfun(plotfun)

Arguments

Value

Invisibly returns the previous plot function.

See Also

tabulergm_default_plotfun(), tabulergm_get_plotfun()

Examples

my_plotfun <- function(netobj, layout, vcolor, ecolor, directed, ...) {
  netplot::nplot(netobj, vertex.color = vcolor, edge.color = ecolor,
                 layout = layout)
}
old <- tabulergm_get_plotfun()
tabulergm_set_plotfun(my_plotfun)
# Restore the previous plot function
tabulergm_set_plotfun(old)

Generate a Publication-Ready Table from an ERGM Object

Description

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,
  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,
  override = NULL,
  override.title = NULL,
  override.desc = NULL,
  override.math = NULL,
  override.figure = NULL,
  override.citation = NULL,
  ...
)

Arguments

Value

A data.frame (default), or a knitr_kable object when format is "html" or "markdown". 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.

• tabulergm_table(formula): Method for formula objects.

  Calls parse_ergm_formula() and returns a table with columns term, figure, math, and 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)
tabulergm_table(fit, include_description = TRUE)
tabulergm_table(fit, format = "markdown")

# 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.")
)
library(ergm)
tabulergm_table(network ~ edges + nodematch("gender"))

View an ERGM Table in the RStudio Viewer or System Browser

Description

Builds a self-contained HTML page containing the formatted ERGM table (with MathJax for LaTeX math rendering) and opens it in the RStudio viewer pane when available, falling back to utils::browseURL().

Usage

tabulergm_view(object, ...)

## S3 method for class 'ergm'
tabulergm_view(object, ...)

## S3 method for class 'formula'
tabulergm_view(object, ...)

Arguments

Value

Invisibly returns the path to the temporary HTML file.

Methods (by class)

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

• tabulergm_view(formula): Method for formula objects.

See Also

tabulergm_table()

Examples

library(ergm)
fit <- readRDS(system.file("fits", "fit_edges.rds", package = "tabulergm"))
tabulergm_view(fit)

# Also works with a formula (shows term metadata only)
tabulergm_view(network ~ edges + triangle)