\name{lavTestScore}
\alias{lavTestScore}
\alias{lavtestscore}
\alias{score}
\alias{Score}
\alias{lavScoreTest}
\title{Score test}
\description{
Score test (or Lagrange Multiplier test) for releasing one or more
fixed or constrained parameters in the model.}
\usage{
lavTestScore(object, add = NULL, release = NULL,
             univariate = TRUE, cumulative = FALSE,
             epc = FALSE, standardized = epc, cov_std = epc,
             verbose = FALSE, warn = TRUE, information = "expected", ...)
}
\arguments{
\item{object}{An object of class \code{\linkS4class{lavaan}}.}
\item{add}{Either a character string (typically between single quotes) or
  a parameter table containing additional (currently fixed-to-zero) parameters
  for which the score test must be computed.}
\item{release}{Vector of integers. The indices of the constraints that
should be released. The indices correspond to the order in which the equality
constraints appear in the parameter table.}
\item{univariate}{Logical. If \code{TRUE}, compute the univariate score
statistics, one for each constraint.}
\item{cumulative}{Logical. If \code{TRUE}, order the univariate score
statistics from large to small, and compute a series of
multivariate score statistics, each time adding an additional constraint.}
\item{epc}{Logical. If \code{TRUE}, and we are releasing existing constraints,
compute the expected parameter changes for the existing (free) parameters,
for each released constraint.}
\item{standardized}{If \code{TRUE}, two extra columns (sepc.lv and sepc.all)
in the \code{$epc} table
will contain standardized values for the EPCs. In the first column (sepc.lv),
standardization is based on the variances of the (continuous) latent
variables. In the second column (sepc.all), standardization is based
on the variances of both (continuous) observed and latent variables.
(Residual) covariances are standardized using (residual) variances.}
\item{cov_std}{Logical. See \code{\link{standardizedSolution}}.}
\item{verbose}{Logical. Not used for now.}
\item{warn}{Logical. If \code{TRUE}, print out warnings if they occur.}
\item{information}{\code{character} indicating the type of information matrix
to use (check \code{\link{lavInspect}} for available options). \code{"expected"}
information is the default, which provides better control of Type I errors.}
\item{...}{to allow use of old argumentname cov_std}
}
\details{
    This function can be used to compute both multivariate and univariate
    score tests. There are two modes: 1) releasing fixed-to-zero parameters
    (using the \code{add} argument), and 2) releasing existing equality
    constraints (using the \code{release} argument). The two modes cannot
    be used simultaneously.

    When adding new parameters, they should not already be part of the model
    (i.e. not listed in the parameter table). If you want to test for
    a parameter that was explicitly fixed to a constant (say to zero),
    it is better to label the parameter, and use an explicit equality
    constraint.

    In addition to the standard (normal-theory) score test, robust
    versions are computed whenever the fitted object provides the
    ingredients for a sandwich-type covariance matrix: either because
    robust standard errors were requested (e.g.,
    \code{se = "robust.sem"} or \code{se = "robust.huber.white"}), or
    because a scaled test statistic was requested (e.g.,
    \code{test = "satorra.bentler"}). Following Satorra (2000), three
    robust versions are reported: a mean-scaled statistic
    (\code{score.scaled}), a mean-and-variance adjusted statistic with
    fractional degrees of freedom (\code{score.adjusted}), and the
    generalized, asymptotically distribution-free statistic
    (\code{score.robust}). For a single restriction, the three versions
    coincide. The univariate (and cumulative) score tests are then
    accompanied by scaled counterparts in the \code{X2.scaled} column.
    Note that for estimators that are not asymptotically efficient
    (e.g., \code{DWLS}, \code{ULS} and \code{PML}), only the robust
    versions have the correct asymptotic distribution.
}
\value{
  A list containing at least one \code{data.frame}:
  \itemize{
    \item \code{$test}: The total score test, with columns for the score
      test statistic (\code{X2}), the degrees of freedom (\code{df}), and
      a \emph{p} value under the \eqn{\chi^2} distribution (\code{p.value}).
      If robust versions could be computed, three additional rows are
      included: \code{score.scaled}, \code{score.adjusted} and
      \code{score.robust} (see Details).
    \item \code{$uni}: Optional (if \code{univariate=TRUE}).
      Each 1-\emph{df} score test, equivalent to modification indices.
      If robust versions could be computed, the scaled statistics are
      provided in the \code{X2.scaled} and \code{p.value.scaled} columns.
      If \code{epc=TRUE} when \code{add}ing parameters (not when releasing
      constraints), an unstandardized EPC is provided for each added
      parameter, as would be returned by \code{\link{modificationIndices}}.
    \item \code{$cumulative}: Optional (if \code{cumulative=TRUE}).
      Cumulative score tests, with scaled counterparts if robust versions
      could be computed.
    \item \code{$epc}: Optional (if \code{epc=TRUE}). Parameter estimates,
      expected parameter changes, and expected parameter values if all
      the tested constraints were freed.
  }
}
\references{
Bentler, P. M., & Chou, C. P. (1993). Some new covariance structure model
improvement statistics. Sage Focus Editions, 154, 235-255.

Satorra, A. (2000). Scaled and adjusted restricted tests in multi-sample
analysis of moment structures. In Heijmans, R.D.H., Pollock, D.S.G. &
Satorra, A. (Eds.), Innovations in multivariate statistical analysis:
A festschrift for Heinz Neudecker (pp. 233-247). London: Kluwer Academic
Publishers.
}

\examples{
HS.model <- '
    visual  =~ x1 + b1*x2 + x3
    textual =~ x4 + b2*x5 + x6
    speed   =~ x7 + b3*x8 + x9

    b1 == b2
    b2 == b3
'
fit <- cfa(HS.model, data=HolzingerSwineford1939)

# test 1: release both two equality constraints
lavTestScore(fit, cumulative = TRUE)

# test 2: the score test for adding two (currently fixed
# to zero) cross-loadings
newpar = '
    visual =~ x9
    textual =~ x3
'
lavTestScore(fit, add = newpar)

# equivalently, "add" can be a parameter table specifying parameters to free,
# but must include some additional information:
PT.add <- data.frame(lhs = c("visual","textual"),
                     op = c("=~","=~"),
                     rhs = c("x9","x3"),
                     user = 10L, # needed to identify new parameters
                     free = 1, # arbitrary numbers > 0
                     start = 0) # null-hypothesized value
PT.add
lavTestScore(fit, add = PT.add) # same result as above

}
