% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lav_slopes.R
\name{lav_slopes}
\alias{lav_slopes}
\alias{print.lav_slopes}
\alias{summary.lav_slopes}
\title{Simple slopes and interaction plots for fitted 'lavaan' models}
\usage{
lav_slopes(
  fit,
  outcome,
  pred,
  modx,
  interaction,
  data = NULL,
  modx.values = NULL,
  modx.labels = NULL,
  pred.range = NULL,
  conf.level = 0.95,
  x.label = NULL,
  y.label = NULL,
  legend.title = NULL,
  colors = NULL,
  line.size = 0.80,
  alpha = 0.20,
  table = TRUE,
  digits = 3L,
  modx_n_unique_cutoff = 4L,
  return_data = FALSE
)

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

\method{summary}{lav_slopes}(object, ...)
}
\arguments{
\item{fit}{A fitted 'lavaan' object that includes the product term (required).}

\item{outcome}{Character. Name of the dependent variable in \code{fit} (required).}

\item{pred}{Character. Name of the focal predictor whose simple slopes are probed (required).}

\item{modx}{Character. Name of the moderator. The moderator must appear in
the fitted model as a single numeric variable. General nominal moderators
with more than two categories are not supported.}

\item{interaction}{Character. Name of the product term in \code{fit} (e.g., \code{"X_Z"}) (required).}

\item{data}{\code{data.frame}. Optional raw data (not needed, retained for backward compatibility). 
The function automatically recovers observed data from \code{fit} when needed.}

\item{modx.values}{Numeric vector of moderator values at which to compute
simple slopes. If \code{NULL} and \code{modx} is observed and numeric, the
function uses mean minus 1 SD, the mean, and mean plus 1 SD for moderators
with more than \code{modx_n_unique_cutoff} unique values, and otherwise
uses the observed numeric values as discrete probe points. If \code{modx}
is latent in a single-group model, the function uses the estimated latent
mean minus 1 latent SD, the latent mean, and the latent mean plus 1 latent
SD.}

\item{modx.labels}{Character vector. Legend and table labels for \code{modx.values}.
By default, the labels are \code{c("-1 SD", "Mean", "+1 SD")} when values are derived as 
mean plus or minus 1 SD, and \code{as.character(modx.values)} otherwise.}

\item{pred.range}{Numeric vector of length 2. Range \code{c(min, max)} for the x-axis
for the focal predictor. If \code{NULL} and \code{pred} is observed, the observed 
range recovered from \code{fit} is used. If \code{pred} is latent in a single-group model, 
the function uses the estimated latent mean minus 2 latent SD and the latent mean plus 2 
latent SD. Otherwise, \code{c(-2, 2)} is used.}

\item{conf.level}{Numeric in (0,1). Confidence level for Wald confidence intervals and ribbons (default: 0.95).}

\item{x.label}{Character. X-axis label (default: \code{pred}).}

\item{y.label}{Character. Y-axis label (default: \code{outcome}).}

\item{legend.title}{Character. Legend title; if \code{NULL}, the legend shows only levels (default: NULL).}

\item{colors}{Character vector. Colors for lines and ribbons; named vector recommended with names matching \code{modx.labels} (default: Okabe-Ito palette).}

\item{line.size}{Numeric > 0. Line width (default: 0.80).}

\item{alpha}{Numeric in (0,1). Ribbon opacity (default 0.20).}

\item{table}{Logical. Print APA-style interaction test and simple-slopes table (default: \code{TRUE}).}

\item{digits}{Integer \code{>= 0}. Decimal digits in printed output (default: 3).}

\item{modx_n_unique_cutoff}{Integer \code{>= 1}. Threshold for treating a numeric moderator
as continuous and using mean ± SD (default: 4).}

\item{return_data}{Logical. If \code{TRUE}, include the plotting data.frame in the returned list (default: FALSE).}

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

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

\item{object}{A 'lav_slopes' object.}
}
\value{
A list of class \code{"lav_slopes"} with elements:
\describe{
  \item{\code{plot}}{\code{ggplot} object with lines and confidence ribbons.}
  \item{\code{slope_table}}{Data frame with moderator levels, simple slopes, SE, z, and CI.}
  \item{\code{plot_data}}{Only when \code{return_data = TRUE}: data used to build the plot.}
}
}
\description{
Computes conditional (simple) slopes of a focal predictor across values
of a moderator from a fitted 'lavaan' model that includes their explicit 
product term. Plots predicted lines with Wald confidence ribbons and prints
an APA-style test of the interaction for easy reporting and interpretation,
together with a simple slopes table.
}
\details{
The model should include a main effect for the predictor, a main effect for
the moderator, and one explicit product term between them.

The moderator must enter the fitted model as a single numeric
variable, which may be continuous, a binary observed moderator coded as a
single numeric dummy variable, an observed numeric moderator with a small
number of values treated as discrete probe points, or a latent moderator
treated as a single continuous latent variable. 

Standard errors use the delta method with the model covariance matrix of the
estimates. When moderator values are derived automatically for latent
moderators, probe points are based on the estimated latent mean and
model-implied latent standard deviation.
}
\section{Notes}{

Estimates are unstandardized; a standardized coefficient for the interaction is
also reported for reference. Wald tests assume large-sample normality of the
parameter estimates. Multigroup fitted models are not supported.
}

\examples{
set.seed(42)
X <- rnorm(100); Z <- rnorm(100); X_Z <- X*Z
Y <- 0.6*X + 0.6*Z + 0.3*X_Z + rnorm(100, sd = 0.7) 
dataset <- data.frame(Y, X, Z, X_Z)
fit <- lavaan::sem("Y ~ X + Z + X_Z", data = dataset)
lav_slopes(
fit = fit, 
outcome = "Y", 
pred = "X", 
modx = "Z", 
interaction = "X_Z")

}
\references{
Aiken, L. S., & West, S. G. (1991). \emph{Multiple regression: Testing and
interpreting interactions}. Sage.

Preacher, K. J., Curran, P. J., & Bauer, D. J. (2006). Computational tools
for probing interactions in multiple linear regression, multilevel modeling,
and latent curve analysis. \emph{Journal of Educational and Behavioral
Statistics}, \emph{31}(4), 437-448.
\doi{10.3102/10769986031004437}

Rogosa, D. (1980). Comparing nonparallel regression lines.
\emph{Psychological Bulletin}, \emph{88}(2), 307-321.
\doi{10.1037/0033-2909.88.2.307}
}
\seealso{
\code{\link{lav_jn}} for Johnson-Neyman regions of significance.
}
