asremlPlus-package {asremlPlus}R Documentation

Augments 'ASReml-R' in Fitting Mixed Models and Packages Generally in Exploring Prediction Differences

Description

Assists in automating the selection of terms to include in mixed models when 'asreml' is used to fit the models. Also used to display, in tables and graphs, predictions obtained using any model fitting function and to explore differences between predictions. The content falls into the following natural groupings: (i) Data, (ii) Object manipulation functions, (iii) Model modification functions, (iv) Model testing functions, (v) Model diagnostics functions, (vi) Prediction production and presentation functions, (vii) Response transformation functions, and (viii) Miscellaneous functions (for further details see 'asremlPlus-package' in help). A history of the fitting of a sequence of models is kept in a data frame. Procedures are available for choosing models that conform to the hierarchy or marginality principle and for displaying predictions for significant terms in tables and graphs. The 'asreml' package provides a computationally efficient algorithm for fitting mixed models using Residual Maximum Likelihood. It is a commercial package that can be purchased from 'VSNi' <https://www.vsni.co.uk/> as 'asreml-R', who will supply a zip file for local installation/updating (see <https://asreml.kb.vsni.co.uk/>). It is not needed for functions that are methods for 'alldiffs' and 'data.frame' objects. The package 'asremPlus' can also be installed from <http://chris.brien.name/rpackages/>.

Version: 4.2-32

Date: 2021-03-19

Index

