model.terms: Model specification for a `iglm' object

Description

R package iglm implements generalized linear models (GLMs) for studying relationships among attributes in connected populations, where responses of connected units can be dependent. It extends GLMs for independent responses to dependent responses and can be used for studying spillover in connected populations and other network-mediated phenomena. It is based on a joint probability model for dependent responses ($Y$) and connections $(Z)$ conditional on predictors (X).

The joint probability density is specified as $$f_{\theta}(y,z,x) \propto \Big[\prod_{i=1}^{N} a_y(y_i) \exp(\theta_g^T g_i(x_i, y_i^*)) \Big] \times \Big[\prod_{i \ne j} a_z(z_{i,j}) \exp(\theta_h^T h_{i,j}(x, y_i^*, y_j^*, z)) \Big],$$ which is defined by two distinct sets of user-specified features:

$g_i(x,y,z)$: A vector of unit-level functions (or "g-terms") that describe the relationship between an individual actor $i$'s predictors ($x_i$) and their own response ($y_i$).
$h_{i,j}(x,y,z)$: A vector of pair-level functions (or "h-terms") that specify how the connections ($z$) and responses ($y_i, y_j$) of a pair of units $\{i,j\}$ depend on each other and the wider network structure.

This separation allows the model to simultaneously capture individual-level behavior (via $g_i$) and dyadic, network-based dependencies (via $h_{i,j}$), including local dependence limited to overlapping neighborhoods. This help page documents the various statistics available in 'iglm', corresponding to the $g_i$ (attribute-level) and $h_{i,j}$ (pair-level) components of the joint model. In the formula interface, these terms can be specified by adding them in the right-hand side of a model formula, e.g., iglm.data ~ attribute_x + edges(mode = "local") + popularity, .... See the documentation for iglm for details on model fitting and estimation.

Arguments

Details

Each term defines a component for the model's features, which are a sum of unit-level components, $\sum_i g_i(x,y,z)$, and/or pair-level components, $\sum_{i \ne j} h_{i,j}(x,y,z)$. Here, $x_i$ and $y_i$ are the attributes for actor $i$, and $z_{i,j}$ indicates the presence (1) or absence (0) of a tie from actor $i$ to actor $j$. The local neighborhood of actor $i$ is denoted $\mathcal{N}_i$, and the indicator for whether actors $i$ and $j$ share a local neighborhood is given by $c_{i,j} = \mathbb{I}(\mathcal{N}_i \cap \mathcal{N}_j \neq \emptyset)$. The functions below specify the forms of $g_i(x,y,z)$ and $h_{i,j}(x,y,z)$ for each term. Some terms also depend on other covariates, which are denoted by $v = (v_1, ..., v_N)$ (unit-level) and $w = (w_{i,j}) \in \mathbb{R}^{N \times N}$(dyadic). These covariates must be provided by the user via the data argument. The implemented terms are grouped into three categories:

$g_i$ terms for attribute dependence,
$h_{i,j}$ terms for network dependence,
$h_{i,j}$ Terms for joint attribute/network dependence.

1. $g_i$ Terms for Attribute Dependence

attribute_x

Attribute (X) [g-term]: Intercept for attribute 'x'. $g_i(x,y,z) = x_i$

attribute_y

Attribute (Y) [g-term]: Intercept for attribute 'y'. $g_i(x,y,z) = y_i$

cov_x

Nodal Covariate (X) [g-term]: Effect of a unit-level covariate $v_i$ on attribute $x_i$. $g_i(x,y,z) = v_i x_i$

cov_y(data = v)

Nodal Covariate (Y) [g-term]: Effect of a unit-level covariate $v_i$ on attribute $y_i$. $g_i(x,y,z) = v_i y_i$

attribute_xy(mode = "global")

Nodal Attribute Interaction (X-Y) [g-term]: Interaction of attributes $x_i$ and $y_i$ on the same node. For mode different from "global", we count interactions of an actor's attributes with their local neighbors' attributes.

global: $g_i(x,y,z) = x_i y_i$
local: $g_i(x,y,z) = x_i \sum_{j \in \mathcal{N}_i} y_j + y_i \sum_{j \in \mathcal{N}_i} x_j$
alocal: $g_i(x,y,z) = x_i \sum_{j \notin \mathcal{N}_i} y_j + y_i \sum_{j \notin \mathcal{N}_i} x_j$

2. $h_{i,j}$ Terms for Network Dependence

popularity

Popularity [h-term]: Adds fixed effects for all actors in the network. Estimation of popularity effects is carried out using a MM algorithm. For directed networks, each actors has a sender and receiver effect (we assume that the out effect of actor N is 0 for identifiability). For undirected networks, each actor has a single popularity effect.

edges(mode = "global")

Edges [h-term]: Counts different types of edges.

global: $h_{i,j}(x,y,z) = z_{i,j}$
local: $h_{i,j}(x,y,z) = c_{i,j} z_{i,j}$
alocal: $h_{i,j}(x,y,z) = (1 - c_{i,j}) z_{i,j}$

mutual(mode = "global")

Mutual Reciprocity [h-term]: Counts whether the reciprocal tie between actors $i$ and $j$ is present. This term should only be used for directed networks.

global: $h_{i,j}(x,y,z) = z_{i,j} z_{j,i}$ (for $i < j$)
local: $h_{i,j}(x,y,z) = c_{i,j} z_{i,j} z_{j,i}$ (for $i < j$)
alocal: $h_{i,j}(x,y,z) = (1 - c_{i,j}) z_{i,j} z_{j,i}$ (for $i < j$)

cov_z(data, mode = "global")

Dyadic Covariate [h-term]: The effect of a dyadic covariate $w_{i,j}$ for directed or undirected networks.

global: $h_{i,j}(x,y,z) = w_{i,j} z_{i,j}$
local: $h_{i,j}(x,y,z) = c_{i,j} w_{i,j} z_{i,j}$
alocal: $h_{i,j}(x,y,z) = (1 - c_{i,j}) w_{i,j} z_{i,j}$

isolates

Isolates [z-term]: Counts and accounts for the number of non-isolated nodes.

nonisolates

Non-Isolates [z-term]: Counts and accounts for the number of non-isolated nodes. It is the exact negative of the isolates statistic.

gwodegree(decay)

Geometrically Weighted Out-Degree [z-term]: The Geometrically Weighted Out-Degree statistic is implemented as in the `ergm` package.

gwidegree(decay)

Geometrically Weighted In-Degree [z-term]: The Geometrically Weighted In-Degree (GWIDegree) statistic is implemented as in the `ergm` package.

gwesp(data, mode = "global", variant = "OTP")

Geometrically Weighted Edegewise-Shared Partners [h-term]: Geometrically weighted edgewise shared partners (GWESP) statistic for directed networks as implemented in the `ergm` package. Variants include: OTP (outgoing two-paths, $z_{i,h}\,z_{h,j}\, z_{i,j}$), ITP (incoming two-paths, $z_{h,i}\,z_{j,h}\, z_{i,j}$), OSP (outgoing shared partners, $z_{i,h}\,z_{j,h}\, z_{i,j}$), ISP (incoming shared partners, $z_{h,i}\,z_{h,j}\, z_{i,j}$).

global: ESP counts are calculated over all edges in the network.
local: ESP counts are restricted to local edges only (edges with non-overlapping neighborhoods).

gwdsp(data, mode = "global", variant = "OTP")

Geometrically Weighted Dyadwise-Shared Partners [h-term]: Geometrically weighted dyadwise shared partners (GWDSP) statistic for directed networks as implemented in the `ergm` package. Variants include: OTP (outgoing two-paths, $z_{i,h}\,z_{h,j}$), ITP (incoming two-paths, $z_{h,i}\,z_{j,h}$), OSP (outgoing shared partners, $z_{i,h}\,z_{j,h}$), ISP (incoming shared partners, $z_{h,i}\,z_{h,j}$).

global: ESP counts are calculated over all edges in the network.
local: ESP counts are restricted to local edges only (edges with non-overlapping neighborhoods).

cov_z_out(data, mode = "global")

Covariate Sender [h-term]: The effect of a monadic covariate $v_{i}$ on being the sender in a directed network.

global: $h_{i,j}(x,y,z) = v_i z_{i,j}$
local: $h_{i,j}(x,y,z) = c_{i,j} v_i z_{i,j}$
alocal: $h_{i,j}(x,y,z) = (1 - c_{i,j}) v_i z_{i,j}$

cov_z_in(data, mode = "global")

Covariate Receiver [h-term]: The effect of a monadic covariate $v_{i}$ on being the receiver in a directed network.

global: $h_{i,j}(x,y,z) = v_j z_{i,j}$
local: $h_{i,j}(x,y,z) = c_{i,j} v_j z_{i,j}$
alocal: $h_{i,j}(x,y,z) = (1 - c_{i,j}) v_j z_{i,j}$

transitive

Transitivity (Local) [Joint]: A statistic checking whether the dyad is a local transitive edge, meaning that there exists an actor $h \neq i,j$ such that $h\in \mathcal{N}_i, h\in \mathcal{N}_j$ with $z_{i,j} = z_{i,h} = z_{h,j}$: $h_{i,j} = c_{i,j} z_{i,j} \mathbb{I}(\sum_{k} c_{i,k} c_{j,k} z_{i,k} z_{k,j}>1)$

3. $h_{i,j}$ Terms for Joint Attribute/Network Dependence

outedges_x_global()

Attribute Out-Degree (X-Z Global) [h-term]: Models $x_i$'s effect on its out-degree. Corresponds to $h_{i,j}(x,y,z) = x_i z_{i,j}$.

outedges_x(mode = "global")

Attribute Out-Degree (X-Z) [Joint h-term]: Models $x_i$'s effect on its out-degree.

global: $h_{i,j}(x,y,z) = x_i z_{i,j}$
local: $h_{i,j}(x,y,z) = c_{i,j} x_i z_{i,j}$
alocal: $h_{i,j}(x,y,z) = (1 - c_{i,j}) x_i z_{i,j}$

inedges_x(mode = "global")

Attribute In-Degree (X-Z) [Joint h-term]: Models $x_j$'s effect on its in-degree.

global: $h_{i,j}(x,y,z) = x_j z_{i,j}$
local: $h_{i,j}(x,y,z) = c_{i,j} x_j z_{i,j}$
alocal: $h_{i,j}(x,y,z) = (1 - c_{i,j}) x_j z_{i,j}$

outedges_y(mode = "global")

Attribute Out-Degree (Y-Z) [Joint h-term]: Models $y_i$'s effect on its out-degree.

global: $h_{i,j}(x,y,z) = y_i z_{i,j}$
local: $h_{i,j}(x,y,z) = c_{i,j} y_i z_{i,j}$
alocal: $h_{i,j}(x,y,z) = (1 - c_{i,j}) y_i z_{i,j}$

inedges_y(mode = "global")

Attribute In-Degree (Y-Z) [Joint h-term]: Models $y_j$'s effect on its in-degree.

global: $h_{i,j}(x,y,z) = y_j z_{i,j}$
local: $h_{i,j}(x,y,z) = c_{i,j} y_j z_{i,j}$
alocal: $h_{i,j}(x,y,z) = (1 - c_{i,j}) y_j z_{i,j}$

spillover_xx

Symmetric X-X-Z Outcome Spillover [h-term]: Models $x$-outcome spillover within the local neighborhood. Corresponds to $h_{i,j}(x,y,z) = c_{i,j} x_i x_j z_{i,j}$.

spillover_xx_scaled

X-X-Z Outcome Spillover [h-term]: Models $x$-outcome spillover within the local neighborhood but weights the influence of $x_j$ on $x_i$ by the out-degree of actor $i$ with other actors in its neighborhood, denoted by $\text{local\_degree(i)} (for undirected networks, the degree is used)$. Corresponds to $h_{i,j}(x,y,z) = c_{i,j} x_i x_j z_{i,j} / \text{local\_degree(i)}$.

spillover_yy

Symmetric Y-Y-Z Outcome Spillover [h-term]: Models $y$-outcome spillover within the local neighborhood. Corresponds to $h_{i,j}(x,y,z) = c_{i,j} y_i y_j z_{i,j}$.

spillover_yy_scaled

Y-Y-Z Outcome Spillover [h-term]: Models $y$-outcome spillover within the local neighborhood but weights the influence of $y_j$ on $y_i$ by the degree of actor $i$ with other actors in its neighborhood, defined above. Corresponds to $h_{i,j}(x,y,z) = c_{i,j} y_i y_j z_{i,j} / \text{local\_degree(i)}$.

spillover_xy

Directed X-Y-Z Treatment Spillover [h-term]: Models the $x_i \to y_j$ treatment spillover within the local neighborhood. Corresponds to $h_{i,j}(x,y,z) = c_{i,j} x_i y_j z_{i,j}$.

spillover_xy_scaled

X-Y-Z Outcome Spillover [h-term]: Models the $x_i \to y_j$ treatment spillover within the local neighborhood but weights the influence of $y_j$ on $x_i$ by the degree of actor $i$ with other actors in its neighborhood, defined above. Corresponds to $h_{i,j}(x,y,z) = c_{i,j} x_i y_j z_{i,j} / \text{local\_degree(i)}$.

spillover_xy_symm

Symmetric X-Y-Z Treatment Spillover [h-term]: Models the $x_i \leftrightarrow y_j$ treatment spillover within the local neighborhood. Corresponds to $h_{i,j}(x,y,z) = c_{i,j} (x_i y_j + x_j y_i) z_{i,j}$.

spillover_yx

Directed Y-X-Z Treatment Spillover [h-term]: Models the $y_i \to x_j$ treatment spillover within the local neighborhood. Corresponds to $h_{i,j}(x,y,z) = c_{i,j} y_i x_j z_{i,j}$.

spillover_yx_scaled

Y-X-Z Outcome Spillover [h-term]: Models the $y_i \to x_j$ treatment spillover within the local neighborhood but weights the influence of $x_j$ on $y_i$ by the degree of actor $i$ with other actors in its neighborhood, defined above. Corresponds to $h_{i,j}(x,y,z) = c_{i,j} y_i x_j z_{i,j} / \text{local\_degree(i)}$.

spillover_yc

Directed Y-C-Z Treatment Spillover [h-term]: Models $y$-treat spillover to a covariate $v$ within the local neighborhood. Corresponds to $h_{i,j}(x,y,z) = c_{i,j} y_i v_j z_{i,j}$.

spillover_yc_symm(data = v)

Symmetric Treatment Spillover [h-term]: Models the $v_i \leftrightarrow y_j $ treatment spillover . Corresponds to $h_{i,j}(x,y,z) = c_{i,j} (v_i y_j + v_j y_i) z_{i,j}$.

References

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.

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 (Statistical Methodology), 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.

Stewart, J.R. and M. Schweinberger (2025). Pseudo-Likelihood-Based M-Estimation of Random Graphs with Dependent Edges and Parameter Vectors of Increasing Dimension. The Annals of Statistics, to appear.