OpenMx (version 2.7.9)

mxFitFunctionGREML:

Description

This function creates a new MxFitFunctionGREML object.

Usage

mxFitFunctionGREML(dV=character(0), aug=character(0),
   augGrad=character(0), augHess=character(0))

Arguments

dV

Vector of character strings; defaults to a character vector of length zero. If a value of non-zero length is provided, it must be a named character vector. This vector's names must be the labels of each free parameter in the model. The vector's elements (i.e., the character strings themselves) must be the names of MxAlgebra or MxMatrix object(s), each of which equals the first partial derivative of the 'V' matrix with respect to the corresponding free parameter.

aug

Character string; defaults to a character vector of length zero. Any elements after the first are ignored. The string should name a 1x1 MxMatrix or an MxAlgebra that evaluates to a 1x1 matrix. The named object will be used as an "augmentation" to the GREML fitfunction--specifically, the [1,1] value of the object named by aug will be added to the GREML fitfunction value at each function evaluation during optimization. The augmentation can be used to regularize estimation with a prior likelihood, or to use penalty functions to approximate constraints.

augGrad

Character string; defaults to a character vector of length zero. Any elements after the first are ignored. The string should name a MxMatrix or an MxAlgebra that evaluates to the gradient of aug with respect to free parameters. The gradient can be either a column or row vector. The free parameters corresponding to the elements of the gradient vector are taken from the names of argument dV, e.g. if the third name of dV is 'va', then the third element of the gradient vector should be the first partial derivative of the augmentation function with respect to 'va'. Ignored unless both dV and aug have nonzero length.

augHess

Character string; defaults to a character vector of length zero. Any elements after the first are ignored. The string should name a MxMatrix or an MxAlgebra that evaluates to the Hessian of aug with respect to free parameters. The free parameters corresponding to each row and column of this matrix are dictated by the names of argument dV, in the same manner as for the elements of augGrad. Ignored unless both dV and aug have nonzero length. Providing a nonzero-length value for augHess but not augGrad will result in an error at runtime.

Value

Returns a new object of class MxFitFunctionGREML.

Details

Making effective use of arguments dV, augGrad, and augHess will usually require a custom mxComputeSequence(). The derivatives of the REML loglikelihood function with respect to parameters can be internally computed from the derivatives of the 'V' matrix supplied via dV. These loglikelihood derivatives will be valid as long as (1) the derivatives of 'V' evaluate to symmetric matrices the same size as 'V,' and (2) the model contains no MxConstraints. Internally, the derivatives of the 'V' matrix are assumed to be symmetric, and the elements above their main diagonals are ignored. Currently, if any derivatives are provided via dV, then derivatives must be provided for every free parameter in the MxModel. Argument aug is intended to allow users to provide penalty functions or prior likelihoods in order to approximate constraints or to regularize optimization. The user is warned that careless use of this augmentation feature may undermine the validity of his/her statistical inferences.

References

The OpenMx User's guide can be found at http://openmx.ssri.psu.edu/documentation.

See Also

See MxFitFunctionGREML for the S4 class created by mxFitFunctionGREML(). For more information generally concerning GREML analyses, including a complete example, see mxExpectationGREML(). Other fit functions: mxFitFunctionMultigroup, mxFitFunctionML, mxFitFunctionWLS, mxFitFunctionAlgebra, mxFitFunctionR, mxFitFunctionRow More information about the OpenMx package may be found here.

Examples

gff <- mxFitFunctionGREML()
str(gff)