Skip to contents

Allow the user to set restrictions in the fitAbn for both the Bayesian and the MLE approach. Control function similar to build.control.

Usage

fit.control(
  method = "bayes",
  max.mode.error = 10,
  mean = 0,
  prec = 0.001,
  loggam.shape = 1,
  loggam.inv.scale = 5e-05,
  max.iters = 100,
  epsabs = 1e-07,
  error.verbose = FALSE,
  trace = 0L,
  epsabs.inner = 1e-06,
  max.iters.inner = 100,
  finite.step.size = 1e-07,
  hessian.params = c(1e-04, 0.01),
  max.iters.hessian = 10,
  max.hessian.error = 1e-04,
  factor.brent = 100,
  maxiters.hessian.brent = 10,
  num.intervals.brent = 100,
  min.pdf = 0.001,
  n.grid = 250,
  std.area = TRUE,
  marginal.quantiles = c(0.025, 0.25, 0.5, 0.75, 0.975),
  max.grid.iter = 1000,
  marginal.node = NULL,
  marginal.param = NULL,
  variate.vec = NULL,
  ncores = 1,
  cluster.type = "FORK",
  max.irls = 100,
  tol = 1e-11,
  tolPwrss = 1e-07,
  check.rankX = "message+drop.cols",
  check.scaleX = "message+rescale",
  check.conv.grad = "message",
  check.conv.singular = "message",
  check.conv.hess = "message",
  xtol_abs = 1e-06,
  ftol_abs = 1e-06,
  trace.mblogit = FALSE,
  catcov.mblogit = "free",
  epsilon = 1e-06,
  seed = 9062019L
)

Arguments

method

a character that takes one of two values: "bayes" or "mle". Overrides method argument from buildScoreCache.

max.mode.error

if the estimated modes from INLA differ by a factor of max.mode.error or more from those computed internally, then results from INLA are replaced by those computed internally. To force INLA always to be used, then max.mode.error=100, to force INLA never to be used max.mod.error=0. See also fitAbn.

mean

the prior mean for all the Gaussian additive terms for each node. INLA argument control.fixed=list(mean.intercept=...) and control.fixed=list(mean=...).

prec

the prior precision (\(\tau = \frac{1}{\sigma^2}\)) for all the Gaussian additive term for each node. INLA argument control.fixed=list(prec.intercept=...) and control.fixed=list(prec=...).

loggam.shape

the shape parameter in the Gamma distribution prior for the precision in a Gaussian node. INLA argument control.family=list(hyper = list(prec = list(prior="loggamma",param=c(loggam.shape, loggam.inv.scale)))).

loggam.inv.scale

the inverse scale parameter in the Gamma distribution prior for the precision in a Gaussian node. INLA argument control.family=list(hyper = list(prec = list(prior="loggamma",param=c(loggam.shape, loggam.inv.scale)))).

max.iters

total number of iterations allowed when estimating the modes in Laplace approximation. passed to .Call("fit_single_node", ...).

epsabs

absolute error when estimating the modes in Laplace approximation for models with no random effects. Passed to .Call("fit_single_node", ...).

error.verbose

logical, additional output in the case of errors occurring in the optimization. Passed to .Call("fit_single_node", ...).

trace

Non-negative integer. If positive, tracing information on the progress of the "L-BFGS-B" optimization is produced. Higher values may produce more tracing information. (There are six levels of tracing. To understand exactly what these do see the source code.). Passed to .Call("fit_single_node", ...).

epsabs.inner

absolute error in the maximization step in the (nested) Laplace approximation for each random effect term. Passed to .Call("fit_single_node", ...).

max.iters.inner

total number of iterations in the maximization step in the nested Laplace approximation. Passed to .Call("fit_single_node", ...).

finite.step.size

suggested step length used in finite difference estimation of the derivatives for the (outer) Laplace approximation when estimating modes. Passed to .Call("fit_single_node", ...).

hessian.params

a numeric vector giving parameters for the adaptive algorithm, which determines the optimal stepsize in the finite-difference estimation of the hessian. First entry is the initial guess, second entry absolute error. Passed to .Call("fit_single_node", ...).

max.iters.hessian

integer, maximum number of iterations to use when determining an optimal finite difference approximation (Nelder-Mead). Passed to .Call("fit_single_node", ...).

max.hessian.error

if the estimated log marginal likelihood when using an adaptive 5pt finite-difference rule for the Hessian differs by more than max.hessian.error from when using an adaptive 3pt rule then continue to minimize the local error by switching to the Brent-Dekker root bracketing method. Passed to .Call("fit_single_node", ...).

factor.brent

if using Brent-Dekker root bracketing method then define the outer most interval end points as the best estimate of \(h\) (stepsize) from the Nelder-Mead as \(h/factor.brent,h*factor.brent)\). Passed to .Call("fit_single_node", ...).

maxiters.hessian.brent

maximum number of iterations allowed in the Brent-Dekker method. Passed to .Call("fit_single_node", ...).

num.intervals.brent

the number of initial different bracket segments to try in the Brent-Dekker method. Passed to .Call("fit_single_node", ...).

min.pdf

the value of the posterior density function below which we stop the estimation only used when computing marginals, see details.

n.grid

recompute density on an equally spaced grid with n.grid points.

std.area

logical, should the area under the estimated posterior density be standardized to exactly one, useful for error checking.

marginal.quantiles

vector giving quantiles at which to compute the posterior marginal distribution at.

max.grid.iter

