asremlPlus-package: Augments 'ASReml-R' in Fitting Mixed Models and Packages...

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

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. Procedures are available for choosing models that conform to the hierarchy or marginality principle, for fitting and choosing between two-dimensional spatial models using correlation, natural cubic smoothing spline and P-spline models. A history of the fitting of a sequence of models is kept in a data frame. Also used to compute functions and contrasts of, to investigate differences between and to plot predictions obtained using any model fitting function. The content falls into the following natural groupings: (i) Data, (ii) Model modification functions, (iii) Model selection and description functions, (iv) Model diagnostics and simulation functions, (v) Prediction production and presentation functions, (vi) Response transformation functions, (vii) Object manipulation functions, and (viii) Miscellaneous functions (for further details see 'asremlPlus-package' in help). The 'asreml' package provides a computationally efficient algorithm for fitting a wide range of linear mixed models using Residual Maximum Likelihood. It is a commercial package and a license for it can be purchased from 'VSNi' <https://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: NA

Date: NA

Index

Note that many of the function below are S3 methods so that the suffix can be omitted. Of course, whether or not the suffix is omitted, the object supplied to the first argument must be of the class specified by the suffix. For example getFormulae.asreml is a getFormulae method for an asreml.object and so .asreml can be omitted and the object supplied to the first argument must be of class asreml.

(i) Data
Oats.dat	Data for an experiment to investigate nitrogen response of
	3 oats varieties.
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) Model modification
addSpatialModel.asrtests	Adds, to a supplied model, a spatial model that accounts for
	local spatial variation.
addSpatialModelOnIC.asrtests	Uses information criteria to decide whether to add a spatial
	model to account for local spatial variation.
changeTerms.asrtests	Adds and drops terms from one or both of the fixed or random
	model, replaces the residual (rcov) model with a new model
	and changes bounds or initial values of terms.
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 changed arguments by extracting,
	modifying and evaluating its call - an alternate to
	update.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.
(iii) Model selection and description
addto.test.summary	Adds a row to a test.summary data.frame.
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.
chooseSpatialModelOnIC.asrtests	Uses information criteria to choose the best fitting
	spatial model for accounting for local spatial variation.
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.
R2adj.asreml	Calculates the adjusted coefficient of determination for a
	specified combination of fixed and random terms.
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.
(iv) 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
	distribution and save quantities related to the simulated data.
(v) 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.
exploreLSDs	Explores the computed LSD values for pairwise differences
	between predictions.
linTransform.alldiffs	Calculates a linear transformation of the
	predictions stored in an alldiffs.object.
pairdiffsTransform.alldiffs	Calculates the differences between nominated pairs of
	predictions stored in an alldiffs.object
pickLSDstatistics	Pick LSDstatistics whose values minimize the number of
	errors in pairwise comparisons of predictions.
plotLSDerrors.data.frame	Plots a map of the supplied errors that occur in using the
	computed LSD values for pairwise differences between
	predictions.
plotLSDerrors.alldiffs	Plots a map of the errors that occur in using the computed
	LSD values for pairwise differences between predictions.
plotLSDs.data.frame	Plots a heat map of computed LSD values for pairwise
	differences between predictions.
plotLSDs.alldiffs	Plots a heat map of computed LSD values for pairwise
	differences between predictions.
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.
ratioTransform.alldiffs	Calculates the ratios of nominated pairs of predictions
	stored in an alldiffs.object.
recalcLSD.alldiffs	Adds or recalculates the LSD.frame that is a
	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.
sort.predictions.frame	Sorts a predictions.frame according to the
	predicted values. associated with a factor.
(vi) 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'.
(vii) Object manipulation
as.alldiffs	Forms an alldiffs.object from the supplied
	predictions, along with those statistics, associated with
	the predictions and their pairwise differences, 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 hypothesis testing
	used in obtaining the model.
as.predictions.frame	Forms a predictions.frame from a data.frame, ensuring
	that the correct columns are present.
convAsremlobj.asreml	Recreates an asreml object so that it is compatible with the
	currently loaded asreml version.
convEffectNames2DataFrame.asreml	Converts the effects names for a term stored in the component of an
	asreml object into a data.frame.
facCombine.alldiffs	Combines several factors into one in the components of
	an alldiffs.object.
