control.ergm  R Documentation 
Auxiliary function as user interface for finetuning 'ergm' fitting.
control.ergm(
drop = TRUE,
init = NULL,
init.method = NULL,
main.method = c("MCMLE", "StochasticApproximation"),
force.main = FALSE,
main.hessian = TRUE,
checkpoint = NULL,
resume = NULL,
MPLE.samplesize = .Machine$integer.max,
init.MPLE.samplesize = function(d, e) max(sqrt(d), e, 40) * 8,
MPLE.type = c("glm", "penalized", "logitreg"),
MPLE.maxit = 10000,
MPLE.nonvar = c("warning", "message", "error"),
MPLE.nonident = c("warning", "message", "error"),
MPLE.nonident.tol = 1e10,
MPLE.covariance.samplesize = 500,
MPLE.covariance.method = "invHess",
MPLE.covariance.sim.burnin = 1024,
MPLE.covariance.sim.interval = 1024,
MPLE.constraints.ignore = FALSE,
MCMC.prop = trim_env(~sparse),
MCMC.prop.weights = "default",
MCMC.prop.args = list(),
MCMC.interval = NULL,
MCMC.burnin = EVL(MCMC.interval * 16),
MCMC.samplesize = NULL,
MCMC.effectiveSize = NULL,
MCMC.effectiveSize.damp = 10,
MCMC.effectiveSize.maxruns = 16,
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 = 32,
MCMC.effectiveSize.order.max = NULL,
MCMC.return.stats = 2^12,
MCMC.runtime.traceplot = FALSE,
MCMC.maxedges = Inf,
MCMC.addto.se = TRUE,
MCMC.packagenames = c(),
SAN.maxit = 4,
SAN.nsteps.times = 8,
SAN = control.san(term.options = term.options, SAN.maxit = SAN.maxit, SAN.prop.weights
= MCMC.prop.weights, SAN.prop.args = MCMC.prop.args, SAN.nsteps = EVL(MCMC.burnin,
16384) * SAN.nsteps.times, SAN.samplesize = EVL(MCMC.samplesize, 1024),
SAN.packagenames = MCMC.packagenames, parallel = parallel, parallel.type =
parallel.type, parallel.version.check = parallel.version.check),
MCMLE.termination = c("confidence", "Hummel", "Hotelling", "precision", "none"),
MCMLE.maxit = 60,
MCMLE.conv.min.pval = 0.5,
MCMLE.confidence = 0.99,
MCMLE.confidence.boost = 2,
MCMLE.confidence.boost.threshold = 1,
MCMLE.confidence.boost.lag = 4,
MCMLE.NR.maxit = 100,
MCMLE.NR.reltol = sqrt(.Machine$double.eps),
obs.MCMC.mul = 1/4,
obs.MCMC.samplesize.mul = sqrt(obs.MCMC.mul),
obs.MCMC.samplesize = EVL(round(MCMC.samplesize * obs.MCMC.samplesize.mul)),
obs.MCMC.effectiveSize = NVL3(MCMC.effectiveSize, . * obs.MCMC.mul),
obs.MCMC.interval.mul = sqrt(obs.MCMC.mul),
obs.MCMC.interval = EVL(round(MCMC.interval * obs.MCMC.interval.mul)),
obs.MCMC.burnin.mul = sqrt(obs.MCMC.mul),
obs.MCMC.burnin = EVL(round(MCMC.burnin * obs.MCMC.burnin.mul)),
obs.MCMC.prop = MCMC.prop,
obs.MCMC.prop.weights = MCMC.prop.weights,
obs.MCMC.prop.args = MCMC.prop.args,
obs.MCMC.impute.min_informative = function(nw) network.size(nw)/4,
obs.MCMC.impute.default_density = function(nw) 2/network.size(nw),
MCMLE.min.depfac = 2,
MCMLE.sampsize.boost.pow = 0.5,
MCMLE.MCMC.precision = if (startsWith("confidence", MCMLE.termination[1])) 0.1 else
0.005,
MCMLE.MCMC.max.ESS.frac = 0.1,
MCMLE.metric = c("lognormal", "logtaylor", "Median.Likelihood", "EF.Likelihood",
"naive"),
MCMLE.method = c("BFGS", "NelderMead"),
MCMLE.dampening = FALSE,
MCMLE.dampening.min.ess = 20,
MCMLE.dampening.level = 0.1,
MCMLE.steplength.margin = 0.05,
MCMLE.steplength = NVL2(MCMLE.steplength.margin, 1, 0.5),
MCMLE.steplength.parallel = c("observational", "never"),
MCMLE.sequential = TRUE,
MCMLE.density.guard.min = 10000,
MCMLE.density.guard = exp(3),
MCMLE.effectiveSize = 64,
obs.MCMLE.effectiveSize = NVL3(MCMLE.effectiveSize, . * obs.MCMC.mul),
MCMLE.interval = 1024,
MCMLE.burnin = MCMLE.interval * 16,
MCMLE.samplesize.per_theta = 32,
MCMLE.samplesize.min = 256,
MCMLE.samplesize = NULL,
obs.MCMLE.samplesize.per_theta = round(MCMLE.samplesize.per_theta *
obs.MCMC.samplesize.mul),
obs.MCMLE.samplesize.min = 256,
obs.MCMLE.samplesize = NULL,
obs.MCMLE.interval = round(MCMLE.interval * obs.MCMC.interval.mul),
obs.MCMLE.burnin = round(MCMLE.burnin * obs.MCMC.burnin.mul),
MCMLE.steplength.solver = c("glpk", "lpsolve"),
MCMLE.last.boost = 4,
MCMLE.steplength.esteq = TRUE,
MCMLE.steplength.miss.sample = function(x1) ceiling(sqrt(ncol(rbind(x1)))),
MCMLE.steplength.min = 1e04,
MCMLE.effectiveSize.interval_drop = 2,
MCMLE.save_intermediates = NULL,
MCMLE.nonvar = c("message", "warning", "error"),
MCMLE.nonident = c("warning", "message", "error"),
MCMLE.nonident.tol = 1e10,
SA.phase1_n = function(q, ...) max(200, 7 + 3 * q),
SA.initial_gain = 0.1,
SA.nsubphases = 4,
SA.min_iterations = function(q, ...) (7 + q),
SA.max_iterations = function(q, ...) (207 + q),
SA.phase3_n = 1000,
SA.interval = 1024,
SA.burnin = SA.interval * 16,
SA.samplesize = 1024,
CD.samplesize.per_theta = 128,
obs.CD.samplesize.per_theta = 128,
CD.nsteps = 8,
CD.multiplicity = 1,
CD.nsteps.obs = 128,
CD.multiplicity.obs = 1,
CD.maxit = 60,
CD.conv.min.pval = 0.5,
CD.NR.maxit = 100,
CD.NR.reltol = sqrt(.Machine$double.eps),
CD.metric = c("naive", "lognormal", "logtaylor", "Median.Likelihood", "EF.Likelihood"),
CD.method = c("BFGS", "NelderMead"),
CD.dampening = FALSE,
CD.dampening.min.ess = 20,
CD.dampening.level = 0.1,
CD.steplength.margin = 0.5,
CD.steplength = 1,
CD.adaptive.epsilon = 0.01,
CD.steplength.esteq = TRUE,
CD.steplength.miss.sample = function(x1) ceiling(sqrt(ncol(rbind(x1)))),
CD.steplength.min = 1e04,
CD.steplength.parallel = c("observational", "always", "never"),
CD.steplength.solver = c("glpk", "lpsolve"),
loglik = control.logLik.ergm(),
term.options = NULL,
seed = NULL,
parallel = 0,
parallel.type = NULL,
parallel.version.check = TRUE,
parallel.inherit.MT = FALSE,
...
)
drop 
Logical: If TRUE, terms whose observed statistic values are at the extremes of their possible ranges are dropped from the fit and their corresponding parameter estimates are set to plus or minus infinity, as appropriate. This is done because maximum likelihood estimates cannot exist when the vector of observed statistic lies on the boundary of the convex hull of possible statistic values. 
init 
numeric or
Passing 
init.method 
A chatacter vector or Valid initial methods for a given reference are set by the

