Trying once again. Lots of updates to the help files.
[openmx:openmx.git] / man / mxRowObjective.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 % 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{DEPRECATED: Create MxRowObjective Object}
26
27 \description{
28 WARNING: Objective functions have been deprecated as of OpenMx 2.0.  
29    
30 Please use mxFitFunctionRow() instead.  As a temporary workaround, mxRowObjective returns a list containing a NULL MxExpectation object and an MxFitFunctionRow object.
31
32 All occurrences of
33
34 mxRowObjective(rowAlgebra, reduceAlgebra, dimnames,
35    rowResults = "rowResults", filteredDataRow = "filteredDataRow",
36    existenceVector = "existenceVector")
37
38 Should be changed to
39
40 mxFitFunctionRow(rowAlgebra, reduceAlgebra, dimnames,
41    rowResults = "rowResults", filteredDataRow = "filteredDataRow",
42    existenceVector = "existenceVector")
43 }
44
45
46 \arguments{
47    \item{rowAlgebra}{A character string indicating the name of the algebra to be evaluated row-wise.}
48    \item{reduceAlgebra}{A character string indicating the name of the algebra that collapses the row results into a single number which is then optimized.}
49    \item{dimnames}{A character vector of names corresponding to columns be extracted from the data set.}
50    \item{rowResults}{The name of the auto-generated "rowResults" matrix.  See details.}
51    \item{filteredDataRow}{The name of the auto-generated "filteredDataRow" matrix. See details.}
52    \item{existenceVector}{The name of the auto-generated "existenceVector" matrix. See details.}
53 }
54
55 \details{
56 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.
57
58 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}. 
59 }
60
61 \value{
62 Please use mxFitFunctionRow() instead.  As a temporary workaround, mxRowObjective returns a list containing a NULL MxExpectation object and an MxFitFunctionRow object.
63 }
64
65 \references{
66 The OpenMx User's guide can be found at http://openmx.psyc.virginia.edu/documentation.
67 }
68
69 \examples{
70 # Model that adds two data columns row-wise, then sums that column
71 # Notice no optimization is performed here.
72
73 library(OpenMx)
74
75 xdat <- data.frame(a=rnorm(10), b=1:10) # Make data set
76 amod <- mxModel(model="example1",
77             mxData(observed=xdat, type='raw'),
78             mxAlgebra(sum(filteredDataRow), name = 'rowAlgebra'),
79             mxAlgebra(sum(rowResults), name = 'reduceAlgebra'),
80             mxFitFunctionRow(
81                 rowAlgebra='rowAlgebra',
82                 reduceAlgebra='reduceAlgebra',
83                 dimnames=c('a','b'))
84 )
85 amodOut <- mxRun(amod)
86 mxEval(rowResults, model=amodOut)
87 mxEval(reduceAlgebra, model=amodOut)
88
89 # Model that find the parameter that minimizes the sum of the
90 #  squared difference between the parameter and a data row.
91
92 bmod <- mxModel(model="example2",
93             mxData(observed=xdat, type='raw'),
94             mxMatrix(values=.75, ncol=1, nrow=1, free=TRUE, name='B'),
95             mxAlgebra((filteredDataRow - B) ^ 2, name='rowAlgebra'),
96             mxAlgebra(sum(rowResults), name='reduceAlgebra'),
97             mxFitFunctionRow(
98                 rowAlgebra='rowAlgebra',
99                 reduceAlgebra='reduceAlgebra',
100                 dimnames=c('a'))
101 )
102 bmodOut <- mxRun(bmod)
103 mxEval(B, model=bmodOut)
104 mxEval(reduceAlgebra, model=bmodOut)
105 mxEval(rowResults, model=bmodOut)
106 }