facRecast.alldiffs	Reorders and/or revises the factor levels using the order of
	old levels in levels.order and the new labels for the
	levels given in newlabels.
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.
makeTPPSplineMats.data.frame	Make the spline basis matrices and data needed to fit
	Tensor Product P-Splines.
print.alldiffs	Prints the values in an alldiffs.object in a nice format.
print.asrtests	Prints the values in an asrtests.object.
print.LSDdata	Prints the components of a list containing data on the
	LSDs for all pairwise differences of predictions.
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.
subset.list	Forms a list that contains a subset of the components of
	the supplied list.
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.
(viii) Miscellaneous
getASRemlVersionLoaded	Finds the version of asreml that is loaded and
	returns the initial characters in version.
isCompoundSymmetric	Tests whether an object of class matrix is
	compound symmetric
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 errors 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 data.frame containing LSD values and their summary statistics, (iii) optionally, the variance matrix of the predictions, and (iv) if the response was transformed 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 <[e-mail]>

References

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

See Also

asreml

Examples

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

# Add row and column covariates for the spatial modelling
tmp.dat <- within(Wheat.dat, 
                  {
                    cColumn <- dae::as.numfac(Column)
                    cColumn <- cColumn  - mean(unique(cColumn))
                    cRow <- dae::as.numfac(Row)
                    cRow <- cRow - mean(unique(cRow))
                  })

# Fit an initial model - Row and column random
current.asr <- do.call(asreml, 
                       list(yield ~ Rep + WithinColPairs + Variety, 
                            random = ~ Row + Column,
                            residual = ~ Row:Column,
                            data = tmp.dat))

# Intialize a model sequence by loading the current fit into an asrtests object
current.asrt <- as.asrtests(current.asr, NULL, NULL, IClikelihood = "full", 
                            label = "Initial model")

# Check for and remove any boundary terms and print a summary of the fit in the asrtests object 
current.asrt <- rmboundary(current.asrt)
print(current.asrt)


## Compare a series of information criteria to select a linear mixed model for the data

# Check the need for the term for within Column pairs (a post hoc factor)
current.asrt <- changeModelOnIC(current.asrt, dropFixed = "WithinColPairs", 
                                label = "Try dropping withinColPairs", IClikelihood = "full")
print(current.asrt)

# Fit an ar1 model for local spatial variation
spatial.ar1.asrt <- addSpatialModelOnIC(current.asrt, spatial.model = "corr", 
                                        row.covar = "cRow", col.covar = "cColumn", 
                                        row.factor = "Row", col.factor = "Column", 
                                        IClikelihood = "full")
spatial.ar1.asrt <- rmboundary(spatial.ar1.asrt)
infoCriteria(list(nonspatial = current.asrt$asreml.obj, 
                  ar1 = spatial.ar1.asrt$asreml.obj))
print(spatial.ar1.asrt)

# Choose a model for local spatial variation from several potential models
suppressWarnings(
  spatial.asrts <- chooseSpatialModelOnIC(current.asrt, 
                                          row.covar = "cRow", col.covar = "cColumn",
                                          row.factor = "Row", col.factor = "Column",
                                          dropRandom = "Row + Column",
                                          rotateX = TRUE, ngridangles = NULL, 
                                          asreml.option = "grp", return.asrts = "all"))
# Output the results
print(spatial.asrts$spatial.IC)
print(R2adj(spatial.asrts$asrts$TPNCSS$asreml.obj, include.which.random = ~ .))
print(spatial.asrts$best.spatial.mod)
print(spatial.asrts$asrts$TPNCSS)
printFormulae(spatial.asrts$asrts$TPNCSS$asreml.obj)

## Diagnosting checking using residual plots and variofaces

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

# Do residuals-versus-fitted values plot
with(Wheat.dat, plot(fit, res))

# Plot variofaces
variofaces(current.asr, V=NULL, units="addtores", 
           maxiter=50, update = FALSE, 
           ncores = parallel::detectCores())

# Plot normal quantile plot
ggplot(data = Wheat.dat, mapping = aes(sample = res)) +
  stat_qq_band(bandType = "ts") + stat_qq_line() + stat_qq_point() +
  labs(x = "Theoretical Quantiles", y = "Sample Quantiles",
       title = "Normal probability plot") +
  theme(plot.title = element_text(size = 12, face = "bold")) + theme_bw()

## Prediction production and presentation

# Get Variety predictions 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")

# 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)

asremlPlus documentation built on Oct. 27, 2024, 5:06 p.m.