R: Auxiliary for Controlling ERGM Simulation

control.simulate.ergm {ergm} | R Documentation

## Auxiliary for Controlling ERGM Simulation

### Description

Auxiliary function as user interface for fine-tuning ERGM simulation. `control.simulate`, `control.simulate.formula`, and `control.simulate.formula.ergm` are all aliases for the same function.

While the others supply a full set of simulation settings, `control.simulate.ergm` when passed as a control parameter to `simulate.ergm()` allows some settings to be inherited from the ERGM stimation while overriding others.

### Usage

    control.simulate.formula.ergm(
      MCMC.burnin = MCMC.interval * 16,
      MCMC.interval = 1024,
      MCMC.prop = trim_env(~sparse),
      MCMC.prop.weights = "default",
      MCMC.prop.args = list(),
      MCMC.batch = NULL,
      MCMC.effectiveSize = NULL,
      MCMC.effectiveSize.damp = 10,
      MCMC.effectiveSize.maxruns = 1000,
      MCMC.effectiveSize.burnin.pval = 0.2,
      MCMC.effectiveSize.burnin.min = 0.05,
      MCMC.effectiveSize.burnin.max = 0.5,
      MCMC.effectiveSize.burnin.nmin = 16,
      MCMC.effectiveSize.burnin.nmax = 128,
      MCMC.effectiveSize.burnin.PC = FALSE,
      MCMC.effectiveSize.burnin.scl = 1024,
      MCMC.effectiveSize.order.max = NULL,
      MCMC.maxedges = Inf,
      MCMC.packagenames = c(),
      MCMC.runtime.traceplot = FALSE,
      network.output = "network",
      term.options = NULL,
      parallel = 0,
      parallel.type = NULL,
      parallel.version.check = TRUE,
      parallel.inherit.MT = FALSE,
      ...
    )

    control.simulate(
      MCMC.burnin = MCMC.interval * 16,
      MCMC.interval = 1024,
      MCMC.prop = trim_env(~sparse),
      MCMC.prop.weights = "default",
      MCMC.prop.args = list(),
      MCMC.batch = NULL,
      MCMC.effectiveSize = NULL,
      MCMC.effectiveSize.damp = 10,
      MCMC.effectiveSize.maxruns = 1000,
      MCMC.effectiveSize.burnin.pval = 0.2,
      MCMC.effectiveSize.burnin.min = 0.05,
      MCMC.effectiveSize.burnin.max = 0.5,
      MCMC.effectiveSize.burnin.nmin = 16,
      MCMC.effectiveSize.burnin.nmax = 128,
      MCMC.effectiveSize.burnin.PC = FALSE,
      MCMC.effectiveSize.burnin.scl = 1024,
      MCMC.effectiveSize.order.max = NULL,
      MCMC.maxedges = Inf,
      MCMC.packagenames = c(),
      MCMC.runtime.traceplot = FALSE,
      network.output = "network",
      term.options = NULL,
      parallel = 0,
      parallel.type = NULL,
      parallel.version.check = TRUE,
      parallel.inherit.MT = FALSE,
      ...
    )

    control.simulate.formula(
      MCMC.burnin = MCMC.interval * 16,
      MCMC.interval = 1024,
      MCMC.prop = trim_env(~sparse),
      MCMC.prop.weights = "default",
      MCMC.prop.args = list(),
      MCMC.batch = NULL,
      MCMC.effectiveSize = NULL,
      MCMC.effectiveSize.damp = 10,
      MCMC.effectiveSize.maxruns = 1000,
      MCMC.effectiveSize.burnin.pval = 0.2,
      MCMC.effectiveSize.burnin.min = 0.05,
      MCMC.effectiveSize.burnin.max = 0.5,
      MCMC.effectiveSize.burnin.nmin = 16,
      MCMC.effectiveSize.burnin.nmax = 128,
      MCMC.effectiveSize.burnin.PC = FALSE,
      MCMC.effectiveSize.burnin.scl = 1024,
      MCMC.effectiveSize.order.max = NULL,
      MCMC.maxedges = Inf,
      MCMC.packagenames = c(),
      MCMC.runtime.traceplot = FALSE,
      network.output = "network",
      term.options = NULL,
      parallel = 0,
      parallel.type = NULL,
      parallel.version.check = TRUE,
      parallel.inherit.MT = FALSE,
      ...
    )

    control.simulate.ergm(
      MCMC.burnin = NULL,
      MCMC.interval = NULL,
      MCMC.scale = 1,
      MCMC.prop = NULL,
      MCMC.prop.weights = NULL,
      MCMC.prop.args = NULL,
      MCMC.batch = NULL,
      MCMC.effectiveSize = NULL,
      MCMC.effectiveSize.damp = 10,
      MCMC.effectiveSize.maxruns = 1000,
      MCMC.effectiveSize.burnin.pval = 0.2,
      MCMC.effectiveSize.burnin.min = 0.05,
      MCMC.effectiveSize.burnin.max = 0.5,
      MCMC.effectiveSize.burnin.nmin = 16,
      MCMC.effectiveSize.burnin.nmax = 128,
      MCMC.effectiveSize.burnin.PC = FALSE,
      MCMC.effectiveSize.burnin.scl = 1024,
      MCMC.effectiveSize.order.max = NULL,
      MCMC.maxedges = Inf,
      MCMC.packagenames = NULL,
      MCMC.runtime.traceplot = FALSE,
      network.output = "network",
      term.options = NULL,
      parallel = 0,
      parallel.type = NULL,
      parallel.version.check = TRUE,
      parallel.inherit.MT = FALSE,
      ...
    )

