ergmTerm {ergm}R Documentation

Terms used in Exponential Family Random Graph Models

Description

This page explains how to specify the network statistics g(y) to functions in the ergm package and packages that extend it. It also provides an indexed list of the possible terms (and hence network statistics) visible to the ergm API. Terms can also be searched via search.ergmTerms, and help for an individual term can be obtained with ⁠ergmTerm?<term>⁠ or help("<term>-ergmTerm").

Specifying models

In an exponential-family random graph model (ERGM), the probability or density of a given network, y \in Y, on a set of nodes is

h(y) \exp[\eta(\theta) \cdot g(y)] / \kappa(\theta),

where h(y) is the reference distribution (particularly for valued network models), g(y) is a vector of network statistics for y, \eta(\theta) is a natural parameter vector of the same length (with \eta(\theta)\equiv\theta for most terms), \cdot is the dot product, and \kappa(\theta) is the normalizing constant for the distribution. A complete ERGM specification requires a list of network statistics g(y) and (if applicable) their \eta(\theta) mappings provided by a formula of ergmTerms; and, optionally, sample space \mathcal{Y} and reference distribution h(y) information provided by ergmConstraints and, for valued ERGMs, by ergmReferences.

Network statistics g(y) and mappings \eta(\theta) are specified by a formula object, of the form ⁠y ~ <term 1> + <term 2> ...⁠, where y is a network object or a matrix that can be coerced to a network object, and ⁠<term 1>⁠, ⁠<term 2>⁠, etc, are each terms chosen from the list given below. To create a network object in , use the network function, then add nodal attributes to it using the ⁠%v%⁠ operator if necessary.

Term operators

Operator terms like B and F take formulas with other ergm terms as their arguments and transform them by modifying their inputs (e.g., the network they evaluate) and/or their outputs.

By convention, their names are capitalized and CamelCased.

Interactions

For binary ERGMs, interactions between ergm terms can be specified in a manner similar to lm and others, as using the : and * operators. However, they must be interpreted carefully, especially for dyad-dependent terms. (Interactions involving curved terms are not supported at this time.)

Generally, if term a has p_a statistics and b has p_b, a:b will add p_a \times p_b statistics to the model, corresponding to each element of g_a(y) interacted with each element of g_b(y).

The interaction is defined as follows. Dyad-independent terms can be expressed in the general form g(y;x)=\sum_{i,j} x_{i,j}y_{i,j} for some edge covariate matrix x,

g_{a:b}(y)=\sum_{i,j} x_{a,i,j}x_{b,i,j}y_{i,j}.

In other words, rather than being a product of their sufficient statistics (g_{a}(y)g_{b}(y)), it is a dyadwise product of their dyad-level effects.

This means that an interaction between two dyad-independent terms can be interpreted the same way as it would be in the corresponding logistic regression for each potential edge. However, for undirected networks in particular, this may lead to somewhat counterintuitive results. For example, given two nodal covariates "a" and "b" (whose values for node i are denoted a_i and b_i, respectively), nodecov("a") adds one statistic of the form \sum_{i,j} (a_{i}+a_{j}) y_{i,j} and analogously for nodecov("b"), so nodecov("a"):nodecov("b") produces

\sum_{i,j} (a_{i}+a_{j}) (b_{i}+b_{j}) y_{i,j}.

Binary and valued ERGM terms

ergm functions such as ergm and simulate (for ERGMs) may operate in two modes: binary and weighted/valued, with the latter activated by passing a non-NULL value as the response argument, giving the edge attribute name to be modeled/simulated.

Generalizations of binary terms

Binary ERGM statistics cannot be used directly in valued mode and vice versa. However, a substantial number of binary ERGM statistics — particularly the ones with dyadic independence — have simple generalizations to valued ERGMs, and have been adapted in ergm. They have the same form as their binary ERGM counterparts, with an additional argument: form, which, at this time, has two possible values: "sum" (the default) and "nonzero". The former creates a statistic of the form \sum_{i,j} x_{i,j} y_{i,j}, where y_{i,j} is the value of dyad (i,j) and x_{i,j} is the term's covariate associated with it. The latter computes the binary version, with the edge considered to be present if its value is not 0. Valued version of some binary ERGM terms have an argument threshold, which sets the value above which a dyad is conidered to have a tie. (Value less than or equal to threshold is considered a nontie.)

