\name{estimator_iv}
\alias{estimator_iv}
\alias{iv}
\alias{IV}
\alias{miiv}
\alias{MIIV}
\alias{miivsem}
\alias{MIIVsem}
\alias{instrument}
\alias{instruments}
\alias{sargan}
\alias{Sargan}
\title{Instrumental Variable (MIIV-2SLS) Estimation}
\description{
Estimate a structural equation model using model-implied instrumental
variables and two-stage least squares (MIIV-2SLS), a non-iterative,
equation-by-equation alternative to maximum likelihood (Bollen, 1996).
This page documents how to invoke the estimator, the options that can be
passed via the \code{estimator = list()} argument, how to specify
instruments manually with the \code{|~} operator, and the \code{lavInspect()}
fields that are relevant for IV estimation.
}
\details{
Instead of minimizing a single discrepancy function for the whole model,
MIIV-2SLS estimates each measurement and structural equation separately by
two-stage least squares (2SLS). For each equation, the instruments are other
observed variables in the model that are (under the hypothesized model)
uncorrelated with the equation's composite error term: the \emph{model-implied
instrumental variables} (MIIVs). Because the equations are estimated
separately, a misspecification in one equation does not necessarily propagate
to the others, the method is non-iterative, and no starting values are
required.

The estimator is selected by setting \code{estimator = "IV"} (the alias
\code{"MIIV"} is also accepted; names are case-insensitive), for example
\preformatted{    fit <- sem(model, data = Data, estimator = "IV")}

Estimation proceeds in two stages. In the first stage, the \emph{directed}
effects (factor loadings and regression coefficients) are estimated
equation-by-equation by 2SLS. In the second stage, the \emph{undirected}
effects (residual variances and covariances) are estimated by a weighted
least-squares step applied to the residual moments. Standard errors are
available for both stages (see the options below).

Both continuous and ordered-categorical data are supported (for ordered data,
the polychoric-based PIV estimator of Bollen & Maydeu-Olivares, 2007 is used).
Simple equality constraints (e.g. equal factor loadings) and general linear
equality constraints (e.g. \code{a == 2*b}) are honored. Multiple groups are
supported, with standard errors (for continuous, two-stage-missing and
categorical data), including the mean structure and cross-group equality
constraints for measurement invariance testing (configural, metric and scalar,
e.g. via \code{group.equal = c("loadings", "intercepts")}). For scalar
invariance the latent-mean (and intercept) estimates are obtained by a joint
GLS solve over the mean structure (see \code{iv_mean_structure}), which matches
the maximum likelihood mean estimates given the model-implied covariance
matrix. The IV estimator is restricted to single-level models.

