% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/surv_reg.R
\name{surv_reg}
\alias{surv_reg}
\title{Parametric survival regression}
\usage{
surv_reg(
  data,
  time,
  event,
  exposures,
  adjust_for = NULL,
  stratifier = NULL,
  interaction = NULL,
  multivariable = FALSE,
  multivariate = NULL,
  distribution = "weibull",
  format = c("flextable", "gt"),
  theme = c("minimal"),
  show_sample = "events",
  model_stats = FALSE,
  show_ref = TRUE
)
}
\arguments{
\item{data}{A \code{data.frame} containing survival time, event status, and
exposure 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{exposures}{Character vector of exposure variable names. Quoted names
are recommended in scripts, and bare names are also accepted.}

\item{adjust_for}{Optional character vector of adjustment variables. When
supplied, one adjusted model is fitted per exposure.}

\item{stratifier}{Optional single stratifying variable. When supplied,
stratum-specific parametric survival tables are produced using the same
crude, adjusted, or multivariable workflow requested by the other
arguments. The stratifier cannot also be used as the time, event,
exposure, adjustment, or interaction variable.}

\item{interaction}{Optional character scalar specifying one interaction term
using standard formula syntax, e.g. \code{"trt*prior"}. Quoted and bare
interaction syntax are accepted. In exposure-by-exposure mode, supply a
single exposure; in \code{multivariable = TRUE} mode, the interaction is
added to the single multivariable model.}

\item{multivariable}{Logical; if \code{FALSE} (default), the current
exposure-by-exposure workflow is used. If \code{TRUE}, one multivariable
parametric survival model is fitted using all variables in
\code{exposures}, and all exposure coefficients are reported.}

\item{multivariate}{Optional logical alias for \code{multivariable}. This is
accepted for convenience; \code{multivariable} is used internally.}

\item{distribution}{Parametric survival distribution. One 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{format}{Output table format; one of \code{"flextable"} (default) or
\code{"gt"}.}

\item{theme}{Table styling preset.}

\item{show_sample}{For stratified parametric survival tables, controls which
sample-size columns are shown in the publication table. One of
\code{"events"} (default), \code{"n"}, \code{"both"}, or \code{"none"}.
Model statistics, when requested, still retain both N and event counts.}

\item{model_stats}{Logical; if \code{TRUE}, extract model-fit statistics
including AIC, BIC, log-likelihood, scale, number of events, and N.}

\item{show_ref}{Logical; if \code{TRUE} (default), display reference-category
rows as \code{"Ref."}. If \code{FALSE}, hide reference rows; a message
reminds users to use \code{show_ref = TRUE} when reference rows are needed.}
}
\value{
A list of class \code{c("gtregression","surv_reg", ...)} with elements:
\describe{
  \item{table}{A \code{flextable} or \code{gt_tbl}.}
  \item{table_body}{Data frame of time ratios and confidence intervals.}
  \item{table_display}{Data frame used to render the publication table.}
  \item{models}{List of fitted \code{survreg} models.}
  \item{model_summaries}{Summary output for the fitted models.}
  \item{model_stats}{Model-fit statistics when \code{model_stats = TRUE};
  otherwise \code{NULL}.}
  \item{variable_labels}{Named character vector of display labels.}
  \item{footnotes}{Character vector used by the rendered table. Adjustment
  notes use the same display labels as the table.}
  \item{time,event,distribution,approach,format,source,adjust_for,exposures,interaction}{Metadata fields.}
}
}
\description{
Fit parametric survival models and report time ratios.
}
\details{
\code{surv_reg()} fits accelerated failure time style parametric survival
models using \code{survival::survreg()}. The exponentiated coefficient is
displayed as a time ratio. A time ratio above 1 suggests longer survival time;
a time ratio below 1 suggests shorter survival time, conditional on the chosen
distribution.

By default, \code{surv_reg()} keeps the exposure-by-exposure workflow:
without \code{adjust_for}, one crude model is fitted per exposure; with
\code{adjust_for}, one adjusted model is fitted per exposure and only the
exposure estimate is reported.

With \code{multivariable = TRUE}, all variables in \code{exposures} are
included in one parametric survival model and all coefficients are reported.
Since these estimates are adjusted for the other variables in the same model,
the table reports \code{Adjusted Time Ratio (95\% CI)}. The
\code{adjust_for} argument is not used in this mode; include every variable
that belongs in the model inside \code{exposures}.

Interaction terms specified via \code{interaction} are included using
standard formula expansion (for example, \code{trt*prior}). Interaction
effects are displayed as additional rows beneath the corresponding exposure.

Stratified parametric survival tables show event counts by default. Use
\code{show_sample = "n"}, \code{show_sample = "both"}, or
\code{show_sample = "none"} to control the displayed sample columns. Crude
stratified tables calculate these counts for each exposure-specific model;
adjusted and multivariable stratified tables use the corresponding fitted
model within each stratum.

If exposure variables have a \code{"label"} attribute, for example from
\code{labelled::var_label()}, those labels are used automatically in the
displayed table.
}
\examples{
lung_data <- data_lungcancer
lung_data$trt <- factor(lung_data$trt, levels = c(1, 2),
                        labels = c("Standard", "Test"))
lung_data$prior <- factor(lung_data$prior, levels = c(0, 10),
                          labels = c("No", "Yes"))

surv_reg(
  data = lung_data,
  time = time,
  event = status,
  exposures = c("trt", "celltype", "karno", "age")
)

surv_reg(
  data = lung_data,
  time = time,
  event = status,
  exposures = c(trt, celltype, prior),
  adjust_for = c(age, karno),
  distribution = lognormal
)

# Interaction in an adjusted exposure model
surv_reg(
  data = lung_data,
  time = time,
  event = status,
  exposures = trt,
  adjust_for = c(age, karno),
  interaction = trt*prior,
  distribution = weibull
)

surv_reg(
  data = lung_data,
  time = time,
  event = status,
  exposures = c(trt, celltype, prior, age, karno),
  distribution = weibull,
  multivariable = TRUE
)

# multivariate is accepted as an alias
surv_reg(
  data = lung_data,
  time = time,
  event = status,
  exposures = c(trt, age, karno),
  multivariate = TRUE
)

}
