% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lav_localfit.R
\name{lav_localfit}
\alias{lav_localfit}
\alias{print.lav_localfit}
\alias{summary.lav_localfit}
\alias{plot.lav_localfit}
\title{Local fit diagnostics for fitted \code{lavaan} models}
\usage{
lav_localfit(
  fit,
  group = 1L,
  type = "cor.bentler",
  thresholds = c(1.96, 2.58),
  top_n = 10L,
  triangle = "lower",
  include_diagonal = FALSE,
  plot = TRUE,
  plot_style = "trafficlight",
  show_values = FALSE,
  digits = 3L,
  good_color = "#009E73",
  moderate_color = "#F0E442",
  poor_color = "#D55E00",
  neg_color = "#3B4CC0",
  pos_color = "#B40426",
  na_color = "grey90",
  return_data = FALSE
)

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

\method{summary}{lav_localfit}(object, ...)

\method{plot}{lav_localfit}(x, y = NULL, ...)
}
\arguments{
\item{fit}{A fitted \code{lavaan} object.}

\item{group}{Group to inspect in a multigroup model. May be either a numeric
group index or a character group label. Ignored for single-group models.}

\item{type}{Character string passed to \code{lavaan::lavResiduals()}.
Common choices are \code{"cor.bentler"} (default), \code{"raw"},
\code{"cor"}, and \code{"cor.bollen"}.}

\item{thresholds}{Numeric vector of length 2 giving the descriptive cutoffs
used for standardized residual magnitudes. The first value separates
\code{"minor"} from \code{"moderate"} discrepancies; the second separates
\code{"moderate"} from \code{"notable"} discrepancies. Used for the
traffic-light heatmap and for printed summaries. Defaults to
\code{c(1.96, 2.58)}, as per common z-based guidelines.}

\item{top_n}{Integer. Number of largest absolute standardized covariance
residuals to report in the output table.}

\item{triangle}{Character string. Either \code{"lower"} or \code{"full"}.
If \code{"lower"}, only the lower triangle of the covariance residual
matrix is used in the heatmap and top-residual table.}

\item{include_diagonal}{Logical. If \code{TRUE}, include diagonal elements
(variance residuals) in the covariance residual diagnostics.}

\item{plot}{Logical. If \code{TRUE}, produce a heatmap of covariance residual
misfit.}

\item{plot_style}{Character string. Either \code{"trafficlight"} or
\code{"signed"}. The default \code{"trafficlight"} plots the absolute
standardized covariance residuals in descriptive magnitude categories. The
\code{"signed"} option plots signed standardized residuals on a diverging
color scale.}

\item{show_values}{Logical. If \code{TRUE}, overlay numeric residual values on
the heatmap tiles.}

\item{digits}{Non-negative integer giving the default number of digits used
in printed output and numeric labels.}

\item{good_color}{Fill color for \code{"minor"} discrepancies in the
traffic-light heatmap.}

\item{moderate_color}{Fill color for \code{"moderate"} discrepancies in the
traffic-light heatmap.}

\item{poor_color}{Fill color for \code{"notable"} discrepancies in the
traffic-light heatmap.}

\item{neg_color}{Fill color for negative residuals in the signed heatmap.}

\item{pos_color}{Fill color for positive residuals in the signed heatmap.}

\item{na_color}{Fill color for cells omitted from the heatmap, such as the
upper triangle when \code{triangle = "lower"}.}

\item{return_data}{Logical. If \code{TRUE}, include the long-format heatmap
data frame in the returned object.}

\item{x}{A \code{"lav_localfit"} object.}

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

\item{object}{A \code{"lav_localfit"} object.}

\item{y}{Ignored.}
}
\value{
A list of class \code{"lav_localfit"} with elements:
\itemize{
  \item \code{summary}: residual summary returned by
    \code{lavaan::lavResiduals()} for the selected group;
  \item \code{cov_residuals}: covariance residual matrix for the selected
    group;
  \item \code{cov_z}: standardized covariance residual matrix;
  \item \code{mean_residuals}: mean residual vector, if available;
  \item \code{mean_z}: standardized mean residual vector, if available;
  \item \code{top_cov_residuals}: data frame of the largest absolute
    standardized covariance residuals;
  \item \code{top_mean_residuals}: data frame of the largest absolute
    standardized mean residuals;
  \item \code{counts}: list with counts of covariance residuals exceeding the
    descriptive thresholds, the maximum absolute standardized covariance
    residual, and the corresponding variable pair;
  \item \code{plot}: a \code{ggplot} heatmap object, or \code{NULL} if
    \code{plot = FALSE};
  \item \code{group}: numeric index of the selected group;
  \item \code{group_label}: character label of the selected group;
  \item \code{type}: residual type used;
  \item \code{thresholds}: thresholds used for descriptive classification;
  \item \code{digits}: default number of digits for printing;
  \item \code{call}: matched function call;
  \item \code{plot_data}: only when \code{return_data = TRUE}, the long-format
    data used to build the heatmap.
}
}
\description{
Evaluate local fit in a fitted \code{lavaan} model from residual-based
diagnostics. The function extracts residual summaries, computes standardized 
covariance and mean residual diagnostics, identifies the largest local 
discrepancies, and builds a heatmap of covariance residual misfit. 
By default, the function computes Bentler-standardized residual summaries and
standardized covariance residual diagnostics suitable for screening localized
strain in the model. 
The default plot is a traffic-light heatmap of the absolute standardized
covariance residuals.
}
\section{Notes}{

In this function, local fit is evaluated from residuals of the sample summary
statistics rather than from casewise prediction errors. Standardized residuals
are used to screen where the model reproduces specific covariances or means
poorly. The default thresholds are descriptive aids only. They should not be
treated as formal decision rules or as substitutes for theory-based model
evaluation. When the fitted object uses bootstrap standard errors,
standardized residual diagnostics are obtained from an auxiliary refit of the
same model without bootstrap.
}

\examples{
model <- "
ind60 =~ x1 + x2 + x3
dem60 =~ y1 + y2 + y3 + y4
dem65 =~ y5 + y6 + y7 + y8
dem60 ~ ind60
dem65 ~ ind60 + dem60
y1 ~~ y5
y2 ~~ y6
"
fit <- lavaan::sem(
model = model, 
data = lavaan::PoliticalDemocracy,
std.lv = TRUE, 
estimator = "MLR", 
meanstructure = TRUE)

lav_localfit(fit)

}
\references{
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}

Schermelleh-Engel, K., Moosbrugger, H., & Muller, H. (2003). Evaluating the
fit of structural equation models: Tests of significance and descriptive
goodness-of-fit measures. \emph{Methods of Psychological Research Online},
\emph{8}(2), 23-74.
}
\seealso{
\code{\link[lavaan]{lavResiduals}} for residual extraction and
  \code{\link{lav_deltaR2}} for local structural effect-size diagnostics.
}