main.method 
One of "MCMLE" (default) or
"StochasticApproximation". Chooses the estimation method used
to find the MLE. 
force.main 
Logical: If TRUE, then force MCMCbased estimation method, even if the exact MLE can be computed via maximum pseudolikelihood estimation. 
main.hessian 
Logical: If TRUE, then an approximate Hessian matrix is used in the MCMCbased estimation method. 
checkpoint 
At the start of every iteration, save the state
of the optimizer in a way that will allow it to be resumed. The
name is passed through 
resume 
If given a file name of an 
MPLE.samplesize, init.MPLE.samplesize 
These parameters control the maximum number of dyads (potential ties) that will be used by the MPLE to construct the predictor matrix for its logistic regression. In general, the algorithm visits dyads in a systematic sample that, if it does not hit one of these limits, will visit every informative dyad. If a limit is exceeded, casecontrol approximation to the likelihood, comprising all edges and those nonedges that have been visited by the algorithm before the limit was exceeded will be used.

MPLE.type 
One of 
MPLE.maxit 
Maximum number of iterations for 
MPLE.nonident, MPLE.nonident.tol, MPLE.nonvar, MCMLE.nonident, MCMLE.nonident.tol, MCMLE.nonvar 
A rudimentary nonidentifiability/multicollinearity diagnostic. If

