Fixing some bugs caught by the "make check" process.
[openmx:openmx.git] / man / mxRowObjective.Rd
1 %
2 %   Copyright 2007-2010 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, rowResults = NA, reduceAlgebra = NA)
33 }
34
35
36 \arguments{
37    \item{rowAlgebra}{A character string indicating the name of the algebra to be evaluated row-wise.}
38    \item{rowResults}{A character string indicating the name of the algebra that stores the results of the row algebra.}
39    \item{reduceAlgebra}{A character string indicating the name of the algebra that collapses the row results into a single number which is then optimized.}
40 }
41
42 \details{
43 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 'rowAlgebra' in a row-wise fashion.  It then stores results of the row-wise evaluation in another \link{MxAlgebra} object called the '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 'reduceAlgebra' collapses the row results into a single number.  Any free parameters found in the 'rowAlgebra' will be optimized to minimize the result of the 'reduceAlgebra'.
44
45 All arguments to the mxRowObjective function are required.  There are no optional arguments.
46
47 mxRowObjective evaluates with respect to several \link{MxAlgebra} objects. The \link{MxAlgebra} objects need to be referenced in the mxRowObjective function, and also must be included in the \link{MxModel} object.  Missing values are not currently permitted in the associated \link{MxAlgebra} objects.  \link{MxData} objects can be indirectly referenced by mxRowObjective by placing all or part of the \link{MxData} object into an \link{MxAlgebra} object and referencing the \link{MxAlgebra} object.
48
49 To evaluate, place MxRowObjective objects, referenced \link{MxAlgebra} objects, and optional \link{MxData}, \link{MxMatrix}, \link{MxBounds}, and \link{MxConstraint} objects in an \link{MxModel} object. This model may then be evaluated using the \link{mxRun} function. The results of the optimization can be found in the 'output' slot of the resulting model, and may be referenced using the \link{Extract} functionality.
50 }
51
52 \value{
53 Returns a new MxRowObjective object. MxRowObjective objects should be included with models with referenced \link{MxAlgebra} objects.
54 }
55
56 \references{
57 The OpenMx User's guide can be found at http://openmx.psyc.virginia.edu/documentation.
58 }
59
60 \examples{
61
62 # Model that adds two data columns row-wise, then sums that column
63 # Notice no optimization is performed here.
64 xdat <- data.frame(a=rnorm(10), b=1:10) # Make data set
65 amod <- mxModel(
66                     mxData(observed=xdat, type='raw'),
67                     mxAlgebra(sum(filteredDataRow), name = 'rowAlgebra'),
68                     mxAlgebra(sum(rowResults), name = 'reduceAlgebra'),
69                     mxRowObjective(
70                             rowAlgebra='rowAlgebra',
71                             reduceAlgebra='reduceAlgebra',
72                             dimnames=c('a','b'))
73 )
74
75 # Model that find the parameter that minimizes the sum of the
76 #  squared difference between the parameter and a data row.
77 bmod <- mxModel(
78                     mxData(observed=xdat, type='raw'),
79                     mxMatrix(values=.75, ncol=1, nrow=1, free=TRUE, name='B'),
80                     mxAlgebra((filteredDataRow - B) ^ 2, name='rowAlgebra'),
81                     mxAlgebra(sum(rowResults), name='reduceAlgebra'),
82                     mxRowObjective(
83                             rowAlgebra='rowAlgebra',
84                             reduceAlgebra='reduceAlgebra',
85                             dimnames=c('a'))
86 )
87
88
89 }