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

bootREMLRT.asreml {asremlPlus}

R Documentation

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:

REMLRT: the observed REML ratio statistic.
p: the bootstrap p-value for the observed test statistic.
DF: the calculated difference in DF for the variance parameters in the two models.
totalunconverged: the total number of unconverged analyses over the simulations.
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.
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

Examples

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

## End(Not run)

[Package asremlPlus version 4.4.32 Index]