This vignette describes all model terms available in
iglm (version 1.2.4) for specifying the sufficient
statistics of joint network-attribute models. Terms are passed on the
right-hand side of the formula argument in
iglm() and govern how individual attributes and network
connections jointly determine the log-linear probabilities of the
model.
A model in iglm decomposes its sufficient statistics
into two families:
The total sufficient statistic of the model is then \[ S(x, y, z) = \sum_i g_i(x_i, y_i) + \sum_{i \ne j} h_{i,j}(x, y, z). \]
Before presenting the individual terms, we introduce the notation used throughout this vignette.
Connection Indicators. Let \(z_{i,j} \in \{0,1\}\) denote the binary connection from unit \(i\) to unit \(j\), and let \(c_{i,j}\) indicate whether units \(i\) and \(j\) share a local neighbourhood (i.e., \(\mathbf{N}_i \cap \mathbf{N}_j \neq \emptyset\)).
s \(\in \{\texttt{global},\,
\texttt{local},\, \texttt{alocal}\}\): \[
e_{i,j}^{(\mathtt{s})} \;=\;
\begin{cases}
z_{i,j} & \text{if } \mathtt{s} = \texttt{global} \\
u_{i,j} & \text{if } \mathtt{s} = \texttt{local} \\
k_{i,j} & \text{if } \mathtt{s} = \texttt{alocal}
\end{cases}
\] > Note: For gwesp,
gwdsp, gwodegree, gwidegree,
edges_x_match, and edges_y_match, only
mode %in% c("global", "local") is implemented.Degree Statistics. For unit \(i \in \mathbf{P}\) and mode \(\mathtt{s} \in \{\texttt{global},\, \texttt{local}\}\):
Common Partners (CP). For a dyad \((i,j)\) and mode \(\mathtt{s}\):
Geometrically-Weighted Weight. The decay function used by geometrically weighted statistics is: \[ w_k(\alpha) = \exp(\alpha)\Bigl[1 - \bigl(1 - \exp(-\alpha)\bigr)^k\Bigr]. \]
Auxiliary Indicators.
These terms capture how individual predictors \(x_i\) (exogenous) and \(y_i\) (endogenous) relate to each other, without reference to the network.
attribute_xDescription: Intercept for the endogenous \(x\)-attribute.
\[ g_i(x_i, y_i) = x_i \]
attribute_yDescription: Intercept for the endogenous \(y\)-attribute.
\[ g_i(x_i, y_i) = y_i \]
cov_x(data = v)Description: Effect of a unit-level exogenous covariate \(v_i\) on attribute \(x_i\).
\[ g_i(x_i, y_i) = v_i\, x_i \]
cov_y(data = v)Description: Effect of a unit-level exogenous covariate \(v_i\) on attribute \(y_i\).
\[ g_i(x_i, y_i) = v_i\, y_i \]
attribute_xy(mode = "global" | "local" | "alocal")Description: Interaction between the two attributes \(x_i\) and \(y_i\), optionally mediated by the neighbourhood structure.
| Mode | Formula |
|---|---|
global |
\(x_i\, y_i\) |
local |
\(x_i \sum_{j \in \mathbf{N}_i} y_j + y_i \sum_{j \in \mathbf{N}_i} x_j\) |
alocal |
\(x_i \sum_{j \notin \mathbf{N}_i} y_j + y_i \sum_{j \notin \mathbf{N}_i} x_j\) |
These terms capture how the network topology \(z\) drives edge formation. All are pair-level statistics.
degreesDescription: Node-level degree fixed effects. One parameter per unit, capturing heterogeneity in activity not explained by other terms. Estimation relies on an MM algorithm constraint.
edges(mode = "global" | "local" | "alocal")Description: Baseline propensity for a tie \(z_{i,j}\) to form; the network analogue of an intercept.
\[ h_{i,j}(x, y, z) = e_{i,j}^{(\mathtt{s})} \]
Suitable for both directed and undirected networks.
formula <- object ~ edges(mode = "global")
formula <- object ~ edges(mode = "local")
formula <- object ~ edges(mode = "alocal")mutual(mode = "global" | "local" | "alocal")Description: Reciprocity in directed networks. Counts pairs where \(i \to j\) and \(j \to i\) both exist (counted once per unordered pair, hence the factor \(1/2\)).
\[ h_{i,j}(x, y, z) = \frac{e_{i,j}^{(\mathtt{s})}\, e_{j,i}^{(\mathtt{s})}}{2} \]
Only valid for directed networks.
cov_z(data = w, mode = "global" | "local" | "alocal")Description: Dyadic covariate — exogenous edge-level covariate \(w_{i,j}\) influences tie formation.
\[ h_{i,j}(x, y, z) = w_{i,j}\, e_{i,j}^{(\mathtt{s})} \]
Suitable for both directed and undirected networks.
cov_z_out(data = v, mode = "global" | "local" | "alocal")Description: Sender covariate — exogenous nodal attribute \(v_i\) influences the propensity to send a tie.
\[ h_{i,j}(x, y, z) = v_i\, e_{i,j}^{(\mathtt{s})} \]
Only valid for directed networks.
cov_z_in(data = v, mode = "global" | "local" | "alocal")Description: Receiver covariate — exogenous nodal attribute \(v_j\) influences the propensity to receive a tie.
\[ h_{i,j}(x, y, z) = v_j\, e_{i,j}^{(\mathtt{s})} \]
Only valid for directed networks.
isolatesDescription: Captures the proportion of units with no connections at all (total degree zero).
\[ h_{i,j}(x, y, z) = \mathbb{I}\!\left(\sum_{j \in \mathbf{P} \setminus \{i\}} z_{i,j} + z_{j,i} = 0\right) \]
Suitable for both directed and undirected networks.
nonisolatesDescription: Captures the proportion of units that have at least one connection.
\[ h_{i,j}(x, y, z) = \mathbb{I}\!\left(\sum_{j \in \mathbf{P} \setminus \{i\}} z_{i,j} + z_{j,i} \ne 0\right) \]
Suitable for both directed and undirected networks.
gwdegree(mode = "global" | "local", decay = α)Description: Geometrically Weighted Degree — captures the overall degree distribution with exponential decay parameter \(\alpha\).
\[ h_{i,j}(x, y, z) = w_{\operatorname{deg}(i)}(\alpha) + w_{\operatorname{deg}(j)}(\alpha) \]
Suitable for both directed and undirected networks. Only
mode %in% c("global", "local") is available.
gwodegree(mode = "global" | "local", decay = α)Description: Geometrically Weighted Out-Degree — captures the out-degree distribution in directed networks.
\[ h_{i,j}(x, y, z) = w_{\operatorname{deg}(i,\,\mathtt{s})}(\alpha) \]
Only valid for directed networks. Only
mode %in% c("global", "local") is available.
gwidegree(mode = "global" | "local", decay = α)Description: Geometrically Weighted In-Degree — captures the in-degree distribution in directed networks.
\[ h_{i,j}(x, y, z) = w_{\operatorname{ideg}(i,\,\mathtt{s})}(\alpha) \]
Only valid for directed networks. Only
mode %in% c("global", "local") is available.
transitiveDescription: Transitivity indicator — rewards edges that close a locally transitive triple.
\[ h_{i,j}(x, y, z) = d_{i,j}(\mathbf{z})\, z_{i,j} \]
Suitable for both directed and undirected networks.
gwesp_symm(mode = "global" | "local", decay = α)Description: Geometrically Weighted Edgewise Shared Partners (undirected) — the classic GWESP statistic for undirected networks.
\[ h_{i,j}(x, y, z) = e_{i,j}^{(\mathtt{s})}\, w_{\operatorname{CP}(i,j,\mathtt{s})}(\alpha) \]
Suitable for undirected networks only.
gwesp(mode = "global" | "local", type = "OTP" | "ISP" | "OSP" | "ITP", decay = α)Description: Geometrically Weighted Edgewise Shared Partners (directed) — conditions shared partners on a specific path type.
\[ h_{i,j}(x, y, z) = e_{i,j}^{(\mathtt{s})}\, w_{\operatorname{CP}(i,j,\mathtt{s},\mathtt{type})}(\alpha) \]
Only valid for directed networks. Only
mode %in% c("global", "local") is available.
gwdsp_symm(mode = "local", decay = α)Description: Geometrically Weighted Dyadwise Shared Partners (undirected) — models triadic potential irrespective of the closing edge.
\[ h_{i,j}(x, y, z) = w_{\operatorname{CP}(i,j,\mathtt{local})}(\alpha) \]
Suitable for undirected networks only.
gwdsp(mode = "global" | "local", type = "OTP" | "ISP" | "OSP" | "ITP", decay = α)Description: Geometrically Weighted Dyadwise Shared Partners (directed) — models directed triadic potential irrespective of the closing edge.
\[ h_{i,j}(x, y, z) = w_{\operatorname{CP}(i,j,\mathtt{s},\mathtt{type})}(\alpha) \]
Only valid for directed networks. Only
mode %in% c("global", "local") is available.
These terms capture the interplay between nodal attributes and network position. They are the key building blocks for studying spillover effects.
attribute_xz(mode = "local")Description: Additive effect of \(x_i\) and \(x_j\) on local edge formation.
\[ h_{i,j}(x, y, z) = (x_i + x_j)\, u_{i,j} \]
Suitable for both directed and undirected networks.
attribute_yz(mode = "local")Description: Additive effect of \(y_i\) and \(y_j\) on local edge formation.
\[ h_{i,j}(x, y, z) = (y_i + y_j)\, u_{i,j} \]
Suitable for both directed and undirected networks.
edges_x_match(mode = "global" | "local")Description: Homophily on \(x\) — rewards edges between units with equal \(x\)-values.
\[ h_{i,j}(x, y, z) = \mathbb{I}(x_i = x_j)\, e_{i,j}^{(\mathtt{s})} \]
Suitable for both directed and undirected networks.
edges_y_match(mode = "global" | "local")Description: Homophily on \(y\) — rewards edges between units with equal \(y\)-values.
\[ h_{i,j}(x, y, z) = \mathbb{I}(y_i = y_j)\, e_{i,j}^{(\mathtt{s})} \]
Suitable for both directed and undirected networks.
outedges_x(mode = "global" | "local" | "alocal")Description: Effect of sender attribute \(x_i\) on out-degree formation.
\[ h_{i,j}(x, y, z) = x_i\, e_{i,j}^{(\mathtt{s})} \]
Only valid for directed networks.
inedges_x(mode = "global" | "local" | "alocal")Description: Effect of receiver attribute \(x_j\) on in-degree reception.
\[ h_{i,j}(x, y, z) = x_j\, e_{i,j}^{(\mathtt{s})} \]
Only valid for directed networks.
outedges_y(mode = "global" | "local" | "alocal")Description: Effect of sender attribute \(y_i\) on out-degree formation.
\[ h_{i,j}(x, y, z) = y_i\, e_{i,j}^{(\mathtt{s})} \]
Only valid for directed networks.
inedges_y(mode = "global" | "local" | "alocal")Description: Effect of receiver attribute \(y_j\) on in-degree reception.
\[ h_{i,j}(x, y, z) = y_j\, e_{i,j}^{(\mathtt{s})} \]
Only valid for directed networks.
spillover_xx(mode = "local")Description: Symmetric \(x\)-to-\(x\) spillover — the product \(x_i x_j\) along local connections, capturing peer effects in the \(x\) attribute.
\[ h_{i,j}(x, y, z) = x_i\, x_j\, u_{i,j} \]
Suitable for both directed and undirected networks.
spillover_xx_scaled(mode = "global" | "local")Description: Degree-normalised \(x\)-to-\(x\) spillover, accounting for the number of neighbours.
\[ h_{i,j}(x, y, z) = \left(\frac{x_i\, x_j}{\operatorname{deg}(i,\mathtt{s})} + \frac{x_j\, x_i}{\operatorname{deg}(j,\mathtt{s})}\,\mathbb{I}_U(\mathbf{z})\right) e_{i,j}^{(\mathtt{s})} \]
Suitable for both directed and undirected networks.
spillover_yy(mode = "local")Description: Symmetric \(y\)-to-\(y\) spillover — the product \(y_i y_j\) along local connections.
\[ h_{i,j}(x, y, z) = y_i\, y_j\, u_{i,j} \]
Suitable for both directed and undirected networks.
spillover_yy_scaled(mode = "global" | "local")Description: Degree-normalised \(y\)-to-\(y\) spillover.
\[ h_{i,j}(x, y, z) = \left(\frac{y_i\, y_j}{\operatorname{deg}(i,\mathtt{s})} + \frac{y_j\, y_i}{\operatorname{deg}(j,\mathtt{s})}\,\mathbb{I}_U(\mathbf{z})\right) e_{i,j}^{(\mathtt{s})} \]
Suitable for both directed and undirected networks.
spillover_xy(mode = "local")Description: Symmetric cross-attribute spillover — \(x_i \to y_j\) and \(x_j \to y_i\) along local connections. For undirected networks both directions are summed.
\[ h_{i,j}(x, y, z) = x_i\, y_j\, u_{i,j} + x_j\, y_i\, u_{i,j}\, \mathbb{I}_U(\mathbf{z}) \]
Suitable for both directed and undirected networks.
spillover_xy_scaled(mode = "global" | "local")Description: Degree-normalised symmetric cross-attribute spillover (\(x \to y\)).
\[ h_{i,j}(x, y, z) = \left(\frac{x_i\, y_j}{\operatorname{deg}(i,\mathtt{s})} + \frac{x_j\, y_i}{\operatorname{deg}(j,\mathtt{s})}\,\mathbb{I}_U(\mathbf{z})\right) e_{i,j}^{(\mathtt{s})} \]
Suitable for both directed and undirected networks.
spillover_yx(mode = "local")Description: Directed cross-attribute spillover — \(y_i \to x_j\) only (no symmetrisation). Only for directed networks.
\[ h_{i,j}(x, y, z) = y_i\, x_j\, u_{i,j} \]
Only valid for directed networks.
spillover_yx_scaled(mode = "global" | "local")Description: Degree-normalised cross-attribute spillover (\(y \to x\)), with symmetrisation for undirected networks.
\[ h_{i,j}(x, y, z) = \left(\frac{y_i\, x_j}{\operatorname{deg}(i,\mathtt{s})} + \frac{y_j\, x_i}{\operatorname{deg}(j,\mathtt{s})}\,\mathbb{I}_U(\mathbf{z})\right) e_{i,j}^{(\mathtt{s})} \]
Suitable for both directed and undirected networks.
spillover_yc(mode = "local", data = v)Description: Interaction of endogenous attribute \(y\) with exogenous covariate \(v\) along overlapping connections, with symmetrisation for undirected networks.
\[ h_{i,j}(x, y, z) = c_{i,j}\bigl(v_j\, y_i + \mathbb{I}_U(\mathbf{z})\, v_i\, y_j\bigr)\, z_{i,j} \]
Suitable for both directed and undirected networks.
The table below summarises all terms, their mathematical definitions, and whether they support undirected networks.
| Term | Definition | Undirected |
|---|---|---|
attribute_x |
\(x_i\) | ✓ |
attribute_y |
\(y_i\) | ✓ |
cov_x |
\(v_i\, x_i\) | ✓ |
cov_y |
\(v_i\, y_i\) | ✓ |
attribute_xy(mode = "global") |
\(x_i\, y_i\) | ✓ |
attribute_xy(mode = "local") |
\(x_i \sum_{j \in \mathbf{N}_i} y_j + y_i \sum_{j \in \mathbf{N}_i} x_j\) | ✓ |
attribute_xy(mode = "alocal") |
\(x_i \sum_{j \notin \mathbf{N}_i} y_j + y_i \sum_{j \notin \mathbf{N}_i} x_j\) | ✓ |
degrees |
Degree fixed effects | ✓ |
edges(mode = "s") |
\(e_{i,j}^{(\mathtt{s})}\) | ✓ |
mutual(mode = "s") |
\(e_{i,j}^{(\mathtt{s})}\,e_{j,i}^{(\mathtt{s})}/2\) | ✗ |
cov_z(mode = "s") |
\(w_{i,j}\, e_{i,j}^{(\mathtt{s})}\) | ✓ |
cov_z_out(mode = "s") |
\(v_i\, e_{i,j}^{(\mathtt{s})}\) | ✗ |
cov_z_in(mode = "s") |
\(v_j\, e_{i,j}^{(\mathtt{s})}\) | ✗ |
isolates |
\(\mathbb{I}(\sum_j z_{i,j}+z_{j,i}=0)\) | ✓ |
nonisolates |
\(\mathbb{I}(\sum_j z_{i,j}+z_{j,i}\ne 0)\) | ✓ |
gwdegree(mode = "global") |
\(w_{\deg(i)}(\alpha)+w_{\deg(j)}(\alpha)\) | ✓ |
gwodegree(mode = "s") |
\(w_{\deg(i,\mathtt{s})}(\alpha)\) | ✗ |
gwidegree(mode = "s") |
\(w_{\operatorname{ideg}(i,\mathtt{s})}(\alpha)\) | ✗ |
transitive |
\(d_{i,j}(\mathbf{z})\,z_{i,j}\) | ✓ |
gwesp_symm(mode = "s") |
\(e_{i,j}^{(\mathtt{s})}\,w_{\operatorname{CP}(i,j,\mathtt{s})}(\alpha)\) | ✓ |
gwesp(mode = "s", type = "…") |
\(e_{i,j}^{(\mathtt{s})}\,w_{\operatorname{CP}(i,j,\mathtt{s},\mathtt{type})}(\alpha)\) | ✗ |
gwdsp_symm(mode = "local") |
\(w_{\operatorname{CP}(i,j,\mathtt{local})}(\alpha)\) | ✓ |
gwdsp(mode = "s", type = "…") |
\(w_{\operatorname{CP}(i,j,\mathtt{s},\mathtt{type})}(\alpha)\) | ✗ |
attribute_xz(mode = "local") |
\((x_i+x_j)\,u_{i,j}\) | ✓ |
attribute_yz(mode = "local") |
\((y_i+y_j)\,u_{i,j}\) | ✓ |
edges_x_match(mode = "s") |
\(\mathbb{I}(x_i=x_j)\,e_{i,j}^{(\mathtt{s})}\) | ✓ |
edges_y_match(mode = "s") |
\(\mathbb{I}(y_i=y_j)\,e_{i,j}^{(\mathtt{s})}\) | ✓ |
outedges_x(mode = "s") |
\(x_i\,e_{i,j}^{(\mathtt{s})}\) | ✗ |
inedges_x(mode = "s") |
\(x_j\,e_{i,j}^{(\mathtt{s})}\) | ✗ |
outedges_y(mode = "s") |
\(y_i\,e_{i,j}^{(\mathtt{s})}\) | ✗ |
inedges_y(mode = "s") |
\(y_j\,e_{i,j}^{(\mathtt{s})}\) | ✗ |
spillover_xx(mode = "local") |
\(x_i\,x_j\,u_{i,j}\) | ✓ |
spillover_xx_scaled(mode = "s") |
\(\left(\frac{x_i x_j}{\deg(i,\mathtt{s})}+\frac{x_j x_i}{\deg(j,\mathtt{s})}\mathbb{I}_U\right)e_{i,j}^{(\mathtt{s})}\) | ✓ |
spillover_yy(mode = "local") |
\(y_i\,y_j\,u_{i,j}\) | ✓ |
spillover_yy_scaled(mode = "s") |
\(\left(\frac{y_i y_j}{\deg(i,\mathtt{s})}+\frac{y_j y_i}{\deg(j,\mathtt{s})}\mathbb{I}_U\right)e_{i,j}^{(\mathtt{s})}\) | ✓ |
spillover_xy(mode = "local") |
\(x_i\,y_j\,u_{i,j}+x_j\,y_i\,u_{i,j}\,\mathbb{I}_U\) | ✓ |
spillover_xy_scaled(mode = "s") |
\(\left(\frac{x_i y_j}{\deg(i,\mathtt{s})}+\frac{x_j y_i}{\deg(j,\mathtt{s})}\mathbb{I}_U\right)e_{i,j}^{(\mathtt{s})}\) | ✓ |
spillover_yx(mode = "local") |
\(y_i\,x_j\,u_{i,j}\) | ✗ |
spillover_yx_scaled(mode = "s") |
\(\left(\frac{y_i x_j}{\deg(i,\mathtt{s})}+\frac{y_j x_i}{\deg(j,\mathtt{s})}\mathbb{I}_U\right)e_{i,j}^{(\mathtt{s})}\) | ✓ |
spillover_yc(mode = "local") |
\(c_{i,j}(v_j\,y_i+\mathbb{I}_U\,v_i\,y_j)\,z_{i,j}\) | ✓ |
The example below illustrates how several terms from all three categories can be combined in a single formula for a directed network:
n_actor <- 100
# Simulate attributes and neighbourhood
set.seed(42)
attribute_info <- rnorm(n_actor)
block <- matrix(1, nrow = 10, ncol = 10)
neighborhood <- as.matrix(Matrix::bdiag(replicate(10, block, simplify = FALSE)))
object <- iglm.data(
neighborhood = neighborhood,
directed = TRUE,
type_x = "binomial",
type_y = "binomial",
n_actor = n_actor
)
# Formula combining attribute, network, and spillover terms
formula <- object ~
# Category 1: attribute dependence
attribute_x + attribute_y +
# Category 2: network dependence
edges(mode = "local") + mutual(mode = "local") +
gwodegree(mode = "global", decay = 0.5) +
gwesp(mode = "global", type = "OTP", decay = 0.5) +
# Category 3: joint attribute/network dependence
edges_x_match(mode = "local") +
outedges_y(mode = "local") +
spillover_yy_scaled(mode = "local")For further details on model fitting, simulation, and assessment see
vignette("iglm") and ?iglm-terms.
Fritz, C., Schweinberger, M., Bhadra, S., and D.R. Hunter (2025). A Regression Framework for Studying Relationships among Attributes under Network Interference. Journal of the American Statistical Association, to appear. doi:10.1080/01621459.2025.2565851
Schweinberger, M. and M.S. Handcock (2015). Local Dependence in Random Graph Models: Characterization, Properties, and Statistical Inference. Journal of the Royal Statistical Society, Series B, 7, 647–676.
Schweinberger, M. and J.R. Stewart (2020). Concentration and Consistency Results for Canonical and Curved Exponential-Family Models of Random Graphs. The Annals of Statistics, 48, 374–396.