bootREMLRT.asreml: Uses the parametric bootstrap to calculate the p-value for a...

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

Uses the parametric bootstrap to calculate the p-value for a REML ratio test to compare two models.

Description

Extracts the REML log likelihood for two asreml objects and forms the observed REML ratio statistic. It assumes that the second asreml object is the result of fitting a model that is a reduced version of the model for the first object and is considered to the null model. Using the mean and V, nboot bootstrap samples of simulated response values are generated in parallel; that is, ncores cores are used and each is used to generate and analyse a sample. The full and reduced models are fitted to the data and if either analysis fails to converge another sample is generated and analysed using the current core, with a maximum of max.retries attempts to obtain a sample that converges for both analysis. Thus the maximum number of data sets that will be generated is nboot * max.retries. If a bootstrap sample converges for both analyses, the REML ratio test statistic is formed for it. The p-value is then calculated as (k + 1) / (b + 1) where k is the number of simulated ratio test statistics greater than the observed test statistic and s is the number of bootstrap samples that were returned.

The function checks that the models do not differ in either their fixed or sparse models. It also check the difference in the number of variance parameters between the two fits to the models, taking into account the bound.exclusions.

Usage

## S3 method for class 'asreml'
bootREMLRT(h0.asreml.obj, h1.asreml.obj, 
           nboot = 100, max.retries = 5, seed = NULL, 
           means=NULL, V = NULL, extra.matrix = NULL, ignore.terms = NULL, 
           fixed.spline.terms = NULL, 
           bound.exclusions = c("F","B","S","C"), 
           tolerance = 1E-10, update = TRUE, trace = FALSE, 
           ncores = 2, ...)

Arguments

h0.asreml.obj	asreml object containing the fit under the model for the null hypothesis.
h1.asreml.obj	asreml object containing the fit under the model for the alternative hypothesis.
nboot	The number of bootstrap samples to be generated.
max.retries	The maximum number of attempts to generate a sample whose analyses converge for both models.
seed	A single value, interpreted as an integer, that specifies the starting value of the random number generator. The "L'Ecuyer-CMRG" random generator is used and nextRNGStream is used to seed each core from the original seed.
means	The vector of means to be used in generating simulated bootstrap samples. If it is NULL, the fitted values based on object are used. It must be the same length as the response variable for object.
V	The fitted variance matrix, i.e. having the pattern and values that conform to the model fit stored in the supplied object. If it is NULL, estimateV.asreml is used to estimate the variance matrix for the observations from the variance parameter estimates from the reduced.asreml.obj.
extra.matrix	A matrix of order equal to the number of observations that is to be added to the variance matrix, the latter based on the information in asreml.obj. It is assumed that the sigma-parameterized values of the variance parameter estimates, such as is given in the varcomp component of summary.asreml, have been used in calculating extra.matrix; the values in the vparameters component of G.param and R.param may be either gamma- or sigma-parameterized. The argument extra.matrix can be used in conjunction with ignore.terms as a workaround to include components of the variance matrix for variance functions that have not been implemented in estimateV.
ignore.terms	A character giving terms from either the random or residual models that are to be ignored in that their contributions to the variance is not to be included in the estimated matrix. The term names are those given in the vparameters component of the asreml object or the varcomp component produced by summary.asreml, but only up to the first exclamation mark (!). This can be used in conjunction with estimateV.asreml as a workaround to include components of the variance matrix for variance functions that have not been implemented in estimateV.
fixed.spline.terms	A character vector giving one or more spline terms in the random model that are regarded as fixed and so are to be ignored because they are not regarded as contributing to the variance. The term names are those given in the vparameters component of the asreml object or the varcomp component produced by summary.asreml, but only up to the first exclamation mark (!).
bound.exclusions	A character specifying one or more bound codes that will result in a variance parameter in the random model being excluded from contributing to the variance. If set to NULL then none will be excluded.
tolerance	The value such that eigenvalues less than it are considered to be zero.
update	If TRUE then the arguments R.param and G.param are set to those in the asreml object supplied in object so that the values from the original model are used as starting values. If FALSE then asreml calls are evaluated, the only changes from the previous call being that (i) the model is fitted to simulated data and (ii) modifications specified via ... are mode, except that changes cannot be made to any of the models.
trace	If TRUE then partial iteration details are displayed when ASReml-R functions are invoked; if FALSE then no output is displayed.
ncores	A numeric specifying the number of cores to use in doing the simulations. In choosing a value for ncores, it is necessary to take into account other processes that are using parallel processing at the same time.
...	Other arguments that are passed down to the function asreml. Changes to the models are not allowed. Other changes are dangerous and generally should be avoided.

Value

A list with the following components:

1. REMLRT: the observed REML ratio statistic.

2. p: the bootstrap p-value for the observed test statistic.

3. DF: the calculated difference in DF for the variance parameters in the two models.

4. totalunconverged: the total number of unconverged analyses over the simulations.

5. REMLRT.sim: a numeric containing the values of the ratio statistics for the simulated data. It has an attribute called na.action that can be retrieved using attr(REMLRT.sim, which = "na.action"); it contains a list of the simulation numbers that were abandoned because max.retries failed to converge for both models.

6. nunconverged: the number of unconverged analyses for each bootstrap sample, the maximum being max.retries.

Note

A bootstrap sample is generated using a multivariate normal distribution with expected value as specified by means and variance matrix given by V. Each simulated sample is analysed according to the reduced model and, provided this analysis converges, according to the full.model. If one of these analyses fails to converge, it is abandoned and another sample is generated for this simulation. As many as max.retries attempts are made to generate a data set for which both analyses converge. If data set that converges for both analyses is not generated for a simulation, NA is returned for that bootstrap sample. Hence, the maximum number of data sets that will be generated is nboot * max.retries and less than nboot samples will be generated if a data set that converges for both analyses is not obtained within max.retries attempts.

If a bootstrap sample converges for both analyses, the REML ratio test statistic is calculated as 2(log(REML)_F - log(REML)_R).

The DF is calculated from the information in full.asreml.obj and reduced.asreml.obj. The degrees of freedom are computed as the difference between the two models in the number of variance parameters whose estimates do not have a code for bound specified in bound.exclusions.

If ASReml-R version 4 is being used then the codes specified in bound.exclusions are not restricted to a subset of the default codes, but a warning is issued if a code other than these is specified. For ASReml-R version 3, only a subset of the default codes are allowed: F (Fixed), B (Boundary), C (Constrained) and S (Singular).

Author(s)

Chris Brien

See Also

REMLRT.asreml, infoCriteria.asreml, newfit.asreml, testranfix.asrtests

Examples

## Not run: 
    bootREMLRT(ICV.max, ICV.red, ncores = parallel::detectCores())

## End(Not run)

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