Description Usage Arguments Details Value References See Also
Auxiliary function as user interface for finetuning 'ergm' fitting.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160  control.ergm(
drop = TRUE,
init = NULL,
init.method = NULL,
main.method = c("MCMLE", "RobbinsMonro", "StochasticApproximation", "Stepping"),
force.main = FALSE,
main.hessian = TRUE,
checkpoint = NULL,
resume = NULL,
MPLE.max.dyad.types = 1e+06,
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.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.order.max = NULL,
MCMC.return.stats = TRUE,
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.point.exp = 1,
MCMLE.steplength.prefilter = FALSE,
MCMLE.steplength = NVL2(MCMLE.steplength.margin, 1, 0.5),
MCMLE.steplength.parallel = c("observational", "always", "never"),
MCMLE.steplength.precision = 0.25,
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.last.boost = 4,
MCMLE.steplength.esteq = TRUE,
MCMLE.steplength.miss.sample = function(x1) ceiling(sqrt(ncol(rbind(x1)))),
MCMLE.steplength.maxit = NVL3(MCMLE.steplength.margin, if (. < 0) 5 else 25),
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 = NULL,
SA.initial_gain = NULL,
SA.nsubphases = 4,
SA.niterations = NULL,
SA.phase3_n = NULL,
SA.interval = 1024,
SA.burnin = SA.interval * 16,
SA.samplesize = 1024,
RM.phase1n_base = 7,
RM.phase2n_base = 100,
RM.phase2sub = 7,
RM.init_gain = 0.5,
RM.phase3n = 500,
RM.interval = 1024,
RM.burnin = RM.interval * 16,
RM.samplesize = 1024,
Step.maxit = 50,
Step.gridsize = 100,
Step.interval = 1024,
Step.burnin = Step.interval * 16,
Step.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.maxit = 25,
CD.steplength.min = 1e04,
CD.steplength.parallel = c("observational", "always", "never"),
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),"RobbinsMonro",
"StochasticApproximation", or "Stepping". Chooses the estimation method
used to find the MLE. Note that in recent versions of ERGM, the enhancements of 
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, MPLE.max.dyad.types 
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.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.order.max 
Set 
MCMC.return.stats 
Logical: If TRUE, return the matrix of MCMCsampled
network statistics. This matrix should have 
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 \code{MCMLE.steplength}\ne 1 or \code{MCMLE.steplength.margin}=\code{NULL}.

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.point.exp 
For observation process ERGMs,
allows the step length to scale the spread of points differently
from the amount of shift towards the centroid by exponentiating
the former by 
MCMLE.steplength.prefilter 
Whether to enable prefiltering of target and test points in the Hummel step length calculation. May improve performance for large MCMC sample sizes with missing data MLE. 
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.steplength.precision 
Required relative precision of the step length calculation: (ul)/l. 
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.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.maxit 
Maximum number of iterations in searching for the best step length. 
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 
Number of MCMC samples to draw in Phase 1 of the stochastic approximation algorithm. Defaults to 7 plus 3 times the number of terms in the model. See Snijders (2002) for details. 
SA.initial_gain 
Initial gain to Phase 2 of the stochastic approximation algorithm. See Snijders (2002) for details. 
SA.nsubphases 
Number of subphases in Phase 2 of the stochastic
approximation algorithm. Defaults to 
SA.niterations 
Number of MCMC samples to draw in Phase 2 of the stochastic approximation algorithm. Defaults to 7 plus the number of terms in the model. See Snijders (2002) for details. 
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

RM.phase1n_base, RM.phase2n_base, RM.phase2sub, RM.init_gain, RM.phase3n 
The RobbinsMonro control parameters are not yet documented. 
RM.burnin, RM.interval, RM.samplesize 
Sets the corresponding

Step.maxit 
Maximum number of iterations (steps) allowed by the "Stepping" method. 
Step.gridsize 
Integer N such that the "Stepping" style of optimization chooses a step length equal to the largest possible multiple of 1/N. See Hummel et al. (2012) for details. 
Step.burnin, Step.interval, Step.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.maxit, CD.steplength.min 
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.