Set Control Parameters for iglm Estimation

Description

Create a list of control parameters for the 'iglm' estimation algorithm.

Usage

control.iglm(
  estimate_model = TRUE,
  display_progress = FALSE,
  return_samples = TRUE,
  offset_nonoverlap = 0,
  var_method = "Mean-value",
  non_stop = FALSE,
  tol = 0.001,
  max_it = 100,
  return_x = FALSE,
  return_y = FALSE,
  return_z = FALSE,
  accelerated = TRUE,
  exact = TRUE
)

Arguments

Value

A list object of class '"control.iglm"' containing the specified control parameters.

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.

Schmid, C.S. and D. R. Hunter (2023). Computing Pseudolikelihood Estimators for Exponential-Family Random Graph Models. Journal of Data Science

Copenhagen Network Study

Description

A preprocessed dataset containing social ties, physical proximity, and nodal attributes for a subset of participants in the Copenhagen Networks Study. The object is provided as an iglm.data class.

Usage

data(copenhagen)

Format

The iglm.data provides the following information:

z_network

A E \times 2 integer matrix representing the undirected friendship network ($Z$).

x_attribute

A logical/binomial vector of length N indicating gender (1 for female, 0 for male).

y_attribute

A numeric vector of length N representing the log-transformed total call duration in minutes: y_i = \log(\frac{\text{seconds}}{60}).

neighborhood

A matrix defining the proximity-based constraint space. Pairs are included if their cumulative physical proximity exceeded 24 hours during the observation period.

fix_x

Boolean TRUE, indicating that the x attribute is treated as exogenous.

Details

The following preprocessing steps were carried out:

• Temporal Aggregation: Proximity data (Bluetooth scans) were aggregated into sessions. A session break was defined by any temporal gap exceeding 10 minutes.

• Recursive Pruning: A recursive filter removed actors with missing gender information or isolated actors in either the friendship (z_network) or proximity (neighborhood) networks,

References

Sapiezynski, P., Stopczynski, A., Lassen, D. D. and Lehmann, S. (2019), Interaction data from the Copenhagen Networks Study. Scientific Data 6(1), 315.

Generate the Skeleton for an R package to implement additional iglm terms

Description

This function generates the directory structure and source files for a new R package named iglm.userterms (or whatever name is provided in the parameter pkg_name). This auxiliary package serves as a template for extending the iglm framework to user-defined sufficient statistics. By compiling this package, users can link custom C++ implementations of change statistics directly with the iglm package, enabling seamless integration of new model terms.

Usage

create_userterms_skeleton(path = ".", pkg_name = "iglm.userterms")

Arguments

Details

The function creates a directory with the name specified in pkg_name at the specified location. As an example for a possible statistic, the statistic counting mutual connections in the network is implemented. After defining all possible change-statistics in the c++ function (this has to include a change for z_ij (network), x_i (attribute x), and y_i (attribute y) all toggling from 0 to 1), the function has to be registered using the EFFECT_REGISTER macro. After compiling the package, users have to load the package using library(pkg_name) before using it in iglm.

Construct a iglm Model Specification 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).

Usage

iglm(
  formula = NULL,
  coef = NULL,
  coef_degrees = NULL,
  sampler = NULL,
  control = NULL,
  name = NULL,
  file = NULL
)

Arguments

Value

An object of class iglm.object.

Model Formulation

The joint probability density is specified as

f_{\theta}(y,z,x) \propto \Big[\prod_{i=1}^{N} a_x(x_i)\, a_y(y_i) \exp(\theta_g^T \mathbf{g}_i(x_i^*, y_i^*)) \Big] \times \Big[\prod_{i \ne j} a_z(z_{i,j}) \exp(\theta_h^T \mathbf{h}_{i,j}(x_i^*,x_j^*, y_i^*, y_j^*, z)) \Big],

which is defined by two distinct sets of user-specified features:

• \mathbf{g}_i(x_i^*, y_i^*)= (g_i(x_i^*, y_i^*)): 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).

