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 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.

Usage

## S3 method for class '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, ...)

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.

linear.transformation

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.

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.

x.num

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.

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.

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 and alternative to x.pred.values, it 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.

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 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.

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. It should be a value between 0 and 1. The following rules apply:

  1. If avsed.tolerance is NA then mean LSDs of the type specified by meanLSD.type are calculated and used in error.intervals and plots.

  2. Irrespective of the setting of meanLSD.type, if avsed.tolerance is not exceeded then the mean LSDs are used in error.intervals and plots.

  3. 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.

  4. 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.

  5. 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.

meanLSD.type

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.

LSDby

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.

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.

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.

level.length

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.

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 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.

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.

inestimable.rm

A logical indicating whether rows for predictions that are not estimable are to be removed from the components of the alldiffs.object.

sortFactor

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.

sortWithinVals

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.

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 sortWithinVals 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.

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 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.

alpha

A numeric giving the significance level for LSDs or one minus the confidence level for confidence intervals.

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 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.

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.

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. 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, 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.2-32 Index]