setvarianceterms.call: allows the setting of bounds and initial values for terms in...

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

allows the setting of bounds and initial values for terms in the random and residual arguments of an asreml call, with the resulting call being evaluated.

Description

Takes an unevaluated call and evaluates the call after setting the bounds and initial values for the terms specified in terms. The elements of terms are matched with those generated by asreml and used, for example, in the varcomp component of a summary.asreml object. These names generally include descriptive suffices. To match an element of terms that includes such a suffix, set ignore.suffices to FALSE so that a literal match between the element and the assigned names is sought.

Note that the terms, bounds and initial.values are stored on entry in a data.frame, named setvparameters, as a component in call that is itself a component of the asreml.obj that is returned. The data.frame setvparameters contains all of the values of terms, ignore.suffices, bounds and initial.values that have been set in this and previous calls to setvarianceterms.call and other model modification and selection functions in asremlPlus, for example changeModelOnIC.asrtests, testranfix.asrtests and changeTerms.asrtests. It is used in subsequent calls to model modification and selection functions to ensure that the bounds and initial values that have been set are retained in new model fits.

Usage

## S3 method for class 'call'
setvarianceterms(call, terms, ignore.suffices = TRUE, 
                 bounds = "P", initial.values = NA, ...)

Arguments

call	an unevaluated call to asreml. One way to create such a call is to use the call function with its name argument set to "asreml". Another is to obtain it from the call component of an asreml object (e.g. call <- asreml.obj$call).
terms	A character vector specifying the terms that are to have bounds and/or initial values specified. The names must match those in the vparameters component of the asreml.obj component in the 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 terms. This vector must be of length one or the same length as terms. If it is of length one then the same constraint is applied to all the terms in terms. If any of the bounds are equal to NA then they are left unchanged for those terms. The codes used by ASReml are: B - fixed at a boundary; F - fixed by the user; P - positive definite; C - Constrained by user; U - unbounded.
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 be added to the asreml call, or arguments in the asreml call with changed values.

Value

An asreml object, with the updated setvparameters data.frame, stored in the call component of the 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

newfit.asreml, update.asreml

Examples

## Not run: 
   m1.call <- call("asreml", 
                   fixed = Height ~ (Block + Irrig)*csDay.num,
                   random= ~ spl(csDay.num)/(Irrig+Block)
                             + dev(csDay.num)
                             + str(~Block:Plot/csDay.num, ~us(2):id(20)) 
                             + Block:Plot:spl(csDay.num),
                   data=quote(dat)) ##use quote to stop evaluation of dat here 
   terms <- c("Block:Plot+Block:Plot:csDay.num!us(2).2:1", "R!variance")
   m1.asreml <- setvarianceterms(m1.call, terms, bounds=c("U","P"), 
                                 initial=c(NA,3), ignore.suffices=c(FALSE,TRUE))
   summary(m1.asreml)

## End(Not run)

asremlPlus documentation built on Aug. 21, 2025, 5:58 p.m.