gives number of grid points to estimate posterior density at when not explicitly specifying a grid used to avoid excessively long computation.

marginal.node

used in conjunction with marginal.param to allow bespoke estimate of a marginal density over a specific grid. value from 1 to the number of nodes.

marginal.param

used in conjunction with marginal.node. value of 1 is for intercept, see modes entry in results for the appropriate number.

variate.vec

a vector containing the places to evaluate the posterior marginal density, must be supplied if marginal.node is not null.

ncores

The number of cores to parallelize to, see ‘Details’. If >0, the number of CPU cores to be used. -1 for all available -1 core. Only for method="mle".

cluster.type

The type of cluster to be used, see ?parallel::makeCluster. abn then defaults to "PSOCK" on Windows and "FORK" on Unix-like systems. With "FORK" the child process are started with rscript_args = "--no-environ" to avoid loading the whole workspace into each child.

max.irls

total number of iterations for estimating network scores using an Iterative Reweighed Least Square algorithm. Is this DEPRECATED?

tol

real number giving the minimal tolerance expected to terminate the Iterative Reweighed Least Square algorithm to estimate network score. Passed to irls_binomial_cpp_fast_br and irls_poisson_cpp_fast.

tolPwrss

numeric scalar passed to glmerControl - the tolerance for declaring convergence in the penalized iteratively weighted residual sum-of-squares step. Similar to tol.

check.rankX

character passed to lmerControl and glmerControl - specifying if rankMatrix(X) should be compared with ncol(X) and if columns from the design matrix should possibly be dropped to ensure that it has full rank. Defaults to message+drop.cols.

check.scaleX

character passed to lmerControl and glmerControl - check for problematic scaling of columns of fixed-effect model matrix, e.g. parameters measured on very different scales. Defaults to message+rescale.

check.conv.grad

character passed to lmerControl and glmerControl - checking the gradient of the deviance function for convergence. Defaults to message but can be one of "ignore" - skip the test; "warning" - warn if test fails; "message" - print a message if test fails; "stop" - throw an error if test fails.

check.conv.singular

character passed to lmerControl and glmerControl - checking for a singular fit, i.e. one where some parameters are on the boundary of the feasible space (for example, random effects variances equal to 0 or correlations between random effects equal to +/- 1.0). Defaults to message but can be one of "ignore" - skip the test; "warning" - warn if test fails; "message" - print a message if test fails; "stop" - throw an error if test fails.

check.conv.hess

character passed to lmerControl and glmerControl - checking the Hessian of the deviance function for convergence. Defaults to message but can be one of "ignore" - skip the test; "warning" - warn if test fails; "message" - print a message if test fails; "stop" - throw an error if test fails.

xtol_abs

Defaults to 1e-6 stop on small change of parameter value. Only for method='mle', group.var=.... Default convergence tolerance for fitted (g)lmer models is reduced to the value provided here if default values did not fit. This value here is passed to the optCtrl argument of (g)lmer (see help of lme4::convergence()).

ftol_abs

Defaults to 1e-6 stop on small change in deviance. Similar to xtol_abs.

trace.mblogit

logical indicating if output should be produced for each iteration. Directly passed to trace argument in mclogit.control. Is independent of verbose.

catcov.mblogit

Defaults to "free" meaning that there are no restrictions on the covariances of random effects between the logit equations. Set to "diagonal" if random effects pertinent to different categories are uncorrelated or "single" if random effect variances pertinent to all categories are identical.

epsilon

Defaults to 1e-8. Positive convergence tolerance \(\epsilon\) that is directly passed to the control argument of mclogit::mblogit as mclogit.control. Only for method='mle', group.var=....

seed

a non-negative integer which sets the seed in set.seed(seed).

Value

a list of control parameters for the fitAbn function.

Details

Parallelization over all children is possible via the function foreach of the package doParallel. ncores=0 or ncores=1 use single threaded foreach. ncores=-1 uses all available cores but one.

See also

build.control.

Other fitAbn: fitAbn()

Examples

ctrlmle <- abn::fit.control(method = "mle",
                       max.irls = 100,
                       tol = 10^-11,
                       tolPwrss = 1e-7,
                       xtol_abs = 1e-6,
                       ftol_abs = 1e-6,
                       epsilon = 1e-6,
                       ncores = 2,
                       cluster.type = "PSOCK",
                       seed = 9062019L)
ctrlbayes <- abn::fit.control(method = "bayes",
                         mean = 0,
                         prec = 0.001,
                         loggam.shape = 1,
                         loggam.inv.scale = 5e-05,
                         max.mode.error = 10,
                         max.iters = 100,
                         epsabs = 1e-07,
                         error.verbose = FALSE,
                         epsabs.inner = 1e-06,
                         max.iters.inner = 100,
                         finite.step.size = 1e-07,
                         hessian.params = c(1e-04, 0.01),
                         max.iters.hessian = 10,
                         max.hessian.error = 1e-04,
                         factor.brent = 100,
                         maxiters.hessian.brent = 10,
                         num.intervals.brent = 100,
                         min.pdf = 0.001,
                         n.grid = 100,
                         std.area = TRUE,
                         marginal.quantiles = c(0.025, 0.25, 0.5, 0.75, 0.975),
                         max.grid.iter = 1000,
                         marginal.node = NULL,
                         marginal.param = NULL,
                         variate.vec = NULL,
                         ncores = 1,
                         cluster.type = NULL,
                         seed = 9062019L)