\name{hcfa.xxm.2}
\alias{hcfa}
\title{
xxM Model Example: hcfa.xxm.2.R
}
\section{Introduction: Hierarchical Confirmatory Factor Analysis II}{
\bold{hcfa} is a three level hierarchical SEM model with observed dependent variables at levels 1 and 3; and latent variables at all three levels. The model includes a latent variable regression at level 3.  The data for this model were simulated. The example is intended to illustrate different within- and between- parameter matrices.

Latent variables at all three levels are defined by observed variables at level-1. This model illustrates how equality constraints may be imposed on parameters. In this case, factor loadings for latent variables at all three levels defined by observed variables at level-1 are constrained to be equal. Equality constraints are imposed by using a label matrix. Any two free parameters with the same label are constrained to be equal. 

}

\section{Creating a model: `hcfa`}{
The model involves three levels: \bold{student}, \bold{teacher}, \bold{school} 
\enumerate{
  \item \bold{student} is nested within both \bold{teacher} and \bold{school}. \bold{student}  has a three observed dependent variables: \bold{y1}, \bold{y2}, and \bold{y3}; and a single latent variable \bold{A1}.
  
  \item \bold{teacher} is a \bold{parent} of \bold{student}. For this model, \bold{teacher} is not nested under \bold{school} as the \bold{school} level random-effect for student latent outcome is modeled directly. \bold{teacher} has no observed variable and a single latent variable: \bold{A2} defined by observed variables at the \bold{student} level. 
  
  \item \bold{school} is a \bold{parent} of \bold{student}. \bold{school} includes three observed dependent variables: \bold{q1}, \bold{q2}, and \bold{q3}. \bold{school} submodel has two latent variables: \bold{A3}  defined by observed variables at the \bold{student} level and a school level latent variable \bold{Q} defined by level-3 observed variables. 
}
\bold{hcfa} is created by invoking \code{xxmModel()}.

\preformatted{hcfa <- xxmModel(levels = c("student","teacher","school"))}

Note: Levels are numbered according to their position in the above command.  Hence, \bold{student} corresponds to level 1, \bold{teacher} corresponds to level 2, and \bold{school} corresponds to level 3. 
}

\section{Adding submodels for `student`, `teacher` and `school`}{
For each level declared above, we need to create corresponding submodels. A submodel is created by invoking \code{xxmSubmodel()}: 
\enumerate{
\item \bold{student}

\preformatted{
hcfa <- xxmSubmodel(model = hcfa, level = "student",
 parents = c("teacher","school"), ys = ys1, xs =, 
 etas = c("A1"), data = hcfa.student)}
                  
\item \bold{teacher}

\preformatted{
teacher <- xxmSubmodel(model = hcfa, level="teacher", 
  parents =, ys =, xs =, etas = c("A2"), data = hcfa.teacher)}

\item \bold{school}

\preformatted{
hcfa <-  xxmSubmodel(model = hcfa,level = "school", parents =, 
 ys = c("q1","q2","q3"), xs =, etas = c("A3", "Q3"), 
 data = hcfa.school)}
}
}

\section{Specifying within-level model matrices for `student` (level 1) }{
\bold{student} model involves a factor-model with all three level-1 observed variables loading on a single latent variable \bold{A1}. Factor model involves three parameter matrices: factor-loading matrix \bold{lambda}, latent factor covariance matrix \bold{psi}, and observed residual-covariance matrix \bold{theta}. With raw data, we also need to specify measurement intercepts for observed variables using \bold{nu}. 

\enumerate{

 \item \bold{lambda}: Factor loading matrix is a (3x1) matrix. The first factor loading is fixed to 1.0 and the remaining two are frely estimated.

 \preformatted{
 hcfa <- xxmWithinMatrix(model = hcfa, level = "student", 
 type = "lambda", pattern = ly1_pat, value = ly1_val, label = ly1_lab)}

Note: The above label matrix is constructed as follows:
\preformatted{ly1_lab <- matrix(c("a","b","c"),3,1)}

We will use the same three labels for the two across-level factor-loading matrices.  

 \item \bold{psi}: Latent covariance matrix is a (1x1) matrix with freely estimated variance of the latent variable \bold{A1}.

 \preformatted{
 hcfa <- xxmWithinMatrix(model = hcfa, level ="student", 
  type = "psi", pattern = ps1_pat, value = ps1_val)}

\item \bold{theta}: Observed residual-covariance matrix is a (3x3) matrix with all three residual variances (diagonal elements) freely estimated.

 \preformatted{
 hcfa <- xxmWithinMatrix(model = hcfa, level = "student", 
  type = "theta", pattern = th1_pat, value = th1_val)}
 
  \item \bold{nu}: Observed variable intercept matrix is a (3x1) matrix with freely estimated intercepts.

 \preformatted{
 hcfa <- xxmWithinMatrix(model = hcfa, level = "student", 
  type  ="nu", pattern = nu1_pat, value = nu1_val) }
}
}

\section{Specifying within level model matrices for `teacher`  (level 2) }{
With a single latent variable \bold{A2}, the submodel for \bold{teacher} is simple. It includes a single variance of the latent dependent variable.
\enumerate{
\item \bold{psi}: Latent covariance matrix is a (1x1) matrix with a single element, the variance of the latent variable \bold{A2}.

\preformatted{
hcfa <- xxmWithinMatrix(model = hcfa, level = "teacher", 
 type = "psi", pattern = ps2_pat, value = ps2_val)}
}
}

