1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/auxiliary.R
\name{auxiliary}
\alias{auxiliary}
\alias{lavaan.auxiliary}
\alias{cfa.auxiliary}
\alias{sem.auxiliary}
\alias{growth.auxiliary}
\title{Implement Saturated Correlates with FIML}
\usage{
auxiliary(model, data, aux, fun, ..., envir = getNamespace("lavaan"),
return.syntax = FALSE)
lavaan.auxiliary(model, data, aux, ..., envir = getNamespace("lavaan"))
cfa.auxiliary(model, data, aux, ..., envir = getNamespace("lavaan"))
sem.auxiliary(model, data, aux, ..., envir = getNamespace("lavaan"))
growth.auxiliary(model, data, aux, ..., envir = getNamespace("lavaan"))
}
\arguments{
\item{model}{The analysis model can be specified with 1 of 2 objects:
\enumerate{
\item lavaan \code{\link[lavaan:model.syntax]{lavaan::model.syntax()}} specifying a hypothesized
model \emph{without} mention of auxiliary variables in \code{aux}
\item a parameter table, as returned by \code{\link[lavaan:parTable]{lavaan::parTable()}},
specifying the target model \emph{without} auxiliary variables.
This option requires these columns (and silently ignores all others):
\code{c("lhs","op","rhs","user","group","free","label","plabel","start")}
}}
\item{data}{\code{data.frame} that includes auxiliary variables as well as
any observed variables in the \code{model}}
\item{aux}{\code{character}. Names of auxiliary variables to add to \code{model}}
\item{fun}{\code{character}. Name of a specific lavaan function used to fit
\code{model} to \code{data} (i.e., \code{"lavaan"}, \code{"cfa"},
\code{"sem"}, or \code{"growth"}). Only required for \code{auxiliary}.}
\item{...}{Additional arguments to pass to \verb{fun=}.}
\item{envir}{Passed to \code{\link[=do.call]{do.call()}}.}
\item{return.syntax}{\code{logical} indicating whether to return a
\code{character} string of \code{\link[lavaan:model.syntax]{lavaan::model.syntax()}} that can be
added to a target \verb{model=} that is also a \code{character} string.
This can be advantageous, for example, to use add saturated correlates to
a \pkg{blavaan} model.}
}
\value{
a fitted \link[lavaan:lavaan-class]{lavaan::lavaan} object. Additional
information is stored as a \code{list} in the \verb{@external} slot:
\itemize{
\item \code{baseline.model}. a fitted \link[lavaan:lavaan-class]{lavaan::lavaan}
object. Results of fitting an appropriate independence model for
the calculation of incremental fit indices (e.g., CFI, TLI) in
which the auxiliary variables remain saturated, so only the target
variables are constrained to be orthogonal. See Examples for how
to send this baseline model to \code{\link[lavaan:fitMeasures]{lavaan::fitMeasures()}}.
\item \code{aux}. The character vector of auxiliary variable names.
\item \code{baseline.syntax}. A character vector generated within the
\code{auxiliary} function, specifying the \code{baseline.model}
syntax.
}
}
\description{
Automatically add auxiliary variables to a lavaan model when using full
information maximum likelihood (FIML) to handle missing data
}
\details{
These functions are wrappers around the corresponding lavaan functions.
You can use them the same way you use \code{\link[lavaan:lavaan]{lavaan::lavaan()}}, but you
\emph{must} pass your full \code{data.frame} to the \code{data} argument.
Because the saturated-correlates approaches (Enders, 2008) treats exogenous
variables as random, \code{fixed.x} must be set to \code{FALSE}. Because FIML
requires continuous data (although nonnormality corrections can still be
requested), no variables in the model nor auxiliary variables specified in
\code{aux} can be declared as \code{ordered}.
}
\examples{
dat1 <- lavaan::HolzingerSwineford1939
set.seed(12345)
dat1$z <- rnorm(nrow(dat1))
dat1$x5 <- ifelse(dat1$z < quantile(dat1$z, .3), NA, dat1$x5)
dat1$x9 <- ifelse(dat1$z > quantile(dat1$z, .8), NA, dat1$x9)
targetModel <- "
visual =~ x1 + x2 + x3
textual =~ x4 + x5 + x6
speed =~ x7 + x8 + x9
"
## works just like cfa(), but with an extra "aux" argument
fitaux1 <- cfa.auxiliary(targetModel, data = dat1, aux = "z",
missing = "fiml", estimator = "mlr")
## with multiple auxiliary variables and multiple groups
fitaux2 <- cfa.auxiliary(targetModel, data = dat1, aux = c("z","ageyr","grade"),
group = "school", group.equal = "loadings")
## calculate correct incremental fit indices (e.g., CFI, TLI)
fitMeasures(fitaux2, fit.measures = c("cfi","tli"))
## NOTE: lavaan will use the internally stored baseline model, which
## is the independence model plus saturated auxiliary parameters
lavInspect(fitaux2@external$baseline.model, "free")
}
\references{
Enders, C. K. (2008). A note on the use of missing auxiliary variables in
full information maximum likelihood-based structural equation models.
\emph{Structural Equation Modeling, 15}(3), 434--448.
\doi{10.1080/10705510802154307}
}
\author{
Terrence D. Jorgensen (University of Amsterdam; \email{TJorgensen314@gmail.com})
}
|
