% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/diagnostics.R
\name{hzr_calibrate}
\alias{hzr_calibrate}
\title{Calibrate a continuous variable against an outcome}
\usage{
hzr_calibrate(
  x,
  event,
  groups = 10L,
  by = NULL,
  link = c("logit", "gompertz", "cox"),
  time = NULL
)
}
\arguments{
\item{x}{Numeric vector: the continuous covariate to calibrate.}

\item{event}{Numeric vector: event indicator (1 = event, 0 = no event).}

\item{groups}{Integer: number of quantile bins (default 10).}

\item{by}{Optional factor or character vector for stratified calibration
(SAS \code{logitgr.sas} functionality). If provided, calibration is
computed within each stratum. Default \code{NULL} (no stratification).}

\item{link}{Character: transform to apply to event probabilities.
One of \code{"logit"} (default), \code{"gompertz"} (complementary log-log),
or \code{"cox"}.}

\item{time}{Optional numeric vector: follow-up time, required when
\code{link = "cox"}. The Cox link computes
\eqn{\log(\text{events} / \sum \text{time})} (constant hazard rate).}
}
\value{
A data frame with one row per group (or per group-by-stratum
combination) and columns:
\describe{
\item{group}{Integer group label.}
\item{by}{Stratum level (only present when \code{by} is provided).}
\item{n}{Number of observations in the group.}
\item{events}{Number of events.}
\item{mean}{Mean of \code{x} within the group.}
\item{min}{Minimum of \code{x} within the group.}
\item{max}{Maximum of \code{x} within the group.}
\item{prob}{Event probability (events / n), or for Cox link:
events / sum(time).}
\item{link_value}{Transformed probability on the chosen link scale.}
}
}
\description{
Group a continuous covariate into quantile bins, compute the event
probability (or hazard rate) per bin, and apply a link transform
(logit, Gompertz, or Cox).
This is the R equivalent of the SAS \code{logit.sas} and \code{logitgr.sas}
macros.
}
\details{
Use this function before model entry to assess whether the covariate
relationship with the outcome is approximately linear on the link
scale. If the transformed probabilities are roughly linear against
the group means, the covariate can enter the model untransformed.
Curvature suggests a transformation (log, quadratic) may improve fit.
}
\examples{
data(avc)
avc <- na.omit(avc)

# Logit calibration of age
cal <- hzr_calibrate(avc$age, avc$dead, groups = 10)
print(cal)

\donttest{
if (requireNamespace("ggplot2", quietly = TRUE)) {
  library(ggplot2)
  ggplot(cal, aes(mean, link_value)) +
    geom_point(size = 3) +
    geom_smooth(method = "lm", formula = y ~ x, se = FALSE,
                linetype = "dashed") +
    labs(x = "Age at repair (months)", y = "Logit(P(death))") +
    theme_minimal()
}
}

}
\seealso{
\code{\link[=hzr_deciles]{hzr_deciles()}} for model-based calibration after fitting.
}
