% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gg_survival.R
\name{gg_survival}
\alias{gg_survival}
\alias{gg_survival.rfsrc}
\alias{gg_survival.default}
\title{Nonparametric survival estimates.}
\usage{
gg_survival(
  object = NULL,
  interval = NULL,
  censor = NULL,
  by = NULL,
  data = NULL,
  type = c("kaplan", "nelson"),
  ...
)

\method{gg_survival}{rfsrc}(
  object,
  interval = NULL,
  censor = NULL,
  by = NULL,
  data = NULL,
  type = c("kaplan", "nelson"),
  ...
)

\method{gg_survival}{default}(
  object = NULL,
  interval = NULL,
  censor = NULL,
  by = NULL,
  data = NULL,
  type = c("kaplan", "nelson"),
  ...
)
}
\arguments{
\item{object}{For the \code{rfsrc} method: a fitted
\code{\link[randomForestSRC]{rfsrc}} survival forest.  For the default
method: pass \code{NULL} (or omit) and supply \code{interval},
\code{censor}, and \code{data} instead.}

\item{interval}{Character; name of the time-to-event column in \code{data}
(default method only).}

\item{censor}{Character; name of the event-indicator column in \code{data}
(1 = event, 0 = censored; default method only).}

\item{by}{Optional character; name of a grouping column for stratified
estimates.  For the \code{rfsrc} method, \code{by} must be a column in
\code{object$xvar}.}

\item{data}{A \code{data.frame} containing survival data (default method
only).}

\item{type}{One of \code{"kaplan"} (Kaplan-Meier, default) or
\code{"nelson"} (Nelson-Aalen cumulative hazard).  Default method only.}

\item{...}{Additional arguments passed to \code{\link{kaplan}} or
\code{\link{nelson}}.}
}
\value{
A \code{gg_survival} \code{data.frame} with columns \code{time},
\code{surv}, \code{cum_haz}, \code{lower}, \code{upper}, \code{n.risk},
and optionally \code{groups} when \code{by} is supplied.
}
\description{
Nonparametric survival estimates.
}
\details{
Comparing the forest's ensemble survival curve to the marginal
Kaplan-Meier baseline is a quick sanity check: if they diverge the forest
has found structure the predictors carry; if they track each other closely
the predictors may add little.  \code{gg_survival} computes
the nonparametric baseline -- the Kaplan-Meier or Nelson-Aalen estimate --
so you can place it on the same canvas as the forest predictions from
\code{\link{gg_rfsrc}}.

\code{gg_survival} is an S3 generic that dispatches on the class of its
first argument:

\describe{
\item{\code{rfsrc}}{Extracts the outcome columns from the fitted
forest's \code{$yvar} slot (time in column 1, event indicator in
column 2) and delegates to \code{\link{kaplan}}.  Use \code{by} to
stratify on a predictor from \code{$xvar}: you get one
Kaplan-Meier curve per group, ready to compare against the forest's
group-specific ensemble curves.}
\item{default}{Accepts raw survival columns directly via
\code{interval}, \code{censor}, and \code{data}.  Delegates to
\code{\link{kaplan}} (the default) or \code{\link{nelson}} depending
on \code{type}.}
}
}
\note{
Survival estimation is \code{randomForestSRC}-only; \code{randomForest}
has no survival forest, so no \code{randomForest} method exists.
}
\examples{
## -------- pbc data (default method, raw data columns)
data(pbc, package = "randomForestSRC")
pbc$time <- pbc$days / 364.25

gg_dta <- gg_survival(interval = "time", censor = "status", data = pbc)
plot(gg_dta, error = "none")

# Stratified
gg_dta <- gg_survival(
  interval = "time", censor = "status",
  data = pbc, by = "treatment"
)
plot(gg_dta)

}
\seealso{
\code{\link{kaplan}} \code{\link{nelson}}

\code{\link{plot.gg_survival}}
}
