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 deominator 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.
# S3 method for asreml
predictPlus(asreml.obj, classify, term = NULL,
linear.transformation = NULL, titles = NULL,
x.num = NULL, x.fac = NULL,
x.pred.values = NULL, x.plot.values = NULL,
error.intervals = "Confidence", avsed.tolerance = 0.25,
meanLSD.type = "overall", LSDby = NULL,
pairwise = TRUE, Vmatrix = FALSE,
tables = "all" , level.length = NA,
transform.power = 1, offset = 0, scale = 1,
inestimable.rm = TRUE,
sortFactor = NULL, sortWithinVals = NULL,
sortOrder = NULL, decreasing = FALSE,
wald.tab = NULL, alpha = 0.05,
dDF.na = "residual", dDF.values = NULL,
trace = FALSE, ...)asreml object for a fitted model.
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)".
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.
A formula or a matrix.
If a formula is given then it is taken to be a submodel of
the model term corresponding to the classify. The projection matrix
that transforms the predictions so that they conform to the submodel
is obtained; the submodel should involving the variables in 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.
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.
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.
A character string giving the name of the numeric covariate that
(i) corresponds to x.fac, (ii) is potentially included in
terms in the fitted model, and (iii) which corresponds to the
x-axis variable. It should have the same number of unique values
as the number of levels in x.fac.
A character string giving the name of the factor that
(i) corresponds to x.num, (ii) is potentially included in
terms in the fitted model, and (iii) which corresponds to the
x-axis variable. 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.
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 and
alternative to x.pred.values, it allows more general setting
of the levels to be predicted.
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.
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 meanLSD.type 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.
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. 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
meanLSD.type are calculated and used in error.intervals and plots.
Irrespective of the setting of meanLSD.type, if avsed.tolerance is not
exceeded then the mean LSDs are used in error.intervals and plots.
If meanLSD.type is set to overall, avsed.tolerance is not
NA, and avsed.tolerance is exceeded then error.intervals and
plotting revert to confidence intervals.
If meanLSD.type 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 meanLSD.type 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.
A character string determining whether the mean LSD stored is
(i) the overall mean, based on the square root of the mean of the variances of
all pairwise variances, (ii) the mean for each factor.combination of the
factors specified by LSDby, which is based on the square root of
the mean of the variances for all pairwise differences for each factor combination, unless
there is only one predction for a factor.combination, when notional LSDs are
calculated that are based on the standard error of the prediction multiplied by the square
root of two, or
(iii) the per.prediction mean, based, for each prediction,
on the square root of the mean of the variances for all pairwise differences involving
that prediction. It also
determines, in conjunction with avsed.tolerance, which LSD will be used
in calculating error.intervals and, hence, is used for plots.
A character (vector) of variables names, being the names of the
factors or numerics in the classify for each
combination of which a mean LSD, minLSD and max LSD is stored in the LSD
component of the alldiffs.object when meanLSD.type is
factor.combinatons.
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.
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.
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.
The maximum number of characters from the 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.
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 presented in tables or graphs as appropriate.
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.
A numeric that has been added to each value of the
response after any scaling and before applying any power transformation.
A numeric by which each value of the response has been multiplied
before adding any offset and applying any power transformation.
A logical indicating whether rows for predictions
that are not estimable are to be removed from the components of
the alldiffs.object.
A character containing the name of the
factor that indexes the set of predicted values that determines
the sorting of the components of the alldiffs.object by
sort.alldiffs. If NULL then sorting is not carried
out. If there is more than one variable
in the classify term then sortFactor is sorted for the
predicted values within each combination of the values of the sortWithin
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 sortWithin variables.
A list with a component named for each factor and
numeric that is a classify variable for the predictions,
excluding sortFactor. Each component should contain a single
value that is a value of the variable. 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 to be used for all
combinations of the sortWithinVals variables. If
sortWithinVals is NULL then the first value of each
sortWithin variable in predictions component is used
to define sortWithinVals. If there is only one variable in the
classify then sortWithinVals is ignored.
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 sortWithinVals is ignored.
The following creates a sortOrder vector levs for factor
f based on the values in x:
levs <- levels(f)[order(x)].
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.
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 determinining 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.
A numeric giving the significance level for LSDs or one minus
the confidence level for confidence intervals.
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 subtitute 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.
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.
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.
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.
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.)
alldiffs.object, as.alldiffs, print.alldiffs,
linTransform.alldiffs, sort.alldiffs,
subset.alldiffs, allDifferences.data.frame,
redoErrorIntervals.alldiffs,
recalcLSD.alldiffs, predictPresent.asreml,
plotPredictions.data.frame, as.Date,
predict.asreml
# 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"))
# }
Run the code above in your browser using DataLab