% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/diagnostics.R
\name{hzr_gof}
\alias{hzr_gof}
\title{Goodness-of-fit: observed vs. predicted events}
\usage{
hzr_gof(object, time_grid = NULL)
}
\arguments{
\item{object}{A fitted \code{hazard} object (with \code{fit = TRUE}).}

\item{time_grid}{Optional numeric vector of time points at which to
evaluate the parametric model.
If \code{NULL} (default), uses the sorted unique event times from the
fitted data.}
}
\value{
A data frame with one row per time point and columns:
\describe{
\item{time}{Evaluation time.}
\item{n_risk}{Number at risk (Kaplan-Meier).}
\item{n_event}{Number of events at this time.}
\item{n_censor}{Number censored at this time.}
\item{km_surv}{Kaplan-Meier survival estimate.}
\item{km_cumhaz}{Kaplan-Meier cumulative hazard
(\eqn{-\log(\text{km\_surv})}).}
\item{par_surv}{Parametric survival from the fitted model.}
\item{par_cumhaz}{Parametric cumulative hazard.}
\item{cum_observed}{Cumulative observed events to this time.}
\item{cum_expected}{Cumulative expected events (sum of individual
cumulative hazards for observations exiting the risk set).}
\item{residual}{Expected minus observed
(\code{cum_expected - cum_observed}).}
}

For multiphase models, additional columns are appended for each
phase: \code{par_cumhaz_<phase>}.

An attribute \code{"summary"} is attached with scalar diagnostics:
total observed events, total expected events, and the final residual.
}
\description{
Compare a fitted hazard model against the nonparametric Kaplan-Meier
estimate by computing observed and expected (parametric) event counts
at each distinct event time.  This is the R equivalent of the SAS
\code{hazplot.sas} macro and implements the conservation-of-events
diagnostic.
}
\details{
At each observed event time the function computes:
\itemize{
\item The Kaplan-Meier survival and cumulative hazard.
\item The parametric survival and cumulative hazard from the fitted
model (and per-phase components for multiphase models).
\item Cumulative observed events vs. cumulative expected events
(sum of individual cumulative hazards for those exiting the risk
set at each time).
\item The running residual (expected minus observed).
}

Perfect model fit implies the expected and observed event counts track
each other (residual near zero).  This is the conservation-of-events
principle.
}
\examples{
\donttest{
data(avc)
avc <- na.omit(avc)
fit <- hazard(
  survival::Surv(int_dead, dead) ~ age + mal,
  data  = avc,
  dist  = "weibull",
  theta = c(mu = 0.01, nu = 0.5, beta_age = 0, beta_mal = 0),
  fit   = TRUE
)
gof <- hzr_gof(fit)
print(gof)

# Plot observed vs expected events
if (requireNamespace("ggplot2", quietly = TRUE)) {
  library(ggplot2)
  ggplot(gof, aes(x = time)) +
    geom_line(aes(y = cum_observed), colour = "#D55E00") +
    geom_line(aes(y = cum_expected), colour = "#0072B2") +
    labs(x = "Time", y = "Cumulative events") +
    theme_minimal()
}
}

}
\seealso{
\code{\link[=hzr_deciles]{hzr_deciles()}} for decile-of-risk calibration,
\code{\link[=predict.hazard]{predict.hazard()}} for prediction types.
}