(i) Data
Wheat.dat Data for an experiment to investigate 25 varieties of
wheat.
WaterRunoff.dat Data for an experiment to investigate the quality of
water runoff over time
(ii) Object manipulation
as.alldiffs Forms an alldiffs.object from the supplied
predictions, along with those statistics, associated with the
predictions and their pairwise differnces, that have been supplied.
asrtests Pseudonym for as.asrtests.
as.asrtests Forms an asrtests.object that stores (i) a fitted asreml object,
(ii) a pseudo-anova table for the fixed terms and
(iii) a history of changes and hypthesis testing
used in obtaining the model.
as.predictions.frame Forms a predictions.frame from a data.frame, ensuring that
the correct columns are present.
facCombine.alldiffs Combines several factors into one in the components of
an alldiffs.object.
facRecode.alldiffs Recodes factor levels using values in a vector. The values in the
vector do not have to be unique.
facRename.alldiffs Renames factors in the prediction component of
an alldiffs.object.
getFormulae.asreml Gets the formulae from an asreml object.
is.alldiffs A single-line function that tests whether an object is
of class alldiffs.
is.asrtests A single-line function that tests whether an object is
of class asrtests.
is.predictions.frame A single-line function that tests whether an object is
of classes predictions.frame and data.frame.
print.alldiffs Prints the values in an alldiffs.object in a nice format.
print.asrtests Prints the values in an asrtests.object.
print.predictions.frame Prints the values in a predictions.frame, with or without title and heading.
print.test.summary Prints a data.frame containing a test.summary.
print.wald.tab Prints a data.frame containing a Wald or pseudoanova table.
printFormulae.asreml Prints the formulae from an asreml object.
sort.alldiffs Sorts the components of an alldiffs.object according to
the predicted values associated with a factor.
subset.alldiffs Subsets the components in an alldiffs.object according
to the supplied condition.
validAlldiffs Checks that an object is a valid alldiffs.object.
validAsrtests Checks that an object is a valid asrtests.object.
validPredictionsFrame Checks that an object is a valid predictions.frame.
(iii) Model modification
changeTerms.asrtests Adds and drops the specified sets of terms from one
or both of the fixed or random model and/or replaces the
residual (rcov) model with a new model.
iterate.asrtests Subject the fitted asreml.obj stored in an asrtests.object
to further iterations of the fitting process.
newfit.asreml Refits an asreml model with modified model formula
using either a call to 'update.asreml' or a direct
call to 'asreml'.
reparamSigDevn.asrtests Reparamterizes each random (deviations) term
involving 'devn.fac' to a fixed term and ensures
that the same term, with 'trend.num' replacing
'devn.fac', is included if any other term with
'trend.num' is included in 'terms'.
rmboundary.asrtests Removes any boundary or singular variance components
from the fit stored in 'asreml.obj' and records their
removal in an asrtests.object.
setvarianceterms.call Allows the setting of bounds and initial values
for terms in the 'random' and 'residual' arguments of an
'asreml' call.
(iv) Model selection
changeModelOnIC.asrtests Uses information criteria to decide whether to change an
already fitted model.
chooseModel.asrtests Determines and records the set of significant terms using an
asrtests.object, taking into account the hierarchy
or marginality relations of the terms..
chooseModel.data.frame Determines the set of significant terms from results stored
in a data.frame, taking into account the marginality
relations of terms and recording the tests used in a
data.frame.
getTestPvalue.asrtests Gets the p-value for a test recorded in the test.summary
data.frame of an asrtests.object.
infoCriteria.asreml Computes AIC and BIC for models.
infoCriteria.list Computes AIC and BIC for models.
recalcWaldTab.asrtests Recalculates the denDF, F.inc and P values for a table
of Wald test statistics obtained using 'wald.asreml'.
REMLRT.asreml Performs a REML ratio test.
bootREMLRT.asreml Performs a REML ratio test using the parametric
bootstrap.
testranfix.asrtests Tests for a single fixed or random term in model
fitted using 'asreml' and records the result in an
asrtests.object.
testresidual.asrtests Fits a new residual formula using 'asreml', tests
whether the change is significant and records the
result in an asrtests.object.
testswapran.asrtests Tests, using a REMLRT, the significance of the difference
between the current random model and one in which oldterms
are dropped and newterms are added. The result is recorded
in an asrtests.object.
(v) Model diagnostics and simulation
plotVariofaces Plots empirical variogram faces, including envelopes,
from supplied residuals as described by Stefanova, Smith
& Cullis (2009).
variofaces.asreml Calculates and plots empirical variogram faces, including
envelopes, as described by Stefanova, Smith & Cullis (2009).
estimateV.asreml Forms the estimated variance, random or residual matrix for
the observations from the variance parameter estimates.
simulate.asreml Produce sets of simulated data from a multivariate normal
distribtion and save quantites related to the simulated data.
(vi) Prediction production and presentation
addBacktransforms.alldiffs Adds or recalculates the backtransforms component of an
alldiffs.object.
allDifferences.data.frame Using supplied predictions and standard errors of pairwise
differences or the variance matrix of predictions, forms
all pairwise differences between the set of predictions, and
p-values for the differences.
linTransform.alldiffs Calculates a linear transformation of the
predictions stored in an alldiffs.object.
plotPredictions.data.frame Plots the predictions for a term, possibly with
error bars.
plotPvalues.alldiffs Plots the p-values in the p.differences components
of an alldiffs.object as a heat map.
plotPvalues.data.frame Plots the p-values in data.frame as a heat map.
predictPlus.asreml Forms the predictions and associated statistics for
a term, using an asreml object and a wald.tab and
taking into account that a numeric vector
and a factor having parallel values may occur in the
model. It stores the results in an object of class
'alldifffs' and may print the results. It can be
when there are not parallel values.
predictPresent.asreml Forms the predictions for each of one or more terms
and presents them in tables and/or graphs.
recalcLSD.alldiffs Adds or recalculates the LSD component of an
alldiffs.object.
redoErrorIntervals.alldiffs Adds or replaces the error intervals stored in the
prediction component of an alldiffs.object.
renewClassify.alldiffs Renews the components in an alldiffs.object
according to a new classify.
sort.alldiffs Sorts the components in an alldiffs.object
according to the predicted values associated with a factor.
subset.alldiffs Subsets the components in an alldiffs.object according
to the supplied condition.
(vii) Response transformation
angular Applies the angular transformation to proportions.
angular.mod Applies the modified angular transformation to a
vector of counts.
powerTransform Performs a combination of a linear and a power
transformation on a variable. The transformed
variable is stored in the 'data.frame data'.
(viii) Miscellaneous
getASRemlVersionLoaded Finds the version of asreml that is loaded and
returns the initial characters in version.
loadASRemlVersion Ensures that a specific version of asreml is loaded.
num.recode Recodes the unique values of a vector using the values
in a new vector.
permute.square Permutes the rows and columns of a square matrix.
permute.to.zero.lowertri Permutes a square matrix until all the lower
triangular elements are zero.

The functions whose names end in 'alldiffs" utilize an alldiffs.object that stores: (i) a predictions.frame, being a data frame containing predicted values, variables indexing them and their standard errores and estimability status; the lower and upper limits of error intervals will be included when these are requested, (ii) optionally, square matrices containing all pairwise differences, the standard errors and p-values of the differences, and a summary of the LSD values, (iii) optionally, the variance matrix of the predictions, and (iv) if the response was trandformed for analysis, a data frame with backtransforms of the predicted values.

The functions whose names end in 'asrtests', which are most of the model functions, utilize an asrtests.object that stores: (i) the currently fitted model in asreml.obj, (ii) the table of test statistics for the fixed effects in wald.tab, and (iii) a data frame that contains a history of the changes made to the model in test.summary.

