control.ergm {ergm}R Documentation

Auxiliary for Controlling ERGM Fitting

Description

Auxiliary function as user interface for fine-tuning 'ergm' fitting.

Usage

control.ergm(prop.weights = "default", prop.args = NULL,
             prop.weights.diss = "default", prop.args.diss = NULL, 
             nr.maxit = 100,
             calc.mcmc.se = TRUE, hessian = TRUE, compress = TRUE,
             SAN.burnin=NULL,
             maxNumDyadTypes = 1e+06, maxedges = 20000, maxchanges = 1e+06,
             maxMPLEsamplesize = 1e+05, MPLEtype=c("glm", "penalized"), 
             nr.reltol=sqrt(.Machine$double.eps), trace = 0,
             steplength = 0.5, sequential=TRUE,
             drop = TRUE, force.mcmc = FALSE, check.degeneracy=FALSE, 
             mcmc.precision = 0.05, 
             metric = c("lognormal", "Median.Likelihood",
             "EF.Likelihood", "naive"),
             method = c("BFGS", "Nelder-Mead"),
             trustregion = 20, initial.loglik = NULL, loglik.nsteps = 20,
             initial.network = NULL,
             style = c("Newton-Raphson", "Robbins-Monro",
             "Stochastic-Approximation", "Stepping","PILA"),
             style.dyn = c("Robbins-Monro", "SPSA", "SPSA2"),
             phase1_n = NULL, initial_gain = NULL,
             nsubphases = "maxit", niterations = NULL, phase3_n = NULL,
             RobMon.phase1n_base = 7, RobMon.phase2n_base = 100, RobMon.phase2sub
             = 7, RobMon.init_gain = 0.5, RobMon.phase3n = 500, 
             stepMCMCsize=100, gridsize=100, dyninterval=1000, 
             packagenames="ergm", parallel = 0, returnMCMCstats = TRUE)
             

Arguments

prop.weights

Specifies the proposal distribution used in the MCMC Metropolis-Hastings algorithm. Possible choices are "TNT" or "random"; the "default" is one of these two, depending on the constraints in place (as defined by the constraints argument of the ergm function), though not all weights may be used with all constraints. The TNT (tie / no tie) option puts roughly equal weight on selecting a dyad with or without a tie as a candidate for toggling, whereas the random option puts equal weight on all possible dyads (though the interpretation of random may change according to the constraints in place). When no constraints are in place, the default is TNT, which appears to improve Markov chain mixing particularly for networks with a low edge density, as is typical of many realistic social networks.

prop.args

An alternative, direct way of specifying additional arguments to proposal.

prop.weights.diss

As prop.weights, for dissolution model.

prop.args.diss

As prop.args, for dissolution model.

nr.maxit

count; The maximum number of iterations in the Newton-Raphson optimization. Defaults to 1000. maxit gives the total number of likelihood function evaluations.

calc.mcmc.se

logical; should the contribution to the standard errors of the estimator incurred by the MCMC sampling be computed. Default is TRUE.

hessian

logical; Should the Hessian matrix of the likelihood function be computed. Default is TRUE.

compress

logical; Should the matrix of sample statistics returned be compressed to the set of unique statistics with a column of frequencies post-pended. This also uses a compression algorithm in the computation of the maximum psuedo-likelihood estimate that will dramatically speed it for large networks. Default is FALSE.

SAN.burnin

Burnin used for calling SAN routine. If NULL, burnin is used.

maxNumDyadTypes

count; The maximum number of unique pseudolikelihood change statistics to be allowed if compress=TRUE. It is only relevant in that case. Default is 10000.

maxedges

Maximum number of edges for which to allocate space.

maxchanges

Maximum number of changes in dynamic network simulation for which to allocate space.

maxMPLEsamplesize

count; the sample size to use for endogenous sampling in the pseudolikelihood computation. Default is 10^11.

MPLEtype

one of "glm" or "penalized"; method to use for psuedolikelihood. "glm" is the usual formal logistic regression. "penalized" uses the bias-reduced method of Firth (1993) as originally implemented by Meinhard Ploner, Daniela Dunkler, Harry Southworth, and Georg Heinze in the "logistf" package. Default is "glm".

nr.reltol

Relative convergence tolerance, passed to optimization routines like optim. See the reltol control argument for the optim function.

trace

