% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nl_knots.R
\name{nl_knots}
\alias{nl_knots}
\title{Automatic knot / degrees-of-freedom selection for spline models}
\usage{
nl_knots(
  data,
  y,
  x,
  time = NULL,
  cluster = NULL,
  nested = FALSE,
  controls = NULL,
  method = c("ns", "bs"),
  df_range = 2:10,
  criterion = c("AIC", "BIC"),
  family = stats::gaussian(),
  plot = TRUE,
  ...
)
}
\arguments{
\item{data}{A data frame.}

\item{y}{Outcome variable name (string).}

\item{x}{Focal predictor name (string).}

\item{time}{Optional time variable name.}

\item{cluster}{Optional character vector of cluster variable names.}

\item{nested}{Logical; nested clustering. Default \code{FALSE}.}

\item{controls}{Optional character vector of control variable names.}

\item{method}{Either \code{"ns"} (default) or \code{"bs"}.}

\item{df_range}{Integer vector of candidate df values. Default \code{2:10}.}

\item{criterion}{Either \code{"AIC"} (default) or \code{"BIC"}.}

\item{family}{A family object. Default \code{stats::gaussian()}.}

\item{plot}{Logical; if \code{TRUE}, prints a diagnostic plot of criterion
vs df. Default \code{TRUE}.}

\item{...}{Additional arguments passed to the underlying fitter.}
}
\value{
A list with:
\describe{
\item{\code{best_df}}{The df value with the lowest criterion value.}
\item{\code{search_table}}{Data frame with columns \code{df} and
\code{criterion}.}
\item{\code{criterion}}{The criterion used (\code{"AIC"} or
\code{"BIC"}).}
\item{\code{plot}}{A \code{ggplot} object (if \code{plot = TRUE}).}
}
}
\description{
Performs a grid search over candidate degrees of freedom (df) for a
natural cubic spline (\code{"ns"}) or B-spline (\code{"bs"}) model and
selects the best value by an information criterion (AIC or BIC). A
diagnostic plot of the criterion against df is returned.

This function is called internally by \code{\link{nl_fit}} when
\code{df = "auto"}, but it can also be called directly for exploration
before fitting the final model.
}
\seealso{
\code{\link{nl_fit}}, \code{\link{nl_compare}}
}
