R: Set less frequently used 'asreml()' options

asreml.options {asreml} | R Documentation

## Set less frequently used `asreml()` options

### Description

In `asreml.options()` the less frequently used settings are set per session outside `asreml()` in an options environment. With no arguments, `asreml.options()` returns a list of settings that can be altered.

### Usage

    asreml.options(...)

### Arguments

`about` | If `TRUE`, the date packaged is printed for identification (default = `FALSE`).
`ai.loadings` | Controls modification to Average Information (AI) updates of loadings in extended factor-analytic (`fa(, k)`) models. After `asreml` calculates updates for variance parameters, it checks whether the updates are reasonable and sometimes reduces them over and above any `step.size` shrinkage. The extra shrinkage has two levels: loadings that change sign are restricted to doubling in magnitude; and if the average change in magnitude of loadings is greater than 10-fold, they are all shrunk. Unless the user specifies constraints, `asreml` sets them and rotates the loadings each iteration. When `ai.loadings =` `i` is specified (`i=-1` is no action), it also prevents AI updates of some loadings during the first `i` iterations. For `f > 1` factors, only the last factor is estimated (conditional on the earlier ones) in the first `f - 1` iterations. Then pairs, including the last, are estimated until iteration `i` (default = `0`).
`ai.penalty` | This refers to the algorithm for updating loadings in factor analytic (`fa`) models. The present strategy modifies the average information matrix by increasing the diagonal elements pertaining to loadings by a percentage, `p`. The default is to start with `p = 10`% and reduce it by 1 or 2% each iteration down to 1%. If the starting values are poor, 10% may not be a sufficient initial retardation. If it appears the updates are unreasonable, the value of `p` is increased by 10%. After the penalty has reduced to 1%, it is further reduced to 0.2%. `ai.penalty` can be set to 0 if desired (default = `10`, corresponding to 10%).
`ai.sing` | If `TRUE`, forces continuation if a singularity is detected in the average information matrix. Variance components are reported to help identify singularity but these are often incorrect (default = `FALSE`).
`aodev` | If `TRUE`, return an analysis of deviance (default = `FALSE`).
`aom` | If `TRUE`, return standardized conditional residuals and standardized conditional BLUPs in the `aom` component of the `asreml` object (default = `FALSE`).
`Cfixed` | If `TRUE`, return the computed part of the `C^{-1}` matrix in component `Cfixed`. The inverse coefficient matrix is fully formed for terms in the dense set (default = `FALSE`).
`colourise` | If `TRUE`, the header text produced by methods such as `wald` and `predict` will be displayed in a different colour if supported by the output terminal device (default = `TRUE`).
`Csparse` | If a formula is specified, return the computed part of `C^{-1}` for those terms given in the formula. The library `asreml` does not compute the whole of `C^{-1}`, only that which is sufficient to calculate the REML solution (default = `Csparse = ~NULL`).
`Cinv` | If TRUE, return the computed part of `C^{-1}` for all terms in the model.
`debug` | Return internal data structures for helping debugging (default = `FALSE`).
`dense` | Include the equation(s) for the term(s) in the formula in the dense set. This results in faster processing if the term is associated with a known dense inverse relationship matrix (default = `dense = ~NULL`).
`design` | If `TRUE`, return the design matrix for component `design` of the `asreml` object. This option might be used, for example, in generating design matrices that can then be used in post-processing (default = `FALSE`).
`drop.unused.levels` | If `TRUE`, levels of simple factors that do not appear in the data are dropped (default = `TRUE`).
`eqorder` | Set the algorithm used for ordering the mixed-model equations prior to solution. The argument `eqorder = -1` processes the equations in user order; generally this will run much slower, if at all, in real time for large analyses (default = `3`).
`extra` | Forces other `mod(extra, maxit)` extra iterations after apparent convergence (default = `0`).
`fail` | If `"hard"`, fatal errors will terminate execution, otherwise if `"soft"` such conditions will be reported as warnings, allowing testing runs, for example, to continue. In both cases the `converge` component of the `asreml` object will be set to `FALSE` and the results will be erroneous (default = `"hard"`).
`fixgammas` | If `TRUE`, all variance parameters are constrained to be fixed at their starting values (default = `FALSE`).
`font.scale` | Scale axis text and labels (relative to the `asreml` default settings) in the graphs generated by `plot()` (default = `1.0`).
`gammaPar` | If `TRUE`, single-section-models will be fitted using the `gamma` parameterization irrespective of whether the `residual` formula specifies a correlation or variance model. The default behaviour for single-section models is to fit on the `gamma` scale if the `residual` formula specifies a correlation structure, and on the `sigma` scale if the `residual` formula specifies a variance structure (default = `FALSE`).
`glmminloop` | Set the number of inner iterations performed in an iteratively weighted least squares analysis. These estimate the effects in the linear model for the current set of variance parameters; outer iterations are the average information updates to the variance parameters. The default is to perform 4 inner iterations in the first round and 2 in subsequent rounds of the outer iteration. Set to 2 or more to increase the number of inner iterations (default = `1`).
`grid` | A logical vector of length 1 or `length(design.points)` (see predict) controlling the expansion of coordinates for two-dimensional kriging. For a given term, the coordinates for prediction in two dimensions `(x, y)` are given as a list of two vectors or a two-column matrix component of `design.points`. If `TRUE`, the coordinates are expanded to form an `(x, y)` grid of all possible combinations, otherwise the columns of the matrix are taken in parallel (default = `TRUE`).
`keep.order` | If `TRUE`, the order of terms in the `fixed` formula is retained. Set to `TRUE` if the special model function `and()` is present (default = `FALSE`).
`knots` | The number of knot points for spline terms to consider. For a variate `x`, the number of knot points is `min(length(unique(x)), knots)` (default = `50`).
`license_id` | If `0`, a new license_id is created for identification (default = `0`).
`maxit` | Maximum number of iterations to stop fitting (default = `13`).
`nsppoints` | Value that influences the number of points used when predicting splines and polynomials. The design matrix generated by the `pol(x)` and `spl(x)` functions are modified to include extra rows for points used in prediction. The range of `x` is divided by `nsppoints - 1` to give a step size `i`. For each point `p` in `x`, a predict point is inserted at `p+i` if there is no data value in the interval `[p, p+1.1 i]`. The argument `nsppoints` is ignored if the `predict.asreml()` argument `design.points` is set (or the `design.points` component of the `predict` list argument to `asreml()` is not empty). This process also affects the number of levels identified by `dev(x)` (default = `21`).
`oscillate` | If `TRUE`, the test for oscillating log-likelihood is implemented (default = `TRUE`).
`pworkspace` | Sets the workspace needed by the `predict()` method; follows the same convention as `workspace`. Ignored if the `predict` argument to `asreml()` is not set. Note that the total workspace used for prediction is: `workspace + pworkspace` (default = `"128mb"`).
`pxem` | Selection of the (PX)EM update strategy for unstructured (`us`) variance models when average information updates cause them to be non-positive definite (see `uspd`) (default = `1`). Valid options are:
Option | Action
1 | standard EM + 10 local EM steps
2 | standard EM + 10 local PXEM steps
3 | standard EM + 10 local EM steps`^*`
4 | standard EM + 10 local PXEM steps`^*`
5 | standard EM only
6 | single local PXEM
7 | standard EM + 1 local EM step
8 | standard EM + 1 local PXEM step
`^*`Options 3 and 4 cause all `us` structures to be updated by (PX)EM if any particular one requires EM updates.
`random.order` | If option `"noeff"` the terms in the `random` and `sparse` formulae are reordered in increasing number of effects. This is almost always desirable, especially if the stratum variance decomposition is required. Other options are `"user"` to retain the order given in the model specification, or `"R"` for the default R rules (default = `"noeff"`).
`rotate.fa` | If `FALSE`, `asreml()` initially constrains the first `k-1` loadings for higher order (`k > 1`) factors in factor analytic models to zero. If constraints are not set for factor analytic models with more than one factor, `asreml()` will set them internally and rotate the loadings each iteration (`rotate.fa = TRUE`). This option also modifies the action of `update.Gcon` such that rotation, if specified, is applied on an update (default = `FALSE`).
`scale` | Overall scale parameter (default = `1.0`).
`score` | If `TRUE`, the score vector is returned in a component `score` of the `asreml` object (default = `FALSE`).
`spline.scale` | When forming a design matrix for a `spl()` term, a standardized scale is used. Setting `spline.scale = 1` forces `asreml` to use the scale of the variable. The value `-1` is recommended in most cases (default = `-1`).
`spline.step` | A list with components named `spl`, `dev` and `pol` specifying the resolution for spline deviations and polynomial functions, respectively. Points closer together than `1/spline.step` of the range will be treated as a single point (default `spline.step = list(spl = 10000, dev = 10000, pol = 10000)`).
`step.size` | Value for updating shrinkage factor. It reduces the update step sizes of the variance parameters. The step size is incremented each iteration to a maximum of 1.0 (default = `0.316`).
`threads` | The maximum number of threads to be used with OMP parallel processing. `asreml` will use all threads available up to the maximum number specified. The value `-1` will use all available threads (default = `-1`).
`tol` | A vector of length two that modifies the sensitivity of `asreml` to detect singularities in the mixed model equations. This is intended for the rare occasions when singularities are detected after the first iteration (default = `c(0, 0)`). Normally a singularity is declared if the adjusted sum of squares of a covariable is less than `e`, or less than the *uncorrected sum of squares* `\times e`, where `e = 10^{-8}` in the first iteration and `10^{-10}` thereafter. If `tol = c(a, b)`, `e` is scaled by `10^a` for the the first iteration, and `10^b` for subsequent iterations. Once a singularity is detected, the corresponding equation is dropped (forced to be zero) in subsequent iterations. If the problem of later singularities arises because of the low coefficient of variation of a covariable, it may be advisable to centre and rescale the covariable. If the degrees of freedom are correct in the first iteration, the problem lies with the variance parameters and a different variance model (or constraint) is needed.
`trace` | If `TRUE`, convergence monitoring of the current fit is reported in the console (default = `TRUE`).
`update.Gcon` | If `TRUE`, the constraint status of variance parameters in the `G.param` list component on termination is updated; this may influence subsequent updates to the model fit (default = `TRUE`).
`update.Rcon` | If `TRUE`, the constraint status of variance parameters in the `R.param` list component on termination is updated; this may influence subsequent updates to the model fit (default = `TRUE`).
`update.step.size` | Value for updating shrinkage factor to use in a call to `update()`. If ignored it is set to `0.316` or if `step.size` is explicitly specified on the `update()` call; otherwise the shrinkage factor is set to `update.step.size` in the call to `asreml()` constructed by `update()` (default = `0.316`).
`use.blas` | If `"standard"`, then `asreml` will make use of linear algebra routines compiled into the `asreml` package, otherwise the version of BLAS / LAPACK from R will be used (default = `"standard"`).
`uspd` | If `TRUE`, set the boundary constraint for each parameter in unstructured variance models to `"P"`. Under these conditions, `asreml` checks whether the updated matrix is positive definite; if not, the average information update is replaced with an EM update (see `pxem`) (default = `TRUE`).
`workspace` | Sets the workspace for the core `REML` routines in the form of a number optionally followed directly by a valid measurement unit. Valid units are `kb`, `mb` or `gb`; if no units are given then the value is interpreted as double-precision words (groups of 8 bytes) (default = `"128mb"`).
`deepcopy` | Only relevant if the object passed to the `data` argument in asreml is of class `data.table`. If `TRUE`, a copy of `data` is created in memory within the function scope; in this case, the original object passed to `data` is not modified. If `FALSE`, the original object is modified by reference. Setting this option to `FALSE` is useful when the original data object is large, leading to less memory usage (default = `FALSE`).
`wvr` | If `TRUE` residual working variables will be returned in the `asreml.object` (if they exist)

### Details

Arguments are in the form `name = value`, where `name` is the name of the option to set.

[Package asreml version 4.2.0.480 Index]