The B() operator term documented below can be used to pass other binary terms to valued models, and is more flexible, at the cost of being somewhat slower.

Nodal attribute levels and indices

Terms taking a categorical nodal covariate also take the levels argument. (There are analogous b1levels and b2levels arguments for some terms that apply to bipartite networks, and the levels2 argument for mixing terms.) The levels argument can be used to control the set and the ordering of attribute levels.

Terms that allow the selection of nodes do so with the nodes argument, which is interpreted in the same way as the levels argument, where the categories are the relevant nodal indices themselves.

Both levels and nodes use the new level selection UI. (See Specifying Vertex attributes and Levels (⁠? nodal_attributes⁠) for details.)

Legacy arguments

The legacy base and keep arguments are deprecated as of version 3.10, and replaced by the levels UI. The levels argument provides consistent and flexible mechanisms for specifying which attribute levels to exclude (previously handled by base) and include (previously handled by keep). If levels or nodes argument is given, then base and keep arguments are ignored. The legacy arguments will most likely be removed in a future version.

Note that this exact behavior is new in version 3.10, and it differs slightly from older versions: previously if both levels and base/keep were given, levels argument was applied first and then applied the base/keep argument. Since version 3.10, base/keep would be ignored, even if old term behavior is invoked (as described in the next section).

Term versioning

When a term's behavior has changed from prior version, it is often possible to invoke the old behavior by setting and/or passing a version term option, giving the verison (constructed by as.package_version) desired.

Custom ergm terms