MPLE.covariance.method, MPLE.covariance.samplesize, MPLE.covariance.sim.burnin, MPLE.covariance.sim.interval 
Controls for estimating the MPLE covariance
matrix. 
MPLE.constraints.ignore 
If 
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 onesided formula
with hints separated by A common and default "hint" is 
MCMC.prop.weights 
Specifies the proposal
distribution used in the MCMC MetropolisHastings algorithm. Possible
choices depending on selected 
MCMC.prop.args 
An alternative, direct way of specifying additional arguments to proposal. 
MCMC.interval 
Number of proposals between sampled statistics. Increasing interval will reduces the autocorrelation in the sample, and may increase the precision in estimates by reducing MCMC error, at the expense of time. Set the interval higher for larger networks. 
MCMC.burnin 
Number of proposals before any MCMC sampling is done. It typically is set to a fairly large number. 
MCMC.samplesize 
Number of network statistics, randomly drawn from a given distribution on the set of all networks, returned by the MetropolisHastings algorithm. Increasing sample size may increase the precision in the estimates by reducing MCMC error, at the expense of time. Set it higher for larger networks, or when using parallel functionality. 
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 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 burnin which would reduce
the difference between the initial values of statistics and their
equilibrium values by a factor of A Geweke diagnostic is then run, after thinning the sample to
If The effective
size of the postburnin 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.return.stats 
Numeric: If positive, include an

MCMC.runtime.traceplot 
Logical: If 
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.addto.se 
Whether to add the standard errors induced by the MCMC algorithm to the estimates' standard errors. 
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. 
SAN.maxit 
When 
SAN.nsteps.times 
Multiplier for 
SAN 
Control arguments to 
MCMLE.termination 
The criterion used for terminating MCMLE estimation:
Note that this criterion is incompatible with
Note that this criterion is incompatible with

MCMLE.maxit 
Maximum number of times the parameter for the MCMC should be updated by maximizing the MCMC likelihood. At each step the parameter is changed to the values that maximizes the MCMC likelihood based on the current sample. 
MCMLE.conv.min.pval 
The Pvalue used in the Hotelling test for early termination. 
MCMLE.confidence 
The confidence level for declaring
convergence for 
MCMLE.confidence.boost 
The maximum increase factor in sample
size (or target effective size, if enabled) when the

