% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot_surv_fit.R
\name{plot_surv_fit}
\alias{plot_surv_fit}
\title{Plot observed and fitted parametric survival curves}
\usage{
plot_surv_fit(
  data,
  time,
  event,
  by = NULL,
  adjust_for = NULL,
  distributions = c("weibull", "exponential", "lognormal", "loglogistic"),
  break_time_by = NULL,
  xlim = NULL,
  xlab = "Time",
  ylab = "Survival probability",
  title = NULL,
  legend_title = NULL,
  palette = NULL,
  base_size = 13,
  n_points = 200
)
}
\arguments{
\item{data}{A \code{data.frame} containing survival time, event status, and
optional grouping or adjustment variables.}

\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 observed and fitted curves. Quoted
and bare names are accepted.}

\item{adjust_for}{Optional character vector of adjustment variables included
in the fitted parametric model. Fitted curves are predicted at typical
adjustment values.}

\item{distributions}{Parametric survival distributions to overlay. One or
more of \code{"weibull"}, \code{"exponential"}, \code{"lognormal"}, or
\code{"loglogistic"}. Quoted and bare values are accepted. Common
spellings such as \code{"log-normal"} and \code{"log-logistic"} are also
accepted.}

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

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

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

\item{title}{Optional plot title.}

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

\item{palette}{Optional character vector of colors for observed groups.}

\item{base_size}{Base font size.}

\item{n_points}{Number of points used to draw each fitted curve.}
}
\value{
A \code{ggplot2} object with attributes \code{km_fit},
  \code{model_fits}, \code{observed_data}, \code{fitted_data}, and
  \code{prediction_data}.
}
\description{
Compare the observed Kaplan-Meier survival curve with fitted parametric
survival curves from \code{survival::survreg()}.
}
\details{
\code{plot_surv_fit()} is a visual diagnostic for parametric survival
modelling. It is useful after \code{surv_model_compare()} and before treating
a final \code{surv_reg()} model as the preferred model. It is not a Cox-model
diagnostic; use \code{check_ph()} for Cox proportional hazards assumptions.

When \code{adjust_for} is supplied, fitted curves are predicted at typical
adjustment values: medians for numeric variables and the most common level for
categorical variables. Use this as a model-fit screen, not as a replacement
for clinical or subject-matter judgement.
}
\examples{
lung_data <- data_lungcancer
lung_data$trt <- factor(lung_data$trt, levels = c(1, 2),
                        labels = c("Standard", "Test"))

plot_surv_fit(
  data = lung_data,
  time = time,
  event = status,
  by = trt,
  distributions = c(weibull, lognormal),
  break_time_by = 200
)

plot_surv_fit(
  data = lung_data,
  time = "time",
  event = "status",
  by = "trt",
  adjust_for = c(age, karno),
  distributions = "log-logistic"
)

}
