R: Tests for a single fixed or random term in model fitted using...

testranfix.asrtests {asremlPlus}

R Documentation

Tests for a single fixed or random term in model fitted using `asreml` and records the result in an `asrtests.object`.

Description

Tests for a single term, using a REML ratio test (REMLRT) for a random term or based on Wald statistics for a fixed term. The term must be in the fitted model. A random term is removed from the model fit and a REMLRT is performed using REMLRT.asreml. It compares the fit of the model in asreml.obj and the newly fitted model without the term. If the newly fitted model is retained, any boundary terms are then removed using rmboundary.asrtests. For a fixed term, the probability of the Wald statistics is extracted from the pseudo-anova table produced by wald.asreml. If this is available in the asrtests.object, it is used; otherwise wald.asreml is called to add it to the asrtests.object. Whether nonsignificant terms are dropped is controlled by drop.ran.ns for random terms and drop.fix.ns for fixed terms. A row is added to the test.summary data.frame for the term that is tested.

Usage

## S3 method for class 'asrtests'
testranfix(asrtests.obj, term=NULL, alpha = 0.05, 
           allow.unconverged = TRUE, allow.fixedcorrelation = TRUE, 
           checkboundaryonly = FALSE, 
           drop.ran.ns = TRUE, positive.zero = FALSE, 
           bound.test.parameters = "none", 
           bound.exclusions = c("F","B","S","C"), REMLDF = NULL, 
           drop.fix.ns = FALSE, denDF="numeric", dDF.na = "none", 
           dDF.values = NULL, IClikelihood = "none", 
           trace = FALSE, update = TRUE,
           set.terms = NULL, ignore.suffices = TRUE, 
           bounds = "P", initial.values = NA, ...)

Arguments

