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
- formula
An ERGM formula.
- directed
Logical or
NULL. Whether the network is directed, used to select the matching term metadata (math and figures). WhenNULL(the default), directedness is inferred from the network on the left-hand side of the formula if it can be evaluated; otherwise the lookup tries undirected metadata first, then directed.- 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 aretitle,description(ordesc),math,figure, andcitation.- 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 overoverride.- 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.
- attribute
Character or
NA. The attribute(s) used in the term, comma-separated when multiple.- estimate
Numeric. Always
NAfor formula-only parsing.- se
Numeric. Always
NAfor formula-only parsing.- pvalue
Numeric. Always
NAfor 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.
Details
Metadata is resolved from the same three sources, and with the same
precedence, as parse_ergm_model(); see its “Metadata sources”
section.
See also
parse_ergm_model() for parsing fitted models,
ergm::search.ergmTerms() for the underlying term database.
Examples
library(ergm)
#> Loading required package: network
#>
#> ‘network’ 1.20.0 (2026-02-06), part of the Statnet Project
#> * ‘news(package="network")’ for changes since last version
#> * ‘citation("network")’ for citation information
#> * ‘https://statnet.org’ for help, support, and other information
#>
#> ‘ergm’ 4.12.0 (2026-02-17), part of the Statnet Project
#> * ‘news(package="ergm")’ for changes since last version
#> * ‘citation("ergm")’ for citation information
#> * ‘https://statnet.org’ for help, support, and other information
#> ‘ergm’ 4 is a major update that introduces some backwards-incompatible
#> changes. Please type ‘news(package="ergm")’ for a list of major
#> changes.
parse_ergm_formula(network ~ edges + nodematch("gender"))
#> term attribute estimate se pvalue title
#> 1 edges <NA> NA NA NA Number of edges
#> 2 nodematch gender NA NA NA 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
# Directedness can be stated explicitly when the formula has no
# network on its left-hand side
parse_ergm_formula(~ edges + mutual, directed = TRUE)
#> term attribute estimate se pvalue title
#> 1 edges <NA> NA NA NA Number of edges
#> 2 mutual <NA> NA NA NA Reciprocated ties
#> description
#> 1 Counts the directed ties present in the network. Acts as the baseline density term, playing the role an intercept plays in a regression model.
#> 2 Counts the dyads in which both directed ties are present, capturing the tendency for ties to be returned.
#> math
#> 1 \\sum_{i \\neq j} y_{ij}
#> 2 \\sum_{i<j} y_{ij} y_{ji}
#> figure
#> 1 /tmp/RtmpQpSy5d/tabulergm-960c6a358da018c9eaef6ebd9adb9f65-b6f3c9a3a81099857159db04549de0da-0-directed.png
#> 2 /tmp/RtmpQpSy5d/tabulergm-0378c6771f0d7527417250d501cf7375-b6f3c9a3a81099857159db04549de0da-0-directed.png
#> citation
#> 1 <NA>
#> 2 holland1981
# 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")
)
)
#> term attribute estimate se pvalue title
#> 1 edges <NA> NA NA NA Number of edges
#> 2 kstar <NA> NA NA NA k-stars
#> 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 This term adds one network statistic to the model for each element in k . The i th such statistic counts the number of distinct k[i] -stars in the network, where a k -star is defined to be a node N and a set of k different nodes \\{O_1, \\dots, O_k\\}{O[1], ..., O[k]} such that the ties \\{N, O_i\\}{N, O[i]} exist for i=1, \\dots, k . This term can only be used for undirected networks; for directed networks, see istar , ostar , twopath and m2star . Note that kstar(1) is equal to edges .
#> math
#> 1 \\sum_{i<j} y_{ij}
#> 2 <NA>
#> figure
#> 1 /tmp/RtmpQpSy5d/tabulergm-83bf88159c17a513202a912d589a0254-b6f3c9a3a81099857159db04549de0da-0-undirected.png
#> 2 <NA>
#> citation
#> 1 <NA>
#> 2 frank1986