OpenMx: mxAlgebra – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

mxAlgebra

Create MxAlgebra Object

Description

This function creates a new MxAlgebra. The common use is to compute a value in a model: for instance a standardized value of a parameter, or a parameter which is a function of other values. It is also used in models with an mxFitFunctionAlgebra objective function.

note: Unless needed in the model objective, algebras are only computed twice: once at the beginning and once at the end of running a model, so adding them doesn't often add a lot of overhead.

Usage

mxAlgebra(expression, name = NA, dimnames = NA, ..., fixed = FALSE,
          joinKey=as.character(NA), joinModel=as.character(NA),
	verbose=0L, initial=matrix(as.numeric(NA),1,1),
        recompute=c('always','onDemand'))

Arguments

`expression`	An R expression of OpenMx-supported matrix operators and matrix functions.
`name`	An optional character string indicating the name of the object.
`dimnames`	list. The dimnames attribute for the algebra: a list of length 2 giving the row and column names respectively. An empty list is treated as NULL, and a list of length one as row names. The list can be named, and the list names will be used as names for the dimensions.
`...`	Not used. Forces other arguments to be specified by name.
`fixed`	Deprecated. Use the ‘recompute’ argument instead.
`joinKey`	The name of the column in current model's raw data that is used as a foreign key to match against the primary key in the joinModel's raw data.
`joinModel`	The name of the model that this matrix joins against.
`verbose`	For values greater than zero, enable runtime diagnostics.
`initial`	a matrix. When `recompute='onDemand'`, you must provide this initial algebra result.
`recompute`	If ‘onDemand’, this algebra will not be recomputed automatically when things it depends on change. mxComputeOnce can be used to force it to recompute.

Details

The mxAlgebra function is used to create algebraic expressions that operate on one or more MxMatrix objects. To evaluate an MxAlgebra object, it must be placed in an MxModel object, along with all referenced MxMatrix objects and the mxFitFunctionAlgebra function. The mxFitFunctionAlgebra function must reference by name the MxAlgebra object to be evaluated.

Note: f the result for an MxAlgebra depends upon one or more "definition variables" (see mxMatrix()), then the value returned after the call to mxRun() will be computed using the values of those definition variables in the first (i.e., first before any automated sorting is done) row of the raw dataset.

The following operators and functions are supported in mxAlgebra:

Operators

solve(): Inversion
t(): Transposition
^: Elementwise powering
%^%: Kronecker powering
+: Addition
-: Subtraction
%*%: Matrix Multiplication
*: Elementwise product
/: Elementwise division
%x%: Kronecker product
%&%: Quadratic product: pre- and post-multiply B by A and its transpose t(A), i.e: A %&% B == A %*% B %*% t(A)

Functions

cov2cor: Convert covariance matrix to correlation matrix
chol: Cholesky Decomposition
cbind: Horizontal adhesion
rbind: Vertical adhesion
colSums: Matrix column sums as a column vector
rowSums: Matrix row sums as a column vector
det: Determinant
tr: Trace
sum: Sum
mean: Arithmetic mean
prod: Product
max: Maximum
min: Min
abs: Absolute value
sin: Sine
sinh: Hyperbolic sine
asin: Arcsine
asinh: Inverse hyperbolic sine
cos: Cosine
cosh: Hyperbolic cosine
acos: Arccosine
acosh: Inverse hyperbolic cosine
tan: Tangent
tanh: Hyperbolic tangent
atan: Arctangent
atanh: Inverse hyperbolic tangent
exp: Exponent
log: Natural Logarithm
mxRobustLog: Robust natural logarithm
sqrt: Square root
p2z: Standard-normal quantile
logp2z: Standard-normal quantile from log probabilities
lgamma: Log-gamma function
lgamma1p: Compute log(gamma(x+1)) accurately for small x
eigenval: Eigenvalues of a square matrix. Usage: eigenval(x); eigenvec(x); ieigenval(x); ieigenvec(x)
rvectorize: Vectorize by row
cvectorize: Vectorize by column
vech: Half-vectorization
vechs: Strict half-vectorization
vech2full: Inverse half-vectorization
vechs2full: Inverse strict half-vectorization
vec2diag: Create matrix from a diagonal vector (similar to diag)
diag2vec: Extract diagonal from matrix (similar to diag)
expm: Matrix Exponential
logm: Matrix Logarithm
omxExponential: Matrix Exponential
omxMnor: Multivariate Normal Integration
omxAllInt: All cells Multivariate Normal Integration
omxNot: Perform unary negation on a matrix
omxAnd: Perform binary and on two matrices
omxOr: Perform binary or on two matrices
omxGreaterThan: Perform binary greater on two matrices
omxLessThan: Perform binary less than on two matrices
omxApproxEquals: Perform binary equals to (within a specified epsilon) on two matrices
omxSelectRows: Filter rows from a matrix
omxSelectCols: Filter columns from a matrix
omxSelectRowsAndCols: Filter rows and columns from a matrix
mxEvaluateOnGrid: Evaluate an algebra on an abscissa grid and collect column results

If solve is used on an uninvertible square matrix in R, via mxEval(), it will fail with an error will; if solve is used on an uninvertible square matrix during runtime, it will fail silently.

mxRobustLog is the same as log except that it returns -745 instead of -Inf for an argument of 0. The value -745 is less than log(4.94066e-324), a good approximation of negative infinity because the log of any number represented as a double will be of smaller absolute magnitude.

