predictparallel.asreml {asreml3Plus}R Documentation

Uses an asreml object and a wald.tab to form the predictions and associated statistics for a term. It stores the results in an object of class alldifffs and may print the results. It can be used when a numeric vector and a factor that have parallel values both occur in the model and need to be taken into account.

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 through ... e.g. present. 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 valculating the minimum, mean and maximum LSD fro 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 predictiondiffs.asreml. This adds them to the alldiffs object as additional list components named differences, sed, p.differences and LSD.

If a transformation has been applied (any one of transform.power is not one, scale is not one and offset is nonzero), the back-transforms of the predicted values and their lower and upper confidence intervals are added to a data.frame that is consistent with an object of class asremlPredict, such as is stored in the pvals component of the prediction component of the value produced by predict.asreml. 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.

Usage

predictparallel.asreml(classify, term = NULL, asreml.obj = NULL, titles = NULL,  
                       x.num = NULL, x.fac = NULL,  
                       x.pred.values = NULL, x.plot.values = NULL, 
                       error.intervals = "Confidence", avsed.tolerance = 0.25, 
                       pairwise = TRUE, tables = "all" , levels.length = NA, 
                       transform.power = 1, offset = 0, scale = 1, 
                       inestimable.rm = TRUE, wald.tab = NULL,
                       alpha = 0.05, dDF.na = "residual",  dDF.values = NULL, 
                       trace = FALSE, ...)

Arguments

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.

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.

asreml.obj

asreml object for a fitted model.

titles

A list, each component of which is named for an object name and contains a character string giving a title to use in output (e.g. tables and graphs) for the object. 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.

x.pred.values

The values of x.num for which predicted values are required.

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 and plot 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 mean Least Significant Difference (LSD) being added and subtracted to the predictions, the mean LSD being calculated using the average of the standard errors of all pairwise differences (SEDs) between the predictions. However, if the range of the SEDs divided by the average of the SEDs exceeds avsed.tolerance, calculations and plotting will revert to confidence intervals. Also, half LSDs cannot be used for backtransformed values and so confidence intervals will be used instead.

avsed.tolerance

The values of the range of the SEDs divided by the average of the SEDs that, if exceeded, will cause calculations and plotting to revert to confidence intervals. It should be a value between 0 and 1.

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.

tables

A character vector containing a combination of none, predictions, backtransforms, differences, p.differences, sed, LSD and all. These nominate which components of the alldiffs object to print.

levels.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 number 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 number that has been added to each value of the response after any scaling and before applying any power transformation.

scale

A number by which each value of the response has been multiply 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 thealldiffs 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 determinining the degrees of freedom of the standard errors of the predictions. denominator degrees of freedom when p-values or confidence intervals are to be calculated.

alpha

the significance level for a test or one minus the confidence level for confidence intervals.

dDF.na

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

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

An 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. If power.transform is not one, it will contain a data.frame with the backtransformed predictions. 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 names of these columns will consist of three parts separated by full stops: 1) the first part will be lower or upper; 2) the second part will be one of Confidence, StandardError or halfLeastSignificant; 3) the third component will be limits.

The name of the response, the term, the classify and tdf, as well as the degrees of freedom of the standard error, will be set as attributes to the object.

See Also

alldiffs, print.alldiffs, predictiondiffs.asreml, pred.present.asreml, as.Date,
predictionplot.asreml, pred.present.asreml, predict.asreml

Examples

## Not run: 
data(WaterRunoff.dat)
current.asr <- asreml(fixed = pH ~ Benches + (Sources * (Type + Species)), 
                      random = ~ Benches:MainPlots,
                      keep.order=TRUE, data= WaterRunoff.dat)
current.asrt <- asrtests(current.asr, NULL, NULL)
diffs <- predictparallel.asreml(classify = "Sources:Type", 
                                asreml.obj = current.asr, 
                                x.num = "xDay", x.fac = "Date", 
                                x.pred.values=sort(unique(WaterRunoff.dat$xDay)),
                                x.plot.values=c(0,28,56,84),
                                wald.tab = current.asrt$wald.tab, 
                                present = c("Sources", "Type", "Species"))

## End(Not run)

[Package asreml3Plus version 2.0-14 Index]