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