asreml {asreml} | R Documentation |
asreml estimates variance components under a general linear mixed model by residual maximum likelihood (REML).
asreml(fixed = y ~ 1, random = ~NULL, sparse = ~NULL, residual = ~NULL, G.param = list(), R.param = list(), data = sys.parent(), na.action = na.method(), subset, weights, predict = predict.asreml(), vcm = vcm.lm(), vcc = matrix(NA), 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, ...)
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 | ||||||||||||||||||||||
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 ~ expression is ignored. The default
is ~ 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, | ||||||||||||||||||||||
data |
A data frame in which to interpret the variables named in
| ||||||||||||||||||||||
na.action |
A call to
The default action is to include (and estimate) missing values in the response, and raise an error if there are missing values in the explanatory variables. | ||||||||||||||||||||||
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 | ||||||||||||||||||||||
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. Optionally a list of such structures for a multivariate analysis involving non-normal variates. Currently this is restricted to a bivariate model where the first variate (excluding the multinomial distribution) is non-normal. Supported families are gaussian, inverse Gaussian,
binomial, negative binomial, poisson,
Gamma and multinomial. 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. If factor | ||||||||||||||||||||||
start.values |
If If 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 four components:
The | ||||||||||||||||||||||
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 n specifying that
the first n levels of the term 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 | ||||||||||||||||||||||
model.frame |
If The model frame is required by the In large analyses, the model frame is likely to be a large
object. If | ||||||||||||||||||||||
... |
Additional arguments to |
Models for asreml
are specified symbolically in the formula
objects fixed, random, sparse
and residual
. A typical
model has the form response
\sim terms
,
fixed
only, or \sim terms
for random
,
sparse
and residual
, where response
is the
(usually numeric) response vector and terms
is a linear
predictor for response
. An exception is raised if the
response is a factor and family
is not multinomial.
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 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.
If the response is a matrix, a multivariate linear model is fitted
to the columns unless family
= asr_multinomial()
is
declared.
The terms in the fixed
formula are re-ordered by default so
that main effects preceed 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.
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.
An object of class asreml
containing the results of the
fitted model. Instances of generic methods such as plot()
,
predict()
and summary()
return various derived
results of the fit; resid()
, coef()
and
fitted()
extract some of its components. See
asreml.object
for the components of the returned
list.
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 categorised as
constructor-type functions, or (default)
identity, time-series,
general-structure, 1d
metric, 2d metric, known
relationship, general variance structures that span more than one
term (str), or user-defined structures.
The special model functions that are available in
asreml
model formulae are introduced below; see the user
guide, relevent vignette or the man pages for selected functions
for more details or illustration.
The symbols used in the following tables are defined as:
obj | a factor in data . |
n | 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 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 contr . |
lin(obj) | Fits 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) | Forms a moving average (1) design matrix from factor obj |
at(obj, vec) | Form conditioning covariables for the levels in obj
given in vec . |
dsum(~term | obj, ~model) | Direct sum of term for the
levels of obj with variance structure model . |
Used in residual to define multiple sections. |
|
and(obj, k) | Add k times the design matrix for obj
to the previous columns. |
grp(name) | Include the term defined by name in
the group argument in the model. |
mbf(name) | Include the covariates defined by name in
the mbf argument as a factor. |
sbs(name) | Include the term defined in the prune argument
in the model. |
gpf(name) | Include the term defined in the combine argument
in the model. |
uni(name) | Include the term defined in the uid argument
in the model.
|
Default identity
Call | Description | p | v | h |
id(obj) | identity | 0 | 1 | n |
Time series type 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 | 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 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) | heterogeneous variance | n | ||
us(obj) | unstructured variance | n(n+1)/2 | ||
sfa(obj, k) | factor analytic; k factors | kn+n | ||
fa(obj, k) | sparse factor analytic | kn+n | ||
facv(obj, k) | factor analytic, covariance form | kn+n | ||
rr(obj, k) | reduced rank variant of fa | kn+n | ||
chol(obj, k) | Cholesky order k | (k+1)(n-k/2) | ||
cholc(obj, k) | Cholesky | (k+1)(n-k/2) | ||
ante(obj, k) | antedependence order k | (k+1)(n-k/2) | ||
mthr(obj) | multinomial models only |
Metric based models in 1D or 2D
Call | Description | p | v | h |
exp(x) | exponential 1D | 1 | 2 | 1+n |
iexp(x, y) | isotropic exponential 2D | 1 | 2 | 1+n |
aexp(x, y) | anisotropic exponential 2D | 2 | 3 | 2+n |
gau(x) | gaussian 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 |
isp(x, y) | isotropic spherical 2D | 1 | 2 | 1+n |
cir(x, y) | isotropic circular 2D | 1 | 2 | 1+n |
mtrn(x, y, ...) | Matern class 2D | * | * | * |
^*See the user guide for an extended discussion of the Matern class.
Known relationship structures
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
Call | Description |
str(~terms, ~model) | Apply the direct product variance structure
in ~model |
to the set of terms in ~terms .
|
User defined structures
Call | Description |
own(obj, fun, init, type) | Call fun with the parameter
estimates in init |
to compute the variance matrix and its derivatives. |
Gilmour AR, Thompson R, Cullis BR (1995). “AI, An Efficient Algorithm for REML Estimation in Linear Mixed Models.” Biometrics, 51, 1440-1450. Kenward MG, Roger JH (1997). “The Precision of Fixed Effects Estimates from Restricted Maximum Likelihood.” Biometrics, 53, 983-997.
asreml.options
asreml.object
asr_families
## Not run: data(oats) oats.asr <- asreml(yield ~ Variety*Nitrogen, random = ~ Blocks/Wplots, data=oats) ## End(Not run)