Update references to mxFitFunctionAlgebra and correct dot multiplication explanation...
[openmx:openmx.git] / man / mxAlgebra.Rd
1 %
2 %   Copyright 2007-2014 The OpenMx Project
3 %
4 %   Licensed under the Apache License, Version 2.0 (the "License");
5 %   you may not use this file except in compliance with the License.
6 %   You may obtain a copy of the License at
7
8 %        http://www.apache.org/licenses/LICENSE-2.0
9
10 %   Unless required by applicable law or agreed to in writing, software
11 %   distributed under the License is distributed on an "AS IS" BASIS,
12 %   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 %   See the License for the specific language governing permissions and
14 %   limitations under the License.
15
16 \name{mxAlgebra}
17 \alias{mxAlgebra}
18
19 \title{Create MxAlgebra Object}
20
21 \description{
22    This function creates a new \link{MxAlgebra} object.
23 }
24
25 \usage{
26 mxAlgebra(expression, name = NA, dimnames = NA, fixed = FALSE)
27 }
28
29 \arguments{
30    \item{expression}{An R expression of OpenMx-supported matrix operators and matrix functions.}
31    \item{name}{An optional character string indicating the name of the object.}
32    \item{dimnames}{list. The dimnames attribute for the algebra: a list
33    of length 2 giving the row and column names respectively. An empty
34    list is treated as NULL, and a list of length one as row names. The
35    list can be named, and the list names will be used as names for the
36    dimensions.}
37    \item{fixed}{If TRUE, this algebra will not be recomputed
38      automatically when things it depends on change. \link{mxComputeOnce}
39      can be used to force it to recompute.}
40 }
41
42 \details{
43 The mxAlgebra function is used to create algebraic expressions that operate on one or more \link{MxMatrix} objects. To evaluate an \link{MxAlgebra} object, it must be placed in an \link{MxModel} object, along with all referenced \code{MxMatrix} objects and the \code{mxFitFunctionAlgebra} function. The \code{mxFitFunctionAlgebra} function must reference by name the \code{MxAlgebra} object to be evaluated.
44
45 The following operators and functions are supported in mxAlgebra:
46
47 Operators
48
49 \describe{
50 \item{\code{solve()}}{Inversion}
51 \item{\code{t()}}{Transposition}
52 \item{\code{^}}{Elementwise powering}
53 \item{\code{\%^\%}}{Kronecker powering}
54 \item{\code{+}}{Addition}
55 \item{\code{-}}{Subtraction}
56 \item{\code{\%*\%}}{Matrix Multiplication}
57 \item{\code{*}}{Element product}
58 \item{\code{/}}{Element division}
59 \item{\code{\%x\%}}{Kronecker product}
60 \item{\code{\%&\%}}{Quadratic product}
61 }
62
63 Functions
64
65 \describe{
66 \item{\code{cov2cor}}{Convert covariance matrix to correlation matrix}
67 \item{\code{chol}}{Cholesky Decomposition}
68 \item{\code{cbind}}{Horizontal adhesion}
69 \item{\code{rbind}}{Vertical adhesion}
70 \item{\code{det}}{Determinant}
71 \item{\code{tr}}{Trace}
72 \item{\code{sum}}{Sum}
73 \item{\code{prod}}{Product}
74 \item{\code{max}}{Maximum}
75 \item{\code{min}}{Min}
76 \item{\code{abs}}{Absolute value}
77 \item{\code{sin}}{Sine}
78 \item{\code{sinh}}{Hyperbolic sine}
79 \item{\code{cos}}{Cosine}
80 \item{\code{cosh}}{Hyperbolic cosine}
81 \item{\code{tan}}{Tangent}
82 \item{\code{tanh}}{Hyperbolic tangent}
83 \item{\code{exp}}{Exponent}
84 \item{\code{log}}{Natural Logarithm}
85 \item{\code{sqrt}}{Square root}
86 \item{\code{\link{eigenval}}}{Eigenvalues of a square matrix. Usage: eigenval(x); eigenvec(x); ieigenval(x); ieigenvec(x)}
87 \item{\code{\link{rvectorize}}}{Vectorize by row}
88 \item{\code{\link{cvectorize}}}{Vectorize by column}
89 \item{\code{\link{vech}}}{Half-vectorization}
90 \item{\code{\link{vechs}}}{Strict half-vectorization}
91 \item{\code{\link{vech2full}}}{Inverse half-vectorization}
92 \item{\code{\link{vechs2full}}}{Inverse strict half-vectorization}
93 \item{\code{\link{vec2diag}}}{Create matrix from a diagonal vector (similar to \link{diag}) }
94 \item{\code{\link{diag2vec}}}{Extract diagonal from matrix (similar to \link{diag}) }
95 \item{\code{\link{omxMnor}}}{Multivariate Normal Integration}
96 \item{\code{\link{omxAllInt}}}{All cells Multivariate Normal Integration}
97 \item{\code{\link{omxNot}}}{Perform unary negation on a matrix}
98 \item{\code{\link{omxAnd}}}{Perform binary and on two matrices}
99 \item{\code{\link{omxOr}}}{Perform binary or on two matrices}
100 \item{\code{\link{omxGreaterThan}}}{Perform binary greater on two matrices}
101 \item{\code{\link{omxLessThan}}}{Perform binary less than on two matrices}
102 \item{\code{\link{omxApproxEquals}}}{Perform binary equals to (within a specified epsilon) on two matrices}
103 \item{\code{omxExponential}}{Matrix Exponential}
104 }}
105
106 \value{
107     Returns a new \link{MxAlgebra} object.
108 }
109
110 \references{
111 The OpenMx User's guide can be found at http://openmx.psyc.virginia.edu/documentation.
112 }
113
114 \seealso{
115 \link{MxAlgebra} for the S4 class created by mxAlgebra. \link{mxFitFunctionAlgebra} for an objective function which takes an  MxAlgebra or MxMatrix object as the function to be minimized. 
116 \link{MxMatrix} and \link{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 \link[=OpenMx]{here}. 
117 }
118
119 \examples{
120
121 A <- mxMatrix("Full", nrow = 3, ncol = 3, values=2, name = "A")
122
123 # Simple example: algebra B simply evaluates to the matrix A
124 B <- mxAlgebra(A, name = "B")
125
126 # Compute A + B
127 C <- mxAlgebra(A + B, name = "C")
128
129 # Compute sin(C)
130 D <- mxAlgebra(sin(C), name = "D")
131
132 # Make a model and evaluate the mxAlgebra object 'D'
133 A <- mxMatrix("Full", nrow = 3, ncol = 3, values=2, name = "A")
134 model <- mxModel("AlgebraExample", A, B, C, D )
135 fit   <- mxRun(model)
136 mxEval(D, fit)
137
138
139 # Numbers in mxAlgebras are upgraded to 1x1 matrices
140 # Example of Kronecker powering (%^%) and multiplication (%*%)
141 A  <- mxMatrix(type="Full", nrow=3, ncol=3, value=c(1:9), name="A")
142 m1 <- mxModel("kron", A, mxAlgebra(A \%^\% 2, name="KroneckerPower"))
143 mxRun(m1)$KroneckerPower
144 # Running kron 
145 # mxAlgebra 'KroneckerPower' 
146 # @formula:  A %^% 2 
147 # @result:
148 #      [,1] [,2] [,3]
149 # [1,]    1   16   49
150 # [2,]    4   25   64
151 # [3,]    9   36   81
152
153 }