predict.asreml {asreml} | R Documentation

## Predict linear functions of effects.

### Description

An instance of the generic method `predict` for objects of class `asreml`. Forms a linear function of the vector of fixed and random effects in the linear model to obtain an estimated or predicted value.

### Usage

    ## S3 method for class 'asreml'
    predict(
      object = NULL,
      classify = character(0),
      levels = list(),
      present = list(),
      ignore = character(0),
      use = character(0),
      except = character(0),
      only = character(0),
      associate = formula("~NULL"),
      average = list(),
      vcov = FALSE,
      sed = FALSE,
      parallel = FALSE,
      aliased = FALSE,
      design.points = list(),
      evaluate = TRUE,
      ...
    )

### Arguments

`object` | An `asreml` object.
`classify` | A character string giving the variables that define the margins of the multiway table to be predicted. Multiway tables are specified by forming an interaction type term from the classifying variables, that is, separating the variable names with the ":" operator.
`levels` | A list, named by the margins of the classifying table, of vectors specifying the levels at which predictions are required. If omitted, factors are predicted at each level, simple covariates are predicted at their overall mean and covariates used as a basis for splines or orthogonal polynomials are predicted at their design points. Additional prediction points for spline terms should be included in the design matrix with the `asreml` `knot.points` argument and included in the predict set with the `predict` `design.points` argument. The factors `mv` and `units` are always ignored.
`present` | A character vector specifying which variables to include in the `present` averaging set. The `present` set is used when averaging is to be based only on cells with data. The `present` set may include variables in the classify set but not those in the `average set`. If a list, there can be a maximum of two components, each a character vector of variable names, representing non-overlapping `present` categorisations and one optional component named `prwts` containing a vector of weights to be used for averaging the first present table only. The vector(s) of names may include variables in the classify set but not those in the average set.
`ignore` | A character vector specifying which variables to ignore in forming the predictions.
`use` | A character vector specifying which variables to add to the prediction model after the default rules have been invoked.
`except` | A character vector specifying which variables to exclude in the prediction process. That is, the prediction model includes all fitted model terms not in the `except` list.
`only` | A character vector specifying which variables (only) form the prediction model, that is, the default rules are not invoked.
`associate` | A one-sided formula specifying terms in up to two independent nested hierarchies. The factors in each hierarchy are written as a compound term separated by the `":"` operator and in left-to-right outer to inner nesting order. Nested hierarchies are separated by the `"+"` operator; only one `"+"` operator is currently permitted, giving a maximum of two `associate` lists.
`average` | A list, named by the margins of the classifying table, specifying which variables to include in the averaging set. Optionally, each component of the list is a vector specifying the weights to use in the averaging process. If omitted, equal weights are used.
`vcov` | If `TRUE` (default `FALSE`), the full variance-covariance matrix of the predicted values is returned in a component `vcov`.
`sed` | If `TRUE` (default `FALSE`), the full standard error of difference matrix of the predicted values is returned in a component `sed`.
`parallel` | If `TRUE` (default `FALSE`), the levels of the `classify` factors given in the `levels` list are expanded in parallel; in this case levels must be specified for all factors in the classify set, and they must be of equal length.
`aliased` | If `TRUE` (default `FALSE`), the predicted values are returned for non-estimable functions.
`design.points` | A list with named components where each component is a list or matrix (for two dimensions), or vector (single dimension) of user supplied prediction design points for `spl()`, `pol()`, `dev()` or metric type models. If an element of this list is a list of length 2 then the first vector component is taken as the x coordinates and the second as the y coordinates. If a component is a matrix, then it is assumed that the (x, y) coordinates occupy columns 1 and 2, respectively. The names of `design.points` must match exactly those used in the model functions.
`evaluate` | If `FALSE` (the default is `TRUE`), an unevaluated call to `update.asreml` is returned, otherwise the call is evaluated. Setting `evaluate =` `FALSE` returns a list that may be used with the `predict` argument in a call to `asreml`.
`...` | Additional arguments to `asreml`.

### Details

The prediction process forms a linear function of the vector of fixed and random effects in the linear model to obtain a predicted value for a quantity of interest. It is primarily used for predicting tables of adjusted means. If the table is based on a subset of the explanatory variables then the other variables need to be accounted for. It is usual to form a predicted value either at specified values of the remaining variables, or averaging over them in some way.

Prediction equations are formed just prior to the final iteration in `asreml`. The `predict.asreml` method passes the list of user specifications for the prediction design matrix to the `REML` routines through the `predict` argument of `asreml`. Predicted values and standard errors are returned in the `predictions` component of the `asreml` object. In forming the predictions, `predict.asreml` calls `update.asreml` to re-run the model from its previous solution.

### Value

The full `asreml` object is not returned, only the `predictions` element containing the following components:

pvals

  A data frame of predicted values with class `asreml.predict`.

sed

  Optional matrix of class `dspMatrix` of standard errors of difference.

vcov

  Optional variance-covariance matrix of class `dspMatrix` of the predicted values.

avsed

  Summary standard error of difference.

### References

Welham SJ, Cullis BR, Gogel BJ, Gilmour AR, Thompson R (2004). “Prediction in linear mixed models.” Australian and New Zealand Journal of Statistics, 46, 325–347.

[Package asreml version 4.1.0.176 Index]