Author(s)

Chris Brien [aut, cre] (<https://orcid.org/0000-0003-0581-1817>)

Maintainer: Chris Brien <chris.brien@adelaide.edu.au>

References

Butler, D. G., Cullis, B. R., Gilmour, A. R., Gogel, B. J. and Thompson, R. (2018). ASReml-R Reference Manual Version 4. VSN International Ltd, https://asreml.kb.vsni.co.uk/.

Stefanova, K. T., Smith, A. B. & Cullis, B. R. (2009) Enhanced diagnostics for the spatial analysis of field trials. Journal of Agricultural, Biological, and Environmental Statistics, 14, 392–410.

See Also

asreml

Examples

## Not run: 
## Analyse wheat dat using asreml and asremlPlus (see also the Wheat Vignette)
## Set up for analysis
library(dae)
library(asreml)
library(asremlPlus)
## use ?Wheat.dat for data set details
data(Wheat.dat)

# Fit initial model
current.asr <- asreml(yield ~ Rep + WithinColPairs + Variety, 
                      random = ~ Row + Column + units,
                      residual = ~ ar1(Row):ar1(Column), 
                      data=Wheat.dat)
summary(current.asr)

# Intialize a testing sequence by loading the current fit into an asrtests object
current.asrt <- as.asrtests(current.asr, NULL, NULL)

# Check for and remove any boundary terms
current.asrt <- rmboundary(current.asrt)

#Unbind Rep, Row and Column components and reload into an asrtests object
current.asr <- setvarianceterms(current.asr$call, 
                                terms = c("Rep", "Rep:Row", "Rep:Column"), 
                                bounds = "U")
current.asrt <- as.asrtests(current.asr, NULL, NULL)
current.asrt <- rmboundary(current.asrt)
summary(current.asrt$asreml.obj)$varcomp
print(current.asrt, which = "testsummary")
print(current.asrt, which = "pseudoanova")

# Check term for within Column pairs (a post hoc covariate)
current.asrt <- testranfix(current.asrt, "WithinColPairs", drop.fix.ns=TRUE)
  
# Test nugget term
current.asrt <- testranfix(current.asrt, "units", positive=TRUE)
  
# Test Row autocorrelation
current.asrt <- testresidual(current.asrt, "~ Row:ar1(Column)", 
                             label="Row autocorrelation", simpler=TRUE)
  
# Test Col autocorrelation (depends on whether Row autocorrelation retained)
(p <- getTestPvalue(current.asrt, label = "Row autocorrelation"))
{ if (p <= 0.05)
    current.asrt <- testresidual(current.asrt, "~ ar1(Row):Column", 
                                 label="Col autocorrelation", 
                                 simpler=TRUE, update=FALSE)
  else
    current.asrt <- testresidual(current.asrt, "~ Row:Column", 
                                 label="Col autocorrelation", 
                                 simpler=TRUE, update=FALSE)
}

# Output the results
print(current.asrt, which = "test")
info <- infoCriteria(current.asrt$asreml.obj)
summary(current.asrt$asreml.obj)$varcomp

# Get current fitted asreml object and update to include standardized residuals
current.asr <- current.asrt$asreml.obj
current.asr <- update(current.asr, aom=TRUE)
Wheat.dat$res <- residuals(current.asr, type = "stdCond")
Wheat.dat$fit <- fitted(current.asr)

#### Do diagnostic checking  
# Do residuals-versus-fitted values plot
with(Wheat.dat, plot(fit, res))
  
#Produce variogram and variogram faces plot (Stefanaova et al, 2009)
plot.varioGram(varioGram(current.asr))
faces <- variofaces(current.asr, V=NULL, units="addtores", 
                    maxiter=50, update = FALSE)

#Get Variety predictions, sorted in increasing order for the predicted values, 
#and all pairwise prediction differences and p-values
Var.diffs <- predictPlus(classify = "Variety", 
                         asreml.obj=current.asr, 
                         error.intervals="halfLeast",
                         wald.tab=current.asrt$wald.tab, 
                         sortFactor = "Variety",
                         tables = "predictions")
print(Var.diffs, which = c("differences", "p.differences"))

# Plot the Variety predictions, with halfLSD intervals, and the p-values
plotPredictions(Var.diffs$predictions, 
                classify = "Variety", y = "predicted.value", 
                error.intervals = "half")
plotPvalues(Var.diffs)

## End(Not run)

[Package asremlPlus version 4.2-32 Index]