R: Mixed effects linear models

asreml {asreml} | R Documentation

## Mixed effects linear models

### Description

The library `asreml()` estimates variance components under a general linear mixed model by residual maximum likelihood (REML).

### Usage

    asreml(
      fixed = ~1,
      random = ~NULL,
      sparse = ~NULL,
      residual = ~NULL,
      G.param = list(),
      R.param = list(),
      na.action = na.method(),
      subset,
      weights,
      predict = predict.asreml(),
      vcm = vcm.lm(),
      vcc = matrix(0),
      family = asr_gaussian(),
      asmv = NULL,
      mbf = list(),
      group = list(),
      equate.levels = character(0),
      start.values = FALSE,
      knot.points = list(),
      pwr.points = list(),
      wald = list(),
      prune = list(),
      combine = list(),
      uid = list(),
      mef = list(),
      last = list(),
      model.frame = TRUE,
      data = sys.parent(),
      ...
    )

### Arguments

`fixed` | A formula object specifying the fixed terms in 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 all formulae should appear 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 (y) evaluates to a matrix then a factor `trait` with levels `dimnames(y)[[2]]` is added to the model frame, and must be explicitly included in the model formulae (default = `NULL`).
`random` | A formula object specifying the random effects in the model. This argument has the same general characteristics as `fixed`, but there can be no left side to the `~` operator. Variance structures imposed on random terms are specified using special model functions (default = `~NULL`).
`sparse` | A formula object, specifying the fixed effects for which the full variance-covariance matrix is not required. This argument has the same general characteristics as `fixed`, but there can be no left side to the `~` expression. Wald statistics are not available for sparse fixed terms in order to reduce the computing load (default = `~NULL`).
`residual` | A formula object specifying the residual model; any term specified on the left of the `~` expression is ignored. The default is `~ units`, where the reserved word `units` is defined as `seq(1,nrow(data))` and is automatically included in the model frame. Variance models for the residual component of the model can be specified using special model functions (default = `~NULL`). For single-section univariate models, the residual variance model determines the computational mode: If the residual variance model specifies a correlation structure (includes `id()`), then the model is fitted on the gamma scale, otherwise the model is fitted on the sigma scale. The default is `id(units)` if not explicitly specified.
`G.param` | Either: A list object derived from the `random` formula, holding initial parameter estimates and boundary constraints for each term, or A character string naming a comma-delimited file with a header line and three columns for the variance component name, initial value and constraint code, respectively. This file can be created using the `start.values = TRUE` argument; the internal list object is then generated from the contents of this file. On termination, `G.param` is updated with the final `random` component estimates.
`R.param` | Either: A list object derived from the `random` formula, holding initial parameter estimates and boundary constraints, or A character string naming a comma-delimited file with a header line and three columns for the variance component name, initial value and constraint code, respectively. This file can be created using the `start.values = TRUE` argument; the internal list object is then generated from the contents of this file. On termination, `R.param` is updated with the final `residual` component estimates.
`na.action` | A call to `na.method()` specifying the action to be taken when missing values are encountered in the response (`y`) or explanatory variables (`x` for factors and/or variates). The function definition for `na.method` is: `function(y = c("include", "omit", "fail"),` `x = c("fail", "include", "omit"))` The default action is `"include"` (and estimate) missing values in the response, and raise an error (`"fail"` if there are missing values in any of the explanatory variables.
`subset` | A logical vector identifying which subset of the rows of `data` should be used in the fit. All observations are included by default.
`weights` | A character string or name identifying the column of `data` to use as weights in the fit.
`predict` | A list object specifying the classifying factors and related options when forming predictions from the model. This list would normally be the value returned by a call to the method `predict` for `asreml` objects.
`vcm` | A matrix defining relationships among variance parameters. The matrix has a row for each original variance parameter and a column for each new parameter. The default is the identity matrix, that is, no action. See function `vcm.lm` for further information and an example.
`vcc` | Equality constraints between variance parameters; a two-column numeric matrix with a `dimnames` attribute. The first column defines the grouping structure of equated components, that is, components within an equality group are given the same numeric index, and the second column contains the scaling coefficients. The `dimnames()[[1]]` attribute must match the component names in the `asreml` parameter vector; see `start.values`. The parameters are scaled relative to the first parameter in its group, so the scaling of the first parameter in each group is one. For example, the following `vcc` matrix:
1 | 1
2 | 1
2 | 2
3 | 1
is equivalent to the `vcm` matrix:
1 | 0 | 0
0 | 1 | 0
0 | 2 | 0
0 | 0 | 1
`family` | A list of functions and expressions for defining the link and variance functions. Supported families are: gaussian, inverse Gaussian, binomial, negative binomial, poisson and Gamma. Family objects are generated from the `asreml` family distributions which prefix the usual function names with `"asr_"`; for example `asr_gaussian()`, `asr_binomial()`, etc. In addition to the link argument, these functions take an additional `dispersion` argument and a `total` argument where relevant; for example: `asr_binomial(dispersion = 1.0, total = counts)`. The default for `asr_gaussian()` is `dispersion = NA`, which implies that `asreml` will estimate the dispersion parameter, otherwise the scale is fixed at the nominated value.
`asmv` | A character string or name specifying the column in the data that identifies the traits in a multivariate analysis. If not `NULL`, `asmv` implies that the data for a multivariate analysis is set up as though it were for a univariate analysis with the response in a single variate (default = `NULL`).
`mbf` | A named list specifying sets of covariates to be included with one or more `mbf()` model functions. Each component of the list must in turn contain components named `key` and `cov`, where `cov` is a character string naming the data frame holding the covariates, and `key` is a character vector of length two naming the columns in `data` and `cov`, respectively, used to match corresponding records in the two data frames. The default is an empty list.
`group` | A named list where each component is a numeric vector specifying contiguous fields in `data` that are to be considered as a single term. The component names can then appear in the `asreml` model formulae using the `grp()` special function. The default is an empty list.
`equate.levels` | A character vector of factor names whose levels are to be equated. For example, if factor `A` has levels a, b, c, d and factor `B` has levels a, b, c, e, the effect of `equate.levels(A, B)` is that both `A` and `B` have five levels, with `as.numeric(A)` = 1, 2, 3, 4 and `as.numeric(B)` = 1, 2, 3, 5. This may be necessary if using the `and()` model function to overlay columns of the model's design matrix in forming a compound term. The default is a zero-length character vector.
`start.values` | If `TRUE`, `asreml` exits prior to the fitting process and returns a list of length three: the `G.param` and `R.param` lists, and a data frame (containing variance parameter names, initial values and boundary constraints). Initial values or constraints can then be set in the list or data frame objects (default = `FALSE`). If this is a character string, then a file of that name is created and the data frame object containing initial parameter values is written out in comma-separated form. This file can be edited externally and subsequently specified in the `G.param` or `R.param` arguments.
`knot.points` | A named list where each component is a vector of user-supplied knot points for a particular spline term; the component name is the object of the `spl()` model function.
`pwr.points` | A named list with each component containing a vector of distances to be used in a one-dimensional power model. The component names must correspond to the `object` arguments of the power function model terms.
`wald` | A named list with three components: `denDF`, `ssType` and `Ftest`. `denDF`: A character string from the options: `"none"`, `"numeric"`, `"algebraic"`, and `"default"` specifying the calculation of approximate denominator degrees of freedom. The option `"none"` is to suppress the computations. Algebraic computations are not feasible in large analyses; use `"default"` to automatically choose numeric or algebraic computations depending on problem size. The denominator degrees of freedom are calculated according to Kenward and Roger, 1997 for terms in the `fixed` model formula (default = `"none"`). `ssType`: It can be `"incremental"` for incremental sum of squares or `"conditional"` for F-tests that respect both structural and intrinsic marginality (default = `"incremental"`. `Ftest`: A one-sided formula of the form `~ test_term | background_terms` specifying a conditional Wald test of the contribution of `test_term` conditional on those fixed terms listed in `background_terms`, and the those in the `random` and `sparse` model formulae.
`prune` | A named list with each component generated from a call to `Subset()`. The argument `prune`, in conjunction with `Subset` and the model function `sbs()`, forms a new factor from an existing one by selecting a subset of its levels. The function `Subset` is defined as: `function(f, x)` where `f` is the name of an existing factor and `x` is a character or numeric vector of levels to select. The name of the list component is the new factor that may appear in the model formulae as the argument to the `sbs()` model function. For example, `prune = list(A = Subset(Site, c(2, 3)))` creates a new factor `A` by selecting the second and third levels of `Site`, and would be included in the model as: `sbs(A)`, for example by using `idv(sbs(A))` as part of a random term. While the actions of `prune` can be duplicated outside `asreml`, `sbs()` is necessary if the `asreml` method `predict()` is to be used.
`combine` | A named list with each component generated from a call to `Levels()`. The argument `combine`, in conjunction with `Levels` and the model function `gpf()`, forms a new factor from an existing one by merging a subset of its levels. The function `Levels` is defined as: `function(f, x)` where `f` is the name of an existing factor and `x` is a vector of length `length(levels(f))` defining the levels of `f` to merge. The name of the list component is the new factor that may appear in the model formulae as the argument to the `gpf()` model function. For example, if `Site` has levels `"1"`, `"2"` and `"3"`, `combine = list(A = Levels(Site, c("1", "2", "1")))` creates a new factor `A` with levels `"1"` and `"2"` by merging levels `"1"` and `"3"` of `Site`, and would be included in the model as `gpf(A)`. While the actions of `combine` can be duplicated outside `asreml`, `gpf()` is necessary if the `asreml` method `predict()` is to be used.
`uid` | A named list with each component generated from a call to `Units()`. The argument `uid`, in conjunction with `Units` and the model function `uni()`, forms a new factor by selecting a subset of records from an existing one. The function `Units` is defined as: `function(f, n = 0)` where `f` is the name of an existing factor and `n` is a character or numeric scalar that determines which records are selected. The default, `n = 0`, forms a factor with a level for each record where `f` is non-zero (strictly, `f` != 0). Otherwise, a factor with a level for each record in `data` where `f` has the value `n` is formed. For example, `uid = list(A = Units(group, 1))` creates a new factor `A` with levels from `row.names(data)` where `group = 1`, and would be included in the model as: `uni(A)`. While the actions of `uid` can be duplicated outside `asreml`, `uni()` is necessary if the `asreml` method `predict()` is to be used.
`mef` | A named list linking a relationship matrix (or its inverse) as specified in the `vm()` special function with the original matrix of subject x regressor (typically molecular marker) scores. If this is not an empty list `mef` flags the computation of the regressor (marker) effects from the subject effects. For example, `mef = list(MM = snp.mat)` links the relationship matrix `MM` to the original marker scores found in the file `snp.mat`. The `mef` list would typically be set from a call to the `asreml` `meff()` method.
`last` | A named list restricting the order equations are solved in the sparse partition for the nominated model terms. Each component of the list is named by a model term and contains a scalar `n` specifying that the first `n` levels of the term will be solved after all others in the sparse set. It is intended for use when there are multiple fixed terms in the sparse equations so that `asreml` will be consistent in which effects are identified as singular. A maximum of three factor/level pairs can be specified.
`model.frame` | If `TRUE`, the model frame (a `data.table` object with additional attributes derived from the model specification) is included in the returned object (default = `TRUE`). The model frame is required by the `asreml` `summary`, `plot`, `resid` and `fitted` methods. In large analyses, the model frame is likely to be a large object. If `model.frame` is a character string, the model frame is saved in a file as an `RDS` object by a call to `saveRDS()`, and named by the supplied string with the extension `.RDS`. If the model frame is not included in the returned `asreml` object, this `RDS` file is searched for by the methods noted previously.
`data` | A data frame in which to interpret the variables named in `fixed`, `random`, `sparse` and `residual`. If the `data` argument is missing, the default is `sys.parent()`. The data frame is converted internally to a `data.table` object and returned as such by `model.frame`.
`...` | Additional arguments to `asreml()` directed at `asreml.options()`, such as: `maxit`, `workspace`, `pworkspace`, `fixgammas`, `trace`, `aom`.

### Details

Models for `asreml` are specified symbolically in the formula objects: `fixed, random, sparse` and `residual`. A typical model has the form: `response ~ terms`, `fixed` only, or `~ terms` for `random`, `sparse` and `residual`, where `response` is the (usually numeric) response vector and `terms` is a linear predictor for `response`.

The formulae objects are parsed in the context of the data frame, all internal data structures are constructed in R or compiled code, and the model is fitted by calls to the underlying `Fortran` `REML` routines (Gilmour et al., 1995). Variance models for random model terms are specified using special functions in the `random` and `residual` formulae. If not specified, the variance models default to (scaled) identity variance structures. A table of special model functions is included below; see the reference guide or appropriate vignette for further details and examples of their use. Some of these model functions require the formula arguments to be partially evaluated before the final model frame is computed; it is recommended that all names used in the formulae be resolvable in a data frame named by the `data` argument.

The terms in the `fixed` formula are re-ordered by default so that main effects precede interactions in increasing order. The option `keep.order` (see `asreml.options`) can be used to modify this behaviour.

A formula has an implied intercept term. To remove the intercept use: `y ~ -1 + ...`. This is only effective in the `fixed` formula; in all other formula arguments any reference to the intercept is ignored. Note that currently there must be at least one fixed effect in the model.

In addition to the formal arguments, various options can be set with `asreml.options`; these are stored in an environment for the duration of the `R` session.

The library `asreml` uses either a `"gamma"` (ratio) or `"sigma"` (component) scale parameterization for estimation depending on the residual model specification. The current default for single-section analyses is the gamma parameterization if the error model specifies a correlation structure. In this case, all scale parameters are estimated as a ratio with respect to the residual variance, with correlation parameters unchanged. If the residual model specifies a variance structure then variance parameters are estimated on the sigma scale. For models with more than one residual section, `asreml` *always* estimates variance parameters on the sigma scale.

### Value

An object of class `asreml` containing the results of the fitted linear model. Instances of generic methods such as `plot()`, `predict()` and `summary()` return various derived results of the fit. The methods `resid()`, `coef()` and `fitted()` extract some of its components. See `asreml.object` for details of the components of the returned list.

### Special `asreml` model functions

Special model functions are used in `asreml()` formulae objects to create new or modify existing model terms, or more often to specify the variance model associated with one or more terms. These functions can be broadly categorized as: constructor-type functions, or identity, time-series, general-structure, metric-1D, metric-2D, and known relationship, general variance structures that span more than one term (str), and finally user-defined variance structures.

The special model functions that are available in `asreml()` model formulae are briefly described below; see the reference manual guide, relevant vignette or the main pages for selected functions and for more details or illustrations.

The arguments (symbols) used in the following descriptions are defined as:

`obj` | A factor in `data`.
`n` | Number of elements: `length(levels(obj))`.
`p` | Number of parameters estimated by the base function.
`v` | Number of parameters estimated by the homogeneous function form.
`h` | Number of parameters estimated by the heterogeneous function form.

Constructor model syntax type functions

Call | Description
`con(obj)` | Apply sum-to-zero constraints to factor `obj`.
`C(obj, contr)` | Define contrasts among the levels of `obj` from the coefficients in vector `contr`.
`lin(obj)` | Fit factor `obj` as a variate.
`pow(obj, p, offset)` | Create the term `(offset + obj)``^p`.
`pol(x, t)` | Orthogonal polynomials to degree `t`; `-t` omits the intercept polynomial.
`leg(x, t)` | Legendre polynomials to degree `t`; `-t` omits the intercept polynomial.
`spl(x, k)` | The random component of a cubic spline; optionally `k` knot points.
`dev(x)` | Fit variate `x` as a factor; typically used for spline deviations.
`ma(obj)` | Form a moving average (order 1) design matrix from factor `obj`.
`at(obj, l)` | Form conditioning covariables for the levels in factor `obj` given in `l`.
`dsum(~term | obj)` | Form direct sum operation of `term` for the levels of `obj`. Used in `residual` to define multiple sections.
`and(obj, t)` | Add `t` times the design matrix for `obj` to the previous columns.
`grp(obj)` | Include the term defined by `obj` in the `group` argument in the model.
`mbf(obj)` | Include the covariates defined by `obj` in the `obj` argument as a factor.
`sbs(obj)` | Include the term defined in the `prune` argument in the model.
`gpf(obj)` | Include the term defined in the `combine` argument in the model.
`uni(obj)` | Include the term defined in the `uid` argument in the model.

Identity variance structure models (default)

Call | Description | p | v | h
`id(obj)` | identity | 0 | 1 | n

Time series type variance structure models

Call | Description | p | v | h
`ar1(obj)` | Autoregressive order 1 | 1 | 2 | 1+n
`ar2(obj)` | Autoregressive order 2 | 2 | 3 | 2+n
`ar3(obj)` | Autoregressive order 3 | 3 | 4 | 3+n
`sar(obj)` | Symmetric autoregressive order 1 | 1 | 2 | 1+n
`sar2(obj)` | Symmetric autoregressive order 2 | 2 | 3 | 2+n
`ma1(obj)` | Moving average order 1 | 1 | 2 | 1+n
`ma2(obj)` | Moving average order 2 | 2 | 3 | 2+n
`arma(obj)` | Autoregressive-moving average | 2 | 3 | 2+n

General variance structure models

Call | Description | p | v | h
`cor(obj)` | Simple correlation | 1 | 2 | 1+n
`corb(obj, b)` | Banded correlation; b bands | b | b+1 | b+n
`corg(obj)` | General correlation | n(n-1)/2 | 1+n(n-1)/2 | n(n+1)/2
`diag(obj)` | Diagonal variance | n |  |
`us(obj)` | Unstructured variance | n(n+1)/2 |  |
`chol(obj, k)` | Cholesky order k | (k+1)(n-k/2) |  |
`cholc(obj, k)` | Cholesky C | (k+1)(n-k/2) |  |
`ante(obj, k)` | Antedependence order k | (k+1)(n-k/2) |  |
`sfa(obj, k)` | Factor analytic; k factors | kn+n |  |
`facv(obj, k)` | Factor analytic, covariance scale | kn+n |  |
`fa(obj, k)` | Sparse factor analytic | kn+n |  |
`rr(obj, k)` | Reduced rank variant of fa | kn+n |  |

Metric-based variance structure models in 1D or 2D

Call | Description | p | v | h
`exp(x, dist)` | Exponential (power) 1D | 1 | 2 | 1+n
`iexp(x, y)` | Isotropic exponential (power) 2D | 1 | 2 | 1+n
`aexp(x, y)` | Anisotropic exponential (power) 2D | 2 | 3 | 2+n
`gau(x, dist)` | Gaussian power 1D | 1 | 2 | 1+n
`igau(x, y)` | Isotropic Gaussian 2D | 1 | 2 | 1+n
`agau(x, y)` | Anisotropic Gaussian 2D | 2 | 3 | 2+n
`ieuc(x, y)` | Isotropic Euclidean 2D | 1 | 2 | 1+n
`lvr(x, dist)` | Linear variance 1D | 1 | 2 | 1+n
`ilv(x, y)` | Isotropic linear variance 2D | 1 | 2 | 1+n
`sph(x, y)` | Isotropic spherical 2D | 1 | 2 | 1+n
`cir(x, y)` | Isotropic circular 2D | 1 | 2 | 1+n
`mtrn(x, y, ...)` | Matern variance 2D | * | * | *

`^*`See the reference manual for an extended discussion of the Matern variance class.

Known relationship variance structure models

Call | Description
`vm(obj, source, singG)` | Create a term based on `obj` with known variance structure in `source`.
`ide(obj)` | Identity term based on `obj` with levels as for `vm(obj)`

General variance structures models

Call | Description
`str(~terms, ~model)` | Apply the direct product variance structure in `~model`
| to the set of terms in `~terms`.

User-defined variance structure models

Call | Description
`own(obj, fun, init, type)` | Call `fun` with the parameter estimates in `init` to compute the variance
matrix and its derivatives. |

### See Also

`asreml.options` `asreml.object` `family_dist`

### Examples

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

    ## End(Not run)

[Package asreml version 4.2.0.480 Index]