% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/difftest.chibarsq.R
\name{difftest.chibarsq}
\alias{difftest.chibarsq}
\title{Chi-Bar-Square Difference Test}
\usage{
difftest.chibarsq(clpm, riclpm, alpha = 0.05, digits = 2, p.digits = 3,
                  write = NULL, append = TRUE, check = TRUE, output = TRUE)
}
\arguments{
\item{clpm}{an object of class lavaan, i.e., a fitted random intercept
cross-lagged panel model (RI-CLPM) with the variance and
covariances of latent intercept factors fixed to zero. Note
that a RI-CLPM with the variance of all random intercepts
fixed to zero is statistically equivalent to the traditional
cross-lagged panel model (CLPM).}

\item{riclpm}{an object of class lavaan, i.e., a fitted random intercept
cross-lagged panel model with variance and covariances of
latent intercept factors freely estimated.}

\item{alpha}{a numeric value indicating the type-I-risk, \eqn{\alpha}.}

\item{digits}{an integer value indicating the number of decimal places
to be used for displaying results.}

\item{p.digits}{an integer value indicating the number of decimal places
to be used for displaying the \emph{p}-values.}

\item{write}{a character string naming a file for writing the output into
either a text file with file extension \code{".txt"} (e.g.,
\code{"Output.txt"}) or Excel file with file extension
\code{".xlsx"}  (e.g., \code{"Output.xlsx"}). If the file
name does not contain any file extension, an Excel file will
be written.}

\item{append}{logical: if \code{TRUE} (default), output will be appended
to an existing text file with extension \code{.txt} specified
in \code{write}, if \code{FALSE} existing text file will be
overwritten.}

\item{check}{logical: if \code{TRUE} (default), argument specification is checked.}

\item{output}{logical: if \code{TRUE} (default), output is shown on the console.}
}
\value{
Returns an object of class \code{misty.object}, which is a list with following
entries:

\item{\code{call}}{function call}
\item{\code{type}}{type of analysis}
\item{\code{model}}{data frame including all variables used in the analysis, i.e.,
                   indicators for the factor, grouping variable and cluster
                   variable}
\item{\code{args}}{specification of function arguments}
\item{\code{model.fit}}{list of fitted lavaan objects specified in the argument
                       \code{riclpm} and \code{clpm}}
\item{\code{result}}{list with result tables, i.e., \code{difftest} for the
                     chi-bar-square difference test and \code{weights} for the
                     weights for the mixture of chi-square mixture distribution}
}
\description{
This function performs the chi-bar-square difference test to compare the random
intercept cross-lagged panel model (RI-CLPM) and traditional cross-lagged panel
model (CLPM) as discussed in Hamaker et al. (2015).
}
\details{
\describe{
\item{\strong{Random Intercept Cross-Lagged Panel Model (RI-CLPM)}}{The RI-CLPM
is an extension of the traditional cross-lagged panel model that disentangles the
within-person process from stable between-person differences (Hamaker et al., 2015).
In a bivariate RI-CLPM, each variable \eqn{x} and \eqn{y} is decomposed into a
stable time-invariant trait-like component, captured with random intercept factors
denoted by \eqn{\kappa} for variable \eqn{x} and \eqn{\omega} for variable \eqn{y}
(see Figure 1 in Hamaker et al., 2015). Note that the CLPM is nested under the
RI-CLPM, i.e., the RI-CLPM is statistically equivalent to the CLPM when fixing
the variance of all random intercepts and their covariances to zero.}

\item{\strong{Chi-Bar-Square Difference Test}}{The \eqn{\bar{\chi^2}} difference
test is used to compare the fit of the nested models CLPM and RI-CLPM based on
a mixture of chi-square distributions to test the null hypothesis e.g.,
\eqn{H_0: Var_{\kappa} = 0, Var_{\omega} = 0, Cov_{\kappa, \omega} = 0}.
The chi-bar-square distribution is a weighted sum of different chi-square distributions
with varying degrees of freedom resulting from parameters fixed at the boundaries
of the parameter space as variances are non-negative values (Stoel et al., 2016).}

\item{\strong{Chi-Square Difference Test}}{The regular \eqn{\chi^2} difference
test is conservative due to ignoring the mixture distribution, i.e., if it is
statistically significant, we are certain that the chi-bar-square difference test
will be significant too, while the reverse will not be the case. Accordingly, if
researchers find it more important to detect a true CLPM than a true RI-CLPM, it
is advised to use the regular chi-square difference test (Sukpan & Kuiper, 2026).
It should also be mentioned that estimating a RI-CLPM when the CLPM is the true
model may reduce statistical power due to estimating additional parameters, but
it does not introduce bias (see Table 4 in Scott, 2021), while estimating a CLPM
when the RI-CLPM is the true model introduces bias (see Table 3 in Scott, 2021).}
}
}
\note{
This function is based on modified copies of the function \code{ChiBarSq.DiffTest}
from the \pkg{ChiBarSq.DiffTest} package by Rebecca M. Kuiper.
}
\examples{
\dontrun{
#————————————————————————————————————————————————————————————————————————————
# Step-wise Procedure (Sukpan & Kuiper, 2026)
#
# Note that only the first step is shown in this example:
# - CLPM versus RI-CLPM(Kappa)
# - CLPM versus RI-CLPM(Omega)
#
# Model specification based on code provided on the accompanying website of
# Mulder and Hamaker (2021)

#···················
# Model Specification: Cross-Lagged Panel Model (CLPM)
# i.e., Var(Kappa) = 0, Var(Omega) = 0, Cov(Kappa, Omega) = 0

mod.clpm <- '
  # Create between components (random intercepts)
  RIx =~ 1*x1 + 1*x2 + 1*x3
  RIy =~ 1*y1 + 1*y2 + 1*y3

  # Create within-person centered variables
  wx1 =~ 1*x1
  wx2 =~ 1*x2
  wx3 =~ 1*x3
  wy1 =~ 1*y1
  wy2 =~ 1*y2
  wy3 =~ 1*y3

  # Estimate lagged effects between within-person centered variables
  wx2 + wy2 ~ wx1 + wy1
  wx3 + wy3 ~ wx2 + wy2

  # Estimate covariance between within-person centered variables at first wave
  wx1 ~~ wy1 # Covariance

  # Estimate covariances between residuals of within-person centered variables
  wx2 ~~ wy2
  wx3 ~~ wy3

  # Fix variance and covariance of random intercepts to zero, i.e.,
  RIx ~~ 0*RIx
  RIy ~~ 0*RIy
  RIx ~~ 0*RIy

  # Estimate (residual) variance of within-person centered variables
  wx1 ~~ wx1
  wy1 ~~ wy1
  wx2 ~~ wx2
  wy2 ~~ wy2
  wx3 ~~ wx3
  wy3 ~~ wy3
'

#···················
# Model Specification: Random Intercept Cross-Lagged Panel Model RI-CLPM(Kappa)
# i.e., Var(Kappa) > 0, Var(Omega) = 0, Cov(Kappa, Omega) = 0

mod.ri.clpm.k <- '
  # Create between components (random intercepts)
  RIx =~ 1*x1 + 1*x2 + 1*x3
  RIy =~ 1*y1 + 1*y2 + 1*y3

  # Create within-person centered variables
  wx1 =~ 1*x1
  wx2 =~ 1*x2
  wx3 =~ 1*x3
  wy1 =~ 1*y1
  wy2 =~ 1*y2
  wy3 =~ 1*y3

  # Estimate lagged effects between within-person centered variables
  wx2 + wy2 ~ wx1 + wy1
  wx3 + wy3 ~ wx2 + wy2

  # Estimate covariance between within-person centered variables at first wave
  wx1 ~~ wy1

  # Estimate covariances between residuals of within-person centered variables
  wx2 ~~ wy2
  wx3 ~~ wy3

  # Fix variance of random intercept RIy and covariance with RIx to zero
  RIx ~~ RIx
  RIy ~~ 0*RIy
  RIx ~~ 0*RIy

  # Estimate (residual) variance of within-person centered variables
  wx1 ~~ wx1
  wy1 ~~ wy1
  wx2 ~~ wx2
  wy2 ~~ wy2
  wx3 ~~ wx3
  wy3 ~~ wy3
'

#···················
# Model Specification: Random Intercept Cross-Lagged Panel Model RI-CLPM(Omega)
# i.e., Var(Kappa) = 0, Var(Omega) > 0, Cov(Kappa, Omega) = 0

mod.ri.clpm.o <- '
  # Create between components (random intercepts)
  RIx =~ 1*x1 + 1*x2 + 1*x3
  RIy =~ 1*y1 + 1*y2 + 1*y3

  # Create within-person centered variables
  wx1 =~ 1*x1
  wx2 =~ 1*x2
  wx3 =~ 1*x3
  wy1 =~ 1*y1
  wy2 =~ 1*y2
  wy3 =~ 1*y3

  # Estimate lagged effects between within-person centered variables
  wx2 + wy2 ~ wx1 + wy1
  wx3 + wy3 ~ wx2 + wy2

  # Estimate covariance between within-person centered variables at first wave
  wx1 ~~ wy1 # Covariance

  # Estimate covariances between residuals of within-person centered variables
  wx2 ~~ wy2
  wx3 ~~ wy3

  # Fix variance of random intercept RIx and covariance with RIy to zero
  RIx ~~ 0*RIx
  RIy ~~ RIy
  RIx ~~ 0*RIy

  # Estimate (residual) variance of within-person centered variables
  wx1 ~~ wx1
  wy1 ~~ wy1
  wx2 ~~ wx2
  wy2 ~~ wy2
  wx3 ~~ wx3
  wy3 ~~ wy3
'

#···················
# Estimate Models
#
# Note that the example analysis cannot be conduct as the data set 'data'
# is not available.

# CLPM
fit.clpm <- lavaan(mod.clpm, data = data, estimator = "MLR")

# RI-CLPM(Kappa)
fit.ri.clpm.k <- lavaan(mod.ri.clpm.k, data = data, estimator = "MLR")

# RI-CLPM(Omega)
fit.ri.clpm.o <- lavaan(mod.ri.clpm.o, data = data, estimator = "MLR")

#···················
# Chi-Bar-Square Difference Test

# CLPM vs. RI-CLPM(Kappa)
difftest.chibarsq(fit.clpm, fit.ri.clpm.k)

# CLPM vs. RI-CLPM(Omega)
difftest.chibarsq(fit.clpm, fit.ri.clpm.o)
}
}
\references{
Hamaker, E. L., Kuiper, R. M., & Grasman, R. P. (2015). A critique of the
cross-lagged panel model. \emph{Psychological Methods, 20}(1), 102-116.
https://doi.org/10.1037/a0038889

Kuiper R (2026). \emph{ChiBarSq.DiffTest: Chi-bar-square difference test of the
RI-CLPM versus the CLPM and more general}. R package version 0.0.0.9000.
https://github.com/rebeccakuiper/ChiBarSq.DiffTest

Mulder, J. D., & Hamaker, E. L. (2021). Three extensions of the random intercept
cross-lagged panel model. \emph{Structural Equation Modeling: A Multidisciplinary Journal, 28}(4),
638-648. https://doi.org/10.1080/10705511.2020.1784738

Scott, P. W. (2021). Accounting for time-varying inter-individual differences
in trajectories when assessing cross-lagged models. \emph{Structural Equation Modeling, 28}(3),
365-375. https://doi.org/10.1080/10705511.2020.1819815

Stoel, R. D., Garre, F. G., Dolan, C., & van den Wittenboer, G. (2006). On
the likelihood ratio test in structural equation modeling when parameters
are subject to boundary constraints. \emph{Psychological Methods, 11}(4),
439-455. https://doi.org/10.1037/1082-989X.11.4.439

Sukpan, C., & Kuiper, R. M. (2026). Selecting the correct RI-CLPM using
chi-square-type tests and AIC-type criteria. \emph{Structural Equation Modeling: A Multidisciplinary Journal},
1-14. https://doi.org/10.1080/10705511.2025.2592831
}
\author{
Takuya Yanagida
}
