% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nl_compare.R
\name{nl_compare}
\alias{nl_compare}
\title{Built-in model comparison workflow}
\usage{
nl_compare(
  object,
  polynomial_degrees = c(2L, 3L),
  digits = 3L,
  return_models = FALSE
)
}
\arguments{
\item{object}{An \code{nl_fit} object (the spline model to compare against).}

\item{polynomial_degrees}{Integer vector of polynomial degrees to include
as additional comparators. Default \code{c(2L, 3L)}. Set to
\code{integer(0)} to skip.}

\item{digits}{Integer; decimal places for the output table. Default \code{3}.}

\item{return_models}{Logical; if \code{TRUE}, also returns the fitted
comparison model objects. Default \code{FALSE}.}
}
\value{
A list (invisibly) of class \code{"nl_compare"} with:
\describe{
\item{\code{table}}{A data frame with the comparison statistics.}
\item{\code{models}}{Named list of fitted models (when
\code{return_models = TRUE}).}
\item{\code{best}}{Name of the model with the lowest AIC.}
}
The table is pretty-printed automatically.
}
\description{
Compares a nonlinear spline model against simpler alternatives—a linear
model and optional polynomial terms—to help researchers justify the
spline approach over simpler specifications.

For each model, the function reports:
\itemize{
\item AIC and BIC
\item Log-likelihood (and likelihood-ratio test versus the linear model
where available)
\item Number of parameters (df)
\item Residual variance / deviance
}
}
\examples{
\dontrun{
fit <- nl_fit(data = mydata, y = "score", x = "age", df = 4)
nl_compare(fit)
nl_compare(fit, polynomial_degrees = c(2, 3, 4))
}

}
\seealso{
\code{\link{nl_fit}}, \code{\link{nl_knots}}
}