• \mathbf{h}_{i,j}(x_i^*,x_j^*, y_i^*, y_j^*, z)= (h_{i,j}(x_i^*,x_j^*, y_i^*, y_j^*, 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. See model.terms for details on specifying all model terms via the formula interface.

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.

Examples

# Example usage:
library(iglm)
# Create a iglm.data data object (example)
n_actor <- 50
neighborhood <- matrix(1, nrow = n_actor, ncol = n_actor)
xyz_obj <- iglm.data(
  neighborhood = neighborhood, directed = FALSE,
  type_x = "binomial", type_y = "binomial"
)
# Define ground truth coefficients
gt_coef <- c("edges_local" = 3, "attribute_y" = -1, "attribute_x" = -1)
gt_coef_pop <- rnorm(n = n_actor, -2, 1)
# Define MCMC sampler
sampler_new <- sampler.iglm(
  n_burn_in = 100, n_simulation = 10,
  sampler_x = sampler.net.attr(n_proposals = n_actor * 10, seed = 13),
  sampler_y = sampler.net.attr(n_proposals = n_actor * 10, seed = 32),
  sampler_z = sampler.net.attr(n_proposals = sum(neighborhood > 0) * 10, seed = 134),
  init_empty = FALSE
)
# Create iglm model specification
model_tmp_new <- iglm(
  formula = xyz_obj ~ edges(mode = "local") +
    attribute_y + attribute_x + degrees,
  coef = gt_coef,
  coef_degrees = gt_coef_pop,
  sampler = sampler_new,
  control = control.iglm(
    accelerated = FALSE,
    max_it = 200, display_progress = FALSE
  )
)
# Simulate from the model
model_tmp_new$simulate()
model_tmp_new$set_target(model_tmp_new$get_samples()[[1]])

# Estimate model parameters
model_tmp_new$estimate()

# Model Assessment
model_tmp_new$assess(formula = ~degree_distribution)
# model_tmp_new$results$plot(assess = TRUE)

Constructor for the iglm.data R6 object

Description

Creates a 'iglm.data' object, which stores network and attribute data. This function acts as a user-friendly interface to the 'iglm.data' R6 class generator. It handles data input, infers parameters like the number of actors ('n_actor') and network directedness ('directed') if not explicitly provided, processes network data into a consistent edgelist format, calculates the overlap relation based on an optional neighborhood definition, and performs extensive validation of all inputs.

Usage

iglm.data(
  x_attribute = NULL,
  y_attribute = NULL,
  z_network = NULL,
  neighborhood = NULL,
  directed = TRUE,
  n_actor = NA,
  type_x = "binomial",
  type_y = "binomial",
  scale_x = 1,
  scale_y = 1,
  fix_x = FALSE,
  fix_z = FALSE,
  fix_z_alocal = FALSE,
  return_neighborhood = TRUE,
  file = NULL
)

Arguments

Value

An object of class 'iglm.data' (and 'R6').

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.

Daraganova, G., and Robins, G. (2013). Exponential random graph models for social networks: Theory, methods and applications, 102-114. Cambridge University Press.

Examples

data("state_twitter")
state_twitter
state_twitter$iglm.data$degree_distribution(prob = FALSE, plot = TRUE)
state_twitter$iglm.data$geodesic_distances_distribution(prob = FALSE, plot = TRUE)
state_twitter$iglm.data$mean_x()
state_twitter$iglm.data$mean_y()


# Generate a small iglm data object either via adjacency matrix or edgelist
tmp_adjacency <- iglm.data(
  z_network = matrix(c(
    0, 1, 1, 0,
    1, 0, 0, 1,
    1, 0, 0, 1,
    0, 1, 1, 0
  ), nrow = 4, byrow = TRUE),
  directed = FALSE,
  n_actor = 4,
  type_x = "binomial",
  type_y = "binomial"
)


tmp_edgelist <- iglm.data(
  z_network = tmp_adjacency$z_network,
  directed = FALSE,
  n_actor = 4,
  type_x = "binomial",
  type_y = "binomial"
)

tmp_edgelist$mean_z()
tmp_adjacency$mean_z()

A R6 class to represent networks with unit-level attributes

Description

The 'iglm.data' class is a container for storing, validating, and analyzing unit-level attributes (x_attribute, y_attribute) and connections (z_network).

Active bindings

Methods

Public methods

• iglm.data_generator$new()

• iglm.data_generator$set_z_network()

• iglm.data_generator$set_type_x()

• iglm.data_generator$set_type_y()

• iglm.data_generator$set_scale_x()

• iglm.data_generator$set_scale_y()

• iglm.data_generator$set_x_attribute()

• iglm.data_generator$set_y_attribute()

• iglm.data_generator$gather()

• iglm.data_generator$set_fix_z_alocal()

• iglm.data_generator$delete_isolates()

• iglm.data_generator$save()

• iglm.data_generator$set_fix_x()

• iglm.data_generator$set_fix_z()

• iglm.data_generator$mean_z()

• iglm.data_generator$mean_x()

• iglm.data_generator$mean_y()

• iglm.data_generator$x_distribution()

• iglm.data_generator$y_distribution()

• iglm.data_generator$edgewise_shared_partner()

• iglm.data_generator$set_neighborhood_overlap()

• iglm.data_generator$dyadwise_shared_partner()

• iglm.data_generator$geodesic_distances_distribution()

• iglm.data_generator$geodesic_distances()

• iglm.data_generator$edgewise_shared_partner_distribution()

• iglm.data_generator$dyadwise_shared_partner_distribution()

• iglm.data_generator$degree_distribution()

• iglm.data_generator$degree()

• iglm.data_generator$spillover_degree_distribution()

• iglm.data_generator$plot()

• iglm.data_generator$print()

• iglm.data_generator$clone()

Method new()

Create a new 'iglm.data' object, that includes data on two attributes and one network.

Usage

iglm.data_generator$new(
  x_attribute = NULL,
  y_attribute = NULL,
  z_network = NULL,
  neighborhood = NULL,
  directed = NA,
  n_actor = NA,
  type_x = "binomial",
  type_y = "binomial",
  scale_x = 1,
  scale_y = 1,
  fix_x = FALSE,
  fix_z = FALSE,
  fix_z_alocal = TRUE,
  return_neighborhood = TRUE,
  file = NULL
)

Arguments

Returns

A new 'iglm.data' object.

Method set_z_network()

Sets the 'z_network' of the 'iglm.data' object.

Usage

iglm.data_generator$set_z_network(z_network)

Arguments

Method set_type_x()

Sets the 'type_x' of the 'iglm.data' object.

Usage

iglm.data_generator$set_type_x(type_x)

Arguments

Method set_type_y()

Sets the 'type_y' of the 'iglm.data' object.

Usage

iglm.data_generator$set_type_y(type_y)

Arguments

Returns

The 'iglm.data' object itself ('self'), invisibly.

Method set_scale_x()

Sets the 'scale_x' of the 'iglm.data' object.

Usage

iglm.data_generator$set_scale_x(scale_x)

Arguments

Returns

The 'iglm.data' object itself ('self'), invisibly.

Method set_scale_y()

Sets the 'scale_y' of the 'iglm.data' object.

Usage

iglm.data_generator$set_scale_y(scale_y)

Arguments

Returns

The 'iglm.data' object itself ('self'), invisibly.

Method set_x_attribute()

Sets the 'x_attribute' of the 'iglm.data' object.

Usage

iglm.data_generator$set_x_attribute(x_attribute)

Arguments

Returns

The 'iglm.data' object itself ('self'), invisibly.

Method set_y_attribute()

Sets the 'y_attribute' of the 'iglm.data' object.

Usage

iglm.data_generator$set_y_attribute(y_attribute)

Arguments

Returns

The 'iglm.data' object itself ('self'), invisibly.

Method gather()

Gathers the current state of the 'iglm.data' object into a list. This includes all attributes, network, and configuration details necessary to reconstruct the object later.

Usage

iglm.data_generator$gather()

Returns

A list containing the current state of the 'iglm.data' object.

Method set_fix_z_alocal()

Sets the option whether alocal edges are fixed or not.

Usage

iglm.data_generator$set_fix_z_alocal(fix_z_alocal)

Arguments

Method delete_isolates()

Deletes isolates from the 'z_network' and updates the attributes and neighborhood accordingly. Isolates are actors that do not have any connections in the 'z_network'. This method identifies such actors, removes them from the attributes and neighborhood, and updates the 'z_network' to reflect the new actor indices.

Usage

iglm.data_generator$delete_isolates()

Returns

The 'iglm.data' object itself ('self'), invisibly.

Method save()

Saves the current state of the 'iglm.data' object to a specified file path in RDS format. This includes all attributes, network, and configuration details necessary to reconstruct the object later.

Usage

iglm.data_generator$save(file)

Arguments

Returns

The 'iglm.data' object itself ('self'), invisibly.

Method set_fix_x()

Sets the 'fix_x' of the 'iglm.data' object.

Usage

iglm.data_generator$set_fix_x(fix_x)

Arguments

Returns

The 'iglm.data' object itself ('self'), invisibly.

Method set_fix_z()

Sets the 'fix_z' of the 'iglm.data' object.

Usage

iglm.data_generator$set_fix_z(fix_z)

Arguments

Returns

The 'iglm.data' object itself ('self'), invisibly.

Method mean_z()

Calculates the density of the 'z_network'.

Usage

iglm.data_generator$mean_z()

Returns

A numeric value for the network density.

Method mean_x()

Calculates the mean of the 'x_attribute'.

Usage

iglm.data_generator$mean_x()

Returns

A numeric value for the mean of 'x_attribute'.

Method mean_y()

Calculates the mean of the 'y_attribute'.

Usage

iglm.data_generator$mean_y()

Returns

A numeric value for the mean of 'y_attribute'.

Method x_distribution()

Calculates the distribution of the 'x_attribute'.

Usage

iglm.data_generator$x_distribution(
  value_range = NULL,
  prob = TRUE,
  plot = FALSE
)

Arguments

Returns

A numeric vector representing the distribution of 'x_attribute' (invisible).

Method y_distribution()

Calculates the distribution of the 'y_attribute'.

Usage

iglm.data_generator$y_distribution(
  value_range = NULL,
  prob = TRUE,
  plot = FALSE
)

Arguments

Returns

A numeric vector representing the distribution of 'y_attribute' (invisible).

Method edgewise_shared_partner()

Calculates the matrix of edgewise shared partners. This is a two-path matrix (e.g., $A A^T$ or $A^T A$).

Usage

iglm.data_generator$edgewise_shared_partner(type = "ALL")

Arguments

Returns

A sparse matrix ('dgCMatrix') of shared partner counts.

Method set_neighborhood_overlap()

Sets the neighborhood and overlap matrices.

Usage

iglm.data_generator$set_neighborhood_overlap(neighborhood, overlap)

Arguments

Returns

None. Updates the internal neighborhood and overlap matrices.

Method dyadwise_shared_partner()

Calculates the matrix of dyadwise shared partners.

Usage

iglm.data_generator$dyadwise_shared_partner(type = "ALL")

Arguments

Returns

A sparse matrix ('dgCMatrix') of shared partner counts.

Method geodesic_distances_distribution()

Calculates the geodesic distance distribution of the symmetrized 'z_network'.

Usage

iglm.data_generator$geodesic_distances_distribution(
  value_range = NULL,
  prob = TRUE,
  plot = FALSE
)

Arguments

Returns

A named vector (a 'table' object) with the distribution of geodesic distances. Includes 'Inf' for unreachable pairs.

Method geodesic_distances()

Calculates the all-pairs geodesic distance matrix for the symmetrized 'z_network' using a matrix-based BFS algorithm.

Usage

iglm.data_generator$geodesic_distances()

Returns

A sparse matrix ('dgCMatrix') where 'D[i, j]' is the shortest path distance from i to j. 'Inf' indicates no path.

Method edgewise_shared_partner_distribution()

Calculates the distribution of edgewise shared partners.

Usage

iglm.data_generator$edgewise_shared_partner_distribution(
  type = "ALL",
  value_range = NULL,
  prob = TRUE,
  plot = FALSE
)

Arguments

Returns

A named vector (a 'table' object) with the distribution of shared partner counts.

Method dyadwise_shared_partner_distribution()

Calculates the distribution of dyadwise shared partners.

Usage

iglm.data_generator$dyadwise_shared_partner_distribution(
  type = "ALL",
  value_range = NULL,
  prob = TRUE,
  plot = FALSE
)

Arguments

Returns

A named vector (a 'table' object) with the distribution of shared partner counts.

Method degree_distribution()

Calculates the degree distribution of the 'z_network'.

Usage

iglm.data_generator$degree_distribution(
  value_range = NULL,
  prob = TRUE,
  plot = FALSE
)

Arguments

Returns

If the network is directed, a list containing two 'table' objects: 'in_degree' and 'out_degree'. If undirected, a single 'table' object with the degree distribution.

Method degree()

Calculates the degree sequence(s) of the 'z_network'.

Usage

iglm.data_generator$degree()

Returns

If the network is directed, a list containing two vectors: 'in_degree_seq' and 'out_degree_seq'. If undirected, a single list containing the vector 'degree_seq'.

Method spillover_degree_distribution()

Calculates the spillover degree distribution between actors with 'x_attribute == 1' and actors with 'y_attribute == 1'.

Usage

iglm.data_generator$spillover_degree_distribution(
  prob = TRUE,
  value_range = NULL,
  plot = FALSE
)

Arguments

Returns

A list containing two 'table' objects: 'out_spillover_degree' (from x_i=1 to y_j=1) and 'in_spillover_degree' (from y_i=1 to x_j=1).

Method plot()

Plot the network using 'igraph'.

Visualizes the 'z_network' using the 'igraph' package. Nodes can be colored by 'x_attribute' and sized by 'y_attribute'. 'neighborhood' edges can be plotted as a background layer.

Usage

iglm.data_generator$plot(
  node_color = "x",
  node_size = "y",
  show_overlap = TRUE,
  layout = igraph::layout_with_fr,
  network_edges_col = "grey60",
  neighborhood_edges_col = "orange",
  main = "",
  legend_col_n_levels = NULL,
  legend_size_n_levels = NULL,
  legend_pos = "right",
  alpha_neighborhood = 0.2,
  edge.width = 1,
  edge.arrow.size = 1,
  vertex.frame.width = 0.5,
  coords = NULL,
  legend_size = 0.5,
  ...
)

Arguments

Returns

A list containing the 'igraph' object ('graph') and the layout coordinates ('coords'), invisibly.

Method print()

Print a summary of the 'iglm.data' object to the console.

Usage

iglm.data_generator$print(digits = 3, ...)

Arguments

Returns

The object's private environment, invisibly.

Method clone()

The objects of this class are cloneable with this method.

Usage

iglm.data_generator$clone(deep = FALSE)

Arguments

An R6 class for Network GLM (Generalized Linear Model) Objects

Description

The 'iglm.object' class encapsulates all components required to define, estimate, and simulate from a network generalized linear model. This includes the model formula, coefficients, the underlying network and attribute data (via a 'iglm.data' object), sampler controls, estimation controls, and storage for results.

Active bindings

Methods

Public methods

• iglm.object.generator$new()

• iglm.object.generator$is_equivalent()

• iglm.object.generator$assess()

• iglm.object.generator$print()

• iglm.object.generator$plot()

• iglm.object.generator$gather()

• iglm.object.generator$set_name()

• iglm.object.generator$set_control()

• iglm.object.generator$save()

• iglm.object.generator$estimate()

• iglm.object.generator$summary()

• iglm.object.generator$simulate()

• iglm.object.generator$predict()

• iglm.object.generator$set_coefficients()

• iglm.object.generator$get_samples()

• iglm.object.generator$set_sampler()

• iglm.object.generator$set_target()

• iglm.object.generator$clone()

Method new()

Internal method to calculate the observed count statistics based on the model formula and the data in the 'iglm.data' object. Populates the 'private$.sufficient_statistics' field.

Internal validation method. Checks the consistency and validity of all components of the 'iglm.object'. Stops with an error if any check fails.

Creates a new 'iglm.object'. This involves parsing the formula, linking the data object, initializing coefficients, setting up sampler and control objects, calculating initial statistics, and validating.

Usage

iglm.object.generator$new(
  formula = NULL,
  coef = NULL,
  coef_degrees = NULL,
  sampler = NULL,
  control = NULL,
  name = NULL,
  file = NULL
)

Arguments

Returns

A new 'iglm.object'.

Method is_equivalent()

Check if this iglm object is equivalent to another iglm object by comparing their defining features, data, and parameters.

Usage

iglm.object.generator$is_equivalent(other, tol = 1e-05, check_results = FALSE)

Arguments

Returns

'TRUE' if the objects are equivalent, otherwise 'FALSE'.

Method assess()

Performs model assessment by calculating specified network statistics on the observed network and comparing their distribution to the distribution obtained from simulated networks based on the current model parameters. Requires simulations to have been run first (via iglm.object$simulate or iglm.object_generator$estimate).

Usage

iglm.object.generator$assess(formula, plot = TRUE)

Arguments

Returns

An object of class 'iglm_model_assessment' containing the observed statistics and the distribution of simulated statistics. The result is also stored internally.

Method print()

Print a summary of the 'iglm.object'. If estimation results are available, they are printed in a standard coefficient table format.

Usage

iglm.object.generator$print(digits = 4, rows = c(1, 2), formula_print = TRUE)

Arguments

Method plot()

Plot the estimation results, including coefficient convergence paths and model assessment diagnostics if available.

Usage

iglm.object.generator$plot(
  stats = FALSE,
  trace = FALSE,
  model_assessment = FALSE
)

Arguments

Method gather()

Gathers all components of the iglm.object into a single list for easy saving or inspection.

Usage

iglm.object.generator$gather()

Returns

A list containing all key components of the iglm.object. This includes the formula, coefficients, sampler, control settings, preprocessing info, time taken for estimation, count statistics, results, and the underlying iglm.data data object.

Method set_name()

Set the name of the iglm.object.

Usage

iglm.object.generator$set_name(name)

Arguments

Returns

The name of the object as a character string.

Method set_control()

Set control parameters for model estimation.

Usage

iglm.object.generator$set_control(control)

Arguments

Returns

Invisibly returns 'NULL'.

Method save()

Save the iglm.object to a file in RDS format.

Usage

iglm.object.generator$save(file = NULL)

Arguments

Returns

Invisibly returns 'NULL'.

Method estimate()

Estimate the model parameters using the specified control settings. Stores the results internally and updates the coefficient fields.

Usage

iglm.object.generator$estimate()

Returns

If no preprocessing should be returned (as per control settings), this function returns a list containing detailed estimation results, invisibly. Includes final coefficients, variance-covariance matrix, convergence path, Fisher information, score vector, log-likelihood, and any simulations performed during estimation. Else, the function returns a list of the desired preprocessed data (as a data.frame) and needed time.

Method summary()

Provides a summary of the estimation results with the following columns: Estimate, SE, t-value, and Pr(>|t|). Requires the model to have been estimated first.

Usage

iglm.object.generator$summary(digits = 3)

Arguments

Returns

Prints the summary to the console and returns 'NULL' invisibly.

Method simulate()

Simulate networks from the fitted model or a specified model. Stores the simulations and/or summary statistics internally. The simulation is carried out using the internal MCMC sampler described in simulate_iglm.

Usage

iglm.object.generator$simulate(
  only_stats = FALSE,
  display_progress = TRUE,
  offset_nonoverlap = 0
)

Arguments

Returns

A list containing the simulated networks ('samples', as a 'iglm.data.list' if 'only_stats = FALSE') and/or their summary statistics ('stats'), invisibly.

Method predict()

Calculates predicted values for the nodal covariates (x), the outcome variable (y), and the network structure (z). The function supports two prediction modes: marginal (based on Monte Carlo integration over simulated samples) and conditional (based on the analytical linear predictor and point estimates).

Usage

iglm.object.generator$predict(
  variant = c("conditional", "marginal"),
  type = c("x", "y", "z")
)

Arguments

Details

Marginal Predictions: When variant = "marginal", the function approximates the expected value via Monte Carlo integration:

\hat{\mu} = \frac{1}{S} \sum_{s=1}^{S} y^{(s)}

where y^{(s)} are the realized values from the s-th simulation sample. For the network z, this results in an edge probability matrix averaged over all sampled networks.

Conditional Predictions: When variant = "conditional", the function calculates the theoretical mean \mu based on the estimated coefficients \hat{\theta}:

• For Binomial families: \mu = (1 + \exp(-\eta))^{-1} (Logistic).

• For Poisson families: \mu = \exp(\eta) (Exponential).

• For Gaussian families: \mu = \eta (Identity).

For the network component z, the linear predictor includes dyadic covariates, degrees effects (sender/receiver variances), and structural offsets.

Returns

A list containing the requested predictions:

x, y

A matrix or data frame where the first column is the actor ID and subsequent columns represent the predicted mean values.

z

A data frame containing the edgelist with columns: sender, receiver, and prediction (probability or intensity).

The results are also invisibly stored in the internal state private$.results.

Method set_coefficients()

Manually set the model coefficients to new values. This is useful for sensitivity analyses or applying the model to different scenarios.

Usage

iglm.object.generator$set_coefficients(coef, coef_degrees = NULL)

Arguments

Returns

The iglm.object itself, invisibly.

Method get_samples()

Retrieve the simulated networks stored in the object. Requires simulate or estimate to have been run first.

Usage

iglm.object.generator$get_samples()

Returns

A list of iglm.data objects representing the simulated networks, invisibly. Returns an error if no samples are available.

Method set_sampler()

Replace the internal MCMC sampler with a new one. This is useful for changing the sampling scheme without redefining the entire model.

Usage

iglm.object.generator$set_sampler(sampler)

Arguments

Method set_target()

Replace the internal 'iglm.data' data object with a new one. This is useful for applying a fitted model to new observed data. Recalculates count statistics and re-validates the object.

Usage

iglm.object.generator$set_target(x)

Arguments

Returns

The iglm.object itself, invisibly.

Method clone()

The objects of this class are cloneable with this method.

Usage

iglm.object.generator$clone(deep = FALSE)

Arguments

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.

Stewart, J. R. and M. Schweinberger (2025). Pseudo-Likelihood-Based M-Estimation of Random Graphs with Dependent Edges and Parameter Vectors of Increasing Dimension. Annals of Statistics, 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.

Model specification for a ‘iglm’ object

Description

The help pages of iglm describe the model with details on model fitting and estimation. Generally, a model is specified via it's sufficient statistics, that can be further decomposed into two parts:

• \mathbf{g}_i(x_i^*,y_i^*) = \mathbf{g}_i(x_i,y_i)= (g_i(x_i,y_i)): 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).

• \mathbf{h}_{i,j}(x_i^*,x_j^*, y_i^*, y_j^*, z) = \mathbf{h}_{i,j}(x,y,z)= (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.

Each term defines a component for the model's features, which are a sum of unit-level components, \sum_i g_i(x_i,y_i), and/or pair-level components, \sum_{i \ne j} h_{i,j}(x,y,z). The implemented terms are grouped into three categories:

1. {g}_i terms for attribute dependence,

2. {h}_{i,j} terms for network dependence,

3. {h}_{i,j} Terms for joint attribute/network dependence.

Below is a detailed description of each term that can be specified in the model formula (see, iglm): iglm.data ~ <term_1> + <term_2> + ... , where the left-hand side of the formula has to be a iglm.data object, and the right-hand side lists some of the terms from the list below, which should be included in the model. Setting, e.g., <term_1> to attribute_x includes the term g_i(x,y,z) = x_i in g_i. Note that the function create_userterms_skeleton can be used to create custom terms.

Notation

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_i,y_i) 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 of the terms. Assuming that the matriv x exists in the environment associated with the used formula, cov_z(data = v) includes the dyadic covariable v = (v_{i,j}) in the model. Some terms also have a mode argument, which can take values "global", "local", or "alocal". The "global" mode indicates that the statistic is computed over the entire network, while "local" restricts the statistic to local neighborhoods only (i.e., edges where c_{i,j} = 1). The "alocal" mode restricts the statistic to non-local edges only (i.e., edges where c_{i,j} = 0). For instance, edges(mode = "local") counts the number of edges that connect actors with overlapping neighborhoods. See underneath for which options are implemented for each term. See the documentation for iglm for details on model fitting and estimation.

List of Terms

1. g_i Terms for Attribute Dependence

attribute_x

Attribute (X) [g-term]: Intercept for attribute x. g_i(x_i,y_i) = x_i

attribute_y

Attribute (Y) [g-term]: Intercept for attribute y. g_i(x_i,y_i) = y_i

cov_x

Nodal Covariate (X) [g-term]: Effect of a unit-level exogenous covariate v_i on endogenous attribute x_i. g_i(x_i,y_i) = v_i x_i

cov_y(data = v)

Nodal Covariate (Y) [g-term]: Effect of a unit-level exogenous covariate v_i on endogenous attribute y_i. g_i(x_i,y_i) = v_i y_i

attribute_xy(mode = "global")

Nodal Attribute Interaction (X-Y) [g-term]: Interaction of attributes x_i and y_i. Spatial or structural boundaries determine the interaction scale.

• global: g_i(x_i,y_i) = x_i y_i

• local: g_i(x_i,y_i) = x_i \sum_{j \in \mathcal{N}_i} y_j + y_i \sum_{j \in \mathcal{N}_i} x_j

• alocal: g_i(x_i,y_i) = 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

degrees

Degrees [h-term]: Specifies node-level fixed effects. Estimation requires an MM algorithm constraint. Directed networks assign distinct sender and receiver effects (constraining node N's out-effect to 0 for identifiability). Undirected networks assign a singular degree effect per node.

edges(mode = "global")

Edges [h-term]: Captures the baseline propensity of tie formation z_{i,j}, partitioned by structural boundary c_{i,j}.

• 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]: Evaluates reciprocal tie formation in 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]: Exogenous dyadic covariate w_{i,j} influence on edge formation.

