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.
control.simulate.formula.ergm(
MCMC.burnin = MCMC.interval * 16,
MCMC.interval = 1024,
MCMC.prop = trim_env(~sparse + .triadic),
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 + .triadic),
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 + .triadic),
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,
...
)
A list with arguments as components.
Number of proposals before any MCMC sampling is done. It typically is set to a fairly large number.
Number of proposals between sampled statistics.
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.
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.
An alternative, direct way of specifying additional arguments to proposal.
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.
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
VaFl15m;textualergm, 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.
Lastly, if MCMC.effectiveSize is a matrix, say, \(W\), it
will be treated as a target precision (inverse-variance) matrix.
If \(V\) is the sample covariance matrix, the target effective
size \(n_{\text{eff}}\) will be set such that
\(V/n_{\text{eff}}\) is close to \(W\) in magnitude,
specifically that \(\operatorname{tr}((V/n_{\text{eff}})W)/p\approx 1\).
The maximum number of edges that may occur during the MCMC sampling. If this number is exceeded at any time, sampling is stopped immediately.
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.
Logical: If TRUE, plot traceplots of the MCMC
sample.
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)
A list of additional arguments to be passed to term initializers. See ? term.options.
Number of threads in which to run the sampling. Defaults to 0 (no parallelism). See the entry on parallel processing for details and troubleshooting.
API to use for parallel processing. Supported values
are "MPI" and "PSOCK". Defaults to using the parallel
package with PSOCK clusters. See ergm-parallel
Logical: If TRUE, check that the version of ergm running on the slave nodes is the same as that running on the master node.
Logical: If TRUE, slave nodes and
processes inherit the set.MT_terms() setting.
A dummy argument to catch deprecated or mistyped control parameters.
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.
This function is only used within a call to the ERGM simulate()
function. See the Usage section in simulate.ergm() for
details.
simulate.ergm(), simulate.formula().
control.ergm() performs a similar function for
ergm(); control.gof() performs a similar function
for gof().