Updated copyright to 2013 for R/ demo/ models/passing and src/ folders, and also...
[openmx:openmx.git] / man / omxGetParameters.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{omxGetParameters}
17 \alias{omxGetParameters}
18
19 \title{Fetch Model Parameters}
20
21 \description{
22     Return a vector of the chosen parameters from the model.
23 }
24
25 \usage{
26 omxGetParameters(model, indep = FALSE, free = c(TRUE, FALSE, NA),
27         fetch = c('values', 'free', 'lbound', 'ubound', 'all'))
28 }
29
30 \arguments{
31    \item{model}{a MxModel object}
32    \item{indep}{fetch parameters from independent submodels.}
33    \item{free}{fetch either free parameters (TRUE), or fixed parameters or both types. Default value is TRUE.}
34    \item{fetch}{which attribute of the parameters to fetch. Default choice is \sQuote{values}.}
35 }
36
37 \details{
38   The argument \sQuote{free} dictates whether to return only free parameters or only fixed parameters or both free and fixed parameters. The function can return unlabelled free parameters (parameters with a label of NA). These anonymous free parameters will be identified as \sQuote{modelname.matrixname[row,col]}.  It will not return fixed parameters that have a label of NA. No distinction is made between ordinary labels, definition variables, and square bracket constraints. The function will return either a vector of parameter values, or free/fixed designations, or lower bounds, or upper bounds, depending on the \sQuote{fetch} argument. Using fetch with \sQuote{all} returns a data frame that is populated with all of the attributes.
39 }
40
41 \seealso{
42 \code{\link{omxSetParameters}}, \code{\link{omxLocateParameters}}, \code{\link{omxAssignFirstParameters}} 
43 }
44
45 \examples{
46
47 A <- mxMatrix('Full', 2, 2, labels = c("A11", "A12", "A21", NA), values= 1:4, 
48         free = c(TRUE,TRUE,FALSE,TRUE), byrow=TRUE, name = 'A')
49 model <- mxModel(A, name = 'model')
50
51 # Request all free parameters in model
52 omxGetParameters(model)
53
54 # A11  A12 model.A[2,2] 
55 #   1    2    4 
56
57 # Request fixed parameters from model
58 omxGetParameters(model, free = FALSE)
59 # A21 
60 #   3
61
62 A@labels
63 #      [,1]  [,2] 
64 # [1,] "A11" "A12"
65 # [2,] "A21" NA   
66
67 A@free
68 #       [,1] [,2]
69 # [1,]  TRUE TRUE
70 # [2,] FALSE TRUE
71
72 A@labels
73 #      [,1]  [,2] 
74 # [1,] "A11" "A12"
75 # [2,] "A21" NA   
76
77 # Example using un-labelled parameters
78 # Load the OpenMx Package if not already loaded
79 require(OpenMx) 
80 # Read in some demo data
81 data(demoOneFactor)
82 # Grab the names for manifestVars 
83 manifestVars <- names(demoOneFactor)
84 nVar = length(manifestVars) # 5 variables
85 factorModel <- mxModel("One Factor",
86     mxMatrix(name="A", type="Full", nrow=nVar, ncol=1, values=0.2, free=TRUE, 
87                 lbound = 0.0, labels=letters[1:nVar]),
88     mxMatrix(name="L", type="Symm", nrow=1, ncol=1, values=1, free=FALSE),
89     # the "U" matrix has nVar (5) anonymous free parameters
90     mxMatrix(name="U", type="Diag", nrow=nVar, ncol=nVar, values=1, free=TRUE),
91     mxAlgebra(expression=A \%&\% L + U, name="R"),
92     mxMLObjective(covariance="R", dimnames=manifestVars),
93     mxData(observed=cov(demoOneFactor), type="cov", numObs=500)
94 )
95
96 # Get all free parameters
97 params         <- omxGetParameters(factorModel)
98 lbound         <- omxGetParameters(factorModel, fetch="lbound")
99 # Set new values for these params, saving them in a new model
100 newFactorModel <- omxSetParameters(factorModel, names(params), values = 1:10)
101 # Read out the values from the new model
102 newParams      <- omxGetParameters(newFactorModel)
103
104 }