• 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]: Captures the frequency of nodes with degree zero \mathbb{I} (\sum_{j\neq i} z_{i,j} = 0).

nonisolates

Non-Isolates [z-term]: Captures the frequency of nodes with degree strictly greater than zero \mathbb{I} (\sum_{j\neq i} z_{i,j} \neq 0).

gwodegree(mode = "global", decay = 2.0)

Geometrically Weighted Out-Degree [z-term]: Captures the out-degree distribution utilizing an exponential decay parameter \alpha.

• global: Evaluated across the entire adjacency matrix.

• local: Evaluated strictly within local neighborhood partitions c_{i,j}.

gwidegree(mode = "global", decay = 2.0)

Geometrically Weighted In-Degree [z-term]: Captures the in-degree distribution utilizing an exponential decay parameter \alpha.

• global: Evaluated across the entire adjacency matrix.

• local: Evaluated strictly within local neighborhood partitions c_{i,j}.

gwesp(data, mode = "global", type = "OTP", decay = 2.0)

Geometrically Weighted Edgewise-Shared Partners [h-term]: Models triadic closure propensity conditioning on existing edges, scaled by decay parameter \alpha. Types dictate the structural path constraint: 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: Path evaluations span the entire network topology.

• local: Path evaluations are constrained exclusively to c_{i,j} overlapping neighborhoods.

