ergm.allstats: Calculate all possible vectors of statistics on a network for an ERGM

Description

ergm.allstats produces a matrix of network statistics for an arbitrary statnet exponential-family random graph model. One possible use for this function is to calculate the exact loglikelihood function for a small network via the ergm.exact function.

Usage

ergm.allstats(formula, zeroobs = TRUE, force = FALSE,
  maxNumChangeStatVectors = 2^16, ...)

Arguments

formula

an formula object of the form y ~ <model terms>, where y is a network object or a matrix that can be coerced to a network object. For the details on the possible <model terms>, see ergm-terms. To create a network object in , use the network() function, then add nodal attributes to it using the %v% operator if necessary.

zeroobs

Logical: Should the vectors be centered so that the network passed in the formula has the zero vector as its statistics?

force

Logical: Should the algorithm be run even if it is determined that the problem may be very large, thus bypassing the warning message that normally terminates the function in such cases?

maxNumChangeStatVectors

Maximum possible number of distinct values of the vector of statistics. It's good to use a power of 2 for this.

…

further arguments; not currently used.

Value

Returns a list object with these two elements:

weights

integer of counts, one for each row of statmat telling how many networks share the corresponding vector of statistics.

statmat

matrix in which each row is a unique vector of statistics.

Details

The mechanism for doing this is a recursive algorithm, where the number of levels of recursion is equal to the number of possible dyads that can be changed from 0 to 1 and back again. The algorithm starts with the network passed in formula, then recursively toggles each edge twice so that every possible network is visited.

ergm.allstats should only be used for small networks, since the number of possible networks grows extremely fast with the number of nodes. An error results if it is used on a directed network of more than 6 nodes or an undirected network of more than 8 nodes; use force=TRUE to override this error.

Examples

Run this code

# NOT RUN {
# Count by brute force all the edge statistics possible for a 7-node 
# undirected network
mynw <- network(matrix(0,7,7),dir=FALSE)
system.time(a <- ergm.allstats(mynw~edges))

# Summarize results
rbind(t(a$statmat),a$weights)

# Each value of a$weights is equal to 21-choose-k, 
# where k is the corresponding statistic (and 21 is 
# the number of dyads in an 7-node undirected network).  
# Here's a check of that fact:
as.vector(a$weights - choose(21, t(a$statmat)))

# Simple ergm.exact outpuf for this network.  
# We know that the loglikelihood for my empty 7-node network
# should simply be -21*log(1+exp(eta)), so we may check that
# the following two values agree:
-21*log(1+exp(.1234)) 
ergm.exact(.1234, mynw~edges, statmat=a$statmat, weights=a$weights)

# }