R: Internal Function to Sample Networks and Network Statistics

ergm_MCMC_sample {ergm} | R Documentation

## 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 caple 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(nw, model, proposal, control, theta = NULL,
      response = NULL, update.nws = TRUE, verbose = FALSE, ...,
      eta = ergm.eta(theta, model$etamap))

    ergm_MCMC_slave(Clist, proposal, eta, control, verbose, ...,
      prev.run = NULL, burnin = NULL, samplesize = NULL,
      interval = NULL, maxedges = NULL)

### Arguments

`nw` | a `network` (or `pending_update_network`) object representing the sampler state.
`model` | an `ergm_model` to be sampled from, as returned by `ergm_model()`.
`proposal` | a list of the parameters needed for Metropolis-Hastings proposals and the result of calling `ergm_proposal()`.
`control` | list of MCMC tuning parameters; see `control.ergm()`.
`theta` | the (possibly curved) parameters of the model.
`response` | Name of the edge attribute whose value is to be modeled in the valued ERGM framework. Defaults to `NULL` for simple presence or absence, modeled via a binary ERGM.
`update.nws` | whether to actually update the network state or to return an object "promising" to update the network.
`verbose` | verbosity level.
`...` | additional arugments.
`eta` | the natural parameters of the model; by default constructed from `theta`.
`Clist` | the list of parameters returned by `ergm.Cprepare`
`prev.run` | a summary of the state of the sampler allowing a run to be resumed quickly by `ergm_MCMC_slave`.
`burnin, samplesize, interval, maxedges` | MCMC paramters that can be used to temporarily override those in the `control` list.

### Details

Note that the returned stats will be relative to the original network, i.e., the calling function must shift the statistics if required. The calling function must also attach column names to the statistics matrix if required.

### 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.mcmcslave`.
`final.interval` | adaptively determined MCMC interval.

If `update.nws==FALSE`, rather than returning the updated networks, the function will return a `pending_update_network`.

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

`s` | the matrix of statistics.
`newnwtails` | the vector of tails for the new network.
`newnwheads` | the vector of heads for the new network.
`newnwweights` | the vector of weights for the new network (if applicable)
`status` | success or failure code: `0` is success, `1` for too many edges, and `2` for a Metropolis-Hastings proposal failing.
`maxedges` | maximum allowed edges at the time of return.

### Note

`ergm_MCMC_sample` and `ergm_MCMC_slave` replace `ergm.getMCMCsample` and `ergm.mcmcslave` respectively. They differ slightly in their argument names and in their return formats. For example, `ergm_MCMC_sample` expects `proposal` rather than `MHproposal` and `theta` or `eta` rather than `eta0`; and it does not return `statsmatrix` or `newnetwork` elements. Rather, if parallel processing is not in effect, `stats` is an `mcmc.list` with one chain and `networks` is a list with one element.

[Package ergm version 3.10.4 Index]