% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/diagnostics.R
\name{hzr_kaplan}
\alias{hzr_kaplan}
\title{Kaplan-Meier survival with exact logit confidence limits}
\usage{
hzr_kaplan(time, status, conf_level = 0.95, event_only = TRUE)
}
\arguments{
\item{time}{Numeric vector of follow-up times.}

\item{status}{Numeric event indicator (1 = event, 0 = censored).}

\item{conf_level}{Confidence level for the interval (default 0.95).
The SAS default of 0.68268948 corresponds to a 1-SD interval.}

\item{event_only}{Logical; if \code{TRUE} (default), only return rows at
event times (where \code{n_event > 0}).
If \code{FALSE}, return rows at all times reported by
\code{survival::survfit()} (events and censoring times).}
}
\value{
A data frame with one row per time point and columns:
\describe{
\item{time}{Event/censoring time.}
\item{n_risk}{Number at risk at start of interval.}
\item{n_event}{Number of events at this time.}
\item{n_censor}{Number censored at this time.}
\item{survival}{Kaplan-Meier survival estimate.}
\item{std_err}{Standard error of survival (Greenwood).}
\item{cl_lower}{Lower confidence limit (logit-transformed).}
\item{cl_upper}{Upper confidence limit (logit-transformed).}
\item{cumhaz}{Cumulative hazard \eqn{= -\log(S)}.}
\item{hazard}{Interval hazard rate
\eqn{= \log(S_{t-1} / S_t) / \Delta t}.}
\item{density}{Probability density estimate
\eqn{= (S_{t-1} - S_t) / \Delta t}.}
\item{life}{Restricted mean survival time (area under curve to
this time).}
}
}
\description{
Compute the product-limit (Kaplan-Meier) survival estimate with
logit-transformed confidence limits that respect the \eqn{[0, 1]}
boundary.
This is the R equivalent of the SAS \code{kaplan.sas} macro.
}
\details{
The standard Greenwood confidence interval can exceed \eqn{[0, 1]} in the
tails. The logit-transformed interval avoids this by working on the
log-odds scale:

\deqn{
  \text{CL}_{\text{lower}} = S / \bigl(S + (1-S)\,
  \exp(z_\alpha\,\text{SI})\bigr)
}
\deqn{
  \text{CL}_{\text{upper}} = S / \bigl(S + (1-S)\,
  \exp(-z_\alpha\,\text{SI})\bigr)
}

where \eqn{\text{SI} = \sqrt{V_P - 1} / (1 - S)}, \eqn{V_P} is the
cumulative Greenwood variance product, and \eqn{z_\alpha} is the
normal quantile for the requested confidence level.
}
\examples{
data(cabgkul)
km <- hzr_kaplan(cabgkul$int_dead, cabgkul$dead)
head(km)

\donttest{
if (requireNamespace("ggplot2", quietly = TRUE)) {
  library(ggplot2)
  ggplot(km, aes(time)) +
    geom_step(aes(y = survival * 100)) +
    geom_ribbon(aes(ymin = cl_lower * 100, ymax = cl_upper * 100),
                stat = "identity", alpha = 0.2) +
    labs(x = "Months", y = "Survival (\%)") +
    theme_minimal()
}
}

}
\references{
Kaplan EL, Meier P (1958). Nonparametric estimation from incomplete
observations. \emph{J Am Stat Assoc} 53(282):457--481.
\doi{10.1080/01621459.1958.10501452}

Greenwood M (1926). The natural duration of cancer. \emph{Reports on Public
Health and Medical Subjects} 33:1--26.
}
\seealso{
\code{\link[=hzr_gof]{hzr_gof()}} for parametric vs. nonparametric comparison.
}