`asrtests.obj`	An `asrtests.object` containing the components (i) `asreml.obj`, (ii) `wald.tab`, and (iii) `test.summary`.
`term`	A single model term that is valid in `asreml`, stored as a `character`. The names of fixed terms must match those in the `wald.tab` component of the `asrtests.obj`, while the names of random terms must match those in the `vparameters` component of the `asreml.obj` component in the `asrtests.obj`.
`alpha`	The significance level for the test.
`allow.unconverged`	A `logical` indicating whether to accept a new model even when it does not converge. If `FALSE`, it will be checked whether convergence can be achieved with the removal of any boundary random terms; random terms will be retested if terms are removed. Also, if `FALSE` and the fit of the new model has converged, but that of the old model has not, the new model will be accepted.
`allow.fixedcorrelation`	A `logical` indicating whether to accept a new model even when it contains correlations in the model whose values have been designated as fixed, bound or singular. If `FALSE` and the new model contains correlations whose values have not been able to be estimated, the supplied `asrtests.obj` is returned. The fit in the `asreml.obj` component of the supplied `asrtests.obj` will also be tested and a warning issued if both fixed correlations are found in it and `allow.fixedcorrelation` is `FALSE`.
`checkboundaryonly`	If `TRUE` then boundary and singular terms are not removed by `rmboundary.asrtests`; a warning is issued instead.
`drop.ran.ns`	A `logical` indicating whether to drop a random term from the model when it is nonsignificant. Note that multiple terms specified using a single `asreml::at` function will only be dropped as a whole. If the term was specified using an `asreml::at` function with a single level, then it can be removed and either the level itself or its `numeric` position in the levels returned by the `levels` function can be specified in `term`.
`positive.zero`	Indicates whether the hypothesized values for the variance components being tested are on the boundary of the parameter space. For example, this is true for positively-constrained variance components that, under the reduced model, are zero. This argument does not need to be set if `bound.test.parameters` is set.
`bound.test.parameters`	Indicates whether for the variance components being tested, at least some of the hypothesized values are on the boundary of the parameter space. The possibilities are `"none"`, `"onlybound"` and `"one-and-one"`. The default is `"none"`, although if it is set to `"none"` and `positive.zero` is `TRUE` then `bound.test.parameters` is taken to be `"onlybound"`. When `bound.test.parameters` is set to `"one-and-one"`, it signifies that there are two parameters being tested, one of which is bound and the other is not. For example, the latter is true for testing a covariance and a positively-constrained variance component that, under the reduced model, are zero.
`bound.exclusions`	A `character` specifying one or more bound (constraint) codes that will result in a variance parameter being excluded from the count of estimated variance parameters in using `REMLRT.asreml`. If set to `NULL` then none will be excluded.
`REMLDF`	A `numeric` giving the difference in the number of variance parameters whose estimates are not of the type specified in `bound.exclusions` for two models being compared in a REML ratio test using `REMLRT.asreml`. If `NULL` then this is determined from the information in the `asreml` object for the two models.
`drop.fix.ns`	A `logical` indicating whether to drop a fixed term from the model when it is nonsignificant. Note that multiple terms specified using a single `asreml::at` function can only be dropped as a whole. If the term was specified using an `asreml::at` function with a single level, then it can be removed and either the level itself or its `numeric` position in the levels returned by the `levels` function can be specified.
`denDF`	Specifies the method to use in computing approximate denominator degrees of freedom when `wald.asreml` is called. Can be `none` to suppress the computations, `numeric` for numerical methods, `algebraic` for algebraic methods or `default`, the default, to autommatically choose numeric or algebraic computations depending on problem size. The denominator degrees of freedom are calculated according to Kenward and Roger (1997) for fixed terms in the dense part of the model.
`dDF.na`	The method to use to obtain substitute denominator degrees of freedom. when the numeric or algebraic methods produce an `NA`. If `dDF.na = "none"`, no subtitute denominator degrees of freedom are employed; if `dDF.na = "residual"`, the residual degrees of freedom from `asreml.obj$nedf` are used; 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`.
`IClikelihood`	A `character` that controls both the occurence and the type of likelihood for information criterion in the `test.summary` of the new `asrtests.object`. If `none`, none are included. Otherwise, if `REML` and `family` is set to `asr_guassian` (the default), then the AIC and BIC based on the Restricted Maximum Likelihood are included; if `full` and `family` is set to `asr_guassian`, then the AIC and BIC based on the full likelihood, evaluated using REML estimates, are included. If `family` is `asr_binomial` or `asr_poisson`, with `dispersion` set to 1, the `deviance` is extracted from `object` and used to calculate the AIC and BIC. (See also `infoCriteria.asreml`.)
`trace`	If TRUE then partial iteration details are displayed when ASReml-R functions are invoked; if FALSE then no output is displayed.
`update`	If `TRUE`, and `set.terms` is `NULL`, then `newfit.asreml` is called to fit the model to be tested, using the values of the variance parameters stored in the `asreml.object`, that is stored in `asrtests.obj`, as starting values. If `FALSE` or `set.terms` is not `NULL`, then `newfit.asreml` will not use the stored variance parameter values as starting values when fitting the new model, the only modifications being (i) those for the supplied `terms` and (ii) those specified via `...`.
`set.terms`	A character vector specifying the terms that are to have bounds and/or initial values set prior to fitting. The names must match those in the `vparameters` component of the `asreml.obj` component in the new `asrtests.object`.
`ignore.suffices`	A logical vector specifying whether the suffices of the `asreml`-assigned names of the variance terms (i.e. the information to the right of an "!", other than "R!") is to be ignored in matching elements of `terms`. If `TRUE` for an element of `terms`, the suffices are stripped from the `asreml`-assigned names. If `FALSE` for an element of `terms`, the element must exactly match an `asreml`-assigned name for a variance term. This vector must be of length one or the same length as `terms`. If it is of length one then the same action is applied to the `asreml`-assigned suffices for all the terms in `terms`.
`bounds`	A `character` vector specifying the bounds to be applied to the terms specified in `set.terms`. This vector must be of length one or the same length as `set.terms`. If it is of length one then the same constraint is applied to all the terms in `set.terms`. If any of the bounds are equal to NA then they are left unchanged for those terms.
`initial.values`	A character vector specifying the initial values for the terms specified in `terms`. This vector must be of length one or the same length as `terms`. If it is of length one then the same initial value is applied to all the terms in `terms`. If any of the initial.values are equal to NA then they are left unchanged for those terms.
`...`	Further arguments passed to `asreml`, `wald.asreml` and `as.asrtests`.

Value

An asrtests.object containing the components (i) asreml.obj, (ii) wald.tab, and (iii) test.summary. If the term is not in the model, then the supplied asreml object will be returned. Also, reml.test will have the likelihood ratio and the p-value set to NA and the degrees of freedom to zero. Similarly, the row of test.summary for the term will have its name, DF set to NA, p-value set to NA, and action set to Absent.

Author(s)

Chris Brien

References

Kenward, M. G., & Roger, J. H. (1997). Small sample inference for fixed effects from restricted maximum likelihood. Biometrics, 53, 983-997.

Examples

## Not run: 
data(Wheat.dat)
current.asr <- asreml(yield ~ Rep + WithinColPairs + Variety, 
                      random = ~ Row + Column + units,
                      residual = ~ ar1(Row):ar1(Column), 
                      data=Wheat.dat)
current.asrt <- as.asrtests(current.asr, NULL, NULL)
current.asrt <- rmboundary(current.asrt)
# Test nugget term
current.asrt <- testranfix(current.asrt, "units", positive=TRUE)

## End(Not run)

[Package asremlPlus version 4.4.32 Index]

Tests for a single fixed or random term in model fitted using asreml and records the result in an asrtests.object.