asreml | R Documentation

## Fit the linear mixed model

### Description

Asreml estimates variance components under a general linear mixed model by residual maximum likelihood (REML).

### Usage

    asreml(fixed = y ~ 1, random, sparse, rcov, G.param, R.param,
           predict = predict.asreml(), constraints = asreml.constraints(),
           data = sys.parent(), subset, family = asreml.gaussian(),
           weights = NULL, offset = NULL, na.method.Y = "include",
           na.method.X = "fail", keep.order = FALSE, ran.order = "user",
           fixgammas = FALSE, as.multivariate = NULL, model.frame = FALSE,
           start.values = FALSE, dump.model = FALSE, model = FALSE,
           control = asreml.control(...), ...)

### Arguments

`fixed` | formula object specifying the fixed effects part of the model, with the response on the left of a ~ operator, and the terms, separated by + operators, on the right. If `data` is given, all names used in the formula should be defined as variables or columns in the data frame. A model with the intercept as the only fixed effect can be specified as ~1. There must be at least one fixed effect specified. If the response evaluates to a matrix (y) then a factor `trait` with levels `dimnames(y)[[2]]` is added to the model frame.
`random` | a formula object, specifying the random effects part of the model, with the terms, separated by + operators, on the right of a ~ operator. This argument has the same general characteristics as `fixed`, but there will be no left side to the ~ operator. Variance structures imposed on random terms are specified using special functions.
`sparse` | a formula object, specifying the fixed effects to be absorbed, with the terms, separated by + operators, on the right of a ~ operator. This argument has the same general characteristics as fixed, but there will be no left side to the ~ expression.
`rcov` | a formula object, specifying the R model, with the terms, separated by + operators, on the right of a ~ operator. This argument has the same general characteristics as fixed, but there will be no left side to the ~ expression. The default is the keyword `units` which is defined as `seq(1,nrow(data))` and automatically included in the model frame. Variance models for the residual component of the model can be specified using special functions.
`G.param` | a list object, generated by a call to `asreml.gdflt` using the `random` formula, holding initial parameter estimates and constraints relating to G. Can also be a character string, in which case it is treated as the name of a comma delimited file with a header line and a column for each variance component's name, initial value and constraint code. The internal list object is generated from the contents of this file. See `start.values`
`R.param` | a list object, generated by a call to to `asreml.rdflt` using the `rcov` formula, holding initial parameter estimates and constraints, including σ^2, relating to R. Can also be a character string, in which case it is treated as the name of a comma delimited file with a header line and a column for each of the varianve component name, its initial value and constraint code. The required list object is generated from the contents of this file. see `start.values`
`predict` | a list object specifying the classifying factors and related options to obtain tables of predicted values from the model. This list would normally be the value returned by a call to `predict.asreml`.
`constraints` | A matrix used to constraints among the variance components with as many rows as there are (original) variance parameters and as many columns as there are constrained parameters. See `asreml.constraints` for an example.
`data` | a data frame in which to interpret the variables named in `fixed, random, sparse`, and `rcov`. If the `data` argument to `asreml` is missing, the function sets `data` to `sys.parent()` and the context for interpreting names will be the next function up the calling stack.
`subset` | a logical vector identifying which subset of the rows of the data should be used in the fit. All observations are included by default.
`family` | family object - a list of functions and expressions for defining the link and variance functions. The currently supported families are gaussian, binomial, negative binomial, poisson and Gamma. Family objects are supported via the `asreml` family functions `asreml.gaussian()`, `asreml.binomial()` etc. In addition to the link argument, these functions take an additional dispersion argument as in `asreml.gaussian(link="identity",dispersion=NA)`. The default for `asreml.gaussian()` is NA which implies that `asreml` will estimate the scale parameter, otherwise the parameter is fixed at the nominated value.
`weights` | character string or name identifying the column of `data` to use as weights in the fit.
`offset` | character string or name identifying the column of `data` to include as an offset in the model. This is ignored if family=gaussian(link="identity").
`na.method.Y` | a character string (`"include", "omit"` or `"fail"`) specifying how missing data in the response is to be handled. This is applied to the model frame after any `subset` argument has been used. The default (`"include"`) is to estimate missing values; this is necessary in spatial models to preserve the spatial structure. `"omit"` deletes observations that contain missing values in the response.
`na.method.X` | a character string (`"include", "omit"` or `"fail"`) specifying how missing data in covariates is to be handled. This is applied to the model frame after any `subset` argument has been used but before any `at()` functions are invoked. The default `"fail"` causes an error if there are missing values in any covariate. `"omit"` deletes observations that contain missing values in any covariate.
`keep.order` | should the terms in the fixed formula be kept in the order they are specified. By default (FALSE), terms are re-ordered so that main effects appear before interactions.
`ran.order` | a character string specifying the order of terms in the `random` formula, may be one of: "user:" terms are kept in the order in which they appear, "R": the order determined by `terms(random,keep.order=FALSE)`, "noef": terms ordered by increasing numbers of effects. Default is "user".
`fixgammas` | if TRUE, overrides the settings in `R.param` and `G.param` and constrains all variance parameters to be fixed.
`as.multivariate` | A character string or name specifying the column in the data that identifies the traits in a multivariate analysis. If not NULL, implies that the data for a multivariate analysis is set up as though it were for a univariate analysis.
`model.frame` | if TRUE, the model frame used in the fit is returned in the `asreml` object.
`start.values` | if TRUE, `asreml` exits prior to the fitting process and returns a list of length 3 containing the `G.param` and `R.param` lists and a data frame containing component names, initial values and boundary constraints. Initial values or constraints in the list or data frame objects can then be set. If a character string, then a file of that name is created and the data frame object written out in comma separated form. This file can be edited externally by a text editor or spreadsheet application and subsequently used with the `G.param` or `R.param` arguments.
`dump.model` | if TRUE, `asreml` exits prior to the fitting process and returns a list with all components necessary for the fit. This argument would be used in conjunction with model in a simulation setting, for example, to avoid the overheads of (repeatedly) interpreting the formulae objects.
`model` | if this argument is not of mode logical, the object is assumed to have been created by the `dump.model` argument and `asreml` will extract the necessary components and perform the fit. The default is FALSE which implies normal execution; TRUE generates an error.
`control` | a list of iteration, algorithmic and parameter settings, including those related to spline knot points and known variance structures. See `asreml.control()` for their names and default values. These can also be set as argument/value pairs in the `asreml` call.

