OpenMx (version 2.7.9)

mxConstraint: Create MxConstraint Object

Description

This function creates a new MxConstraint object.

Usage

mxConstraint(expression, name=NA, ..., jac=character(0))

Arguments

expression

The MxAlgebra-like expression representing the constraint function.

name

An optional character string indicating the name of the object.

...

Not used. Helps OpenMx catch bad input to argument expression, and requires argument jac--meant for advanced users--to be specified by name.

jac

An optional character string naming the MxAlgebra or MxMatrix representing the Jacobian for the constraint function.

Value

Returns an MxConstraint object.

Details

The mxConstraint() function defines relationships between two MxAlgebra or MxMatrix objects. They are used to affect the estimation of free parameters in the referenced objects. The constraint relation is written identically to how a MxAlgebra expression would be written. The outermost operator in this relation must be either ‘<’, ‘==’ or ‘>’. To affect an estimation or optimization, an MxConstraint object must be included in an MxModel object with all referenced MxAlgebra and MxMatrix objects. Usage Note: Use of mxConstraint() should be avoided where it is possible to achieve the constraint by equating free parameters by label or position in an MxMatrix or MxAlgebra object. Including mxConstraints in an mxModel will disable standard errors and the calculation of the final Hessian, and thus should be avoided when standard errors are of importance. Constraints also add computational overhead. If one labels two parameters the same, the optimizer has one fewer parameter to optimize. However, if one uses mxConstraint to do the same thing, both parameters remain estimated and a Lagrangian multiplier is added to maintain the constraint. This constraint also has to have its gradients computed and the order of the Hessian grows as well. So while both approaches should work, the mxConstraint() will take longer to do so. Alernatives to mxConstraints include using labels, lbound or ubound arguments or algebras. Free parameters in the same MxModel may be constrained to equality by giving them the same name in their respective 'labels' matrices. Similarly, parameters may be fixed to an individual element in a MxModel object or the result of an MxAlgebra object through labeling. For example, assigning a label of ``name[1,1]`` fixes the value of a parameter at the value in first row and first column of the matrix or algebra ``name``. The mxConstraint function should be used to enforce inequalities that cannot be conveyed using other methods. Argument jac is used to provide the name of an MxMatrix or MxAlgebra that equals the matrix of first derivatives--the Jacobian--of the constraint function with respect to the free parameters. Here, the "constraint function" refers to the constraint expression in canonical form, with an arbitrary matrix expression on the left-hand side of the comparator, and a matrix with the same dimensions, and constant with respect to free parameters (typically, a matrix of zeroes), on the right-hand side. The rows of the Jacobian correspond to elements of the matrix result of the right-hand side, in column-major order. Each row of the Jacobian is the vector of first partial derivatives, with respect to the free parameters of the MxModel, of its corresponding element. Each column of the Jacobian corresponds to a free parameter of the MxModel; each column must be named with the label of the corresponding free parameter. Only the gradient-descent optimizers NPSOL and SLSQP are able to take advantage of user-supplied Jacobians.

References

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

See Also

MxConstraint for the S4 class created by mxConstraint.

Examples

library(OpenMx)

#Create a constraint between MxMatrices 'A' and 'B'
constraint <- mxConstraint(A > B, name = 'AdominatesB')

# Constrain matrix 'K' to be equal to matrix 'limit'

model <- mxModel(model="con_test", 
    mxMatrix(type="Full", nrow=2, ncol=2, free=TRUE, name="K"),
    mxMatrix(type="Full", nrow=2, ncol=2, free=FALSE, name="limit", values=1:4),
    mxConstraint(K == limit, name = "Klimit_equality"), 
    mxAlgebra(min(K), name="minK"), 
    mxFitFunctionAlgebra("minK")
)

fit <- mxRun(model)
fit$matrices$K$values

#      [,1] [,2]
# [1,]    1    3
# [2,]    2    4

# Constrain both free parameters of a matrix to equality using labels (both are set to "eq")
equal <- mxMatrix("Full", 2, 1, free=TRUE, values=1, labels="eq", name="D")

# Constrain a matrix element in to be equal to the result of an algebra
start <- mxMatrix("Full", 1, 1, free=TRUE,  values=1, labels="param", name="F")
alg   <- mxAlgebra(log(start), name="logP")

# Force the fixed parameter in matrix G to be the result of the algebra
end   <- mxMatrix("Full", 1, 1, free=FALSE, values=1, labels="logP[1,1]", name="G")