% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/negbin_helpers.R
\name{lgspline_negbin}
\alias{lgspline_negbin}
\title{Fit Negative Binomial Model via lgspline}
\usage{
lgspline_negbin(formula, data, ...)
}
\arguments{
\item{formula}{Formula specifying the model. The response should be
non-negative integer counts.}

\item{data}{Data frame.}

\item{...}{Additional arguments passed to \code{lgspline}, including
\code{Vhalf} and \code{VhalfInv} for correlation structures.}
}
\value{
An object of class \code{"lgspline"}.
}
\description{
Convenience wrapper that calls \code{lgspline} with the correct
family, weight, dispersion, score, and unconstrained-fit functions for
NB2 regression. All standard lgspline arguments (knots, penalties,
constraints, parallel, correlation structures, etc.) are passed through.
}
\details{
Internally sets:
\itemize{
  \item \code{family = negbin_family()}
  \item \code{unconstrained_fit_fxn = unconstrained_fit_negbin}
  \item \code{glm_weight_function = negbin_glm_weight_function}
  \item \code{qp_score_function = negbin_qp_score_function}
  \item \code{dispersion_function = negbin_dispersion_function}
  \item \code{schur_correction_function = negbin_schur_correction}
  \item \code{need_dispersion_for_estimation = TRUE}
  \item \code{estimate_dispersion = TRUE}
  \item \code{standardize_response = FALSE}
}

A formula interface is needed, e.g. \code{lgspline_negbin(t, y)} won't work,
unlike for ordinary \code{\link{lgspline}}.

When a correlation structure is supplied via \code{Vhalf}/\code{VhalfInv},
the model is fitted through the GEE Path 1b machinery in \code{get_B}.
The dispersion function uses \code{VhalfInv} to whiten Pearson
residuals for a better moment-based initialization of \eqn{\theta},
which stabilizes the profile MLE under moderate to strong correlation.
The score function handles the whitened design consistently with the
Weibull AFT GEE convention.
}
\examples{

set.seed(1234)
N <- 300
t <- rnorm(N)
mu <- exp(1 + 0.5 * sin(2 * t))
y <- rnbinom(N, size = 3, mu = mu)
df <- data.frame(response = y, predictor = t)

fit <- lgspline_negbin(
  response ~ spl(predictor),
  data = df,
  K = 2,
  opt = FALSE,
  wiggle_penalty = 1e-2
)
print(summary(fit))
plot(fit, show_formulas = TRUE,
     custom_response_lab = 'Count')
points(t, mu, col = 'grey', cex=0.67)

}
\seealso{
\code{\link{lgspline_cox}} for Cox PH,
  \code{\link{lgspline_weibull}} for Weibull AFT,
  \code{\link{negbin_family}}, \code{\link{unconstrained_fit_negbin}}
}