gwdsp(data, mode = "global", type = "OTP", decay = 2.0)

Geometrically Weighted Dyadwise-Shared Partners [h-term]: Models the baseline triadic potential irrespective of the closing z_{i,j} edge, scaled by decay parameter \alpha. Types dictate the structural path constraint: 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: Path evaluations span the entire network topology.

• local: Path evaluations are constrained exclusively to c_{i,j} overlapping neighborhoods.

cov_z_out(data, mode = "global")

Covariate Sender [h-term]: Exogenous monadic covariate v_{i} influence on generating an outgoing tie.

• 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]: Exogenous monadic covariate v_{j} influence on receiving an incoming tie.

• 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]: Indicator evaluating the presence of a local transitive triad configuration. An actor h \neq i,j must exist fulfilling h\in \mathcal{N}_i, h\in \mathcal{N}_j mapping to 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

attribute_xz(mode = "local")

Attribute Sum (X-Z) [Joint h-term]: Models the additive effect of x_i and x_j on edge formation within local neighborhoods.

• local: h_{i,j}(x,y,z) = c_{i,j} (x_i + x_j) z_{i,j}

attribute_yz(mode = "local")

Attribute Sum (Y-Z) [Joint h-term]: Models the additive effect of y_i and y_j on edge formation within local neighborhoods.