non-negative integer; If positive, tracing information on the progress of the optimization is produced. Higher values may produce more tracing information: for method "L-BFGS-B" there are six levels of tracing. (To understand exactly what these do see the source code for optim: higher levels give more detail.)

steplength

Multiplier for step length, to make fitting more stable at the cost of efficiency.

sequential

Should the next iteration of the fit use the last network sampled as the starting network or always use the initially passed network? The results should be similar (stochastically), but the sequential=TRUE option if meanstats is far from the passed network.

drop

logical; Should the degenerate terms in the model be dropped from the fit? If statistics occur on the extreme of their range they correspond to infinite parameter estimates. Default is TRUE.

force.mcmc

logical; should MCMC maximum likelihood be used? Only relevant for dyadic independent networks, in which the MLE could be found using MPLE instead.

check.degeneracy

Logical: Should the diagnostics include a check for model degeneracy?

mcmc.precision

vector; upper bounds on the precision of the standard errors induced by the MCMC algorithm. Defaults to 0.05.

metric

character; The name of the optimization metric to use. Defaults to "Median.Likelihood". See Hummel et al (2010) for an explanation of "lognormal" and "naive".

method

character; The name of the optimization method to use. See optim for the options. The default method "BFGS" is a quasi-Newton method (also known as a variable metric algorithm). It is attributed to Broyden, Fletcher, Goldfarb and Shanno. This uses function values and gradients to build up a picture of the surface to be optimized.

trustregion

numeric; The maximum amount the algorithm will allow the approximated likelihood to be increased at a given iteration. Defaults to 20. See Snijders (2002) for details.

initial.loglik

Initial value of loglikelihood, if known.

loglik.nsteps

Number of bridges to use to evaluate dyad-dependent log-likelihood if eval.loglik=TRUE.

initial.network

Initial network for MCMC, if different from observed network.

style

character; The style of maximum likelihood estimation to use. The default is optimization of an MCMC estimate of the log-likelihood. An alternative is to use a form of stochastic approximation ("Robbins-Monro"). Another alternative is a partial stepping algorithm ("Stepping") as in Hummel et al. (2010). The direct use of the likelihood function has many theoretical advantages over stochastic approximation, but the choice will depend on the model and data being fit. See Handcock (2000) and Hunter and Handcock (2006) for details.

style.dyn

character; The style of method of moments estimation to use. The default is a form of stochastic approximation ("Robbins-Monro"), but it should only be used if it is known a priori that the derivative of each element of the equilibrium expected values of statistics of interest with respect to the corresponding formation phase parameter is positive. The other option, ("SPSA") is less precise but does not make this assumption. "SPSA2" is multithreaded, but runs slower for some reason.

phase1_n

count; The 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.

initial_gain

numeric; The initial gain to Phase 2 of the stochastic approximation algorithm. Defaults to 0.1. See Snijders (2002) for details.

nsubphases

count; The number of sub-phases in Phase 2 of the stochastic approximation algorithm. Defaults to maxit. See Snijders (2002) for details.

niterations

count; The 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.

phase3_n

count; The sample size for the MCMC sample in Phase 3 of the stochastic approximation algorithm. Defaults to 1000. See Snijders (2002) for details.

RobMon.phase1n_base

Robbins-Monro control parameter

RobMon.phase2n_base

Robbins-Monro control parameter

RobMon.phase2sub

Robbins-Monro control parameter

RobMon.init_gain

Robbins-Monro control parameter

RobMon.phase3n

Robbins-Monro control parameter

returnMCMCstats

logical; If this is TRUE (the default) the matrix of change statistics from the MCMC run is returned as component sample. This matrix is actually an object of class mcmc and can be used directly in the CODA package to assess MCMC convergence.

stepMCMCsize

MCMC sample size for the preliminary steps of the "Stepping" style of optimization. This is usually chosen to be smaller than the final MCMC sample size (which equals MCMCsamplesize).

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. (2010) for details.

dyninterval

Number of Metropolis-Hastings proposal for each phase in the dynamic network simulation.

packagenames

Names of packages in which changestatistics are found.

parallel

Number of threads in which to run the sampling.

Details

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

Value

A list with arguments as components.

References

See Also

ergm. The control.simulate function performs a similar function for simulate.ergm; control.gof performs a similar function for gof.


[Package ergm version 2.4-3 Index]