ergm: ergm_MCMC_sample – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

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 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.

ergm

Fit, Simulate and Diagnose Exponential-Family Models for Networks

v3.11.0

GPL-3 + file LICENSE

Authors

Mark S. Handcock [aut], David R. Hunter [aut], Carter T. Butts [aut], Steven M. Goodreau [aut], Pavel N. Krivitsky [aut, cre] (<https://orcid.org/0000-0002-9101-3362>), Martina Morris [aut], Li Wang [ctb], Kirk Li [ctb], Skye Bender-deMoll [ctb], Chad Klumb [ctb], Michał Bojanowski [ctb], Ben Bolker [ctb]

Initial release

2020-10-14