• local: h_{i,j}(x,y,z) = c_{i,j} (y_i + y_j) z_{i,j}

edges_x_match(mode = "global")

Attribute Match (X-Z) [Joint h-term]: Models homophily/matching on the binary attribute x.

• global: h_{i,j}(x,y,z) = \mathbb{I}(x_i = x_j) z_{i,j}

• local: h_{i,j}(x,y,z) = c_{i,j} \mathbb{I}(x_i = x_j) z_{i,j}

edges_y_match(mode = "global")

Attribute Match (Y-Z) [Joint h-term]: Models homophily/matching on the binary attribute y.

• global: h_{i,j}(x,y,z) = \mathbb{I}(y_i = y_j) z_{i,j}

• local: h_{i,j}(x,y,z) = c_{i,j} \mathbb{I}(y_i = y_j) z_{i,j}

outedges_x(mode = "global")

Attribute Out-Degree (X-Z) [Joint h-term]: Influence of endogenous x_i on out-degree formation.

• 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]: Influence of endogenous x_j on in-degree reception.

• 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]: Influence of endogenous y_i on out-degree formation.

• 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]: Influence of endogenous y_j on in-degree reception.

• 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(mode = "local")

Symmetric X-X-Z Outcome Spillover [h-term]: Propagates x-outcome spillover effects through explicit network ties.

• local: h_{i,j}(x,y,z) = c_{i,j} x_i x_j z_{i,j}

spillover_xx_scaled(mode = "local")

Scaled X-X-Z Outcome Spillover [h-term]: Normalizes the x-outcome spillover influence by the relevant out-degree topology of actor i.

• global: h_{i,j}(x,y,z) = x_i x_j z_{i,j} / \text{deg}(i)

