##### https://github.com/cran/lavaan.survey
Tip revision: 09c8996
lavaan.survey.Rd
\name{lavaan.survey}
\alias{lavaan.survey}
\title{
Complex survey analysis of structural equation models (SEM)
}
\description{
Takes a lavaan fit object and a complex survey design object as input
and returns a structural equation modeling analysis based on the fit
object, where the complex sampling design is taken into account.

The structural equation model parameter estimates are "aggregated" (Skinner, Holt & Smith 1989), i.e. they consistently estimate parameters aggregated over any
clusters and strata and no explicit modeling of the effects of clusters and strata
is involved. Standard errors are design-based.
See Satorra and Muthen (1995) and references below for details on the procedure.

Both the pseudo-maximum likelihood (PML) procedure popular in the SEM world
(e.g. Asparouhov 2005; Stapleton 2006) and
weighted least squares procedures similar to aggregate regression modeling with
complex sampling (e.g. Fuller 2009, chapter 6) are implemented.

It is possible to give a list of multiply imputed datasets to svydesign as data.
\code{lavaan.survey} will then apply the standard Rubin (1987) formula to obtain
point and variance estimates under multiple imputation. Some care is required with
this procedure when survey weights are also involved, however (see Notes).
}
\usage{
lavaan.survey(lavaan.fit, survey.design,
estimator=c("MLM", "MLMV", "MLMVS", "WLS", "DWLS", "ML"),
estimator.gamma=c("default","Yuan-Bentler"))

}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{lavaan.fit}{
A \code{\linkS4class{lavaan}} object resulting from a lavaan call.

Since this is the estimator that will be used in the complex sample
estimates, for comparability it can be convenient to use the same estimator in the call
generating the \pkg{lavaan} fit object as in the \code{lavaan.survey} call. By default
this is "MLM".
}
\item{survey.design}{
An  \code{\link{svydesign}} object resulting from a call to
\code{svydesign} in the \pkg{survey} package. This allows for incorporation of
clustering, stratification, unequal probability weights, finite
population correction, and multiple imputation.
}
\item{estimator}{
The estimator used determines how parameter estimates are obtained,
how standard errors are calculated, and how the test statistic and

The default estimator is MLM. It is recommended to use one
of the ML estimators.
}
\item{estimator.gamma}{
Whether to use the usual estimator of Gamma as given by \code{svyvar} (the variance-covariance
matrix of the observed variances and covariances), or apply some kind
of smoothing or adjustment. Currently the only other option is the
Yuan-Bentler (1998) adjustment based on model residuals.
}
}
\details{
The user specifies a complex sampling design with the \pkg{survey} package's
\code{\link{svydesign}} function, and a structural equation model with

\code{lavaan.survey} follows these steps:
\enumerate{
\item The covariance matrix of the observed variables
(or matrices in the case of multiple
group analysis) is estimated using the \code{svyvar} command from the
\pkg{survey} package.
\item The asymptotic covariance matrix of the variances and
covariances is obtained from the \code{svyvar} output  (the "Gamma"
matrix)
\item The last step depends on the estimation method chosen:

\enumerate{
\item[MLM, MLMV, MLMVS] The \pkg{lavaan} model is re-fit using Maximum Likelihood
with the covariance matrix as data. After normal-theory ML
estimation, the standard errors (\code{vcov} matrix), likelihood ratio
("chi-square") statistic, and all derived fit indices and
statistics are adjusted for the complex sampling design using
the Gamma matrix. I.e. the Satorra-Bentler (SB) corrections are
obtained ("MLM" estimation in \pkg{lavaan} terminology). This procedure
is equivalent to "pseudo"-maximum likelihood (PML).
\item[WLS, DWLS] The \pkg{lavaan} model is re-fit using Weighted Least Squares
with the covariance matrix as data, and the Moore-Penrose inverse
of the Gamma matrix as estimation weights. If DWLS is chosen
only the diagonal of the weight matrix is used.
}
}

}
\value{
An object of class \code{\linkS4class{lavaan}}, where the estimates,
standard errors, \code{vcov} matrix, chi-square statistic, and fit measures
based on the chi-square take into account the complex survey
design. Several methods are available for \code{\linkS4class{lavaan}}
objects, including a \code{summary} method.}
\references{
Asparouhov T (2005). Sampling Weights in Latent Variable Modeling. Structural
Equation Modeling, 12(3), 411-434.

Bollen, K, Tueller, S, Oberski, DL (2013). Issues in the Structural Equation
Modeling of Complex Survey Data. In: Proceedings of the 59th World Statistics
Congress 2013 (International Statistical Institute, ed.), Hong Kong.
\url{http://daob.nl/publications/}

Fuller WA (2009). Sampling Statistics. John Wiley & Sons, New York.

Kim J, Brick J, Fuller WA, Kalton G (2006). On the Bias of the Multiple-Imputation
Variance Estimator in Survey Sampling. Journal of the Royal Statistical Society:
Series B (Statistical Methodology), 68(3), 509-521.

Oberski, D.L. (2014). lavaan.survey: An R Package for Complex Survey Analysis
of Structural Equation Models. Journal of Statistical Software, 57(1), 1-27.
\url{http://www.jstatsoft.org/v57/i01/}.

Oberski, D. and Saris, W. (2012). A model-based procedure to evaluate
the relative effects of different TSE components on structural equation
model parameter estimates. Presentation given at the International
Total Survey Error Workshop in Santpoort, the Netherlands.
\url{http://daob.nl/publications/}

Satorra, A., & Bentler, P. M. (1994). Corrections to test statistics
and standard errors in covariance structure analysis.

Satorra, A., and Muthen, B. (1995). Complex sample data in structural
equation modeling. Sociological methodology, 25, 267-316.

Skinner C, Holt D, Smith T (1989). Analysis of Complex Surveys.
John Wiley & Sons, New York.

Stapleton L (2006). An Assessment of Practical Solutions for Structural Equation
Modeling with Complex Sample Data. Structural Equation Modeling, 13(1), 28-58.

Stapleton L (2008). Variance Estimation Using Replication Methods in Structural
Equation Modeling with Complex Sample Data. Structural Equation Modeling, 15(2), 183-210.

Yuan K, Bentler P (1998). Normal Theory Based Test Statistics in Structural Equation
Modelling. British Journal of Mathematical and Statistical Psychology, 51(2), 289-309.
}
\author{
Daniel Oberski - \url{http://daob.nl/} - \email{daniel.oberski@gmail.com}
}
\note{
1) Some care should be taken when applying multiple imputation with survey
weights. The weights should be incorporated in the imputation, and even
then the variance produced by the usual Rubin (1987) estimator may not
be consistent (Kott 1995; Kim et al. 2006).

If multiple imputation is used to deal with unit nonresponse,
calibration and/or propensity score weighting with jackknifing may be a
more appropriate method. See the \pkg{survey} package.

2) Note that when using PML or WLS, the Gamma matrix need not be positive definite.
Preliminary investigations suggest that it often is not. This may happen due to
reduction of effective sample size from clustering, for instance.
In itself this need not be a problem, depending on the restrictiveness of the model.
In such cases \code{lavaan.survey} checks explicitly whether the covariance matrix
of the parameter estimates is still positive definite and produces a warning otherwise.

3) Currently only structural equation models for continuous variables are
implemented.
}

%% ~Make other sections like Warning with \section{Warning }{....} ~

\seealso{

}
\examples{
###### A single group example #######

# European Social Survey Denmark data (SRS)
data(ess.dk)

# A saturated model with reciprocal effects from Saris & Gallhofer
dk.model <- "
socialTrust ~ 1 + systemTrust + fearCrime
systemTrust ~ 1 + socialTrust + efficacy
socialTrust ~~ systemTrust
"
lavaan.fit <- lavaan(dk.model, data=ess.dk, auto.var=TRUE, estimator="MLM")
summary(lavaan.fit)

# Create a survey design object with interviewer clustering
survey.design <- svydesign(ids=~intnum, prob=~1, data=ess.dk)

survey.fit <- lavaan.survey(lavaan.fit=lavaan.fit, survey.design=survey.design)
summary(survey.fit)

###### A multiple group example #######

data(HolzingerSwineford1939)

# The Holzinger and Swineford (1939) example - some model with complex restrictions
HS.model <- ' visual  =~ x1 + x2 + c(lam31, lam31)*x3
textual =~ x4 + x5 + c(lam62, lam62)*x6
speed   =~ x7 + x8 + c(lam93, lam93)*x9
speed ~ textual
textual ~ visual'

# Fit multiple group per school
fit <- lavaan(HS.model, data=HolzingerSwineford1939,
int.ov.free=TRUE, meanstructure=TRUE,
auto.var=TRUE, auto.fix.first=TRUE, group="school",
auto.cov.lv.x=TRUE, estimator="MLM")
summary(fit, fit.measures=TRUE)

# Create fictional clusters in the HS data
set.seed(20121025)
HolzingerSwineford1939\$clus <- sample(1:100, size=nrow(HolzingerSwineford1939), replace=TRUE)
survey.design <- svydesign(ids=~clus, prob=~1, data=HolzingerSwineford1939)

summary(fit.survey <- lavaan.survey(fit, survey.design))

# For more examples, please see the Journal of Statistical Software Paper,
#  the accompanying datasets ?cardinale ?ess4.gb ?liss ?pisa.be.2003
#  and my homepage http://daob.nl/

}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{survey}
\keyword{models}
\keyword{regression}
\keyword{robust}
\keyword{multivariate}