There are also several multi-argument functions usable in MxAlgebras, which apply themselves elementwise to the matrix provided as their first argument. These functions have slightly different usage from their R counterparts. Their result is always a matrix with the same dimensions as that provided for their first argument. Values must be provided for ALL arguments of these functions, in order. Provide zeroes as logical values of FALSE, and non-zero numerical values as logical values of TRUE. For most of these functions, OpenMx cycles over values of arguments other than the first, by column (i.e., in column-major order), to the length of the first argument. Notable exceptions are the log, log.p, and lower.tail arguments to probability-distribution-related functions, for which only the [1,1] element is used. It is recommended that all arguments after the first be either (1) scalars, or (2) matrices with the same dimensions as the first argument.

Function	Arguments	Notes
`besselI` & `besselK`	`x,nu,expon.scaled`	Note that OpenMx does cycle over the elements of `expon.scaled`.
`besselJ` & `besselY`	`x,nu`
`dbeta`	`x,shape1,shape2,ncp,log`	The algorithm for the non-central beta distribution is used for non-negative values of `ncp`. Negative `ncp` values are ignored, and the algorithm for the central beta distribution is used.
`pbeta`	`q,shape1,shape2,ncp,lower.tail,log.p`	Values of `ncp` are handled as with `dbeta()`.
`dbinom`	`x,size,prob,log`
`pbinom`	`q,size,prob,lower.tail,log.p`
`dcauchy`	`x,location,scale,log`
`pcauchy`	`q,location,scale,lower.tail,log.p`
`dchisq`	`x,df,ncp,log`	The algorithm for the non-central chi-square distribution is used for non-negative values of `ncp`. Negative `ncp` values are ignored, and the algorithm for the central chi-square distribution is used.
`pchisq`	`q,df,ncp,lower.tail,log.p`	Values of `ncp` are handled as with `dchisq()`.
`omxDnbinom`	`x,size,prob,mu,log`	Exactly one of arguments `size`, `prob`, and `mu` should be negative, and therefore ignored. Otherwise, `mu` is ignored, possibly with a warning, and the values of `size` and `prob` are used, irrespective of whether they are in the parameter space. If only `prob` is negative, the algorithm for the alternative `size`-`mu` parameterization is used. If `size` is negative, a value for `size` is calculated as `mu*prob/(1-prob)`, and the algorithm for the `size`-`prob` parameterization is used (note that this approach is ill-advised when `prob` is very close to 0 or 1).
`omxPnbinom`	`q,size,prob,mu,lower.tail,log.p`	Arguments are handled as with `omxDnbinom()`.
`dpois`	`x,lambda,log`
`ppois`	`q,lambda,lower.tail,log.p`

Value

Returns a new MxAlgebra object.

References

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

Examples

A <- mxMatrix("Full", nrow = 3, ncol = 3, values=2, name = "A")

# Simple example: algebra B simply evaluates to the matrix A
B <- mxAlgebra(A, name = "B")

# Compute A + B
C <- mxAlgebra(A + B, name = "C")

# Compute sin(C)
D <- mxAlgebra(sin(C), name = "D")

# Make a model and evaluate the mxAlgebra object 'D'
A <- mxMatrix("Full", nrow = 3, ncol = 3, values=2, name = "A")
model <- mxModel(model="AlgebraExample", A, B, C, D )
fit   <- mxRun(model)
mxEval(D, fit)


# Numbers in mxAlgebras are upgraded to 1x1 matrices
# Example of Kronecker powering (%^%) and multiplication (%*%)
A  <- mxMatrix(type="Full", nrow=3, ncol=3, value=c(1:9), name="A")
m1 <- mxModel(model="kron", A, mxAlgebra(A %^% 2, name="KroneckerPower"))
mxRun(m1)$KroneckerPower

# Running kron 
# mxAlgebra 'KroneckerPower' 
# $formula:  A %^% 2 
# $result:
#      [,1] [,2] [,3]
# [1,]    1   16   49
# [2,]    4   25   64
# [3,]    9   36   81

OpenMx

Extended Structural Equation Modelling

v2.19.5

Apache License (== 2.0)

Authors

Steven M. Boker [aut], Michael C. Neale [aut], Hermine H. Maes [aut], Michael J. Wilde [ctb], Michael Spiegel [aut], Timothy R. Brick [aut], Ryne Estabrook [aut], Timothy C. Bates [aut], Paras Mehta [ctb], Timo von Oertzen [ctb], Ross J. Gore [aut], Michael D. Hunter [aut], Daniel C. Hackett [ctb], Julian Karch [ctb], Andreas M. Brandmaier [ctb], Joshua N. Pritikin [aut, cre], Mahsa Zahery [aut], Robert M. Kirkpatrick [aut], Yang Wang [ctb], Ben Goodrich [ctb], Charles Driver [ctb], Massachusetts Institute of Technology [cph], S. G. Johnson [cph], Association for Computing Machinery [cph], Dieter Kraft [cph], Stefan Wilhelm [cph], Sarah Medland [cph], Carl F. Falk [cph], Matt Keller [cph], Manjunath B G [cph], The Regents of the University of California [cph], Lester Ingber [cph], Wong Shao Voon [cph], Juan Palacios [cph], Jiang Yang [cph], Gael Guennebaud [cph], Jitse Niesen [cph]

Initial release

2021-03-26