% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/weibull_helpers.R
\name{weibull_dispersion_function}
\alias{weibull_dispersion_function}
\title{Estimate Weibull Dispersion for Accelerated Failure Time Model}
\usage{
weibull_dispersion_function(
  mu,
  y,
  order_indices,
  family,
  observation_weights,
  VhalfInv,
  status
)
}
\arguments{
\item{mu}{Predicted survival times}

\item{y}{Observed response/survival times}

\item{order_indices}{Indices to align status with response}

\item{family}{Weibull AFT model family specification; unused here and
retained for interface compatibility.}

\item{observation_weights}{Optional observation weights}

\item{VhalfInv}{Inverse square root of the correlation matrix; unused here
and retained for interface compatibility.}

\item{status}{Censoring indicator (1 = event, 0 = censored)
Indicates whether an event of interest occurred (1) or the observation was
right-censored (0). In survival analysis, right-censoring occurs when the
full survival time is unknown, typically because the study ended or the
subject was lost to follow-up before the event of interest occurred.}
}
\value{
Dispersion estimate (sigma^2) for the Weibull AFT model, i.e., the squared
scale parameter. The Weibull scale (sigma) matching \code{survreg$scale} is
\code{sqrt()} of this value.
}
\description{
Computes the dispersion parameter (sigma^2 = scale^2) for a Weibull
accelerated failure time (AFT) model, supporting right-censored survival
data. The returned value is sigma^2, where sigma is the Weibull scale
parameter matching \code{survreg$scale}.

This both provides a tool for actually fitting Weibull AFT Models, and
boilerplate code for users who wish to incorporate Lagrangian multiplier
smoothing splines into their own custom models.
}
\examples{

## Simulate survival data with covariates
set.seed(1234)
n <- 1000
t1 <- rnorm(n)
t2 <- rbinom(n, 1, 0.5)

## Generate survival times with Weibull-like structure
lambda <- exp(0.5 * t1 + 0.3 * t2)
yraw <- rexp(n, rate = 1/lambda)

## Introduce right-censoring
status <- rbinom(n, 1, 0.75)
y <- ifelse(status, yraw, runif(length(yraw), 0, yraw))

## Example of using dispersion function
mu <- mean(y)
order_indices <- seq_along(y)
weights <- rep(1, n)

## Estimate dispersion (= scale^2 = sigma^2)
dispersion_est <- weibull_dispersion_function(
  mu = mu,
  y = y,
  order_indices = order_indices,
  family = weibull_family(),
  observation_weights = weights,
  VhalfInv = NULL,
  status = status
)

print(dispersion_est)          # sigma^2
print(sqrt(dispersion_est))    # sigma (comparable to survreg$scale)

}
\seealso{
\code{\link{weibull_scale}} for the underlying scale estimation
  function
}
