% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/km_plot.R
\name{km_plot}
\alias{km_plot}
\title{Kaplan-Meier survival plot}
\usage{
km_plot(
  data,
  time,
  event,
  by = NULL,
  conf.int = TRUE,
  risk_table = TRUE,
  p_value = TRUE,
  p_value_position = NULL,
  censor = TRUE,
  break_time_by = NULL,
  xlim = NULL,
  ylim = NULL,
  xlab = "Time",
  ylab = "Survival probability",
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  title_size = NULL,
  title_face = "bold",
  legend_title = NULL,
  legend_position = NULL,
  palette = NULL,
  y_percent = TRUE,
  theme = "classic",
  grid = FALSE,
  base_size = 13
)
}
\arguments{
\item{data}{A \code{data.frame} containing survival time and event status.}

\item{time}{Survival follow-up time. Quoted and bare names are accepted.}

\item{event}{Event indicator. Quoted and bare names are accepted. Numeric
\code{0/1}, numeric \code{1/2}, logical, character, and factor variables
are accepted. For two-level character or factor variables, the second level
is treated as the event.}

\item{by}{Optional grouping variable for separate Kaplan-Meier curves. Quoted
and bare names are accepted.}

\item{conf.int}{Logical; if \code{TRUE}, show confidence limits.}

\item{risk_table}{Logical; if \code{TRUE}, add a number-at-risk table below
the curve.}

\item{p_value}{Logical; if \code{TRUE}, show the log-rank p-value when
\code{by} is supplied.}

\item{p_value_position}{Optional numeric vector of length 2 giving the
\code{x} and \code{y} coordinates for the log-rank p-value inside the
plotting panel. If \code{NULL}, a lower-left position is chosen
automatically.}

\item{censor}{Logical; if \code{TRUE}, show censoring marks.}

\item{break_time_by}{Optional numeric interval for x-axis and risk-table time
breaks. If \code{NULL}, breaks are chosen automatically.}

\item{xlim}{Optional numeric vector of length 2 specifying x-axis limits.}

\item{ylim}{Optional numeric vector of length 2 specifying y-axis limits.
Values may be supplied on the survival-probability scale
(for example \code{c(0.5, 1)}) or, when \code{y_percent = TRUE}, on the
percentage scale (for example \code{c(50, 100)}).}

\item{xlab, ylab}{Axis labels.}

\item{title}{Optional plot title.}

\item{subtitle}{Optional plot subtitle.}

\item{caption}{Optional plot caption.}

\item{title_size}{Optional numeric title font size. If \code{NULL}, ggplot2's
theme default is used.}

\item{title_face}{Font face for the title. One of \code{"plain"},
\code{"bold"}, \code{"italic"}, or \code{"bold.italic"}. Quoted and bare
values are accepted.}

\item{legend_title}{Optional legend title. If \code{NULL}, the labelled
\code{by} variable name is used.}

\item{legend_position}{Legend position. One of \code{"bottom"}, \code{"top"},
\code{"right"}, \code{"left"}, or \code{"none"}. If \code{NULL}, grouped
plots use \code{"bottom"} and ungrouped plots hide the legend. Quoted and
bare values are accepted.}

\item{palette}{Optional character vector of colors for grouped curves.}

\item{y_percent}{Logical; if \code{TRUE}, display survival probability as
percentages. If \code{FALSE}, display the raw 0 to 1 probability scale.}

\item{theme}{Plot theme. One of \code{"classic"}, \code{"minimal"},
\code{"bw"}, \code{"light"}, or \code{"none"}. Quoted and bare values are
accepted.}

\item{grid}{Logical; if \code{TRUE}, show major grid lines. The default is
\code{FALSE} for a cleaner publication-style Kaplan-Meier plot.}

\item{base_size}{Base font size.}
}
\value{
A \code{ggplot2} object when \code{risk_table = FALSE}; otherwise a
  \code{patchwork} object combining the survival curve and risk table. The
  returned object has attributes \code{fit}, \code{plot_data},
  \code{risk_table}, and \code{logrank_p}.
}
\description{
Plot observed survival over time, with optional confidence intervals,
censoring marks, a log-rank p-value, and a number-at-risk table.
}
\examples{
lung_data <- data_lungcancer
lung_data$trt <- factor(lung_data$trt, levels = c(1, 2),
                        labels = c("Standard", "Test"))

km_plot(
  data = lung_data,
  time = time,
  event = status
)

km_plot(
  data = lung_data,
  time = time,
  event = status,
  by = trt,
  break_time_by = 200,
  ylim = c(50, 100),
  title = "A. Treatment group",
  title_size = 11,
  legend_position = "none"
)

}
