pred.present.asreml {asreml3Plus}R Documentation

This function forms the predictions for each significant term and presents them in tables and/or graphs.

Description

This function forms the predictions for each term in terms using a supplied asreml object and predictparallel.asreml. Tables are produced using predictparallel.asreml, in conjunction with predictiondiffs.asreml, with the argument tables specifying which tables are printed. The argument plots, along with transform.power, controls which plots are produced. The plots are produced using predictionplot.asreml, with line plots produced when variables involving x.num or x.fac are involved in classify for the predictions and bar charts otherwise. In order to get the correct predictions you may need to supply additional arguments to predict through ... e.g. present.

Usage

pred.present.asreml(terms, asreml.obj = NULL, 
                    wald.tab = NULL, dDF.na = "residual", dDF.values = NULL, 
                    x.num = NULL, x.fac = NULL, nonx.fac.order = NULL,  
                    x.pred.values = NULL, x.plot.values = NULL, 
                    plots = "predictions", panels = "multiple", 
                    graphics.device = NULL, 
                    error.intervals = "Confidence", avsed.tolerance = 0.25, 
                    titles = NULL, colour.scheme = "colour", save.plots = FALSE, 
                    transform.power = 1, offset = 0, scale = 1, 
                    pairwise = TRUE, tables = "all", levels.length = NA, 
                    alpha = 0.05, inestimable.rm = TRUE, 
                    trace = FALSE, ggplotFuncs = NULL, ...)

Arguments

terms

a character vector giving the terms for which predictions are required.

asreml.obj

asreml object for a fitted model.

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 getting denominator degrees of freedom when confidence intervals are to be plotted.

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.

x.num

A character string giving the name of the numeric covariate that corresponds to x.fac, is potentially included in terms in the fitted model and 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 corresponds to x.num, is potentially included in terms in the fitted model and 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.

nonx.fac.order

A character vector giving the order in which factors other than x.fac are to be plotted in plots with multiple panels (i.e. where the number of non-x factors is greater than 1). The first factor in the vector will be plotted on the X axis (if there is no x.num or x.fac. Otherwise, the order of plotting the factors is in columns (X facets) and then rows (Y facets). By default the order is in decreasing order for the numbers of levels of the non x factors.

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 or in the labels of tables. 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.

plots

Possible values are "none", "predictions", "backtransforms" and "both". Plots are not produced if the value is "none". If data are not transformed for analysis (transform.power = 1), a plot of the predictions is produced provided plots is not "none". If the data are transformed, the value of plots determines what is produced.

panels

Possible values are "single" and "multiple". When line plots are to be produced, because variables involving x.num or x.fac are involved in classify for the predictions, panels determines whether or not a single panel or multiple panels in a single window are produced. The panels argument is ignored for for bar charts.

graphics.device

A character specifying a graphics device for plotting. The default is
graphics.device = NULL, which will result in plots being produced on the current graphics device. Setting it to "windows", for example, will result in a windows graphics device being opened.

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 Least Significant Difference (LSD) being added and subtracted to the predictions, the 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 backtansformed 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.

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

colour.scheme

A character string specifying the colour scheme for the plots. The default is "colour" which produces coloured lines and bars, a grey background and white gridlines. A value of "black" results in black lines, grey bars and gridlines and a white background.

save.plots

A logical that determines whether any plots will be saved. If they are to be saved, a file name will be generated that consists of the following elements separated by full stops: the response variable name with .back if backtransformed values are being plotted, the classify term, Bar or Line and, if error.intervals is not "none", one of SE, CI or LSI. The file will be saved as a ‘png’ file in the current work directory.

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-transform will raise the predictions to the power equal to the reciprocal of transform.power, unless it equals 0 in which case the exponential will be taken. Any scaling and offsetting will also be taken into account in the backtransformation.

offset

A number that has been added to each value of the response after any scaling and before applying any power transformation. Unless it is equal to 0, the default, back-transforms of the predictions will be obtained and presented in tables or graphs as appropriate. The back-transform will, after backtransforming for any power transformation and scaling for any scale transformation, subtract the offset.

scale

A number by which each value of the response has been multiply before adding any offset and applying any power transformation. 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-transform will, after backtransforming for any power transformation, divide by the scale.

pairwise

A logical indicating whether all pairise 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

The elements of the alldiffs object to print. Possible values are "none", "predictions", "backtransforms", "nodifferences", "differences" and "all". The option "nodifferences" will result in "predictions" and "backtransforms" being printed. The option "differences" will also result in the printing of the predictions from the alldiffs object.

levels.length

The maximum number of characters from the the levels of factors to use in the row and column labels of the tables produced by predictiondiffs.asreml.

alpha

the significance level for the test or 1 - alpha is the confidence level for confidence intervals.

inestimable.rm

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

trace

if TRUE then partial iteration details are displayed when ASReml-R functions are invoked; if FALSE then no output is displayed.

ggplotFuncs

A list, each element of which contains the results of evaluating a ggplot function. It is created by calling the list function with a ggplot function call for each element. It is passed to predictionplot.asreml.

...

further arguments passed to predict.asreml via predictparallel.asreml and to ggplot via predictionplot.asreml.

Value

a list containing a alldiffs object for each term for which tables are produced. The names of the components of this list are the terms with full-stops (.) replacing colons (:).

See Also

predictparallel.asreml, predictiondiffs.asreml, predictionplot.asreml, print.alldiffs,
as.Date, Devices

Examples

## Not run: 
data(WaterRunoff.dat)
titles <- list("Days since first observation", "Days since first observation", 
               "pH", "Turbidity (NTU)")
names(titles) <- names(WaterRunoff.dat)[c(5,7,11:12)]
current.asr <- asreml(fixed = log.Turbidity ~ Benches + Sources + Type + Species + 
                                 Sources:Type + Sources:Species + Sources:Species:xDay + 
                                 Sources:Species:Date, 
                      data = WaterRunoff.dat, keep.order = TRUE)
current.asrt <- asrtests(current.asr, NULL, NULL)
diff.list <- pred.present.asreml("Date:Sources:Species", 
                                 asreml.obj = current.asrt$asreml.obj, 
                                 wald.tab = current.asrt$wald.tab, 
                                 x.num = "xDay", x.fac = "Date", 
                                 x.pred.values=sort(unique(WaterRunoff.dat$xDay)),
                                 x.plot.values=sort(unique(WaterRunoff.dat$Day)),
                                 plots = "predictions", 
                                 error.intervals = "StandardError", 
                                 titles = titles, 
                                 transform.power = 0, 
                                 present = c("Type","Species","Sources"), 
                                 tables = "differences", levels.length = 6)

## End(Not run)

[Package asreml3Plus version 2.0-14 Index]