% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/diagnostics.R
\name{hzr_deciles}
\alias{hzr_deciles}
\title{Decile-of-risk calibration}
\usage{
hzr_deciles(object, time, groups = 10L, status = NULL, event_time = NULL)
}
\arguments{
\item{object}{A fitted \code{hazard} object (with \code{fit = TRUE}).}

\item{time}{Numeric scalar: the time point at which to evaluate
predicted survival / cumulative hazard.  For example, \code{time = 12}
evaluates 12-month predictions.}

\item{groups}{Integer: number of risk groups (default 10 for deciles).}

\item{status}{Optional numeric vector of event indicators (1 = event,
0 = censored).
If \code{NULL} (default), extracted from the fitted object's stored data.}

\item{event_time}{Optional numeric vector of observed event/censoring
times.  If \code{NULL} (default), extracted from the fitted object.}
}
\value{
A data frame with one row per risk group and columns:
\describe{
\item{group}{Integer group label (1 = lowest risk).}
\item{n}{Number of observations in the group.}
\item{events}{Observed event count by the requested horizon
(event indicator = 1 and event time <= \code{time}).}
\item{expected}{Expected event count by the requested horizon,
computed as the sum of individual event probabilities
(\eqn{1 - S(time)}).}
\item{observed_rate}{Observed event rate (events / n).}
\item{expected_rate}{Expected event rate (expected / n).}
\item{chi_sq}{Chi-square contribution: (events - expected)^2 /
expected.}
\item{p_value}{Upper-tail p-value from the chi-square test for
this group (1 df).}
\item{mean_survival}{Mean predicted survival probability in the
group.}
\item{mean_cumhaz}{Mean predicted cumulative hazard in the group.}
}

An attribute \code{"overall"} is attached with the overall chi-square
statistic, degrees of freedom, and p-value.
}
\description{
Partition observations into groups (default 10) by predicted risk and
compare observed vs. expected event counts in each group.  Good
calibration means the two track each other across the risk spectrum.
}
\details{
This implements the workflow of the SAS \code{deciles.hazard.sas} macro.
Patients are ranked by predicted cumulative hazard at a specified time
point, grouped into quantile bins, and each bin is tested with a
chi-square goodness-of-fit statistic. Subjects censored before the
requested horizon are excluded from the observed-vs-expected comparison.
}
\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
)
cal <- hzr_deciles(fit, time = 120)
print(cal)
}

}
\seealso{
\code{\link[=predict.hazard]{predict.hazard()}} for the prediction types used internally.
}
