% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/negbin_helpers.R
\name{negbin_dispersion_function}
\alias{negbin_dispersion_function}
\title{NB Dispersion Function}
\usage{
negbin_dispersion_function(
  mu,
  y,
  order_indices,
  family,
  observation_weights,
  VhalfInv
)
}
\arguments{
\item{mu}{Predicted values.}

\item{y}{Observed counts.}

\item{order_indices}{Observation indices.}

\item{family}{NB family object.}

\item{observation_weights}{Observation weights.}

\item{VhalfInv}{Inverse square root of the correlation matrix, or NULL
for independent observations. When non-NULL, used to whiten residuals
for the moment-based initialization of \eqn{\theta}.}
}
\value{
Scalar \eqn{\theta} estimate (stored as \code{sigmasq_tilde}).
}
\description{
Estimates the shape parameter \eqn{\theta} from current fitted values.
When a correlation structure is present (\code{VhalfInv} is non-NULL),
the Pearson residuals are whitened before computing the moment-based
initial value, giving a better starting point for the profile MLE
under correlated data. The final estimate is always the profile MLE
over \eqn{\theta}.
}
\details{
The profile MLE maximizes \eqn{\ell(\theta \mid \mu)} via Brent's
method. When \code{VhalfInv} is provided, the Pearson residuals
\eqn{r_i = (y_i - \mu_i) / \sqrt{V(\mu_i)}} are pre-whitened as
\eqn{\tilde{r} = V^{-1/2} r} before computing the moment estimator
used for initialization. This accounts for the correlation structure
in the variance decomposition and produces a more stable starting
point for the optimizer, particularly when the correlation inflates
the marginal variance beyond what the NB model alone would predict.

The profile MLE itself does not use \code{VhalfInv} because the NB
log-likelihood is a marginal quantity; the correlation structure
affects estimation only through the mean model (handled by the GEE
paths in \code{get_B}).
}