• local: h_{i,j}(x,y,z) = c_{i,j} x_i x_j z_{i,j} / \text{deg}(i, \text{local})

spillover_yy(mode = "local")

Symmetric Y-Y-Z Outcome Spillover [h-term]: Propagates y-outcome spillover effects through explicit network ties.

• local: h_{i,j}(x,y,z) = c_{i,j} y_i y_j z_{i,j}

spillover_yy_scaled(mode = "local")

Scaled Y-Y-Z Outcome Spillover [h-term]: Normalizes the y-outcome spillover influence by the relevant out-degree topology of actor i.

• global: h_{i,j}(x,y,z) = y_i y_j z_{i,j} / \text{deg}(i)

• local: h_{i,j}(x,y,z) = c_{i,j} y_i y_j z_{i,j} / \text{deg}(i, \text{local})

spillover_xy(mode = "local")

Directed X-Y-Z Treatment Spillover [h-term]: Maps the cross-attribute x_i \to y_j treatment assignment across the network graph.

• local: h_{i,j}(x,y,z) = c_{i,j} x_i y_j z_{i,j}

spillover_xy_scaled(mode = "local")

Scaled X-Y-Z Treatment Spillover [h-term]: Normalizes the cross-attribute x_i \to y_j spillover influence by the relevant out-degree topology of actor i.

• global: h_{i,j}(x,y,z) = x_i y_j z_{i,j} / \text{deg}(i)

• local: h_{i,j}(x,y,z) = c_{i,j} x_i y_j z_{i,j} / \text{deg}(i, \text{local})

spillover_yx(mode = "local")

Directed Y-X-Z Treatment Spillover [h-term]: Maps the cross-attribute y_i \to x_j treatment assignment across the network graph.

• local: h_{i,j}(x,y,z) = c_{i,j} y_i x_j z_{i,j}

spillover_yx_scaled(mode = "local")

Scaled Y-X-Z Treatment Spillover [h-term]: Normalizes the cross-attribute y_i \to x_j spillover influence by the relevant out-degree topology of actor i.

• global: h_{i,j}(x,y,z) = y_i x_j z_{i,j} / \text{deg}(i)

• local: h_{i,j}(x,y,z) = c_{i,j} y_i x_j z_{i,j} / \text{deg}(i, \text{local})

spillover_yc(mode = "local")

Directed Y-C-Z Treatment Spillover [h-term]: Specifies exogenous covariate v interacting with endogenous trait y over the network.

• local: h_{i,j}(x,y,z) = c_{i,j} y_i v_j z_{i,j}

spillover_yc_symm(data = v, mode = "local")

Symmetric Y-C-Z Treatment Spillover [h-term]: Bidirectional mapping of the exogenous covariate v and endogenous trait y interaction.

• local: 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.

Constructor for the results R6 Object

Description

Creates a new instance of the 'results' R6 class. This class is designed to store various outputs from 'iglm' model estimation and simulation. Users typically do not need to call this constructor directly; it is used internally by the 'iglm_object'.

Usage

results(size_coef, size_coef_degrees, file = NULL)

Arguments

Value

An object of class 'results' (and 'R6'), initialized with empty or NA structures appropriately sized based on the input dimensions.

R6 Class for Storing iglm Estimation and Simulation Results

Description

The 'results' class stores estimation ('$estimate()') and simulation ('$simulate()') results.

This class is primarily intended for internal use within the 'iglm' framework but provides structured access to the results via the active bindings of the main 'iglm_object'.

Active bindings

Methods

Public methods

• results.generator$new()

• results.generator$set_model_assessment()

• results.generator$set_prediction()

• results.generator$gather()

• results.generator$save()

• results.generator$resize()

• results.generator$update()

• results.generator$remove_samples()

• results.generator$plot()

• results.generator$print()

• results.generator$clone()

Method new()

Creates a new 'results' object. Initializes internal fields, primarily setting up an empty matrix for the 'coefficients_path' based on the expected number of coefficients.

Usage

results.generator$new(size_coef, size_coef_degrees, file)

Arguments

Returns

A new 'results' object, initialized to hold results for a model with the specified dimensions.

Method set_model_assessment()

Stores the results object generated by a model assessment (goodness-of-fit) procedure within this 'results' container.

Usage

results.generator$set_model_assessment(res)

Arguments

Returns

The 'results' object itself ('self'), invisibly. Called for its side effect of storing the assessment results.

Method set_prediction()

Stores prediction results.

Usage

results.generator$set_prediction(prediction)

Arguments

Method gather()

Gathers the current state of the 'results' object into a list for saving or inspection. This includes all internal fields such as coefficient paths, samples, statistics, variance-covariance matrix, Fisher information, score vectors, log-likelihood values, model assessment results, and estimation status.

Usage

results.generator$gather()

Returns

A list containing all the internal fields of the 'results' object.

Method save()

Saves the current state of the 'results' object to a specified file path in RDS format. This allows for persisting the results for later retrieval and analysis.

Usage

results.generator$save(file)

Arguments

Returns

The 'results' object itself ('self'), invisibly.

Method resize()

Resizes the internal storage for the coefficient paths to accommodate a different number of coefficients. This is useful if the model structure changes and the results object needs to be reset.

Usage

results.generator$resize(size_coef, size_coef_degrees)

Arguments

Method update()

Updates the internal fields of the 'results' object with new outputs, typically after an estimation run ('$estimate()') or simulation run ('$simulate()'). Allows selectively updating components. Appends to 'coefficients_path' and 'llh' if called multiple times after estimation. Replaces 'samples' and 'stats'.

Usage

results.generator$update(
  coefficients_path = NULL,
  samples = NULL,
  var = NULL,
  fisher_degrees = NULL,
  fisher_nondegrees = NULL,
  score_degrees = NULL,
  score_nondegrees = NULL,
  llh = NULL,
  stats = NULL,
  estimated = FALSE
)

Arguments

Returns

The 'results' object itself ('self'), invisibly. Called for its side effects.

Method remove_samples()

Clears the stored simulation samples ('.samples') and statistics ('.stats') from the object, resetting it to an empty list. This might be used to save memory or before running new simulations.

Usage

results.generator$remove_samples()

Returns

The 'results' object itself ('self'), invisibly.

Method plot()

Generates diagnostic plots for the estimation results. Currently plots:

• The log-likelihood path across iterations.

• The convergence paths for degrees coefficients (if present).

• The convergence paths for non-degrees coefficients.

Optionally, can also trigger plotting of model assessment results if available.

Usage

results.generator$plot(
  trace = FALSE,
  stats = FALSE,
  model_assessment = FALSE,
  ...
)

Arguments

Details

Requires estimation results ('private$.estimated == TRUE') to plot convergence diagnostics. Requires model assessment results for the model assessment plots.

Method print()

Prints a concise summary of the contents of the 'results' object, indicating whether various components (coefficients path, variance matrix, Fisher info, score, samples, stats, etc.) are available.

Usage

results.generator$print(...)

Arguments

Returns

The 'results' object itself ('self'), invisibly.