\section{Specifying within-level model matrices for `school`  (level 3) }{
\bold{school} has two latent variables \bold{A3} and \bold{Q}. 

\bold{Q} is defined by all  level-3 observed indicators. As in case of level-1 we need to define a measurement model for \bold{Q}. Measurement model involves three parameter matrices: factor-loading matrix \bold{lambda}, latent factor covariance matrix \bold{psi}, and observed residual-covariance matrix \bold{theta}. With raw data, we also need to specify measurement intercepts for observed variables using \bold{nu}. 

\bold{A3} is regressed on \bold{Q}.  The latent regression matrix is called \bold{beta}. 

\enumerate{

\item \bold{lambda}: Factor loading matrix is a (3x2) matrix. The first latent variable \bold{A3} is defined by level-1 indicators. Hence the first column is fixed to 0.0. The second latent variable \bold{Q}. The first row of the second column is fixed to 1.0 to define the latent variable scale. The last two elements of second column are freely estimated.

 \preformatted{
 hcfa <- xxmWithinMatrix(model = hcfa, level = "school", 
  type = "lambda", pattern = ly3_pat, value = ly3_val)}

\item \bold{psi}: Latent covariance matrix is a (2x2) diagonal matrix. The first element is the residual variance of the latent dependent variable \bold{A3} and the second element is the unconditional variance of the latent predictor \bold{Q}. 

\preformatted{
hcfa <- xxmWithinMatrix(mdoel = hcfa, level = "school", 
 type = "psi", pattern = ps2_pat, value = ps2_val)}

\item \bold{theta}: Observed residual-covariance matrix is a (3x3) matrix with all three residual variances (diagonal elements) freely estimated.

 \preformatted{
 hcfa <- xxmWithinMatrix(model = hcfa, level = "school", 
  type = "theta", pattern = th3_pat, value = th3_val)}
 
  \item \bold{nu}: Observed variable intercept matrix is a (3x1) matrix with freely estimated intercepts.

 \preformatted{
 hcfa <- xxmWithinMatrix(model = hcfa, level = "school", 
  type  ="nu", pattern = nu3_pat, value = nu3_val) }

 
  \item \bold{beta}: Latent variable rergession matrix is a (2x2) upper-triangular matrix with a single free element \eqn{\beta_{1,2}}.

 \preformatted{
 hcfa <- xxmWithinMatrix(model = hcfa, level = "school", 
  type  = "beta", pattern = be3_pat, value = be3_val) }

}
}
\section{Specifying across-level model matrices connecting `teacher` and `student`}{So far, we have specified within-level matrices.  We now need to connect observed and latent variables across-levels. For this models, latent variables at level-2 and level-3 are measured by observed indicators at level-1. Across-level measurement relationship is specified with a \bold{lambda} matrix.  All across-level matrices connecting variables across two submodels are specified by invoking \code{xxmBetweenMatrix()}. 

Note: The direction of influence is from the higher level model \bold{teacher} (2) or the \bold{school} to the lower level model \bold{student} (1) or the \bold{child}.

\enumerate{
\item \bold{lambda}: Factor-loading matrix is a (3x1) matrix. The first element is fixed to 1.0 and the remaining elements are freely estimated. 

\preformatted{
hcfa <- xxmBetweenMatrix(model = hcfa, parent = "teacher", 
 child = "student", type = "lambda", pattern = ly12_pat, 
 value = ly12_val, label = ly12_lab)}

Note: The above label matrix is constructed as follows:
\preformatted{ly1_lab <- matrix(c("a","b","c"),3,1)}

Labels for the three factor-loadings are identical to those for level-1 factor loading matrix. 
}
}

\section{Specifying across-level model matrices connecting `school` and `teacher`}{
The first lLatent variable at leve-3 \bold{A3} is measured by observed indicators at level-1. 

\enumerate{
 \item \bold{lambda}: Factor-loading matrix is a (3x2) matrix.  The first latent variable \bold{A3} is defined by level-1 indicators.  The first row of the first column is fixed to 1.0 to define the latent variable scale. The last two elements of first column are freely estimated. The second latent variable \bold{Q} was already defined by level-3 observed variables. Hence all elements of second column are fixed to 0.0. 

 \preformatted{
 hcfa <- xxmBetweenMatrix(model = hcfa, parent = "school", 
  child = "student", type = "lambda", pattern = ly13_pat, 
  value = ly13_val)}
  
Note: The above label matrix is constructed as follows:
\preformatted{
ly13_lab <- matrix(c("a","b","c","d","e","f"),3,2) 
}

Labels for the three factor-loadings are identical to those for level-1 factor loading matrix as well as across-level factor-loadings connecting \bold{teacher} and \bold{student}. 
}
}
}
\section{Compute: \bold{xxmRun()}}{
Model specification is now complete. Parameter estimation is initiated as follows:
\preformatted{hcfa <-xxmRun(model = hcfa)}
}

\section{Notes}{
\enumerate{
\item Dataset for this model is packaged with \code{xxm} in an R workspace called \code{hcfa.xxm.RData}. The three data frames called `hcfa.student`, 'hcfa.teacher`, and 'hcfa,school` are loaded into the R workspace when the library is loaded: 

\code{library(xxm)}

\code{data(hcfa.xxm, package="xxm")}

\item Datasets for this model are documented under \code{hcfa.xxm.RData} in ???.

\item R script for running this model is stored under \code{.../models/hcfa.2.xxm.R}
}

}
