ergmito_formulae: Processing formulas in `ergmito`

Description

Analyze formula objects returning the matrices of weights and sufficient statistics to be used in the model together with the log-likelihood and gradient functions for joint models.

Usage

ergmito_formulae(
  model,
  model_update = NULL,
  target_stats = NULL,
  stats_weights = NULL,
  stats_statmat = NULL,
  target_offset = NULL,
  stats_offset = NULL,
  env = parent.frame(),
  ...
)

Value

A list of class ergmito_loglik.

loglik A function. The log-likelihood function.
grad A function. The gradient of the model.
stats_weights,stats_statmat two list of objects as returned by ergm::ergm.allstats.
target_offset,stats_offset A vector of offset terms and a list of vectors of offset terms, one for the target stats and the other for the support of the sufficient statistics (defaults to 0).
model A formula. The model passed.
npars Integer. Number of parameters.
nnets Integer. Number of networks in the model.
vertex_attr Character vector. Vertex attributes used in the model.
term_names Names of the terms used in the model.

Arguments

model: A formula. The left-hand-side can be either a small network, or a list of networks.
model_update: A formula. If specified, the after computing the sufficient statistics (observed and support), the model is updated using stats::model.frame(). This includes processing offset terms.
target_stats: Observed statistics. If multiple networks, then a list, otherwise a named vector (see ergm::summary_formula).
stats_weights, stats_statmat: Lists of sufficient statistics and their respective weights.
target_offset, stats_offset: See exact_loglik().
env: Environment in which model should be evaluated.
...: Further arguments passed to ergm::ergm.allstats.

Details

One of the main advantages of been able to compute exact likelihoods is that we can build arbitrarily complex models in the same way that we would do in the context of Generalized Linear Models, this is, adding offset terms, interaction effects, or transformations of statistics without much effort.

In particular, if the user passes a formula via model_update, the cannonical additive ERGM can be modified to include other terms, for example, if we wanted to add an interaction effect of the nodematch("age") with network size, we can simply type

model_update = ~ . + I(nodematch.age * n)

The I() function allows operating over variables in the model, in this case, we took the nodematch.age variable (which is the name that ergm::ergm() assigns to it after computing the sufficient statistics) and multiplied it by n, which is the network size (this variable is included by default).

By default, the ergm package calculates up to 2^16 unique values for the vector of sufficient statistics. This results in issues if the user tries to fit a model with too heterogenous networks or sets of attributes. To deal with this it suffices with adding the option maxNumChangeStatVectors in the ergmito call, e.g.:

# Networks of size 5 have up to 2^20 unique sets of sufficient statistics
ergmito(..., maxNumChangeStatVectors = 2^20)

See more in ?ergm::ergm.allstats.

Examples

Run this code

data(fivenets)
model0 <- ergmito_formulae(fivenets ~ edges + nodematch("female"))
print(model0)
model0$loglik(c(-2, 2))

# Model with interaction effects and an offset term
model1 <- ergmito_formulae(
  fivenets ~ edges + nodematch("female"),
  model_update = ~ . + offset(edges) + I(edges * nodematch.female)
)