The `iglm.object` class encapsulates all components required to define, estimate, and simulate from a generalized linear model under interference. 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.
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.
Active bindings
formula(`formula`) Read-only. The model formula specifying terms and data object.
coef(`numeric`) Read-only. The current vector of non-degrees coefficient estimates or initial values.
coef_degrees(`numeric` or `NULL`) Read-only. The current vector of degrees coefficient estimates or initial values, or `NULL` if not applicable.
results(`results`) Read-only. The
resultsR6 object containing all estimation and simulation outputs.iglm.data(`iglm.data`) The associated
iglm.dataR6 object containing the network and attribute data.control(`control.iglm`) The
control.iglmobject specifying estimation parameters.sampler(`sampler.iglm`) The
sampler.iglmobject specifying MCMC sampling parameters.name(`character`) The name of the model.
sufficient_statistics(`numeric`) Read-only. A named vector of the observed network statistics corresponding to the model terms, calculated on the current `iglm.data` data.
Methods
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
formulaA model `formula` object. The left-hand side should be the name of a
iglm.dataobject available in the calling environment. Seeiglm-termsfor details on specifying the right-hand side terms.coefA numeric vector of initial coefficients for the terms in the formula (excluding degree coefficeints). If `NULL`, coefficients are initialized to zero.
coef_degreesAn optional numeric vector of initial degree coefficients. Should be `NULL` if the formula does not include degree-correcting terms.
samplerA
sampler.iglmobject specifying the MCMC sampler settings. If `NULL`, default settings are used.controlA
control.iglmobject specifying estimation control parameters. If `NULL`, default settings are used.nameAn optional character string specifying a name for the model, would be used in plots and model assessment.
file(character or `NULL`) If provided, loads the sampler state from the specified .rds file instead of initializing from parameters.
Method is_equivalent()
Check if this iglm object is equivalent to another iglm object by comparing their defining features, data, and parameters.
Arguments
otherAnother object to compare against.
tolTolerance for numeric comparisons (default is 1e-5).
check_results(logical) If `TRUE`, also requires the estimation results and MCMC samples to match exactly. Default is `FALSE` (only compares model specification, input data, and initial coefficients).
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).
Arguments
formulaA formula specifying the network statistics to assess (e.g., `~ degree_distribution() + geodesic_distances_distribution()`). The terms should correspond to methods available in the
iglm.dataobject that end with `distributions`. If the term mcmc_diagnostics is included, MCMC diagnostics will also be computed.plot(logical) If `TRUE`, generates plots comparing observed and simulated statistics. Default is `TRUE`.
Method print()
Print a summary of the `iglm.object`. If estimation results are available, they are printed in a standard coefficient table format.
Arguments
digits(integer) Number of digits for rounding numeric output.
rowsIf a numeric vector with values between 1 and 5 is provided, only the corresponding columns are printed (1: Estimate, 2: S.E., 3: t-value, 4: Pr(>|t|), 5: Global Count of Sufficient Statistic). Default is `c(1, 2)` to show only estimates and standard errors.
signif.stars(logical) If `TRUE`, prints significance stars for the coefficients. Default is `getOption("show.signif.stars")`.
eps.Pvalue(numeric) Tolerance for small p-values. Default is `0.0001`.
print.formula(logical) If `TRUE` (default), prints the model formula.
print.fitinfo(logical) If `TRUE` (default), prints information about the estimation results.
print.coefmat(logical) If `TRUE` (default), prints the coefficient table.
print.call(logical) If `TRUE` (default), prints the call that generated the object.
...Additional arguments passed to
printCoefmat.
Method plot()
Plot the estimation results, including coefficient convergence paths and model assessment diagnostics if available.
Arguments
stats(logical) If `TRUE`, plot the observed vs. simulated statistics from model assessment. Default is `FALSE`.
trace(logical) If `TRUE`, plot the coefficient convergence paths. Default is `FALSE`.
model_assessment(logical) If `TRUE`, plot diagnostics from the model assessment (if already carried out). Default is `FALSE`.
Method gather()
Gathers all components of the iglm.object into a single list for
easy saving or inspection.
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.
Method set_control()
Set control parameters for model estimation.
Arguments
controlA
control.iglmobject specifying new control settings.
Method save()
Save the iglm.object to a file in RDS format.
Method estimate()
Estimate the model parameters using the specified control settings. Stores the results internally and updates the coefficient fields.
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.
Arguments
digits(integer) Number of digits for rounding numeric output.
...Additional arguments passed to
printCoefmat.
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
only_stats(logical) If `TRUE`, only calculate and store summary statistics for each simulation, discarding the network object itself. Default is `FALSE`.
display_progress(logical) If `TRUE` (default), display a progress bar during simulation.
offset_nonoverlap(numeric) Offset to apply for non-overlapping dyads during simulation (if applicable to the sampler). This option is useful if the sparsity of edges of units with non-overlapping neighborhoods is known. Default is 0.
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).
Arguments
variantA character string specifying the type of prediction to generate. Must be one of:
"marginal": Computes predictions by aggregating over the MCMC samples stored in the internal results. If samples do not exist,self$simulate()is triggered automatically."conditional": Computes predictions using the systematic component of the Generalized Linear Model (GLM). It calculates the linear predictor \(\eta = X\beta\) (plus offset and degrees terms for the network) and applies the inverse link function \(\mu = g^{-1}(\eta)\).
Defaults to
c("conditional", "marginal").typeA character vector indicating which components to predict. Options are:
"x": Nodal covariates."y": Nodal outcome variable."z": Dyadic network structure (interaction probabilities).
Defaults to
c("x", "y", "z").
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} h^{(s)}$$
where \(h^{(s)}\) are the realized values from the \(s\)-th simulation sample (being either attribute x, y or the connections z).
For the network z, this results in a marginal 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,yA matrix or data frame where the first column is the actor ID and subsequent columns represent the predicted mean values.
zA data frame containing the edgelist with columns:
sender,receiver, andprediction(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.
Arguments
coefA numeric vector of new coefficient values for the non-degrees terms.
coef_degreesA numeric vector of new coefficient values for the degrees terms, if applicable. Must be provided if the model includes degrees effects.
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.
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.
Arguments
samplerA
sampler.iglmobject. @return Theiglm.objectitself, invisibly.
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.
Arguments
xA
iglm.data“ object containing the new observed data.
Returns
The iglm.object itself, invisibly.