newfit.asreml: Refits an 'asreml' model with changed arguments by...

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

Refits an asreml model with changed arguments by extracting, modifying and evaluating its call - an alternate to update.asreml.

Description

Extracts the call from the asreml.obj and evaluates that call, replacing supplied asreml arguments with changed values. If update is TRUE and set.terms is NULL, the call is evaluated using the variance parameter estimates from the call stored in asreml.obj; if some variance terms in the newly fitted model are singular (S) or bound (B), a refit of the model will be tried in which the variance parameter estimates in asreml.obj are not used and will become the fitted model if its boundary terms are a subset of those in the fitted model stored in asreml.obj. If update is FALSE or set.terms is not NULL, the previous values of the variance parameters are not used as initial values for fitting the new model; G.param and R.param are set to NULL or to values as specified for set.terms. The ... argument can be used to pass G.param and/or R.param, provided update is FALSE and set.terms is NULL.

Irrespective of whether set.terms is NULL, variance parameter names, bounds and initial.values stored in the setvparameters data.frame located in the call component of the asreml.obj are added to any set.terms supplied in the current call. except for those in setvparameters that are specified in the set.terms argument. In the process of fitting the model, the setvparameters data.frame stored in the supplied asreml.obj is updated to include the prior and current set.terms. Then, just before exiting newfit.asreml, a search for changes in the bounds of the stored terms is made. If any have changed, an attempt is made to force the values back to their values on entry.

Usage

## S3 method for class 'asreml'
newfit(asreml.obj, fixed., random., sparse., 
       residual., rcov., update = TRUE, trace = FALSE, 
       allow.unconverged = TRUE, allow.fixedcorrelation = TRUE,
       keep.order = TRUE, 
       set.terms = NULL, ignore.suffices = TRUE, 
       bounds = "P", initial.values = NA, ...)

Arguments

asreml.obj	A valid asreml object with a component named call (from a previous call to either asreml or update.asreml).
fixed.	A character or formula specifying changes to the fixed formula. This is a two-sided formula where "." is substituted for existing components in the fixed component of asreml.obj$call. If changes are specified, the fixed terms will be reordered so that single-variable terms come first, followed by two-variable terms and so on.
random.	A character or formula specifying changes to the random formula. This is a one-sided formula where "." is substituted for existing components in the random component of asreml.obj$call.
sparse.	A character or formula specifying changes to the sparse formula. This is a one-sided formula where "." is substituted for existing components in the sparse component of asreml.obj$call.
residual.	A character or formula specifying changes to the error formula, used when version 4 or later of ASReml-R is loaded. This is a one-sided formula where "." is substituted for existing components in the residual component of asreml.obj$call.
rcov.	A character or formula specifying changes to the error formula, used when version 3 of ASReml-R is loaded. This is a one-sided formula where "." is substituted for existing components in the residual component of asreml.obj$call.
update	A logical indicating whether to use the variance parameter estimates in fitting a new model using newfit.asreml. If update is TRUE and set.terms is NULL, the call stored in the asreml.obj is evaluated using the variance parameter estimates stored in R.param and G.param, as well as the changes specified in the arguments to newfit.asreml. If FALSE or set.terms is not NULL, then the use of previous values of the variance parameters as initial values is not enforced; G.param and R.param are set to NULL or to values as specified for set.terms.
trace	A logical that control output from ASReml-R. If TRUE then partial iteration details are displayed when ASReml-R functions are invoked; if FALSE then no output is displayed.
allow.unconverged	A logical indicating whether to accept a new model even when it does not converge. If FALSE and the fit does not converge, the supplied asreml.obj is returned.
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 asreml.obj is returned. The fit in the supplied the asreml.obj will also be tested and a warning issued if both fixed correlations are found in it and allow.fixedcorrelation is FALSE.
keep.order	A logical value indicating whether the terms should keep their positions. If FALSE the terms are reordered so that main effects come first, followed by the interactions, all second-order, all third-order and so on. Effects of a given order are kept in the order specified.
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 new asreml.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.
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.
...	additional arguments to the call, or arguments with changed values.

Value

An asreml object.

Author(s)

Chris Brien

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

convAsremlobj.asreml, update.asreml, setvarianceterms.call

Examples

## Not run: 
    m2.asreml <- newfit(m1.asreml, random. = "~ . - Blocks:Plots", maxiter=75)

## End(Not run)

asremlPlus documentation built on April 12, 2025, 1:23 a.m.