mxAlgebra: Create MxAlgebra Object

In OpenMx: Extended Structural Equation Modelling

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

mpinv

Moore-Penrose Inverse

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 https://openmx.ssri.psu.edu/documentation/.

See Also

MxAlgebra for the S4 class created by mxAlgebra. mxFitFunctionAlgebra for an objective function which takes an MxAlgebra or MxMatrix object as the function to be minimized. MxMatrix and mxMatrix for objects which may be entered in the expression argument and the function that creates them. More information about the OpenMx package may be found here.

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 documentation built on Oct. 19, 2024, 9:06 a.m.