% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lav_deltaR2.R
\name{lav_deltaR2}
\alias{lav_deltaR2}
\alias{print.lav_deltaR2}
\alias{summary.lav_deltaR2}
\title{Incremental effect sizes for structural predictors in fitted \code{lavaan} models}
\usage{
lav_deltaR2(
  fit,
  data = NULL,
  outcome = NULL,
  terms = NULL,
  block = NULL,
  quiet = TRUE,
  digits = 3L
)

\method{print}{lav_deltaR2}(x, ...)

\method{summary}{lav_deltaR2}(object, ...)
}
\arguments{
\item{fit}{A fitted \code{lavaan} object.}

\item{data}{Optional data frame used to fit \code{fit}. If supplied, this data
frame is used to refit reduced models. If \code{NULL}, reduced models are
refit using the internal data and options stored in \code{fit}.}

\item{outcome}{Optional character vector naming endogenous variables for which
incremental effect sizes should be computed. If \code{NULL}, all endogenous
variables with at least one free structural predictor are used.}

\item{terms}{Optional character vector naming predictors to test one at a
time. Ignored if \code{block} is supplied. If \code{NULL}, all eligible
structural predictors are tested individually.}

\item{block}{Optional character vector naming predictors to remove jointly.
When supplied, one reduced-model comparison is computed per selected outcome
for the entire predictor block. A block is evaluated only for outcomes in
which all named predictors appear as free structural regressors.}

\item{quiet}{Logical. If \code{TRUE}, suppress reduced-model refit messages.}

\item{digits}{Non-negative integer giving the default number of digits used in
printing.}

\item{x}{A 'lav_deltaR2' object.}

\item{...}{Additional arguments; unused.}

\item{object}{A 'lav_deltaR2' object.}
}
\value{
A list with:
\itemize{
  \item \code{delta_r2_table}: A data frame containing one row per
  outcome-by-test comparison, with columns:
  \itemize{
    \item \code{outcome}: endogenous variable whose \eqn{R^2} is evaluated;
    \item \code{tested_set}: predictor or predictor block fixed to zero in the
      reduced model;
    \item \code{test_type}: either \code{"single"} or \code{"block"};
    \item \code{n_terms}: number of predictors removed jointly;
    \item \code{group}: numeric group index;
    \item \code{group_label}: group label, if available;
    \item \code{r2_full}: \eqn{R^2} from the fitted model;
    \item \code{r2_reduced}: \eqn{R^2} from the reduced model;
    \item \code{delta_r2}: \eqn{R^2_{full} - R^2_{reduced}};
    \item \code{part_r2}: equal to \code{delta_r2} in this implementation;
    \item \code{f2}: Cohen's \eqn{f^2};
    \item \code{f2_magnitude}: conventional descriptive interpretation of
      \code{f2} based on Cohen's benchmarks (\code{"negligible"},
      \code{"small"}, \code{"medium"}, or \code{"large"});
    \item \code{converged}: logical indicator of whether the reduced model
      converged.
  }
  \item \code{settings}: list of user-supplied function settings;
  \item \code{group_var}: grouping variable name, or \code{NULL};
  \item \code{group_labels}: group labels, if available;
  \item \code{call}: matched function call;
  \item \code{digits}: default number of digits used for printing.
}
}
\description{
Compute outcome-specific incremental effect sizes for structural predictors in
a fitted \code{lavaan} model by comparing the fitted model with nested reduced
models in which one predictor, or a block of predictors, is fixed to zero.
For each tested predictor set, the function returns the reduction in explained
variance (\eqn{\Delta R^2}), the corresponding part \eqn{R^2}, and Cohen's
\eqn{f^2 = \Delta R^2 / (1 - R^2_{full})}.
}
\details{
Reduced models preserve all untargeted model parameters and differ from the
fitted model only in that the tested structural regression path(s) are fixed
to zero. Accordingly, the resulting \eqn{\Delta R^2} quantifies the unique
contribution of the tested predictor or predictor block to the explained
variance of a given endogenous variable, conditional on the rest of the model.

If \code{data} is supplied, reduced models are refit from that data set.
Otherwise, the function reuses the internal data and fitting options stored in
\code{fit}. The function is intended for converged \code{lavaan} models with
free structural regressions.
}
\section{Notes}{

For a given endogenous variable, \eqn{\Delta R^2} is the reduction in
explained variance obtained when the tested predictor or predictor block is
fixed to zero, and the reduced model is refit with all untargeted parameters
left free.
In this implementation, part \eqn{R^2} is numerically identical to \eqn{\Delta R^2}. 
Cohen's \eqn{f^2} expresses the same quantity relative to the residual variance of the
full model. The \code{f2_magnitude} column applies Cohen's conventional 
benchmarks to \eqn{f^2} and is intended only as a descriptive aid.
}

\examples{
library("lavaan")
data("PoliticalDemocracy", 
package = "lavaan")
model <- "
ind60 =~ x1 + x2 + x3
dem60 =~ y1 + y2 + y3 + y4
dem65 =~ y5 + y6 + y7 + y8
dem60 ~ ind60
dem65 ~ ind60 + dem60
y1 ~~ y5
y2 ~~ y4 + y6
y3 ~~ y7
y4 ~~ y8
y6 ~~ y8
"
fit <- lavaan::sem(model, 
data = PoliticalDemocracy)
lav_deltaR2(fit = fit)
lav_deltaR2(fit = fit, outcome = "dem65")
lav_deltaR2(fit = fit, outcome = "dem65", terms = "ind60")
lav_deltaR2(fit = fit, outcome = "dem65", block = c("ind60", "dem60"))

}
\references{
Cohen, J. (1988). \emph{Statistical power analysis for the behavioral sciences}
(2nd ed.). Lawrence Erlbaum Associates.

Rosseel, Y. (2012). lavaan: An R package for structural equation modeling.
\emph{Journal of Statistical Software}, \emph{48}(2), 1-36.
\doi{10.18637/jss.v048.i02}
}
\seealso{
\code{\link{lav_cv}} for cross-validated \eqn{R^2}, \code{\link{lav_vif}}
  for variance inflation factors.
}
