options: spaMM options settings

In spaMM: Mixed-Effect Models, with or without Spatial Random Effects

spaMM options settings

Description

Allow the user to set and examine a variety of options which affect operations of the spaMM package.

Usage

spaMM.options(..., warn = TRUE)

spaMM.getOption(x)

Arguments

x	a character string holding an option name.
warn	Boolean: whether to warn if a previously undefined options is being defined (a protection against typos).
...	A named value or a list of named values. The following values, with their defaults, are used in spaMM: LevenbergM=NULL: NULL or boolean. Whether to use a Levenberg-Marquardt-like algorithm (see Details) by default in most computations. But it is advised to use instead control.HLfit=list(LevenbergM=...) to control this on a case-by-case basis. The joint default behaviour is that Levenberg-Marquardt is used by default for binomial response data that takes only extreme values (in particular, for binary 0/1 response), and that for other models the fitting algorithm switches to it if divergence is suspected. FALSE inhibits its use; TRUE forces its use for all iterative least-square fits, except when 'confint()' is called. example_maxtime=0.7: Used in the documentation and tests to control whether the longer examples should be run. The approximate running time of given examples on one author's laptop is compared to this value. optimizer1D="optimize": Optimizer for one-dimensional optimization. If you want to control the initial value, you should select another optimizer. optimizer=".safe_opt": Optimizer for optimization in several dimensions. Use optimizer="nloptr" to call nloptr with method "NLOPT_LN_BOBYQA"; use optimizer="bobyqa" to call bobyqa; and use optimizer="L-BFGS-B" to call optim with method "L-BFGS-B". The default ".safe_opt" uses nloptr except in some cases where it expects or detects problems with it (the source code should be consulted for details). The optimizer can also be specified on a fit-by-fit basis as the value of control$optimizer in a fitme call, or as the value of control.corrHLfit$optimizer. nloptr: Default control values of nloptr calls. bobyqa: Default control values of bobyqa calls. maxLambda=1e10: The maximum value of lambda: higher fitted lambda values in HLfit are reduced to this. Since version 3.1.0, a much smaller lambda bound is deduced from maxLambda for COMPoisson and log-link response families. regul_lev_lambda Numeric (default: 1e-8); lambda leverages numerically 1 are replaced by 1- regul_lev_lambda COMP_maxn: Number of terms for truncation of infinite sums that are evaluated in the fitting of COMPoisson models. CMP_asympto_cond: Function returning the condition for applying an approximation or the COMPoisson response family, as detailed in COMPoisson. Gamma_min_y=1e-10: A minimum response value in Gamma-response models; used to check data, and in simulate() to correct the simulation results. QRmethod: A character string, to control whether dense matrix or sparse matrix methods are used in intensive matrix computations, overcoming the default choices made by spaMM in this respect. Possible values are "dense" and "sparse". matrix_method: A character string, to control the factorization of dense model matrices. Default value is "def_sXaug_EigenDense_QRP_scaled". The source code should be consulted for further information. Matrix_method: A character string, to control the factorization of sparse model matrices. Default value is "def_sXaug_Matrix_QRP_CHM_scaled". The source code should be consulted for further information. stylefns: Default colors of some screen output (notably that of some fitting functions when called with argument verbose=c(TRACE=TRUE)) barstyle: Integer, or Boolean interpreted as Integer, or quoted expression evaluating to such types; controlling the display of some progress bars. If zero, no progress bar should be displayed; otherwise, a bar should be displayed. Further, when txtProgressBar is called, barstyle is passed as its style argument. Default is quote(if(interactive()) {3L} else {0L}) (in a parallel setting, child processes may display the bar if the parent process is interactive). and many other undocumented values for programming or development purposes. Additional options without default values can also be used (e.g., see algebra).

Details

spaMM.options() provides an interface for changing maximal values of parameters of the Matérn correlation function. However, it is not recommended to change these values unless a spaMM message specifically suggests so.

By default spaMM use Iteratively Reweighted Least Squares (IRLS) methods to estimate fixed-effect parameters (jointly with predictions of random effects). However, a Levenberg-Marquardt algorithm, as described by Nocedal & Wright (1999, p. 266), is also implemented. The Levenberg-Marquardt algorithm is designed to optimize a single objective function with respect to all its parameters. It is thus well suited to compute a PQL fit, which is based on maximization of a single function, the h-likelihood. By contrast, in a fit of a mixed model by (RE)ML, one computes jointly fixed-effect estimates that maximizes marginal likelihood, and random-effect values that maximize h-likelihood given the fixed-effect estimates. The gradient of marginal likelihood with respect to fixed-effect coefficients does not generally vanishes at the solution (although it remains close to zero except in “difficult” cases with typically little information in the data). The Levenberg-Marquardt algorithm is not directly applicable in this case, as it may produce random-effect values that increases marginal likelihood rather than h-likelihood. The (RE)ML variant of the algorithm implemented in spaMM may therefore use additional nested h-likelihood-maximizing steps for correcting random-effect values. In version 3.1.0 this variant was revised for improved performance in difficult cases.

Value

For spaMM.getOption, the current value set for option x, or NULL if the option is unset.

For spaMM.options(), a list of all set options. For spaMM.options(<name>), a list of length one containing the set value, or NULL if it is unset. For uses setting one or more options, a list with the previous values of the options changed (returned invisibly).

References

Jorge Nocedal and Stephen J. Wright (1999) Numerical Optimization. Springer-Verlag, New York.

Examples

  spaMM.options()
  spaMM.getOption("example_maxtime")
  ## Not run: 
  spaMM.options(maxLambda=1e06)
  
## End(Not run)

spaMM documentation built on June 22, 2024, 9:48 a.m.