% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lav_jn.R
\name{lav_jn}
\alias{lav_jn}
\alias{print.lav_jn}
\alias{summary.lav_jn}
\title{Johnson-Neyman regions of significance for fitted 'lavaan' models}
\usage{
lav_jn(
  fit,
  outcome,
  pred,
  modx,
  interaction,
  data = NULL,
  conf.level = 0.95,
  modx.range = NULL,
  n_grid = 1000L,
  x.label = NULL,
  y.label = NULL,
  sig.color = "#009E73",
  nonsig.color = "#D55E00",
  line.color = "#0072B2",
  alpha = 0.20,
  line.size = 0.80,
  rug = TRUE,
  plot = TRUE,
  digits = 3L,
  return_data = FALSE
)

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

\method{summary}{lav_jn}(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 conditional slope
is probed (required).}

\item{modx}{Character. Name of the continuous moderator (required). If
\code{modx} is categorical (fewer than 4 unique values), the function
stops with a message directing the user to \code{\link{lav_slopes}}.}

\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{conf.level}{Numeric in (0, 1). Confidence level for the Wald band and
the JN critical value (default: 0.95).}

\item{modx.range}{Numeric vector of length 2. Range \code{c(min, max)} for
the moderator axis. If \code{NULL}, the observed range of \code{modx} in
the data is used, extended by 5\% on each side for visual padding
(default: NULL).}

\item{n_grid}{Integer. Number of moderator values at which the conditional
slope is evaluated for plotting (default: 1000).}

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

\item{y.label}{Character. Y-axis label (default: \code{"Conditional slope of <pred>"}).}

\item{sig.color}{Character. Fill color for significant-slope regions
(default: \code{"#009E73"}, Okabe-Ito bluish green).}

\item{nonsig.color}{Character. Fill color for non-significant regions
(default: \code{"#D55E00"}, Okabe-Ito vermillion).}

\item{line.color}{Character. Color for the conditional-slope line
(default: \code{"#0072B2"}, Okabe-Ito blue).}

\item{alpha}{Numeric in (0, 1). Opacity of the confidence ribbon and the
region shading (default: 0.20).}

\item{line.size}{Numeric > 0. Width of the conditional-slope line
(default: 0.80).}

\item{rug}{Logical. If \code{TRUE}, draw a rug (density strip) of observed
moderator values along the x-axis (default: TRUE).}

\item{plot}{Logical. If \code{TRUE}, produce the JN plot (default: TRUE).}

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

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

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

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

\item{object}{A 'lav_jn' object.}
}
\value{
A list of class \code{"lav_jn"} with elements:
\describe{
  \item{\code{jn_points}}{Numeric vector of length 0, 1, or 2 giving the
    Johnson-Neyman boundary values of the moderator (the roots of the
    quadratic). \code{numeric(0)} when no real root exists.}
  \item{\code{signif_regions}}{A data frame with columns \code{lower},
    \code{upper}, and \code{significance} (\code{"significant"} or
    \code{"non-significant"}), describing the regions over the observed
    moderator range.}
  \item{\code{plot}}{A \code{ggplot} object (or \code{NULL} when
    \code{plot = FALSE}).}
  \item{\code{observed_support}}{Numeric length-2: the minimum and maximum of
    the observed moderator values.}
  \item{\code{interaction_test}}{List with the unstandardized interaction
    coefficient (\code{b}), its \code{se}, \code{z}, \code{p}, Wald
    confidence interval (\code{ci}), and standardized beta (\code{beta_std}).}
  \item{\code{labels}}{List of the user-supplied variable names.}
  \item{\code{conf.level}}{Confidence level used.}
  \item{\code{digits}}{Default digits for printing.}
  \item{\code{call}}{Matched call.}
  \item{\code{plot_data}}{Only when \code{return_data = TRUE}: data frame
    used to build the plot.}
}
}
\description{
Computes the Johnson-Neyman (JN) interval for a continuous moderator from a
fitted 'lavaan' model that includes an explicit product term. 
Plots the conditional slope with a confidence band, shaded significance
regions, and an observed-moderator density strip.
}
\details{
The model should include a main effect for the predictor, a main effect for
the moderator, and their product term. Standard errors are obtained via the
delta method using the model-implied covariance matrix of the parameter
estimates. If the model was fitted with a robust estimator (e.g., MLR),
the robust covariance matrix returned by \code{vcov(fit)} is used
automatically, so no separate correction is needed.

The JN boundary values are the real roots of the quadratic equation that
equates the squared conditional slope to the squared critical value times
its variance. When the discriminant is negative, the conditional slope is
either significant or non-significant across the entire moderator range and
no finite boundary exists.

This function is restricted to continuous moderators. For categorical
moderators, use \code{\link{lav_slopes}}.
}
\section{Notes}{

All estimates are unstandardized; a standardized coefficient for the interaction is
also reported for reference. Wald tests assume large-sample normality of the
parameter estimates. When the discriminant of the JN quadratic is negative,
the conditional slope is either significant or non-significant everywhere;
the function reports which case applies rather than returning a boundary.
}

\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_jn(
fit = fit,
outcome = "Y",
pred = "X",
modx = "Z",
interaction = "X_Z"
)

}
\references{
Johnson, P. O., & Neyman, J. (1936). Tests of certain linear hypotheses and
their application to some educational problems. \emph{Statistical Research
Memoirs}, \emph{1}, 57-93.

Bauer, D. J., & Curran, P. J. (2005). Probing interactions in fixed and
multilevel regression: Inferential and graphical techniques.
\emph{Multivariate Behavioral Research}, \emph{40}(3), 373-400.
\doi{10.1207/s15327906mbr4003_5}

Carden, S. W., Holtzman, N. S., & Strube, M. J. (2017). CAHOST: An Excel
workbook for facilitating the Johnson-Neyman technique for two-way
interactions in multiple regression. \emph{Frontiers in Psychology},
\emph{8}, Article 1293. \doi{10.3389/fpsyg.2017.01293}
}
\seealso{
\code{\link{lav_slopes}} for pick-a-point simple slopes.
}
