| 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 | ||||||||||||||||||||
random |
A formula object specifying the random effects in the model. This
argument has the same general characteristics as | ||||||||||||||||||||
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 | ||||||||||||||||||||
residual |
A formula object specifying the residual model; any term specified
on the left of the For single-section univariate models, the residual variance model
determines the computational mode: If the residual variance model
specifies a correlation structure (includes | ||||||||||||||||||||
G.param |
Either:
On termination, | ||||||||||||||||||||
R.param |
Either:
On termination, | ||||||||||||||||||||
na.action |
A call to
The default action is | ||||||||||||||||||||
subset |
A logical vector identifying which subset of the rows of | ||||||||||||||||||||
weights |
A character string or name identifying the column of | ||||||||||||||||||||
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
| ||||||||||||||||||||
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 | ||||||||||||||||||||
vcc |
Equality constraints between variance parameters; a two-column
numeric matrix with a 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
is equivalent to the
| ||||||||||||||||||||
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
The default for | ||||||||||||||||||||
asmv |
A character string or name specifying the column in the data that
identifies the traits in a multivariate analysis. If not
| ||||||||||||||||||||
mbf |
A named list specifying sets of covariates to be included with one
or more | ||||||||||||||||||||
group |
A named list where each component is a numeric vector specifying
contiguous fields in | ||||||||||||||||||||
equate.levels |
A character vector of factor names whose levels are to be
equated. For example, if factor | ||||||||||||||||||||
start.values |
If 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 | ||||||||||||||||||||
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 | ||||||||||||||||||||
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 | ||||||||||||||||||||
wald |
A named list with three components:
| ||||||||||||||||||||
prune |
A named list with each component generated from a call to
where
creates a new factor | ||||||||||||||||||||
combine |
A named list with each component generated from a call to
where
creates a new factor | ||||||||||||||||||||
uid |
A named list with each component generated from a call to
where
creates a new factor | ||||||||||||||||||||
mef |
A named list linking a relationship matrix (or its inverse) as
specified in the
links the relationship matrix The | ||||||||||||||||||||
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 | ||||||||||||||||||||
model.frame |
If In large analyses, the model frame is likely to be a large
object. If | ||||||||||||||||||||
data |
A data frame in which to interpret the variables named in
| ||||||||||||||||||||
... |
Additional arguments to |
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)