asreml.options {asreml3} | R Documentation

## Set asreml options.

### Description

Set less frequently used `asreml()` options.

### Usage

    asreml.options(...)

### Arguments

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

### Details

The following settings can be altered:

`about=FALSE`

  If TRUE the date packaged is printed for identification; the default is `FALSE`.

`ai.loadings=0`

  Controls modification to AI updates of loadings in extended factor-analytic (`fa`) 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 (default i=-1 specifies 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.

`ai.penalty=10`

  The algorithm for updating loadings in factor analytic models has been improved. The original update procedure sometimes produced unreasonable updates, or exhibited drift. The present strategy modifys 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 suficient initial retardation. If it appears the updates are unreasonable, the value of p is increased by 10%. The default is p=10%. After the penalty has reduced to 1%, it is further reduced to 0.2%. `ai.penalty` can be set to 0 if desired.

`ai.sing=FALSE`

  Force continuation if a singularity is detected in the average information matrix.

`aodev=FALSE`

  If `TRUE`, return an analyais of deviance.

`aom=FALSE`

  If `TRUE`, return standardized conditional residuals and standardized conditional BLUPs in the `aom` component of the `asreml` object.

`Cfixed=FALSE`

  If `TRUE`, return the computed part of the C^{-1} matrix in component `Cfixed`; the default is `FALSE`. The inverse coefficient matrix is fully formed for terms in the dense set.

`colourise=TRUE`

  If `TRUE` (the default) the header text produced by functions such as `wald` and `predict` will be displayed in a different colour if supported by the output terminal device.

`Csparse=~NULL`

  If a formula is specified, return the computed part of C^{-1} for those terms given in the formula. `asreml` does not compute the whole of C^{-1}, only that which is sufficient to calculate the REML solution.

`debug=FALSE`

  Return internal data structures.

`dense=~NULL`

  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.

`design=FALSE`

  If `TRUE`, return the design matrix in component `design` of the `asreml` object.

`drop.unused.levels=TRUE`

  If `TRUE` (the default), levels of simple factors that do not appear in the data are dropped.

`eqorder=3`

  Set the algorithm used for ordering the mixed-model equations prior to solution. `eqorder``=-1` processes the equations in user order; generally this will run much slower, if at all in real time for large analyses.

`extra = n`

  Forces another `mod(n, maxit)` iterations after apparent convergence; the default is `n=0`.

`fail="hard"`

  If `"hard"` (the default) fatal errors will terminate execution, otherwise if `"soft"` such conditions will be reported as warnings, allowing simulation 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.

`fixgammas=FALSE`

  If `TRUE`, all variance parameters are constrained to be fixed at their starting values.

`font.scale=1.0`

  Scale axis text and labels (relative to the `asreml` default settings) in the graphs generated by `plot.asreml()`.

`gammaPar=FALSE`

  If `TRUE` (the default is `FALSE`), 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.

`glmminloop=1`

  Sets 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 AI 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.

`grid=TRUE`

  A logical vector of length 1 or `length(design.points)` (see predict) controlling the expansion of coordinates for 2 dimensional kriging. For a given term, the coordinates for prediction in 2 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 and are taken in parallel.

`keep.order=FALSE`

  If `TRUE`, the order of terms in the `fixed` formula is retained. Set to `TRUE` if the special model function `and()` is present.

`knots=50`

  The default number of knot points for spline terms. For a variate `x`, the number of knot points is `min(length(unique(x)), knots).`

`maxit=13`

  Maximum number of iterations.

`nsppoints=21`

  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.1i]. `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)`.

`oscillate=TRUE`

  Test for oscillating log-likelihood (default=TRUE).

`pxem=1`

  (PX)EM update strategy for unstructured (US) variance models when Average Information updates cause them to be non-positive definite (see `uspd`). Valid values are:

  `pxem` | 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.

`pworkspace="128mb"`

  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`.

`random.order="noeff"`

  Reorder terms in the `random` and `sparse` formulae in increasing order of 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, or `"R"` for the default R rules.

`rotate.fa=FALSE`

  If `FALSE` (the default), `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.

`scale=1.0`

  Overall scale parameter.

`score=FALSE`

  If `TRUE`, the score vector is returned in a component `score` of the `asreml` object; the default is `FALSE`.

`spline.scale=-1`

  When forming a design matrix for a `spl()` term, a standardised scale is used. Setting `spline.scale = 1` forces `asreml` to use the scale of the variable. The default (-1) is recommended in most cases.

`spline.step=list(spl=10000,dev=10000,pol=10000)`

  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.

`step.size=0.316`

  Update shrinkage factor, reduces the update step sizes of the variance parameters. The step size is incremented each iteration to a maximum of 1.0.

`tol=c(0,0)`

  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.

  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=TRUE`

  Report convergence monitoring in the console.

`update.Gcon=TRUE`

  Update the constraint status of variance parameters in the `G.param` list component on termination; this may influence subsequent updates to the model fit (the default is `TRUE`).

`update.Rcon=TRUE`

  Update the constraint status of variance parameters in the `R.param` list component on termination; this may influence subsequent updates to the model fit (the default is `TRUE`).

`update.step.size=0.316`

  Update shrinkage factor to use in a call to `update()`. Ignored if set to the default (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()`.

`uspd=TRUE`

  If TRUE, (the default) 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`).

`workspace="128mb"`

  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).

[Package asreml3 version 3.0.0.10 Index]