| predictPlus.asreml {asremlPlus} | R Documentation |
Forms the predictions for a term, their pairwise differences and
associated statistics. A factor having parallel values may occur in
the model and a linear transformation of the predictions can be specified.
It results in an object of class alldifffs.
Description
This function forms the predictions for term using
classify and the supplied asreml object and stores
them in an alldiffs.object. If x.num is
supplied, the predictions will be obtained for the values supplied
in x.pred.values and, if supplied, x.plot.values will
replace them in the alldiffs.object that is returned.
If x.fac, but not x.num, is specified, predictions
will involve it and, if supplied, x.plot.values will replace
the levels of x.fac in the alldiffs.object
that is returned. In order to get the correct predictions you may
need to supply additional arguments to predict.asreml
through ... e.g. present, parallel, levels.
Any aliased predictions will be removed, as
will any standard error of pairwise differences involving them.
Also calculated are the approximate degrees of freedom of the
standard errors of the predictions. If the denominator degrees of
freedom for term are available in wald.tab, they are
used. Otherwise the residual degrees of freedom or the maximum of
the denominator degrees in wald.tab, excluding the
Intercept, are used. Which is used depends on the setting of
dDF.na. These degrees of freedom are used for the
t-distribution on which p-values and confidence intervals are
based. It is stored as an attribute to the alldiffs.object.
The degrees of freedom are also used in calculating the minimum,
mean and maximum LSD for comparing pairs of predictions, which are
also stored in the alldiffs.object.
If pairwise = TRUE, all pairwise differences between the
predictions, their standard errors, p-values and LSD
statistics are computed using allDifferences.data.frame.
This adds them to the alldiffs.object as additional
list components named differences, sed,
p.differences and LSD.
If a linear transformation of the predictions is specified then the
values of this linear transformation are returned,
instead of the original predictions, along with their standard errors
and the pairwise differences and associated statistics.
If a transformation has been applied in the analysis (any one of
transform.power is not one, scale is not one and
offset is nonzero), the backtransforms of the transformed
values and their lower and upper error intervals are added
to a data.frame that is consistent with the predictions
data.frame.
If transform.power is other than
one, the standard.error column of the data.frame
is set to NA. This data.frame is added to the
alldiffs.object as a list component called
backtransforms.
The printing of the components produced is controlled by the
tables argument. The order of plotting the levels of
one of the factors indexing the predictions can be modified
and is achieved using sort.alldiffs.
Usage
## S3 method for class 'asreml'
predictPlus(asreml.obj, classify, term = NULL,
inestimable.rm = TRUE,
linear.transformation = NULL, EGLS.linTransform = TRUE,
error.intervals = "Confidence", alpha = 0.05,
wald.tab = NULL, dDF.na = "residual", dDF.values = NULL,
pairwise = TRUE, Vmatrix = FALSE,
avsed.tolerance = 0.25, accuracy.threshold = NA,
LSDtype = "overall", LSDsupplied = NULL, LSDby = NULL,
LSDstatistic = "mean", LSDaccuracy = "maxAbsDeviation",
x.num = NULL, x.fac = NULL,
x.pred.values = NULL, x.plot.values = NULL,
titles = NULL, tables = "all" , level.length = NA,
transform.power = 1, offset = 0, scale = 1,
transform.function = "identity",
sortFactor = NULL, sortParallelToCombo = NULL,
sortNestingFactor = NULL, sortOrder = NULL,
decreasing = FALSE, trace = FALSE, ...)
Arguments
asreml.obj |
asreml object for a fitted model.
|
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. To predict the overall
mean, set the classify to "(Intercept)".
|
term |
A character string giving the variables that define the term
that was fitted using asreml and that corresponds to classify.
It only needs to be specified when it is different to classify; it
is stored as an attribute of the alldiffs.object.
It is likely to be needed when the fitted model includes terms that involve
both a numeric covariate and a factor that
parallel each other; the classify would include the covariate and
the term would include the factor.
|
inestimable.rm |
A logical indicating whether rows for predictions
that are not estimable are to be removed from the components of
the alldiffs.object.
|
linear.transformation |
A formula or a matrix.
If a formula is given then it is taken to be a submodel of
a model term corresponding to the classify. The projection matrix
that transforms the predictions so that they conform to the submodel
is obtained; the submodel does not have to involve variables in the
classify, but the variables must be columns in the predictions
component of alldiffs.obj and the space for the submodel must be a
subspace of the space for the term specified by the classify.
For example, for classify set to "A:B", the submodel
~ A + B will result in the predictions for the combinations of
A and B being made additive for the factors
A and B. The submodel space corresponding to A + B is
a subspace of the space A:B. In this case both the submodel and the
classify involve only the factors A and B. To fit an intercept-only
submodel, specify linear.transformation to be the formula ~1.
If a matrix is provided then it will be
used to apply the linear transformation to the predictions.
It might be a contrast matrix or a matrix of
weights for a factor used to obtain the weighted average over that factor.
The number of rows in the matrix should equal the
number of linear combinations of the predictions desired and
the number of columns should equal the number of predictions.
In either case, as well as the values of the linear combinations,
their standard errors, pairwise differences and associated statistics
are returned.
|
EGLS.linTransform |
A logical indicating whether or not the
linear.transformation of the predictions stored in an
alldiffs.object by fitting a submodel supplied in a
formula is to take into account the variance of the
predictions using a Estimated Generalized Least Squares (EGLS) approach.
This is likely to be appropriate when the variance matrix of the predictions
is not compound symmetric i.e. when not all the variances are equal or not
all the covariances are equal. If the variance matrix is compund symmetric,
then the setting of EGLS.linTransform will not affect the transformed
predictions.
|
error.intervals |
A character string indicating the type of error interval, if any,
to calculate in order to indicate uncertainty in the results.
Possible values are "none", "StandardError", "Confidence"
and "halfLeastSignificant". The default is for confidence limits to
be used. The "halfLeastSignificant" option results in half the
Least Significant Difference (LSD) being added and subtracted to the
predictions, the LSD being calculated using the square root of the mean of the
variances of all or a subset of pairwise differences between the predictions.
If the LSD is zero, as can happen when predictions are constrained to be equal,
then the limits of the error intervals are set to NA.
If LSDtype is set to overall, the avsed.tolerance is not
NA and the range of the SEDs divided by the average of the SEDs exceeds
avsed.tolerance then the error.intervals calculations and the plotting
will revert to confidence intervals.
|
alpha |
A numeric giving the significance level for LSDs or one minus
the confidence level for confidence intervals.
It is stored as an attribute to the alldiffs.object.
|
wald.tab |
A data.frame containing the pseudo-anova table for the
fixed terms produced by a call to wald.asreml. The main
use of it here is in determining the degrees of freedom for
calculating confidence or half-LSD error.intervals and p-values,
the latter to be stored in the p.differences component of the
alldiffs.object that is created.
|
dDF.na |
A character specifying the method to use to
obtain approximate denominator degrees of
freedom. when the numeric or algebraic methods produce an
NA. Consistent with when no denDF are available, the
default is "residual" and so the residual degrees of
freedom from asreml.obj$nedf are used.
If dDF.na = "none", no substitute denominator degrees of
freedom are employed; if dDF.na = "maximum", the maximum
of those denDF that are available, excluding that for the
Intercept, is used; if all denDF are NA, asreml.obj$nedf is used. If
dDF.na = "supplied", a vector of values for the
denominator degrees of freedom is to be supplied in dDF.values.
Any other setting is ignored and a warning message produced.
Generally, substituting these degrees of freedom is
anticonservative in that it is likely that the degrees of freedom
used will be too large.
|
dDF.values |
A vector of values to be used when
dDF.na = "supplied". Its values will be used when
denDF in a test for a fixed effect is NA.
This vector must be the same length as the number of
fixed terms, including (Intercept) whose value could be
NA.
|
pairwise |
A logical indicating whether all pairwise differences of the
predictions and their standard errors and p-values are to be
computed and stored. If tables is equal to
"differences" or "all" or error.intervals is
equal to "halfLeastSignificant", they will be stored
irrespective of the value of pairwise.
|
Vmatrix |
A logical indicating whether the variance matrix of the
predictions will be stored as a component of the
alldiffs.object that is returned.
If linear.transformation is set, it will
be stored irrespective of the value of Vmatrix.
|
avsed.tolerance |
A numeric giving the value of the SED range, the range of the SEDs
divided by the square root of the mean of the variances of all or a subset of the
pairwise differences, that is considered reasonable in calculating
error.intervals. To have it ignored, set it to NA. It should be a
value between 0 and 1. The following rules apply:
If avsed.tolerance is NA then mean LSDs of the type specified by
LSDtype are calculated and used in error.intervals and plots.
Irrespective of the setting of LSDtype, if avsed.tolerance is not
exceeded then the mean LSDs are used in error.intervals and plots.
If LSDtype is set to overall, avsed.tolerance is not
NA, and avsed.tolerance is exceeded then error.intervals and
plotting revert to confidence intervals.
If LSDtype is set to factor.combinations and avsed.tolerance
is not exceeded for any factor combination then the half LSDs are
used in error.intervals and plots; otherwise, error.intervals and
plotting revert to confidence intervals.
If LSDtype is set to per.prediction and avsed.tolerance
is not exceeded for any prediction then the half LSDs are used in error.intervals
and plots; otherwise, error.intervals and plotting revert to confidence intervals.
|
accuracy.threshold |
A numeric specifying the value of the LSD accuracy measure,
which measure is specified by LSDaccuracy, as a threshold value in determining whether the
hallfLeastSignificant error.interval for a predicted value is a reasonable
approximation; this will be the case if the LSDs across all pairwise comparisons for which
the interval's LSD was computed, as specified by LSDtype and LSDby,
are similar enough to the interval's LSD, as measured by LSDaccuracy.
If it is NA, it will be ignored. If it is
not NA, a column of logicals named LSDwarning will be added
to the predictions component of the alldiffs.object. The value of
LSDwarning for a predicted.value will be TRUE if the value of the
LSDaccuracy measure computed from the LSDs for differences between this
predicted.value and the other predicted.values as compared to its
assignedLSD exceeds the value of accuracy.threshold. Otherwise, the
value of LSDwarning for a predicted.value will be FALSE.
|
LSDtype |
A character string that can be overall, factor.combinations,
per.prediction or supplied. It determines whether the values stored in a row
of a LSD.frame are the values calculated
(i) overall from the LSD values for all pairwise comparison2,
(ii) the values calculated from the pairwise LSDs for the levels of each
factor.combination, unless there is only one prediction for a level of the
factor.combination, when a notional LSD is calculated,
(iii) per.prediction, being based, for each prediction, on all pairwise differences
involving that prediction, or
(iv) as supplied values of the LSD, specified with the LSDsupplied argument;
these supplied values are to be placed in the assignedLSD column of the
LSD.frame stored in an alldiffs.object so that they can be used
in LSD calculations.
See LSD.frame for further information on the values in a row of this
data.frame and how they are calculated.
|
LSDsupplied |
A data.frame or a named numeric containing a set of LSD
values that correspond to the observed combinations of the values of the LSDby variables
in the predictions.frame or a single LSD value that is an overall LSD.
If a data.frame, it may have (i) a column for the LSDby variable and a column
of LSD values or (ii) a single column of LSD values with rownames being the
combinations of the observed values of the LSDby variables. Any name can be used
for the column of LSD values; assignedLSD is sensible, but not obligatory. Otherwise,
a numeric containing the LSD values, each of which is named for the observed
combination of the values of the LSDby variables to which it corresponds. (Applying the
function dae::fac.combine to the predictions component is one way of
forming the required combinations for the (row) names.) The values supplied
will be incorporated into assignedLSD column of the LSD.frame stored as the
LSD component of the alldiffs.object.
|
LSDby |
A character (vector) of variables names, being the names of the
factors or numerics in the classify; for each
combination of their levels and values, there will be or is a row in the LSD.frame
stored in the LSD component of the alldiffs.object when LSDtype is
factor.combinatons.
|
LSDstatistic |
A character nominating one or more of minimum, q10, q25,
mean, median, q75, q90 or maximum as the value(s) to be
stored in the assignedLSD column in an LSD.frame; the values in the
assignedLSD column are used in computing halfLeastSignificant error.intervals.
Here q10, q25, q75 and q90 indicate the sample quantiles corresponding
to probabilities of 0.1, 0.25, 0.75 and 0.9 for the group of LSDs from which a single LSD value
is calculated. The function quantile is used to obtain them. The mean LSD is
calculated as the square root of the mean of the squares of the LSDs for the group. The
median is calculated using the median function. Multiple values are only
produced for LSDtype set to factor.combination, in which case LSDby must
not be NULL and the number of values must equal the number of observed combinations of
the values of the variables specified by LSDby. If LSDstatistic is NULL,
it is reset to mean.
|
LSDaccuracy |
A character nominating one of maxAbsDeviation, maxDeviation,
q90Deviation or RootMeanSqDeviation as the statistic to be calculated as a measure
of the accuracy of assignedLSD. The option q90Deviation produces the sample quantile
corresponding to a probability of 0.90. The deviations are the differences between the LSDs used in
calculating the LSD statistics and each assigned LSD and the accuracy is expressed as a
proportion of the assigned LSD value. The calculated values are stored in the column named
accuracyLSD in an LSD.frame.
|
titles |
A list, each component of which is named for a column in
the data.frame for asreml.obj and contains a
character string giving a title to use
in output (e.g. tables and graphs). Here they will
be used for table headings.
|
tables |
A character vector containing a combination of
none,
predictions, vcov, backtransforms, differences,
p.differences, sed, LSD and all.
These nominate which components of the alldiffs.object to print.
|
x.num |
A character string giving the name of the numeric covariate that
(i) is potentially included in terms in the fitted model and (ii) is the
x-axis variable for plots. Its values will not be converted to a factor.
|
x.fac |
A character string giving the name of the factor that
(i) corresponds to x.num and (ii) is potentially included in
terms in the fitted model. It should have the same number of levels as the
number of unique values in x.num. The levels of
x.fac must be in the order in which they are to be plotted
- if they are dates, then they should be in the form
yyyymmdd, which can be achieved using as.Date. However, the levels
can be non-numeric in nature, provided that x.num is also set.
|
x.pred.values |
The values of x.num for which predicted values are
required. If levels is set for passing to predict.asreml,
x.pred.values is ignored. Note that while levels is an
alternative to x.pred.values, x.pred.values allows more
general setting of the levels to be predicted.
|
x.plot.values |
The actual values to be plotted on the x axis. They are
needed when values different to those in x.num are to be
plotted or x.fac is to be plotted because there is no
x.num term corresponding to the same term with x.fac.
|
level.length |
The maximum number of characters from the levels of
factors to use in the row and column labels of the tables of
pairwise differences and their p-values and standard errors.
|
transform.power |
A numeric specifying the power of a transformation, if
one has been applied to the response variable. Unless it is equal
to 1, the default, back-transforms of the predictions will be
obtained and stored in the backtransforms component of the
alldiffs.object.
The back-transformation raises the predictions to the power equal
to the reciprocal of transform.power, unless it equals 0 in
which case the exponential of the predictions is taken.
|
offset |
A numeric that has been added to each value of the
response after any scaling and before applying any power transformation.
|
scale |
A numeric by which each value of the response has been multiplied
before adding any offset and applying any power transformation.
|
transform.function |
A character giving the name of a function that
specifies the scale on which the predicted values are defined. This may be the
result of a transformation of the data using the function or the use of the
function as a link function in the fitting of a generalized linear (mixed)
model (GL(M)M). The possible transform.functions are
identity, log, inverse, sqrt, logit,
probit, and cloglog. The predicted.values and
error.intervals, if not StandardError intervals, will be
back-transformed using the inverse function of the transform.function.
The standard.error column will be set to NA, unless (i)
asreml returns columns named transformed.value and
approx.se, as well as those called predicted.values and
standard.error (such as when a GLM is fitted) and
(ii) the values in transformed.value are equal to those obtained by
backtransforming the predicted.values using the inverse function
of the transform.function. Then, the approx.se values will be
saved in the standard.error column of the backtransforms
component of the returned alldiffs.obj. Also, the
transformed.value and approx.se columns are removed from both
the predictions and backtransforms components of the
alldiffs.obj. Note that the values that end up in the standard errors
column are approximate for the backtransformed values and are not used in
calculating error.intervals.
|
sortFactor |
A character containing the name of the
factor that indexes the set of predicted values that determines
the sorting of the components. If there is only one variable in the
classify term then sortFactor can be NULL and
the order is defined by the complete set of predicted values.
If there is more than one variable in the classify term
then sortFactor must be set. In this case the sortFactor
is sorted in the same order within each combination of the values of
the sortParallelToCombo variables: the classify variables, excluding the
sortFactor. There should be only one predicted value for
each unique value of sortFactor within each set defined by a
combination of the values of the classify variables, excluding the
sortFactor factor.
The order to use is determined by either sortParallelToCombo or
sortOrder.
|
sortParallelToCombo |
A list that specifies a combination of the values
of the factors and numerics, excluding sortFactor, that
are in classify. Each of the components of the supplied list
is named for a classify variable and specifies a single value for it. The
combination of this set of values will be used to define a subset of the predicted
values whose order will define the order of sortFactor. Each of the other
combinations of the values of the factors and numerics will be sorted
in parallel. If sortParallelToCombo is NULL then the first value of
each classify variable, except for the sortFactor factor,
in the predictions component is used to define sortParallelToCombo.
If there is only one variable in the classify then
sortParallelToCombo is ignored.
|
sortNestingFactor |
A character containing the name of the
factor that defines groups of the sortFactor within which the predicted
values are to be ordered.
If there is only one variable in the classify then
sortNestingFactor is ignored.
|
sortOrder |
A character vector whose length is the same as the number
of levels for sortFactor in the predictions component of the
alldiffs.object. It specifies the desired order of the
levels in the reordered components of the alldiffs.object.
The argument sortParallelToCombo is ignored.
The following creates a sortOrder vector levs for factor
f based on the values in x:
levs <- levels(f)[order(x)].
|
decreasing |
A logical passed to order that detemines whether
the order for sorting the components of the alldiffs.object is for
increasing or decreasing magnitude of the predicted values.
|
trace |
A logical that control output from ASReml-R.
If TRUE then partial iteration details are displayed when ASReml-R
functions are invoked; if FALSE then no output is displayed.
|
... |
further arguments passed to predict.asreml.
|
Value
For linear.transformations set to NULL, an S3-class
alldiffs.object with predictions and their standard
errors and, depending on the settings of the arguments, all pairwise
differences between predictions, their standard errors and p-values
and LSD statistics. Also, unless the sortFactor or sortOrder
arguments are invoked, the rows of predictions component are ordered
so that they are in standard order for the variables in the classify.
That is, the values of the last variable change with every row, those of the
second-last variable only change after all the values of the last variable have
been traversed; in general, the values of a variable are the same for all the
combinations of the values to the variables to its right in the classify.
In addition, if necessary, the order of the columns of the variables in the
predictions component are changed to match their order in the classify.
If transform.power or scale is not one or offset
is not zero, it will contain a data.frame with the backtransformed
linear transformation of the predictions. The backtransformation will, after
backtransforming for any power transformation, subtract the offset
and then divide by the scale.
If error.intervals is not "none", then the
predictions component and, if present, the
backtransforms component will contain columns for the lower
and upper values of the limits for the interval.
The name of the response, the response.title,
the term, the classify, tdf, sortFactor
and the sortOrder will be set as attributes to the object.
Also, if error.intervals is "halfLeastSignificant", then those of
LSDtype, LSDby and LSDstatistic that are not NULL
will be added as attributes of the object and of the predictions frame;
additionally, LSDvalues will be added as attribute of the
predictions frame, LSDvalues being the LSD values used in
calculating the error.intervals.
Note that the classify in an alldiffs.object is based on the
variables indexing the predictions, which may differ from the
classify used to obtain the original predictions (for example,
when the alldiffs.objects stores a linear transformation of predictions.
For linear.transformations set to other than NULL,
an alldiffs.object with the linear.transformation
applied to the predictions and their standard errors and,
depending on the settings of the arguments, all pairwise
differences between the linearly transformed predictions, their
standard errors and p-values and LSD statistics.
(See also linTransform.alldiffs.)
Author(s)
Chris Brien
See Also
alldiffs.object, as.alldiffs, print.alldiffs,
linTransform.alldiffs, sort.alldiffs,
subset.alldiffs, allDifferences.data.frame,
redoErrorIntervals.alldiffs,
recalcLSD.alldiffs, exploreLSDs.alldiffs,
pickLSDstatistics.alldiffs,
predictPresent.asreml,
plotPredictions.data.frame, as.Date, predict.asreml
Examples
## Not run:
data(WaterRunoff.dat)
asreml.options(keep.order = TRUE) #required for asreml-R4 only
current.asr <- asreml(fixed = pH ~ Benches + (Sources * (Type + Species)),
random = ~ Benches:MainPlots,
keep.order=TRUE, data= WaterRunoff.dat)
current.asrt <- as.asrtests(current.asr, NULL, NULL)
diffs <- predictPlus(classify = "Sources:Type",
asreml.obj = current.asr,
wald.tab = current.asrt$wald.tab,
present = c("Sources", "Type", "Species"))
## End(Not run)
[Package
asremlPlus version 4.4.35
Index]