Add more aliases
[openmx:openmx.git] / man / mxFitFunctionR.Rd
1 %
2 %   Copyright 2007-2013 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{mxFitFunctionR}
17 \alias{mxFitFunctionR}
18 \alias{MxFitFunctionR-class}
19 \alias{print,MxFitFunctionR-method}
20 \alias{show,MxFitFunctionR-method}
21
22 \title{Create MxFitFunctionR Object}
23
24 \description{
25 mxFitFunctionR returns an MxFitFunctionR object.
26 }
27
28 \usage{
29 mxFitFunctionR(objfun, ...)
30 }
31
32 \arguments{
33    \item{objfun}{A function that accepts two arguments.}
34    \item{...}{The initial state information to the objective function.}
35 }
36
37 \details{
38 The mxFitFunctionR function evaluates a user-defined R function called the 'objfun'.  mxFitFunctionR is useful in defining new mxFitFunctions, since any calculation that can be performed in R can be treated as an mxFitFunction.
39
40 The 'objfun' argument must be a function that accepts two arguments. The first argument
41 is the mxModel that should be evaluated, and the second argument is some persistent 
42 state information that can be stored between one iteration of optimization to the next
43 iteration. It is valid for the function to simply ignore the second argument.
44
45 The function must return either a single numeric value, or a list of exactly two elements.
46 If the function returns a list, the first argument must be a single numeric value and the 
47 second element will be the new persistent state information to be passed into this function
48 at the next iteration. The single numeric value will be used by the optimizer to perform
49 optimization.
50
51 The initial default value for the persistant state information is NA.
52
53 Throwing an exception (via stop) from inside objfun may result
54 in unpredictable behavior. You may want to wrap your code in
55 tryCatch while experimenting.
56 }
57
58 \value{
59 Returns an MxFitFunctionR object. 
60 }
61
62 \references{
63 The OpenMx User's guide can be found at http://openmx.psyc.virginia.edu/documentation.
64 }
65
66 \examples{
67
68 # Create and fit a model using mxFitFunctionR
69
70 library(OpenMx)
71
72 A <- mxMatrix(nrow = 2, ncol = 2, values = c(1:4), free = TRUE, name = 'A')
73 squared <- function(x) { x ^ 2 }
74
75 # Define the objective function in R
76
77 objFunction <- function(model, state) {
78     values <- model[['A']]@values 
79     return(squared(values[1,1] - 4) + squared(values[1,2] - 3) +
80         squared(values[2,1] - 2) + squared(values[2,2] - 1))
81 }
82
83 # Define the expectation function
84
85 fitFunction <- mxFitFunctionR(objFunction)
86
87 # Define the model
88
89 tmpModel <- mxModel('exampleModel', A, fitFunction)
90
91 # Fit the model and print a summary
92
93 tmpModelOut <- mxRun(tmpModel)
94 summary(tmpModelOut)
95
96 }