% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/logrank_test.R
\name{logrank_test}
\alias{logrank_test}
\title{Log-rank test for Kaplan-Meier survival curves}
\usage{
logrank_test(
  data,
  time,
  event,
  by,
  digits = 2,
  format = c("flextable", "gt", "tibble"),
  theme = c("minimal")
)
}
\arguments{
\item{data}{A \code{data.frame} containing survival time, event status, and
grouping variable.}

\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}{Grouping variable used to compare survival curves. Quoted and bare
names are accepted.}

\item{digits}{Number of digits for the chi-square statistic and expected
events.}

\item{format}{Output format. One of \code{"flextable"} (default),
\code{"gt"}, or \code{"tibble"}.}

\item{theme}{Table styling preset.}
}
\value{
A list of class \code{c("gtregression","logrank_test", ...)} with
elements:
\describe{
  \item{\code{table}}{A \code{flextable}, \code{gt_tbl}, or \code{NULL}
  when \code{format = "tibble"}.}
  \item{\code{table_body}}{Tibble with group-level log-rank components and
  overall test statistics.}
  \item{\code{test}}{One-row tibble with chi-square statistic, degrees of
  freedom, and p-value.}
  \item{\code{fit}}{The \code{survdiff} object.}
  \item{\code{time,event,by,format,source}}{Metadata fields.}
}
}
\description{
Compare survival curves between groups using the log-rank test.
}
\details{
The log-rank test compares the observed number of events with the expected
number of events in each group under the null hypothesis that the survival
curves are the same. It is a group comparison, not an effect-size estimate;
use \code{cox_reg()} when a hazard ratio is needed.
}
\examples{
lung_data <- data_lungcancer
lung_data$trt <- factor(lung_data$trt, levels = c(1, 2),
                        labels = c("Standard", "Test"))

logrank_test(
  data = lung_data,
  time = time,
  event = status,
  by = trt
)

logrank_test(
  data = lung_data,
  time = "time",
  event = "status",
  by = "trt",
  format = tibble
)

}