\subsection{Estimator options}{

Options specific to the IV estimator are passed as named elements of a list
to the \code{estimator} argument, alongside the estimator name:
\preformatted{    fit <- sem(model, data = Data,
               estimator = list(estimator = "IV",
                                iv_varcov_method = "2RLS",
                                iv_sargan_adjust = "BH"))}

The option names use snake_case. For backward compatibility, dot.case names
(e.g. \code{iv.varcov.method}) are also accepted and silently converted.

\describe{
  \item{\code{iv_method}:}{Character. The instrumental-variable method.
    Currently only \code{"2SLS"} (two-stage least squares) is available.
    Default is \code{"2SLS"}.}
  \item{\code{iv_samplestats}:}{Logical. If \code{TRUE} (the default), the
    equations are estimated from the sample moments (covariances and means)
    rather than from the raw data. This is required for categorical data and
    when only sample moments are provided as input.}
  \item{\code{iv_varcov_method}:}{Character. The second-stage method used to
    estimate the residual variances and covariances. One of \code{"ULS"},
    \code{"GLS"}, \code{"2RLS"}, \code{"RLS"} or \code{"NONE"}. Default is
    \code{"RLS"} (reweighted least squares). For categorical data, \code{"ULS"}
    is used. If \code{"NONE"}, the variance/covariance parameters are not
    estimated.}
  \item{\code{iv_sargan}:}{Logical. If \code{TRUE} (the default),
    overidentification tests are computed for each overidentified equation. Two
    tests are reported side by side: the classical Sargan test (Sargan, 1958),
    which assumes normality (continuous data) and is not valid for polychoric
    correlations; and a robust, residual-based test that is valid more
    generally. The robust test is Browne's (1984) residual statistic applied to
    the single equation, computed with the asymptotic covariance matrix (ACOV)
    of the sample statistics: the distribution-free (ADF) ACOV of the sample
    covariances for continuous data (so it is robust to non-normality, and is
    then equivalent to Hansen's overidentification test), or the polychoric
    ACOV for categorical data. Both tests share the same degrees of freedom
    (number of instruments minus number of regressors). For continuous data
    with missing values the robust test is not available. The results can be
    retrieved with \code{lavInspect(fit, "sargan")} (or, equivalently,
    \code{lavInspect(fit, "hansen")}).}
  \item{\code{iv_sargan_adjust}:}{Character. A multiple-comparison adjustment
    applied to the per-equation overidentification p-values, using any method
    accepted by \code{\link[stats]{p.adjust}} (\code{"holm"}, \code{"hochberg"},
    \code{"hommel"}, \code{"bonferroni"}, \code{"BH"}, \code{"BY"},
    \code{"fdr"}, or \code{"none"}). Default is \code{"none"}. When a method
    other than \code{"none"} is requested, extra \code{sargan.pval.adj} and
    \code{browne.pval.adj} columns are added to the table returned by
    \code{lavInspect(fit, "sargan")}.}
  \item{\code{iv_weak}:}{Character. How to respond to weak instruments,
    diagnosed per equation by the first-stage F-statistic (Staiger & Stock,
    1997). One of:
    \describe{
      \item{\code{"warn"}:}{(the default) report the affected equations and
        their first-stage F, and suggest supplying stronger instruments
        manually; the estimates are not changed.}
      \item{\code{"prune"}:}{greedily drop the weakest excess instruments from
        weak, overidentified equations (never below just-identified) and report
        what was dropped.}
      \item{\code{"none"}:}{skip the weak-instrument check.}
    }}
  \item{\code{iv_weak_threshold}:}{Numeric. The first-stage F-statistic below
    which instruments are deemed weak. Default is \code{10}.}
  \item{\code{iv_vcov_stage1}:}{Character. The standard-error method for the
    first-stage (directed) coefficients. One of \code{"lm.vcov"},
    \code{"lm.vcov.dfres"}, \code{"gamma"} or \code{"none"}. Default is
    \code{"lm.vcov.dfres"} for continuous data and \code{"gamma"} for
    categorical data. The \code{"gamma"} method requires
    \code{iv_samplestats = TRUE}. When the model contains \emph{simple}
    equality constraints among the directed coefficients (e.g. equal factor
    loadings), the \code{"lm.vcov"}/\code{"lm.vcov.dfres"} methods use a
    variance-weighted restricted-2SLS covariance for the constrained
    coefficients (as in the MIIVsem package); set \code{iv_vcov_stage1 =
    "gamma"} to obtain the delta-method (moment-Jacobian) standard errors
    instead.}
  \item{\code{iv_vcov_stage2}:}{Character. The standard-error method for the
    second-stage (undirected) parameters. One of \code{"h2"}, \code{"delta"}
    or \code{"none"}. Default is \code{"h2"}. The \code{"h2"} method requires
    \code{iv_samplestats = TRUE}.}
  \item{\code{iv_vcov_gamma_modelbased}:}{Logical. If \code{TRUE} (the
    default), the normal-theory weight matrix (gamma) used for the standard
    errors is based on the model-implied covariance matrix; if \code{FALSE},
    it is based on the unrestricted (H1) sample covariance matrix.}
  \item{\code{iv_mean_structure}:}{Character. How the free mean-structure
    parameters (observed intercepts and latent means) are estimated. With
    \code{"wls"} (the default) they are obtained by a joint GLS solve that fits
    the model-implied means to the sample means across all groups, pooling
    parameters that are constrained equal across groups (e.g. intercepts for
    scalar invariance); this matches the maximum likelihood mean estimates
    (given the model-implied covariance matrix). With \code{"moments"} the
    intercepts are recomputed per equation and shared intercepts are pooled by
    a (simpler) nobs-weighted average. The two agree unless intercepts are
    constrained across groups (scalar invariance).}
  \item{\code{iv_vcov_jack_numerical}, \code{iv_vcov_jaca_numerical},
    \code{iv_vcov_jacb_numerical}:}{Logical. If \code{TRUE}, the corresponding
    Jacobians used in the standard-error computation are obtained numerically
    rather than from analytic expressions. The default is \code{FALSE}; these
    are mainly intended for checking the analytic derivatives.}
  \item{\code{iv_mimic_ml}:}{Logical. If \code{FALSE} (the default), the IV
    estimator uses unbiased divisors: the sample covariance matrix is divided
    by \eqn{N-1} (\code{sample.cov.rescale = FALSE}) and the per-equation
    residual variances (the RSS terms entering the standard errors and the
    Sargan test) use the \eqn{N-P} divisor. If \code{TRUE}, the maximum
    likelihood divisor \eqn{N} is used throughout: the sample covariance is
    rescaled to the ML divisor \eqn{N} and the residual variances use the
    \eqn{N} divisor as well. As a result, for just-identified models the IV
    point estimates and standard errors match the ML solution exactly.}
}
}

\subsection{Specifying instruments manually (the \code{|~} operator)}{

By default lavaan determines the model-implied instruments for each equation
automatically. The \code{|~} operator overrides this choice for a specific
equation: the left-hand side is the dependent variable of the equation (for a
latent variable, its scaling indicator), and the right-hand side lists the
instruments to use.

\preformatted{    model <- '
        ind60 =~ x1 + x2 + x3
        dem60 =~ y1 + y2 + y3 + y4
        dem60 ~ ind60
        # use only x2 and x3 as instruments for the 
        # dem60 ~ ind60 equation
        y1 |~ x2 + x3
    '
    fit <- sem(model, data = PoliticalDemocracy, estimator = "IV")}

This is useful when the automatically selected instruments are weak (see
\code{iv_weak} above) or when subject-matter knowledge suggests a different
set of instruments.

\emph{External instruments.} The instruments listed on the right-hand side of
\code{|~} need not be part of the model. If an instrument is an observed
variable that does not otherwise appear in the model (it is not an indicator,
a predictor, an outcome, or otherwise mentioned), it is treated as an
\emph{external} instrument: it is read from the data so that its covariances
with the model variables are available to the 2SLS estimator, but it never
enters the model-implied summary statistics. The model degrees of freedom, the
fit measures, and the model-implied moments are therefore exactly the same as
if the instrument had not been mentioned; only the equations for which it is
used are affected. External instruments require raw data (a \code{data=}
argument); they are not available when only sample moments are supplied. For
categorical data the external instruments must themselves be ordered
(categorical); the augmented polychoric correlations and the asymptotic
covariance of the sample statistics are then used for the estimates and the
standard errors. Single-group and multiple-group categorical models are
supported, but (for now) not equality constraints among the directed
coefficients (e.g. measurement invariance) together with external instruments.

\preformatted{    ## z is not part of the model; it is used only as an
    ## instrument for the (endogenous) regression y ~ x
    model <- '
        y ~ x
        y |~ z
    '
    fit <- sem(model, data = Data, estimator = "IV")}

For external instruments the point estimates and the directed-coefficient
(loading and regression) standard errors are the usual 2SLS quantities. The
second-stage (residual variance and covariance) standard errors also account
for the sampling variability of the instrument moments: the directed
coefficients depend on the instrument-model covariances, and this uncertainty
is propagated into the variance/covariance parameters through the full
(augmented) moment Jacobian.
}

\subsection{Missing data}{

For continuous data with missing values, the IV estimator defaults to a
two-stage (FIML) approach: the saturated mean vector and covariance matrix are
estimated by the EM algorithm, the model is then estimated from these moments,
and the standard errors are corrected for the additional uncertainty stemming
from the EM estimates (Savalei & Bentler, 2009). This default is used when the
data contain missing values and the user does not set the \code{missing}
argument. Set \code{missing = "robust.two.stage"} for sandwich-corrected
standard errors (Savalei & Falk, 2014), or \code{missing = "listwise"} to
delete incomplete cases instead. Two-stage missing-data estimation is also
available for multiple-group models.
}

\subsection{Multiple groups and measurement invariance}{

Multiple-group models are supported, with point estimates and standard errors
for continuous, two-stage-missing and categorical data. Cross-group equality
constraints are imposed in the usual way, either through shared parameter
labels in the model syntax or through the \code{group.equal} argument, so the
standard measurement-invariance sequence is available: configural
(\code{group.equal = NULL}), metric (\code{group.equal = "loadings"}) and
scalar (\code{group.equal = c("loadings", "intercepts")}).

A parameter that is constrained equal across groups is estimated by pooling the
information from all groups; for a configural model the per-group estimates (and
their standard errors) reproduce the separate single-group fits. The mean
structure (observed intercepts and latent means) is estimated by a joint GLS
solve over all groups (see \code{iv_mean_structure}), which reproduces the
maximum likelihood mean estimates given the model-implied covariance matrix.
}

\subsection{Inspecting the instruments and the Sargan test}{

Several \code{\link{lavInspect}} fields are specific to IV estimation:
\describe{
  \item{\code{lavInspect(fit, "iv")}:}{(aliases \code{"miiv"},
    \code{"instruments"}) a per-equation table with the dependent variable
    (\code{lhs}), the regressors (\code{rhs}), the observed variables actually
    used (\code{lhs_new}, \code{rhs_new}), the equation type (\code{type}:
    \code{"miiv"}, \code{"ols"} or \code{"user"}), and the instruments
    (\code{iv}) for that equation.}
  \item{\code{lavInspect(fit, "sargan")}:}{a per-equation table with the
    overidentification tests: the degrees of freedom (\code{df}), the classical
    Sargan statistic (\code{sargan.stat}) and its p-value (\code{sargan.pval}),
    and the robust Browne residual-based statistic (\code{browne.stat}) and its
    p-value (\code{browne.pval}); see \code{iv_sargan} above. For categorical
    data the classical Sargan p-value is \code{NA} (not valid), so use the
    \code{browne.*} columns. Adjusted p-values (\code{sargan.pval.adj} and
    \code{browne.pval.adj}) are added when \code{iv_sargan_adjust} is set.
    \code{lavInspect(fit, "hansen")} is an alias.}
  \item{\code{lavInspect(fit, "eqs")}:}{the underlying per-equation
    information.}
}
}
}
\references{
Bollen, K. A. (1996). An alternative two stage least squares (2SLS) estimator
for latent variable equations. \emph{Psychometrika}, 61(1), 109-121.

Bollen, K. A., & Maydeu-Olivares, A. (2007). A polychoric instrumental variable
(PIV) estimator for structural equation models with categorical variables.
\emph{Psychometrika}, 72(3), 309-326.

Browne, M. W. (1984). Asymptotically distribution-free methods for the analysis
of covariance structures. \emph{British Journal of Mathematical and Statistical
Psychology}, 37(1), 62-83.

Sargan, J. D. (1958). The estimation of economic relationships using
instrumental variables. \emph{Econometrica}, 26(3), 393-415.

Savalei, V., & Bentler, P. M. (2009). A two-stage approach to missing data:
Theory and application to auxiliary variables.
\emph{Structural Equation Modeling}, 16(3), 477-497.

Savalei, V., & Falk, C. F. (2014). Robust two-stage approach outperforms robust
full information maximum likelihood with incomplete nonnormal data.
\emph{Structural Equation Modeling}, 21(2), 280-302.

Staiger, D., & Stock, J. H. (1997). Instrumental variables regression with weak
instruments. \emph{Econometrica}, 65(3), 557-586.
}
\seealso{
\code{\link{lavaan}}, \code{\link{sem}}, \code{\link{lavOptions}},
\code{\link{lavInspect}}.
}
\examples{
## The classic Bollen (1989) Political Democracy example
model <- '
  # measurement model
    ind60 =~ x1 + x2 + x3
    dem60 =~ y1 + y2 + y3 + y4
    dem65 =~ y5 + y6 + y7 + y8
  # regressions
    dem60 ~ ind60
    dem65 ~ ind60 + dem60
'

## fit using MIIV-2SLS instead of maximum likelihood
fit <- sem(model, data = PoliticalDemocracy, estimator = "IV")
summary(fit)

## the model-implied instruments used for each equation
lavInspect(fit, "iv")

## the per-equation Sargan overidentification tests
lavInspect(fit, "sargan")

## pass estimator options via estimator = list(...)
fit2 <- sem(model, data = PoliticalDemocracy,
            estimator = list(estimator = "IV",
                             iv_varcov_method = "2RLS",
                             iv_sargan_adjust = "BH",
                             iv_weak = "warn"))
lavInspect(fit2, "sargan")

## specify instruments manually with the |~ operator:
## use only x2, x3 as instruments for the dem60 ~ ind60 equation
model.iv <- '
    ind60 =~ x1 + x2 + x3
    dem60 =~ y1 + y2 + y3 + y4
    dem60 ~ ind60
    y1 |~ x2 + x3
'
fit3 <- sem(model.iv, data = PoliticalDemocracy, estimator = "IV")
lavInspect(fit3, "iv")

\dontrun{
## equality constraints are honored (here: equal loadings across factors)
model.eq <- '
    ind60 =~ x1 + x2 + x3
    dem60 =~ y1 + a*y2 + b*y3 + c*y4
    dem65 =~ y5 + a*y6 + b*y7 + c*y8
    dem60 ~ ind60
    dem65 ~ ind60 + dem60
'
fit4 <- sem(model.eq, data = PoliticalDemocracy, estimator = "IV")
coef(fit4)

## multiple groups: metric measurement invariance (equal loadings)
HS.model <- ' visual  =~ x1 + x2 + x3
              textual =~ x4 + x5 + x6
              speed   =~ x7 + x8 + x9 '
fit.metric <- sem(HS.model, data = HolzingerSwineford1939, estimator = "IV",
                  group = "school", group.equal = "loadings")
summary(fit.metric)
}
}
\keyword{models}
\keyword{regression}