Users and other packages may build custom terms, and package ergm.userterms (https://github.com/statnet/ergm.userterms) provides tools for implementing them.

The current recommendation for any package implementing additional terms is to document the term with Roxygen comments and a name in the form termName-ergmTerm. This ensures that help("ergmTerm") will list ERGM terms available from all loaded packages.

Terms included in the ergm package

As noted above, a cross-referenced HTML version of the term documentation is also available via vignette('ergm-term-crossRef') and terms can also be searched via search.ergmTerms.

Term index (plain)

Term Package Description Concepts
ergm Absolute difference in nodal attribute directed dyad-independent quantitative nodal attribute undirected
ergm Categorical absolute difference in nodal attribute categorical nodal attribute directed dyad-independent undirected
ergm Alternating k-star categorical nodal attribute curved undirected
ergm Asymmetric dyads directed dyad-independent triad-related
ergm Number of dyads with values greater than or equal to a threshold directed dyad-independent undirected
ergm Number of dyads with values less than or equal to a threshold directed dyad-independent undirected
ergm Edge covariate by attribute pairing directed dyad-independent undirected
ergm Concurrent node count for the first mode in a bipartite network bipartite categorical nodal attribute undirected
ergm Main effect of a covariate for the first mode in a bipartite network bipartite dyad-independent frequently-used quantitative nodal attribute undirected
ergm Degree range for the first mode in a bipartite network bipartite undirected
ergm Degree for the first mode in a bipartite network bipartite categorical nodal attribute frequently-used undirected
b1dsp(d) (bin)
ergm Dyadwise shared partners for dyads in the first bipartition bipartite undirected
ergm Factor attribute effect for the first mode in a bipartite network bipartite categorical nodal attribute dyad-independent frequently-used undirected
ergm Minimum degree for the first mode in a bipartite network bipartite undirected
ergm Nodal attribute-based homophily effect for the first mode in a bipartite network bipartite categorical nodal attribute dyad-independent frequently-used undirected
ergm Degree bipartite dyad-independent undirected
ergm k-stars for the first mode in a bipartite network bipartite categorical nodal attribute undirected
ergm Mixing matrix for k-stars centered on the first mode of a bipartite network bipartite categorical nodal attribute undirected
ergm Two-star census for central nodes centered on the first mode of a bipartite network bipartite categorical nodal attribute undirected
ergm Concurrent node count for the second mode in a bipartite network bipartite frequently-used undirected
ergm Main effect of a covariate for the second mode in a bipartite network bipartite dyad-independent frequently-used quantitative nodal attribute undirected
ergm Degree range for the second mode in a bipartite network bipartite undirected
ergm Degree for the second mode in a bipartite network bipartite categorical nodal attribute frequently-used undirected
b2dsp(d) (bin)
ergm Dyadwise shared partners for dyads in the second bipartition bipartite undirected
ergm Factor attribute effect for the second mode in a bipartite network bipartite categorical nodal attribute dyad-independent frequently-used undirected
ergm Minimum degree for the second mode in a bipartite network bipartite undirected
ergm Nodal attribute-based homophily effect for the second mode in a bipartite network bipartite categorical nodal attribute dyad-independent frequently-used undirected
ergm Degree bipartite dyad-independent undirected
ergm k-stars for the second mode in a bipartite network bipartite categorical nodal attribute undirected
ergm Mixing matrix for k-stars centered on the second mode of a bipartite network bipartite categorical nodal attribute undirected
ergm Two-star census for central nodes centered on the second mode of a bipartite network bipartite categorical nodal attribute undirected
balance (bin)
ergm Balanced triads directed triad-related undirected
ergm Coincident node count for the second mode in a bipartite (aka two-mode) network bipartite undirected
ergm Concurrent node count categorical nodal attribute undirected
ergm Concurrent tie count categorical nodal attribute undirected
ergm Cyclic triples categorical nodal attribute directed triad-related
ergm k-Cycle Census directed undirected
ergm Cyclical ties directed undirected
ergm Cyclical weights directed nonnegative undirected
degcor (bin)
ergm Degree Correlation undirected
ergm Degree Cross-Product undirected
ergm Degree range categorical nodal attribute undirected
ergm Degree categorical nodal attribute frequently-used undirected
degree1.5 (bin)
ergm Degree to the 3/2 power undirected
density (bin)
ergm Density directed dyad-independent undirected
ergm Difference bipartite directed dyad-independent frequently-used quantitative nodal attribute undirected
ergm Directed dyadwise shared partners directed
ergm Dyadic covariate directed dyad-independent quantitative dyadic attribute undirected
ergm Edge covariate directed dyad-independent frequently-used quantitative dyadic attribute undirected
edges (bin)
nonzero (val)
edges (val)
ergm Number of edges in the network directed dyad-independent undirected
ergm Number of dyads with values equal to a specific value (within tolerance) directed dyad-independent undirected
ergm Directed edgewise shared partners directed
ergm Number of dyads with values strictly greater than a threshold directed dyad-independent undirected
ergm Geometrically weighted degree distribution for the first mode in a bipartite network bipartite curved undirected
ergm Geometrically weighted dyadwise shared partner distribution for dyads in the first bipartition bipartite curved undirected
ergm Geometrically weighted degree distribution for the second mode in a bipartite network bipartite curved undirected
ergm Geometrically weighted dyadwise shared partner distribution for dyads in the second bipartition bipartite curved undirected
ergm Geometrically weighted degree distribution curved frequently-used undirected
ergm Geometrically weighted dyadwise shared partner distribution directed
ergm Geometrically weighted edgewise shared partner distribution directed
ergm Geometrically weighted in-degree distribution curved directed
ergm Geometrically weighted non-edgewise shared partner distribution directed
ergm Geometrically weighted out-degree distribution curved directed
ergm Hamming distance directed dyad-independent undirected
ergm In-degree range categorical nodal attribute directed
ergm In-degree categorical nodal attribute directed frequently-used
ergm In-degree to the 3/2 power directed
ergm Number of dyads whose values are in an interval directed dyad-independent undirected
ergm Intransitive triads directed triad-related
ergm Isolated edges bipartite undirected
isolates (bin)
ergm Isolates directed frequently-used undirected
ergm In-stars categorical nodal attribute directed
ergm k-stars categorical nodal attribute undirected
ergm Triangles within neighborhoods categorical dyadic attribute directed triad-related undirected
m2star (bin)
ergm Mixed 2-stars, a.k.a 2-paths directed
meandeg (bin)
ergm Mean vertex degree directed dyad-independent undirected
ergm Mixing matrix cells and margins categorical nodal attribute directed dyad-independent frequently-used undirected
ergm Mutuality directed frequently-used
ergm Near simmelian triads directed triad-related
ergm Main effect of a covariate directed dyad-independent frequently-used quantitative nodal attribute undirected
ergm Covariance of undirected dyad values incident on each actor directed
ergm Factor attribute effect categorical nodal attribute directed dyad-independent frequently-used undirected
ergm Main effect of a covariate for in-edges directed frequently-used quantitative nodal attribute
ergm Covariance of in-dyad values incident on each actor directed
ergm Factor attribute effect for in-edges categorical nodal attribute directed dyad-independent frequently-used
ergm Uniform homophily and differential homophily categorical nodal attribute directed dyad-independent frequently-used undirected
ergm Nodal attribute mixing categorical nodal attribute directed dyad-independent frequently-used undirected
ergm Main effect of a covariate for out-edges directed dyad-independent quantitative nodal attribute
ergm Covariance of out-dyad values incident on each actor directed
ergm Factor attribute effect for out-edges categorical nodal attribute directed dyad-independent
ergm Directed non-edgewise shared partners directed
ergm Out-degree range categorical nodal attribute directed
ergm Out-degree categorical nodal attribute directed frequently-used
ergm Out-degree to the 3/2 power directed
opentriad (bin)
ergm Open triads triad-related undirected
ergm k-Outstars categorical nodal attribute directed
ergm Receiver effect directed dyad-independent
ergm Sender effect directed dyad-independent
simmelian (bin)
ergm Simmelian triads directed triad-related
ergm Ties in simmelian triads directed triad-related
ergm Number of ties between actors with similar attribute values directed dyad-independent quantitative nodal attribute undirected
ergm Number of dyads with values strictly smaller than a threshold directed dyad-independent undirected
ergm Undirected degree categorical nodal attribute dyad-independent undirected
sum(pow) (val)
ergm Sum of dyad values (optionally taken to a power) directed undirected
ergm Three-trails directed triad-related undirected
ergm Transitive triads directed triad-related
ergm Transitive ties categorical nodal attribute directed triad-related undirected
ergm Transitive weights directed nonnegative triad-related undirected
ergm Triad census directed triad-related undirected
ergm Triangles categorical nodal attribute directed frequently-used triad-related undirected
ergm Triangle percentage categorical nodal attribute triad-related undirected
ergm Transitive triples categorical nodal attribute directed triad-related
twopath (bin)
ergm 2-Paths directed undirected

Term index (operator)

Term Package Description Concepts
ergm Wrap binary terms for use in valued models operator
ergm Impose a curved structure on term parameters operator
ergm Exponentiate a network's statistic operator
ergm Filtering on arbitrary one-term model operator
For(...) (bin)
ergm A for operator for terms operator
ergm Modify terms' coefficient names operator
ergm Take a natural logarithm of a network's statistic operator
ergm Filtering on nodematch operator
ergm Terms with fixed coefficients operator
ergm A product (or an arbitrary power combination) of one or more formulas operator
ergm Evaluation on an induced subgraph operator
ergm A sum (or an arbitrary linear combination) of one or more formulas operator
ergm Evaluation on symmetrized (undirected) network directed operator

Frequently-used terms

Term bin bip dir dyad-indep op val undir
b1cov
b1degree
b1factor
b1nodematch
b2concurrent
b2cov
b2degree
b2factor
b2nodematch
degree
diff
edgecov
gwdegree
idegree
isolates
mm
mutual
nodecov
nodefactor
nodeicov
nodeifactor
nodematch
nodemix
odegree
triangle

Operator terms

Term bin bip dir dyad-indep val undir
B
Curve
Exp
F
For
Label
Log
NodematchFilter
Offset
Prod
S
Sum
Symmetrize

All terms

Term op val bin dir dyad-indep quant nodal attr undir cat nodal attr curved triad rel bip freq nneg quant dyad attr cat dyad attr
B
Curve
Exp
F
For
Label
Log
NodematchFilter
Offset
Prod
S
Sum
Symmetrize
absdiff
absdiffcat
altkstar
asymmetric
atleast
atmost
attrcov
b1concurrent
b1cov
b1degrange
b1degree
b1dsp
b1factor
b1mindegree
b1nodematch
b1sociality
b1star
b1starmix
b1twostar
b2concurrent
b2cov
b2degrange
b2degree
b2dsp
b2factor
b2mindegree
b2nodematch
b2sociality
b2star
b2starmix
b2twostar
balance
coincidence
concurrent
concurrentties
ctriple
cycle
cyclicalties
cyclicalweights
degcor
degcrossprod
degrange
degree
degree1.5
density
diff
dsp
dyadcov
edgecov
edges
equalto
esp
greaterthan
gwb1degree
gwb1dsp
gwb2degree
gwb2dsp
gwdegree
gwdsp
gwesp
gwidegree
gwnsp
gwodegree
hamming
idegrange
idegree
idegree1.5
ininterval
intransitive
isolatededges
isolates
istar
kstar
localtriangle
m2star
meandeg
mm
mutual
nearsimmelian
nodecov
nodecovar
nodefactor
nodeicov
nodeicovar
nodeifactor
nodematch
nodemix
nodeocov
nodeocovar
nodeofactor
nsp
odegrange
odegree
odegree1.5
opentriad
ostar
receiver
sender
simmelian
simmelianties
smalldiff
smallerthan
sociality
sum
threetrail
transitive
transitiveties
transitiveweights
triadcensus
triangle
tripercent
ttriple
twopath

Terms by keywords

Jump to keyword: operator valued binary directed dyad-independent quantitative nodal attribute undirected categorical nodal attribute curved triad-related bipartite frequently-used nonnegative quantitative dyadic attribute categorical dyadic attribute

operator

B Curve Exp F For Label Log NodematchFilter Offset Prod S Sum Symmetrize

valued

B Curve Exp Label Log Prod Sum absdiff absdiffcat atleast atmost b1cov b1factor b1sociality b2cov b2factor b2sociality cyclicalties cyclicalweights diff edgecov edges equalto greaterthan ininterval mm mutual nodecov nodecovar nodefactor nodeicov nodeicovar nodeifactor nodematch nodemix nodeocov nodeocovar nodeofactor receiver sender smallerthan sociality sum transitiveweights

binary

Curve Exp F For Label Log NodematchFilter Offset Prod S Sum Symmetrize absdiff absdiffcat altkstar asymmetric attrcov b1concurrent b1cov b1degrange b1degree b1dsp b1factor b1mindegree b1nodematch b1sociality b1star b1starmix b1twostar b2concurrent b2cov b2degrange b2degree b2dsp b2factor b2mindegree b2nodematch b2sociality b2star b2starmix b2twostar balance coincidence concurrent concurrentties ctriple cycle cyclicalties degcor degcrossprod degrange degree degree1.5 density diff dsp dyadcov edgecov edges esp gwb1degree gwb1dsp gwb2degree gwb2dsp gwdegree gwdsp gwesp gwidegree gwnsp gwodegree hamming idegrange idegree idegree1.5 intransitive isolatededges isolates istar kstar localtriangle m2star meandeg mm mutual nearsimmelian nodecov nodefactor nodeicov nodeifactor nodematch nodemix nodeocov nodeofactor nsp odegrange odegree odegree1.5 opentriad ostar receiver sender simmelian simmelianties smalldiff sociality threetrail transitive transitiveties triadcensus triangle tripercent ttriple twopath

directed

Symmetrize absdiff absdiffcat asymmetric atleast atmost attrcov balance ctriple cycle cyclicalties cyclicalweights density diff dsp dyadcov edgecov edges equalto esp greaterthan gwdsp gwesp gwidegree gwnsp gwodegree hamming idegrange idegree idegree1.5 ininterval intransitive isolates istar localtriangle m2star meandeg mm mutual nearsimmelian nodecov nodecovar nodefactor nodeicov nodeicovar nodeifactor nodematch nodemix nodeocov nodeocovar nodeofactor nsp odegrange odegree odegree1.5 ostar receiver sender simmelian simmelianties smalldiff smallerthan sum threetrail transitive transitiveties transitiveweights triadcensus triangle ttriple twopath

dyad-independent

absdiff absdiffcat asymmetric atleast atmost attrcov b1cov b1factor b1nodematch b1sociality b2cov b2factor b2nodematch b2sociality density diff dyadcov edgecov edges equalto greaterthan hamming ininterval meandeg mm nodecov nodefactor nodeifactor nodematch nodemix nodeocov nodeofactor receiver sender smalldiff smallerthan sociality

quantitative nodal attribute

absdiff b1cov b2cov diff nodecov nodeicov nodeocov smalldiff

undirected

absdiff absdiffcat altkstar atleast atmost attrcov b1concurrent b1cov b1degrange b1degree b1dsp b1factor b1mindegree b1nodematch b1sociality b1star b1starmix b1twostar b2concurrent b2cov b2degrange b2degree b2dsp b2factor b2mindegree b2nodematch b2sociality b2star b2starmix b2twostar balance coincidence concurrent concurrentties cycle cyclicalties cyclicalweights degcor degcrossprod degrange degree degree1.5 density diff dyadcov edgecov edges equalto greaterthan gwb1degree gwb1dsp gwb2degree gwb2dsp gwdegree hamming ininterval isolatededges isolates kstar localtriangle meandeg mm nodecov nodefactor nodematch nodemix opentriad smalldiff smallerthan sociality sum threetrail transitiveties transitiveweights triadcensus triangle tripercent twopath

categorical nodal attribute

absdiffcat altkstar b1concurrent b1degree b1factor b1nodematch b1star b1starmix b1twostar b2degree b2factor b2nodematch b2star b2starmix b2twostar concurrent concurrentties ctriple degrange degree idegrange idegree istar kstar mm nodefactor nodeifactor nodematch nodemix nodeofactor odegrange odegree ostar sociality transitiveties triangle tripercent ttriple

curved

altkstar gwb1degree gwb1dsp gwb2degree gwb2dsp gwdegree gwidegree gwodegree

triad-related

asymmetric balance ctriple intransitive localtriangle nearsimmelian opentriad simmelian simmelianties threetrail transitive transitiveties transitiveweights triadcensus triangle tripercent ttriple

bipartite

b1concurrent b1cov b1degrange b1degree b1dsp b1factor b1mindegree b1nodematch b1sociality b1star b1starmix b1twostar b2concurrent b2cov b2degrange b2degree b2dsp b2factor b2mindegree b2nodematch b2sociality b2star b2starmix b2twostar coincidence diff gwb1degree gwb1dsp gwb2degree gwb2dsp isolatededges

frequently-used

b1cov b1degree b1factor b1nodematch b2concurrent b2cov b2degree b2factor b2nodematch degree diff edgecov gwdegree idegree isolates mm mutual nodecov nodefactor nodeicov nodeifactor nodematch nodemix odegree triangle

nonnegative

cyclicalweights transitiveweights

quantitative dyadic attribute

dyadcov edgecov

categorical dyadic attribute

localtriangle

References

See Also

ergm package, search.ergmTerms, ergm, network, %v%, %n%

Examples

## Not run: 
ergm(flomarriage ~ kstar(1:2) + absdiff("wealth") + triangle)

ergm(molecule ~ edges + kstar(2:3) + triangle
                      + nodematch("atomic type",diff=TRUE)
                      + triangle + absdiff("atomic type"))

## End(Not run)

[Package ergm version 4.6.0 Index]