% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tableSurvival.R
\name{tableSurvival}
\alias{tableSurvival}
\title{Table with survival summary}
\usage{
tableSurvival(
  x,
  times = NULL,
  timeScale = "days",
  header = c("estimate"),
  estimates = c("median_survival", "restricted_mean_survival"),
  type = "gt",
  groupColumn = NULL,
  hide = c("result_id", "estimate_type"),
  style = NULL,
  .options = list()
)
}
\arguments{
\item{x}{Result from \code{estimateSingleEventSurvival()} or
\code{estimateCompetingRiskSurvival()}. A \code{summarised_result} or \code{survival_result}
is accepted.}

\item{times}{Times at which to report estimates in the summary table. These
must match available estimate times after applying \code{timeScale}; unavailable
times are omitted with a message.}

\item{timeScale}{Time unit to report survival in: days, months, or years.}

\item{header}{A vector specifying the elements to include in the header.
The order of elements matters, with the first being the topmost header.
Elements in header can be:
\itemize{
\item Any of the columns returned by \code{tableColumns(result)} to create a header
for these columns.
\item Any other input to create an overall header.
}}

\item{estimates}{Character vector specifying which estimates to include in the table.
Options include: "median_survival", "restricted_mean_survival", "q0_survival",
"q05_survival", "q25_survival", "q75_survival", "q95_survival", "q100_survival".
By default it includes c("median_survival", "restricted_mean_survival").}

\item{type}{Character string specifying the desired output table format.
See \code{tableType()} for supported table types. If \code{type = NULL}, global
options (set via \code{setGlobalTableOptions()}) will be used if available;
otherwise, a default \code{'gt'} table is created.}

\item{groupColumn}{Columns to use as group labels, to see options use
\code{tableColumns(result)}. By default, the name of the new group will be the
tidy* column names separated by ";". To specify a custom group name, use a
named list such as:
list("newGroupName" = c("variable_name", "variable_level")).

*tidy: The tidy format applied to column names replaces "_" with a space and
converts to sentence case. Use \code{rename} to customise specific column names.}

\item{hide}{Columns to drop from the output table. By default, \code{result_id} and
\code{estimate_type} are always dropped.}

\item{style}{Defines the visual formatting of the table.
This argument can be provided in one of the following ways:
\enumerate{
\item \strong{Pre-defined style:} Use the name of a built-in style (e.g., \code{"darwin"}).
See \code{tableStyle()} for available options.
\item \strong{YAML file path:} Provide the path to an existing \code{.yml} file defining
a new style.
\item \strong{List of custom R code:} Supply a block of custom R code or a named list
describing styles for each table section. This code must be specific to
the selected table type.
If \code{style = NULL}, the function will use global options
(see \code{setGlobalTableOptions()}) or an existing \verb{_brand.yml} file (if found);
otherwise, the default style is applied.
For more details, see the \emph{Styles} vignette on the package website.
}}

\item{.options}{A named list with additional formatting options.
\code{visOmopResults::tableOptions()} shows allowed arguments and their default values.}
}
\value{
A formatted table containing a summary of observed survival or
cumulative incidence in the required units.
}
\description{
Create a formatted table from the summary and, optionally, time-specific
estimate result types returned by \code{estimateSingleEventSurvival()} or
\code{estimateCompetingRiskSurvival()}. For single-event analyses, time-specific
rows are survival probabilities. For competing-risk analyses, they are
cumulative incidence probabilities for the outcome and competing outcome.
}
\details{
Restricted mean survival is taken from the estimation output. Its
interpretation depends on the \code{restrictedMeanFollowUp} value used when the
survival result was estimated; use a common value there when comparing
restricted means across groups or strata.
}
\examples{
\donttest{
cdm <- mockMGUS2cdm()
surv <- estimateSingleEventSurvival(cdm,
                                    targetCohortTable = "mgus_diagnosis",
                                    outcomeCohortTable = "death_cohort")
tableSurvival(surv, times = c(50,100,365))
}
}