Method clone()

The objects of this class are cloneable with this method.

Usage

results.generator$clone(deep = FALSE)

Arguments

Constructor for a iglm Sampler

Description

Creates an object of class 'sampler.iglm' (and 'R6') which holds all parameters controlling the MCMC sampling process for 'iglm' models. This includes global settings like the number of simulations and burn-in, as well as references to specific samplers for the network ('z') and attribute ('x', 'y') components.

This function provides a convenient way to specify these settings before passing them to the 'iglm' constructor or simulation functions.

Usage

sampler.iglm(
  sampler_x = NULL,
  sampler_y = NULL,
  sampler_z = NULL,
  n_simulation = 100,
  n_burn_in = 10,
  init_empty = TRUE,
  cluster = NULL,
  file = NULL
)

Arguments

Value

An object of class 'sampler.iglm' (and 'R6').

See Also

'sampler.net.attr', 'iglm', 'control.iglm'

Examples

n_actor <- 50
sampler_new <- sampler.iglm(
  n_burn_in = 100, n_simulation = 10,
  sampler_x = sampler.net.attr(n_proposals = n_actor * 10, seed = 13),
  sampler_y = sampler.net.attr(n_proposals = n_actor * 10, seed = 32),
  sampler_z = sampler.net.attr(n_proposals = n_actor^2, seed = 134, tnt = TRUE),
  init_empty = FALSE
)
sampler_new
# Change some values of the  sampler
sampler_new$n_simulation
sampler_new$set_n_simulation(100)
sampler_new$n_simulation

R6 Class for iglm Sampler Settings

Description

The 'sampler.iglm' class is an R6 container for specifying and storing the parameters that control the MCMC (Markov Chain Monte Carlo) sampling process used in iglm simulations and potentially during estimation. It includes settings for the number of simulations, burn-in period, initialization, and parallelization options. It also holds references to component samplers (sampler.net.attr objects) responsible for sampling individual parts (attributes x, y, network z).

Active bindings

Methods

Public methods

• sampler.iglm.generator$new()

• sampler.iglm.generator$set_cluster()

• sampler.iglm.generator$deactive_cluster()

• sampler.iglm.generator$set_n_simulation()

• sampler.iglm.generator$set_n_burn_in()

• sampler.iglm.generator$set_init_empty()

• sampler.iglm.generator$set_x_sampler()

• sampler.iglm.generator$set_y_sampler()

• sampler.iglm.generator$set_z_sampler()

• sampler.iglm.generator$print()

• sampler.iglm.generator$gather()

• sampler.iglm.generator$save()

• sampler.iglm.generator$clone()

Method new()

Create a new 'sampler.iglm' object. Initializes all sampler settings, using defaults for component samplers ('sampler.net.attr') if not provided, and validates inputs.

Usage

sampler.iglm.generator$new(
  sampler_x = NULL,
  sampler_y = NULL,
  sampler_z = NULL,
  n_simulation = 100,
  n_burn_in = 10,
  init_empty = TRUE,
  cluster = NULL,
  file = NULL
)

Arguments

Returns

A new 'sampler.iglm' object.

Method set_cluster()

Sets the parallel cluster object to be used for simulations.

Usage

sampler.iglm.generator$set_cluster(cluster)

Arguments

Method deactive_cluster()

Deactivates parallel processing for this sampler instance by setting the internal cluster object reference to 'NULL'.

Usage

sampler.iglm.generator$deactive_cluster()

Returns

The 'sampler.iglm' object itself ('self'), invisibly.

Method set_n_simulation()

Sets the number of simulations to generate after burn-in.

Usage

sampler.iglm.generator$set_n_simulation(n_simulation)

Arguments

Returns

None.

Method set_n_burn_in()

Sets the number of burn-in iterations.

Usage

sampler.iglm.generator$set_n_burn_in(n_burn_in)

Arguments

Returns

None.

Method set_init_empty()

Sets whether to initialize simulations from an empty state.

Usage

sampler.iglm.generator$set_init_empty(init_empty)

Arguments

Returns

None.

Method set_x_sampler()

Sets the sampler configuration for the x attribute.

Usage

sampler.iglm.generator$set_x_sampler(sampler_x)

Arguments

Returns

None.

Method set_y_sampler()

Sets the sampler configuration for the y attribute.

Usage

sampler.iglm.generator$set_y_sampler(sampler_y)

Arguments

Returns

None.

Method set_z_sampler()

Sets the sampler configuration for the z attribute.

Usage

sampler.iglm.generator$set_z_sampler(sampler_z)

Arguments

Returns

None.

Method print()

Prints a formatted summary of the sampler configuration to the console. Includes core parameters (simulation count, burn-in, etc.) and calls the 'print' method for each component sampler ('sampler_x', 'sampler_y', etc.).

Usage

sampler.iglm.generator$print(digits = 3, ...)

Arguments

Returns

The 'sampler.iglm' object itself ('self'), invisibly.

Method gather()

Gathers all data from private fields into a list.

Usage

sampler.iglm.generator$gather()

Returns

A list containing all information of the sampler.

Method save()

Save the object's complete state to a directory. This will save the main sampler's settings to a file named 'sampler.iglm_state.rds' within the specified directory, and will also call the 'save()' method for each nested sampler (.x, .y, .z), saving them into the same directory.

Usage

sampler.iglm.generator$save(file)

Arguments

Returns

The object itself, invisibly.

Method clone()

The objects of this class are cloneable with this method.

Usage

sampler.iglm.generator$clone(deep = FALSE)

Arguments

Constructor for Single Component Sampler Settings

Description

Creates an object of class 'sampler_net_attr' (and 'R6'). This object specifies the MCMC sampling parameters for a single component (like an attribute vector or a network structure) within the larger 'iglm' simulation framework. It is typically used as input when creating a 'sampler.iglm' object.

Usage

sampler.net.attr(n_proposals = 10000, seed = NA, file = NULL, tnt = TRUE)

Arguments

Value

An object of class 'sampler_net_attr' (and 'R6').

See Also

'sampler.iglm'

Examples

# Default settings
sampler_comp_default <- sampler.net.attr()
sampler_comp_default

# Custom settings
sampler_comp_custom <- sampler.net.attr(n_proposals = 50000, seed = 123, tnt = FALSE)
sampler_comp_custom

R6 Class for Single Component Sampler Settings

Description

The 'sampler_net_attr' class is a simple R6 container used within the 'sampler.iglm' class. It holds the MCMC sampling parameters for a single component of the 'iglm' model, such as one attribute (e.g., 'x_attribute') or a part of the network (e.g., 'z_network' within the overlap). It primarily stores the number of proposals and a random seed.

Active bindings

Methods

Public methods

• sampler.net.attr.generator$new()

• sampler.net.attr.generator$print()

• sampler.net.attr.generator$gather()

• sampler.net.attr.generator$set_n_proposals()

• sampler.net.attr.generator$set_seed()

• sampler.net.attr.generator$set_tnt()

