Processing formulas in ergmito

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.

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

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.

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.

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

data(fivenets)
model0 <- ergmito_formulae(fivenets ~ edges + nodematch("female"))
print(model0)
#> ergmito log-likelihood function
#> Number of networks:  5 
#> Model:  fivenets ~ edges + nodematch("female") 
#> Available elements by using the $ operator:
#> loglik: function (params, ..., as_prob = FALSE, total = TRUE) grad  : function (params, ...) 
model0$loglik(c(-2, 2))
#> [1] -34.86713

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