MCMLE.confidence.boost.threshold, MCMLE.confidence.boost.lag 
Sample size or target effective size will be increaed if the distance from the tolerance region fails to decrease more than MCMLE.confidence.boost.threshold in this many successive iterations. 
MCMLE.NR.maxit, MCMLE.NR.reltol 
The method, maximum number of
iterations and relative tolerance to use within the 
obs.MCMC.prop, obs.MCMC.prop.weights, obs.MCMC.prop.args, obs.MCMLE.effectiveSize, obs.MCMC.samplesize, obs.MCMC.burnin, obs.MCMC.interval, obs.MCMC.mul, obs.MCMC.samplesize.mul, obs.MCMC.burnin.mul, obs.MCMC.interval.mul, obs.MCMC.effectiveSize, obs.MCMLE.burnin, obs.MCMLE.interval, obs.MCMLE.samplesize, obs.MCMLE.samplesize.per_theta, obs.MCMLE.samplesize.min 
Corresponding MCMC parameters and settings used for the constrained sample when
unobserved data are present in the estimation routine. By default, they are controlled by the These can, in turn, be controlled by 
obs.MCMC.impute.min_informative, obs.MCMC.impute.default_density 
Controls for imputation of missing dyads for initializing MCMC
sampling. If numeric, 
MCMLE.min.depfac, MCMLE.sampsize.boost.pow 
When using adaptive MCMC effective size, and methods that increase the MCMC sample size, use 
MCMLE.MCMC.precision, MCMLE.MCMC.max.ESS.frac 
If effective sample size is used (see 
MCMLE.metric 
Method to calculate the loglikelihood approximation. See Hummel et al (2010) for an explanation of "lognormal" and "naive". 
MCMLE.method 
Deprecated. By default, ergm uses 
MCMLE.dampening 
(logical) Should likelihood dampening be used? 
MCMLE.dampening.min.ess 
The effective sample size below which dampening is used. 
MCMLE.dampening.level 
The proportional distance from boundary of the convex hull move. 
MCMLE.steplength.margin 
The extra margin required for a Hummel step
to count as being inside the convex hull of the sample. Set this to 0 if
the step length gets stuck at the same value over several iteraions. Set it
to 
MCMLE.steplength 
Multiplier for step length (on the meanvalue parameter scale), which may (for values less than one) make fitting more stable at the cost of computational efficiency. If 
MCMLE.steplength.parallel 
Whether parallel multisection
search (as opposed to a bisection search) for the Hummel step
length should be used if running in multiple threads. Possible
values (partially matched) are 
MCMLE.sequential 
Logical: If TRUE, the next iteration of the fit uses
the last network sampled as the starting network. If FALSE, always use the
initially passed network. The results should be similar (stochastically),
but the TRUE option may help if the 
MCMLE.density.guard.min, MCMLE.density.guard 
A simple heuristic to
stop optimization if it finds itself in an overly dense region, which
usually indicates ERGM degeneracy: if the sampler encounters a network
configuration that has more than 
MCMLE.effectiveSize, MCMLE.effectiveSize.interval_drop, MCMLE.burnin, MCMLE.interval, MCMLE.samplesize, MCMLE.samplesize.per_theta, MCMLE.samplesize.min 
Sets the corresponding 
MCMLE.steplength.solver 
The linear program solver to use for
MCMLE step length calculation. Can be either 
MCMLE.last.boost 
For the Hummel termination criterion, increase the MCMC sample size of the last iteration by this factor. 
MCMLE.steplength.esteq 
For curved ERGMs, should the estimating function values be used to compute the Hummel step length? This allows the Hummel stepping algorithm converge when some sufficient statistics are at 0. 
MCMLE.steplength.miss.sample 
In fitting the missing data MLE, the rules for step length become more complicated. In short, it is necessary for all points in the constrained sample to be in the convex hull of the unconstrained (though they may be on the border); and it is necessary for their centroid to be in its interior. This requires checking a large number of points against whether they are in the convex hull, so to speed up the procedure, a sample is taken of the points most likely to be outside it. This parameter specifies the sample size or a function of the unconstrained sample matrix to determine the sample size. 
MCMLE.steplength.min 
Stops MCMLE estimation when the step length gets stuck below this minimum value. 
MCMLE.save_intermediates 
Every iteration, after MCMC
sampling, save the MCMC sample and some miscellaneous information
to a file with this name. This is mainly useful for diagnostics
and debugging. The name is passed through 
SA.phase1_n 
A constant or a function of number of free
parameters 
SA.initial_gain 
Initial gain to Phase 2 of the stochastic approximation algorithm. Defaults to 0.1. See Snijders (2002) for details. 
SA.nsubphases 
Number of subphases in Phase 2 of the
stochastic approximation algorithm. Defaults to

SA.min_iterations, SA.max_iterations 
A constant or a function
of number of free parameters 
SA.phase3_n 
Sample size for the MCMC sample in Phase 3 of the stochastic approximation algorithm. See Snijders (2002) for details. 
SA.burnin, SA.interval, SA.samplesize 
Sets the corresponding

CD.samplesize.per_theta, obs.CD.samplesize.per_theta, CD.maxit, CD.conv.min.pval, CD.NR.maxit, CD.NR.reltol, CD.metric, CD.method, CD.dampening, CD.dampening.min.ess, CD.dampening.level, CD.steplength.margin, CD.steplength, CD.steplength.parallel, CD.adaptive.epsilon, CD.steplength.esteq, CD.steplength.miss.sample, CD.steplength.min, CD.steplength.solver 
Miscellaneous tuning parameters of the CD sampler and
optimizer. These have the same meaning as their Note that only the Hotelling's stopping criterion is implemented for CD. 
CD.nsteps, CD.multiplicity 
Main settings for contrastive
divergence to obtain initial values for the estimation:
respectively, the number of Metropolis–Hastings steps to take
before reverting to the starting value and the number of
tentative proposals per step. Computational experiments indicate
that increasing In practice, MPLE, when available, usually outperforms CD for
even a very high The default values have been set experimentally, providing a reasonably stable, if not great, starting values. 
CD.nsteps.obs, CD.multiplicity.obs 
When there are missing dyads,

loglik 
See 
term.options 
A list of additional arguments to be passed to term initializers. See 
seed 
Seed value (integer) for the random number generator. See

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 
parallel.version.check 
Logical: If TRUE, check that the version of

parallel.inherit.MT 
Logical: If TRUE, slave nodes and
processes inherit the 
... 
A dummy argument to catch deprecated or mistyped control parameters. 
This function is only used within a call to the ergm()
function.
See the usage
section in ergm()
for details.
A list with arguments as components.
Snijders, T.A.B. (2002), Markov Chain Monte Carlo Estimation of Exponential Random Graph Models. Journal of Social Structure. Available from https://www.cmu.edu/joss/content/articles/volume3/Snijders.pdf.
Firth (1993), Bias Reduction in Maximum Likelihood Estimates. Biometrika, 80: 2738.
Hunter, D. R. and M. S. Handcock (2006), Inference in curved exponential family models for networks. Journal of Computational and Graphical Statistics, 15: 565583.
Hummel, R. M., Hunter, D. R., and Handcock, M. S. (2012), Improving SimulationBased Algorithms for Fitting ERGMs, Journal of Computational and Graphical Statistics, 21: 920939.
Kristoffer Sahlin. Estimating convergence of Markov chain Monte Carlo simulations. Master's Thesis. Stockholm University, 2011. https://www2.math.su.se/matstat/reports/master/2011/rep2/report.pdf
ergm()
. The control.simulate
function
performs a similar function for simulate.ergm
;
control.gof
performs a similar function for gof
.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.