• sampler.net.attr.generator$save()

• sampler.net.attr.generator$clone()

Method new()

Create a new 'sampler_net_attr' object. Validates inputs and sets a random seed if none is provided.

Usage

sampler.net.attr.generator$new(
  n_proposals = 10000,
  seed = NA,
  file = NULL,
  tnt = TRUE
)

Arguments

Returns

A new 'sampler_net_attr' object.

Method print()

Print a summary of the sampler settings for this component.

Usage

sampler.net.attr.generator$print(indent = "  ")

Arguments

Returns

The object itself, invisibly. Called for side effect.

Method gather()

Gathers all data from private fields into a list.

Usage

sampler.net.attr.generator$gather()

Returns

A list containing all information of the sampler.

Method set_n_proposals()

Sets the number of MCMC proposals for this component.

Usage

sampler.net.attr.generator$set_n_proposals(n_proposals)

Arguments

Returns

None.

Method set_seed()

Sets the random seed for this component's sampler.

Usage

sampler.net.attr.generator$set_seed(seed)

Arguments

Returns

None.

Method set_tnt()

Sets whether to use TNT sampling for this component.

Usage

sampler.net.attr.generator$set_tnt(tnt)

Arguments

Returns

None.

Method save()

Save the object's state to an .rds file.

Usage

sampler.net.attr.generator$save(file)

Arguments

Returns

The object itself, invisibly.

Method clone()

The objects of this class are cloneable with this method.

Usage

sampler.net.attr.generator$clone(deep = FALSE)

Arguments

Simulate responses and connections

Description

Simulate responses and connections.

Usage

simulate_iglm(
  formula,
  basis = NULL,
  coef,
  coef_degrees = NULL,
  sampler = NULL,
  only_stats = TRUE,
  display_progress = FALSE,
  offset_nonoverlap = 0,
  cluster = NULL,
  fix_x = FALSE,
  fix_z = FALSE
)

Arguments

Details

Parallel Execution: When a 'cluster' object is provided, the simulation process is adapted:

1. A single simulation run (including burn-in specified by 'sampler$n_burn_in') is performed on the master node to obtain a starting state for the parallel chains.

2. The total number of requested simulations ('sampler$n_simulation') is divided among the cluster workers.

3. “parallel::parLapply“ is used to run simulations on each worker. Each worker starts from the state obtained after the initial burn-in, performs zero additional burn-in ('n_burn_in = 0' passed to workers), and generates its assigned share of the simulations. Component sampler seeds are offset based on the worker ID to ensure pseudo-independent random number streams.

4. Results (simulated objects or statistics) from all workers are collected and combined.

This approach ensures that the initial burn-in phase happens only once, saving time.

Value

A list containing one or two components (depending on 'only_stats'):

'samples'

If 'only_stats = FALSE', this is a list of length 'sampler$n_simulation' where each element is a 'iglm.data' object representing one simulated draw from the model. The list has the S3 class '"iglm.data.list"'. If 'only_stats = TRUE', this component is omitted.

'stats'

A numeric matrix with 'sampler$n_simulation' rows and 'length(coef)' columns. Each row contains the features (corresponding to the model terms in 'formula') calculated for one simulation draw. Column names are set to match the term names.

Errors

The function stops with an error if:

• The length of 'coef' does not match the number of terms derived from 'formula'.

• 'formula_preprocess' fails.

• The 'sampler' object is not of class 'sampler.iglm'.

• The C++ backend 'xyz_simulate_cpp' encounters an error.

• Helper functions like 'XYZ_to_R' or 'is_cluster_active' are not found.

Warnings may be issued if default sampler settings are used.

See Also

iglm for creating the model object, sampler.iglm for creating the sampler object, iglm.data for the data object structure.

Twitter (X) data list for U.S. state legislators (10-state subset)

Description

This data object is data derived from the Twitter (X) interactions between U.S. state legislators, which is a subset of the data analyzed in Fritz et al. (2025).' The data is filtered to include only legislators from 10 states (NY, CA, TX, FL, IL, PA, OH, GA, NC, MI) and is further subset to the largest connected component based on mention or retweet activity.

This object contains the main iglm.data object and 5 pre-computed dyadic covariates.

Usage

data(state_twitter)

Format

A list object containing 6 components. Let N be the number of legislators in the filtered 10-state subset.

iglm.data

A iglm.data object (which is also a list) parameterized as follows:

• x_attribute: A binary numeric vector of length N. Value is 1 if the legislator's party is 'Republican', 0 otherwise.

• y_attribute: A Poisson numeric vector of length N. Represents the count of hatespeech incidents (actors_data$number_hatespeech) for each legislator.

• z_network: A directed edgelist (2-column matrix) of size n_edges x 2. A tie (i, j) exists if legislator i either mentioned or retweeted legislator j.

• neighborhood: A directed edgelist (2-column matrix). Represents the follower network, where a tie (i, j) exists if legislator i follows legislator j. Self-loops (diagonal) are included.

match_gender

An N x N matrix. matrix[i, j] = 1 if legislator i and legislator j have the same gender, 0 otherwise.

match_race

An N x N matrix. matrix[i, j] = 1 if legislator i and legislator j have the same race, 0 otherwise.

match_state

An N x N matrix. matrix[i, j] = 1 if legislator i and legislator j are from the same state, 0 otherwise.

white_attribute

A 1 x N matrix (a row vector). matrix[1, i] = 1 if legislator i is 'White', 0 otherwise.

gender_attribute

A 1 x N matrix (a row vector). matrix[1, i] = 1 if legislator i is 'female', 0 otherwise.

References

Gopal, Kim, Nakka, Boehmke, Harden, Desmarais. The National Network of U.S. State Legislators on Twitter. Political Science Research & Methods, Forthcoming.

Kim, Nakka, Gopal, Desmarais,Mancinelli, Harden, Ko, and Boehmke (2022). Attention to the COVID-19 pandemic on Twitter: Partisan differences among U.S. state legislators. Legislative Studies Quarterly 47, 1023–1041.

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.

Compute Statistics

Description

Computes statistics.

Usage

statistics(formula)

Arguments

Value

A named numeric vector. Each element corresponds to a term in the 'formula', and its value is the calculated observed feature for that term based on the data in the iglm.data object. The names of the vector match the coefficient names derived from the formula terms.

Examples

# Create a iglm.data object
n_actor <- 10
neighborhood <- matrix(1, nrow = n_actor, ncol = n_actor)
type_x <- "binomial"
type_y <- "binomial"
x_attr_data <- rbinom(n_actor, 1, 0.5)
y_attr_data <- rbinom(n_actor, 1, 0.5)
z_net_data <- matrix(0, nrow = n_actor, ncol = n_actor)
object <- iglm.data(
  z_network = z_net_data, x_attribute = x_attr_data,
  y_attribute = y_attr_data, neighborhood = neighborhood,
  directed = FALSE, type_x = type_x, type_y = type_y
)
statistics(object ~ edges(mode = "local") + attribute_y + attribute_x)