% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nl_het.R
\name{nl_het}
\alias{nl_het}
\title{Cluster heterogeneity in nonlinear effects}
\usage{
nl_het(
  object,
  n_clusters_plot = 30L,
  x_seq = NULL,
  level = 0.95,
  plot = TRUE,
  seed = 42L
)
}
\arguments{
\item{object}{An \code{nl_fit} object fitted with a single \code{cluster}
variable (and either \code{random_slope = TRUE} or \code{FALSE}; in the
latter case the model is refit internally).}

\item{n_clusters_plot}{Maximum number of cluster curves to display in the
trajectory plot. Default \code{30L}. Use \code{Inf} for all clusters.}

\item{x_seq}{Optional numeric vector of x values for prediction.}

\item{level}{Confidence level for the population-mean ribbon. Default
\code{0.95}.}

\item{plot}{Logical; print the trajectory plot. Default \code{TRUE}.}

\item{seed}{Integer seed for reproducibility when sub-sampling clusters.
Default \code{42L}.}
}
\value{
A list (invisibly) with:
\describe{
\item{\code{trajectory_df}}{Long data frame of cluster-specific
predicted values.}
\item{\code{slope_variance}}{Named numeric: SD of first-derivative
estimates across clusters at each x value.}
\item{\code{lrt}}{LRT comparing random-slope vs random-intercept model
(\code{NULL} if \code{random_slope = TRUE} was supplied).}
\item{\code{plot}}{A \code{ggplot} object.}
}
}
\description{
Quantifies and visualises how much the nonlinear relationship between
\code{x} and \code{y} varies across clusters, using a model with random
spline slopes.

The function:
\enumerate{
\item Refits the model with random spline slopes (if not already fitted
with \code{random_slope = TRUE}).
\item Extracts cluster-specific predicted curves (BLUPs).
\item Returns a heterogeneity summary: variance of slopes across clusters
at each x value, and a plot of the cluster-specific trajectories.
\item Performs a likelihood-ratio test comparing the random-slope model
against a random-intercept-only model to assess whether heterogeneity
is statistically significant.
}
}
\seealso{
\code{\link{nl_fit}}, \code{\link{nl_derivatives}}
}