### Arguments

`MCMC.burnin` | Number of proposals before any MCMC sampling is done. It typically is set to a fairly large number.
`MCMC.interval` | Number of proposals between sampled statistics.
`MCMC.prop` | Specifies the proposal (directly) and/or a series of "hints" about the structure of the model being sampled. The specification is in the form of a one-sided formula with hints separated by `+` operations. If the LHS exists and is a string, the proposal to be used is selected directly. A common and default "hint" is `~sparse`, indicating that the network is sparse and that the sample should put roughly equal weight on selecting a dyad with or without a tie as a candidate for toggling.
`MCMC.prop.weights` | Specifies the proposal distribution used in the MCMC Metropolis-Hastings algorithm. Possible choices depending on selected `reference` and `constraints` arguments of the `ergm()` function, but often include `"TNT"` and `"random"`, and the `"default"` is to use the one with the highest priority available.
`MCMC.prop.args` | An alternative, direct way of specifying additional arguments to proposal.
`MCMC.batch` | if not 0 or `NULL`, sample about this many networks per call to the lower-level code; this can be useful if `output=` is a function, where it can be used to limit the number of networks held in memory at any given time.
`MCMC.effectiveSize, MCMC.effectiveSize.damp, MCMC.effectiveSize.maxruns, MCMC.effectiveSize.burnin.pval, MCMC.effectiveSize.burnin.min, MCMC.effectiveSize.burnin.max, MCMC.effectiveSize.burnin.nmin, MCMC.effectiveSize.burnin.nmax, MCMC.effectiveSize.burnin.PC, MCMC.effectiveSize.burnin.scl, MCMC.effectiveSize.order.max` | Set `MCMC.effectiveSize` to a non-NULL value to adaptively determine the burn-in and the MCMC length needed to get the specified effective size; 50 is a reasonable value. In the adaptive MCMC mode, MCMC is run forward repeatedly (`MCMC.samplesize*MCMC.interval` steps, up to `MCMC.effectiveSize.maxruns` times) until the target effective sample size is reached or exceeded. After each run, the returned statistics are mapped to the estimating function scale, then an exponential decay model is fit to the scaled statistics to find that burn-in which would reduce the difference between the initial values of statistics and their equilibrium values by a factor of `MCMC.effectiveSize.burnin.scl` of what it initially was, bounded by `MCMC.effectiveSize.min` and `MCMC.effectiveSize.max` as proportions of sample size. If the best-fitting decay exceeds `MCMC.effectiveSize.max`, the exponential model is considered to be unsuitable and `MCMC.effectiveSize.min` is used. A Geweke diagnostic is then run, after thinning the sample to `MCMC.effectiveSize.burnin.nmax`. If this Geweke diagnostic produces a p-value higher than `MCMC.effectiveSize.burnin.pval`, it is accepted. If `MCMC.effectiveSize.burnin.PC>0`, instead of using the full sample for burn-in estimation, at most this many principal components are used instead. The effective size of the post-burn-in sample is computed via Vats, Flegal, and Jones (2015), and compared to the target effective size. If it is not matched, the MCMC run is resumed, with the additional draws needed linearly extrapolated but weighted in favor of the baseline `MCMC.samplesize` by the weighting factor `MCMC.effectiveSize.damp` (higher = less damping). Lastly, if after an MCMC run, the number of samples equals or exceeds `2*MCMC.samplesize`, the chain will be thinned by 2 until it falls below that, while doubling `MCMC.interval`. `MCMC.effectiveSize.order.max` can be used to set the order of the AR model used to estimate the effective sample size and the variance for the Geweke diagnostic.
`MCMC.maxedges` | The maximum number of edges that may occur during the MCMC sampling. If this number is exceeded at any time, sampling is stopped immediately.
`MCMC.packagenames` | Names of packages in which to look for change statistic functions in addition to those autodetected. This argument should not be needed outside of very strange setups.
`MCMC.runtime.traceplot` | Logical: If `TRUE`, plot traceplots of the MCMC sample.
`network.output` | R class with which to output networks. The options are "network" (default) and "edgelist.compressed" (which saves space but only supports networks without vertex attributes)
`term.options` | A list of additional arguments to be passed to term initializers. See `? term.options`.
`parallel` | Number of threads in which to run the sampling. Defaults to 0 (no parallelism). See the entry on parallel processing for details and troubleshooting.
`parallel.type` | API to use for parallel processing. Supported values are `"MPI"` and `"PSOCK"`. Defaults to using the `parallel` package with PSOCK clusters. See `ergm-parallel`
`parallel.version.check` | Logical: If TRUE, check that the version of `ergm` running on the slave nodes is the same as that running on the master node.
`parallel.inherit.MT` | Logical: If TRUE, slave nodes and processes inherit the `set.MT_terms()` setting.
`...` | A dummy argument to catch deprecated or mistyped control parameters.
`MCMC.scale` | For `control.simulate.ergm()` inheriting `MCMC.burnin` and `MCMC.interval` from the `ergm` fit, the multiplier for the inherited values. This can be useful because MCMC parameters used in the fit are tuned to generate a specific effective sample size for the sufficient statistic in a large MCMC sample, so the inherited values might not generate independent realisations.

### Details

This function is only used within a call to the `simulate` function. See the `usage` section in `simulate.ergm` for details.

### Value

A list with arguments as components.

### See Also

`simulate.ergm`, `simulate.formula`. `control.ergm` performs a similar function for `ergm`; `control.gof` performs a similar function for `gof`.

[Package ergm version 4.2.1 Index]