R: Predict linear functions of model effects

predict.asreml {asreml} | R Documentation

## Predict linear functions of model effects

### Description

An instance of the generic method `predict` for objects of class `asreml`. It 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 = character(0),
      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,
      simple = FALSE,
      ...
    )

### 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`, the full variance-covariance matrix of the predicted values is returned in a component `vcov` (default = `FALSE`).
`sed` | If `TRUE`, the full standard error of difference (SED) matrix of the predicted values is returned in a component `sed` (default = `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 = `FALSE`).
`aliased` | If `TRUE`, the predicted values are returned for non-estimable functions. However, this is rarely a satisfactory solution (default = `FALSE`).
`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 two, 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`, an unevaluated call to `update.asreml` is returned, otherwise the call is evaluated. Setting `FALSE` returns a list that may be used with the `predict` argument in a call to `asreml` (default = `TRUE`).
`simple` | If `FALSE`, is required in conjunction with the only parameter when a design function of a covariate, e.g. mbf(X), and the prediction applies to the actual coefficients, and not the function of the coefficientd.
`...` | 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 (SED).

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

- `avsed`: Average of the standard error of differences (SED).

[Package asreml version 4.2.0.480 Index]