R: Uses information criteria to decide whether to change an...

changeModelOnIC.asrtests {asremlPlus}

R Documentation

Uses information criteria to decide whether to change an already fitted model.

Description

Uses information criteria to decide whether to change the fitted model stored in the supplied asrtests.object according to the specified modifications. The function changeTerms is used to change the model. Thus, the model can be modified using a combination of adding and removing sets of terms from one or both of the fixed or random models, replacing the residual model and changing the bounds and/or initial values of some terms. The model will be unchanged if terms specified in dropFixed or dropRandom are not in the fitted model.

A row is added to the test.summary data.frame of the asrtests.object using the supplied label and stating whether or not the new model has been swapped for the supplied model. Convergence in fitting the model is checked and a note included in the action if there was not. All components of the asrtests.object are updated to exhibit the differences between the supplied and new models.

To obtain a list of the information criteria for a set of models use changeTerms.asrtests with IClikelihood set to REML or full, or use infoCriteria.asreml.

Usage

## S3 method for class 'asrtests'
changeModelOnIC(asrtests.obj, 
                dropFixed = NULL, addFixed = NULL, 
                dropRandom = NULL,  addRandom = NULL, 
                newResidual = NULL, label = "Changed terms", 
                allow.unconverged = TRUE, allow.fixedcorrelation = TRUE,
                checkboundaryonly = FALSE, 
                trace = FALSE, update = TRUE, denDF = "numeric", 
                set.terms = NULL, ignore.suffices = TRUE, 
                bounds = "P", initial.values = NA, 
                which.IC = "AIC", IClikelihood = "REML", 
                fixedDF = NULL, varDF = NULL, 
                bound.exclusions = c("F","B","S","C"), 
          ...)

Arguments

`asrtests.obj`	An `asrtests.object` containing the components (i) `asreml.obj`, (ii) `wald.tab`, and (iii) `test.summary`.
`dropFixed`	A single `character` string in the form of a formula which, after addition of `". ~ . -"` and after expansion, specifies the sum of a set of terms to be dropped from the fixed formula. The names must match those in the `wald.tab` component of the `asrtests.obj`. The fixed terms will be reordered so that single-variable terms come first, followed by two-variable terms and so on. 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.
`addFixed`	A single `character` string in the form of a formula which, after addition of `". ~ . +"` and expansion, specifies the sum of a set of terms to be added to the fixed formula. The fixed terms will be reordered so that single-variable terms come first, followed by two-variable terms and so on.
`dropRandom`	A single `character` string in the form of a formula which, after addition of `" ~ . -"` and expansion, specifies the sum of a set of terms to be dropped from the random formula. The names must match those in the `vparameters` component of the `asreml.obj` component in the `asrtests.obj`. 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.
`addRandom`	A single `character` string in the form of a formula which, after addition of `" ~ . +"`and expansion, specifies the sum of a set of terms to be added to the random formula.
`newResidual`	A single `character` string in the form of a formula which, after addition of `" ~ "`, specifies the `residual` (or `rcov`) model. To remove the model, enter `"-(.)"`.
`label`	A `character` to use as an entry in the `terms` column in `test.summary` to indicate as far as is possible the terms that are being manipulated.
`allow.unconverged`	A `logical` indicating whether to accept a new model even when it does not converge. If `FALSE` and the fit of the new model does not converge, the supplied `asrtests.obj` is returned. 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.
`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 specified by this function's arguments and (ii) those specified via `...`.
`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 automatically 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.
`set.terms`	A `character` vector specifying the terms that are to have bounds and/or initial values set prior to fitting the new model. The names must match those in the `vparameters` component of the `asreml.obj` component in the new `asrtests.object`. The terms in the model do not need to change from those in the model in the supplied `asrtests.obj`.
`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.
`which.IC`	A `character` specifying the information criterion to be used in selecting the best model. Possible values are `AIC` and `BIC`. The value of the criterion for supplied model must exceed that for changed model for the changed model to be returned.
`IClikelihood`	A `character` specifying whether Restricted Maximum Likelihood (`REML`) or the full likelihood, evaluated using REML estimates, (`full`) are to be used in calculating the information criteria for choosing between models when `family` is set to `asr_gaussian`. For `family` set to `asr_binomial` or `asr_poisson` and with `dispersion` set to 1, the `deviance` is extracted from `object` and used to calculate the AIC and BIC (as suggested by Damian Collins); the setting of `IClikelihood` is ignored and the log-likelihood set to `NA`. The information criteria are not valid for other settings of `family` and `dispersion`.
`fixedDF`	A `numeric` giving the number of estimated fixed parameters. If `NULL` then this is determined from the information in `asreml.obj`.
`varDF`	A `numeric` giving the number of estimated variance parameters. If `NULL` then this is determined from the information in `asreml.obj`. It replaces the `varDF` argument.
`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.
`bound.exclusions`	A `character` specifying the bound (constraint) codes that will result in a variance parameter being excluded from the count of estimated variance parameters in calculating the information criteria. If set to `NULL` then none will be excluded.
`...`	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. The values of the degrees of freedom and the information criteria are differences between those of the changed model and those of the model supplied to changeModelOnIC.

Author(s)

Chris Brien

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, 
                            label = "Maximal model")
current.asrt <- rmboundary(current.asrt)

# Drop both Row and Column terms
current.asrt <- changeModelOnIC(current.asrt, 
                                dropRandom = "Row + Column", 
                                checkboundaryonly = TRUE,
                                which.IC = "AIC", IClikelihood = "full")
current.asrt <- iterate(current.asrt)
                          
# Add and drop both fixed and random terms
current.asrt <- changeModelOnIC(current.asrt, 
                                addFixed = "vRow", dropFixed = "WithinColPairs", 
                                addRandom = "spl(vRow)", dropRandom = "units", 
                                checkboundaryonly = TRUE,
                                which.IC = "AIC", IClikelihood = "full")
                          
# Replace residual with model without Row autocorrelation
current.asrt <- changeModelOnIC(current.asrt, 
                                newResidual = "Row:ar1(Column)", 
                                label="Row autocorrelation",
                                IClikelihood = "full")


## End(Not run)

[Package asremlPlus version 4.4.35 Index]