Added documentation for omxCbind(), omxRbind(), and omxTranspose()
[openmx:openmx.git] / man / mxRowObjective.Rd
1 %
2 %   Copyright 2007-2012 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 % Author: Michael D. Hunter
17 % Revision History
18 %   Fri Oct 8 15:56:13 EDT 2010 - Created file
19 %                                 Modified from mxFIMLObjective.Rd
20
21
22 \name{mxRowObjective}
23 \alias{mxRowObjective}
24
25 \title{Create MxRowObjective Object}
26
27 \description{
28    This function creates a new MxRowObjective object.
29 }
30
31 \usage{
32 mxRowObjective(rowAlgebra, reduceAlgebra, dimnames,
33    rowResults = "rowResults", filteredDataRow = "filteredDataRow",
34    existenceVector = "existenceVector")
35 }
36
37
38 \arguments{
39    \item{rowAlgebra}{A character string indicating the name of the algebra to be evaluated row-wise.}
40    \item{reduceAlgebra}{A character string indicating the name of the algebra that collapses the row results into a single number which is then optimized.}
41    \item{dimnames}{A character vector of names corresponding to columns be extracted from the data set.}
42    \item{rowResults}{The name of the auto-generated "rowResults" matrix.  See details.}
43    \item{filteredDataRow}{The name of the auto-generated "filteredDataRow" matrix. See details.}
44    \item{existenceVector}{The name of the auto-generated "existenceVector" matrix. See details.}
45 }
46
47 \details{
48 Objective functions are functions for which free parameter values are chosen such that the value of the objective function is minimized. The mxRowObjective function evaluates a user-defined \link{MxAlgebra} object called the \sQuote{rowAlgebra} in a row-wise fashion.  It then stores results of the row-wise evaluation in another \link{MxAlgebra} object called the \sQuote{rowResults}.  Finally, the mxRowObjective function collapses the row results into a single number which is then used for optimization.  The \link{MxAlgebra} object named by the \sQuote{reduceAlgebra} collapses the row results into a single number.
49
50 The \sQuote{filteredDataRow} is populated in a row-by-row fashion with all the non-missing data from the current row.  You cannot assume that the length of the filteredDataRow matrix remains constant (unless you have no missing data). The \sQuote{existenceVector} is populated in a row-by-row fashion with a value of 1.0 in column j if a non-missing value is present in the data set in column j, and a value of 0.0 otherwise. Use the functions \link{omxSelectRows}, \link{omxSelectCols}, and \link{omxSelectRowsAndCols} to shrink other matrices so that their dimensions will be conformable to the size of \sQuote{filteredDataRow}. 
51 }
52
53 \value{
54 Returns a new MxRowObjective object. MxRowObjective objects should be included with models with referenced \link{MxAlgebra} objects.
55 }
56
57 \references{
58 The OpenMx User's guide can be found at http://openmx.psyc.virginia.edu/documentation.
59 }
60
61 \examples{
62
63 # Model that adds two data columns row-wise, then sums that column
64 # Notice no optimization is performed here.
65 xdat <- data.frame(a=rnorm(10), b=1:10) # Make data set
66 amod <- mxModel(
67                     mxData(observed=xdat, type='raw'),
68                     mxAlgebra(sum(filteredDataRow), name = 'rowAlgebra'),
69                     mxAlgebra(sum(rowResults), name = 'reduceAlgebra'),
70                     mxRowObjective(
71                             rowAlgebra='rowAlgebra',
72                             reduceAlgebra='reduceAlgebra',
73                             dimnames=c('a','b'))
74 )
75
76 # Model that find the parameter that minimizes the sum of the
77 #  squared difference between the parameter and a data row.
78 bmod <- mxModel(
79                     mxData(observed=xdat, type='raw'),
80                     mxMatrix(values=.75, ncol=1, nrow=1, free=TRUE, name='B'),
81                     mxAlgebra((filteredDataRow - B) ^ 2, name='rowAlgebra'),
82                     mxAlgebra(sum(rowResults), name='reduceAlgebra'),
83                     mxRowObjective(
84                             rowAlgebra='rowAlgebra',
85                             reduceAlgebra='reduceAlgebra',
86                             dimnames=c('a'))
87 )
88
89
90 }