ergm (version 4.7.1)

ergm_MCMC_sample: Internal Function to Sample Networks and Network Statistics

Description

This is an internal function, not normally called directly by the user. The ergm_MCMC_sample function samples networks and network statistics using an MCMC algorithm via MCMC_wrapper and is capable of running in multiple threads using ergm_MCMC_slave.

The ergm_MCMC_slave function calls the actual C routine and does minimal preprocessing.

Usage

ergm_MCMC_sample(
  state,
  control,
  theta = NULL,
  verbose = FALSE,
  ...,
  eta = ergm.eta(theta, (if (is.ergm_state(state)) as.ergm_model(state) else
    as.ergm_model(state[[1]]))$etamap)
)
ergm_MCMC_slave(
  state,
  eta,
  control,
  verbose,
  ...,
  burnin = NULL,
  samplesize = NULL,
  interval = NULL
)

Value

ergm_MCMC_sample returns a list containing:

stats

an mcmc.list with sampled statistics.

networks

a list of final sampled networks, one for each thread.

status

status code, propagated from ergm_MCMC_slave().

final.interval

adaptively determined MCMC interval.

final.effectiveSize

adaptively determined target ESS (non-trivial if control$MCMC.effectiveSize is specified via a matrix).

sampnetworks

If control$MCMC.save_networks is set and is TRUE, a list of lists of ergm_states corresponding to the sampled networks.

ergm_MCMC_slave returns the MCMC sample as a list of the following:

s

the matrix of statistics.

state

an ergm_state object for the new network.

status

success or failure code: 0 is success, 1 for too many edges, and 2 for a Metropolis-Hastings proposal failing, -1 for ergm_model or ergm_proposal not passed and missing from the cache.

Arguments

state

an ergm_state representing the sampler state, containing information about the network, the model, the proposal, and (optionally) initial statistics, or a list thereof.

control

A list of control parameters for algorithm tuning, typically constructed with control.ergm(), control.simulate.ergm(), etc., which have different defaults. Their documentation gives the the list of recognized control parameters and their meaning. The more generic utility snctrl() (StatNet ConTRoL) also provides argument completion for the available control functions and limited argument name checking.

theta

the (possibly curved) parameters of the model.

verbose

A logical or an integer to control the amount of progress and diagnostic information to be printed. FALSE/0 produces minimal output, with higher values producing more detail. Note that very high values (5+) may significantly slow down processing.

...

additional arugments.

eta

the natural parameters of the model; by default constructed from theta.

burnin, samplesize, interval

MCMC paramters that can be used to temporarily override those in the control list.

Examples

# This example illustrates constructing "ingredients" for calling
# ergm_MCMC_sample() from calls to simulate.ergm(). One can also
# construct an ergm_state object directly from ergm_model(),
# ergm_proposal(), etc., but the approach shown here is likely to
# be the least error-prone and the most robust to future API
# changes.
#
# The regular simulate() call hierarchy is
#
# simulate_formula.network(formula) ->
#   simulate.ergm_model(ergm_model) ->
#     simulate.ergm_state_full(ergm_state)
#
# They take an argument, return.args=, that will interrupt the call
# and have it return its arguments. We can use it to obtain
# low-level inputs robustly.

data(florentine)
control <- control.simulate(MCMC.burnin = 2, MCMC.interval = 1)


# FYI: Obtain input for simulate.ergm_model():
sim.mod <- simulate(flomarriage~absdiff("wealth"), constraints=~edges,
                    coef = NULL, nsim=3, control=control,
                    return.args="ergm_model")
names(sim.mod)
str(sim.mod$object,1) # ergm_model

# Obtain input for simulate.ergm_state_full():
sim.state <- simulate(flomarriage~absdiff("wealth"), constraints=~edges,
                      coef = NULL, nsim=3, control=control,
                      return.args="ergm_state")
names(sim.state)
str(sim.state$object, 1) # ergm_state

# This control parameter would be set by nsim in the regular
# simulate() call:
control$MCMC.samplesize <- 3

# Capture intermediate networks; can also be left NULL for just the
# statistics:
control$MCMC.save_networks <- TRUE

# Simulate starting from this state:
out <- ergm_MCMC_sample(sim.state$object, control, theta = -1, verbose=6)
names(out)
out$stats # Sampled statistics
str(out$networks, 1) # Updated ergm_state (one per thread)
# List (an element per thread) of lists of captured ergm_states,
# one for each sampled network:
str(out$sampnetworks, 2)
lapply(out$sampnetworks[[1]], as.network) # Converted to networks.

# One more, picking up where the previous sampler left off, but see Note:
control$MCMC.samplesize <- 1
str(ergm_MCMC_sample(out$networks, control, theta = -1, verbose=6), 2)