### Details

Models for `asreml` are specified symbolically in formula objects `fixed, random, sparse` and `rcov`. These objects are parsed in the context of the data frame, all internal objects required by the `REML` routines are constructed and a call to the underlying `C` and `Fortran` routines is generated. Variance models for terms in `random` are specified using “special” formula functions, which if not specified, defaults to (scaled) identity. See the reference guide for details on special model functions and their use. Some of these model functions require the formula arguments be partially evaluated before the final model frame is computed; for this reason, it is recommended that all names mentioned in the formulae be defined as variables in a data frame named by the `data` argument.

If the response is a matrix, a multivariate linear model is fitted to the columns of the matrix.

The terms in the `fixed` formula will be re-ordered so that main effects come first, followed by the interactions, all second-order, all third-order and so on; `keep.order` can be used to modify this behaviour.

A formula has an implied intercept term. To remove this use 'y ~ -1 + ...' . This is only effective in the `fixed` formula; in all other formula arguments any reference to the intercept is ignored.

The `subset` argument, like the terms in formula, is evaluated in the context of the data frame. The specific action of the `subset` argument is as follows: the model frame, including weights, is computed on the rows of `data` after the appropriate subset is extracted.

### Value

an object of class `asreml` representing the fit. Generic functions such as `plot(), predict()` and `summary()` have methods to return various results of the fit. The functions `resid(), coef()` and `fitted()` can be used to extract some of its components. See `asreml.object` for the components of the fit.

### Author(s)

David Butler

### References

Gilmour, A. R., Thompson, R. and Cullis, B. R. (1995). AI, an efficient algorithm for REML estimation in linear mixed models, Biometrics, 51, 1440-1450.

Smith, A. B., Cullis, B. R., Gilmour, A.R. and Thompson, R. (1998). Multiplicative models for interaction in spatial mixed model analyses of Multi-Environment trial data, Proceedings of the International Biometrics Conference, Capetown.

Verbyla, A. P., Cullis, B. R., Kenward, M. G. and Welham, S. J. (1999). The analysis of designed experiments and longitudinal data using smoothing splines, Journal of the Royal Statistical Society, Series C, 48, 269-311.

### See Also

`asreml.object` `summary.asreml` `wald.asreml` `plot.asreml` `predict.asreml` `variogram.asreml` `tr.asreml` `svc.asreml` `asreml.man`

### Examples

    dat <- data.frame(y=rnorm(20),x=seq(1,20))
    ex.asr <- asreml(y ~ x, data=dat)

    ## The oats data
    data(oats)
    oats.asr <- asreml(yield ~ Variety*Nitrogen, random = ~ Blocks/Wplots, data=oats)