predict.asreml | R Documentation

## Predict linear functions of fixed and random effects from an asreml object

### Description

A method for the generic function `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

    predict.asreml(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 = logical(0), sed = logical(0),
                   parallel = logical(0),  aliased = logical(0), ...)

### 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 `splinepoints` argument (see `asreml.control`) and included in the predict set with the `predictpoints` 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 the prediction process.
`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 form the prediction model, that is, the default rules are not invoked.
`associate` | a formula object 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, the full variance matrix of the predicted values is returned in a component `vcov`. Default is FALSE.
`sed` | if TRUE, the full standard error of difference matrix of the predicted values is returned in a component `sed`. Default is FALSE.
`parallel` | if TRUE, 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. Default is FALSE.
`aliased` | if TRUE, the predicted values are returned for non-estimable functions. Default is FALSE.
`...` | other arguments to `asreml` can be given.

### Details

The prediction process forms a linear function of the vector of fixed and random effects in the linear model to obtain an estimated or 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 process is basically: `predict.asreml` passes a list of the user specifications to the predict argument of `asreml`; structures required to construct the prediction design matrix are passed to the REML routines; predicted values and standard errors are returned in a component predictions of the asreml object. `predict.asreml` calls `update.asreml` to run the model from its final solution and set the `predict` argument of `asreml`.

### Value

A list named `predictions` with the following components is included in the asreml object:

`pvals` | a dataframe of predicted values.
`sed` | optional matrix of standard errors of difference.
`vcov` | optional matrix of variances of predicted values.
`avsed` | summary standard error of difference.

### Author(s)

David Butler

### References

Welham, S. J., Cullis, B. R., Gogel, B. J., Gilmour, A. R. and Thompson, R. (2004) Prediction in linear mixed models, Australian and New Zealand Journal of Statistics, 46, 325-347.

### See Also

`asreml`

### Examples

    data(oats, package="asreml3")
    oats.asr <- asreml(yield ~ Variety*Nitrogen,
                       random = ~ Blocks/Wplots, data=oats)
    oats.pv <- predict(oats.asr, classify="Variety")