% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/estimateSurvival.R
\name{estimateSingleEventSurvival}
\alias{estimateSingleEventSurvival}
\title{Estimate survival for a single event of interest}
\usage{
estimateSingleEventSurvival(
  cdm,
  targetCohortTable,
  outcomeCohortTable,
  targetCohortId = NULL,
  outcomeCohortId = NULL,
  outcomeDateVariable = "cohort_start_date",
  outcomeWashout = Inf,
  censorOnCohortExit = FALSE,
  censorOnDate = NULL,
  weight = NULL,
  followUpDays = Inf,
  strata = NULL,
  eventGap = 30,
  estimateGap = 1,
  restrictedMeanFollowUp = NULL,
  minimumSurvivalDays = 1
)
}
\arguments{
\item{cdm}{A CDM reference created by CDMConnector.}

\item{targetCohortTable}{Name of the cohort table containing the target
cohorts. The table must be present in \code{cdm} and contain standard OMOP cohort
columns.}

\item{outcomeCohortTable}{Name of the cohort table containing the outcome
cohorts. The table must be present in \code{cdm} and contain standard OMOP cohort
columns.}

\item{targetCohortId}{Target cohorts to include. It can either be a
cohort_definition_id value or a cohort_name. Multiple ids are allowed. If
\code{NULL}, all non-empty cohorts in \code{targetCohortTable} are used.}

\item{outcomeCohortId}{Outcome cohorts to include. It can either be a
cohort_definition_id value or a cohort_name. Multiple ids are allowed. If
\code{NULL}, all outcome cohorts in \code{outcomeCohortTable} are used.}

\item{outcomeDateVariable}{Variable containing the outcome event date. This
is usually \code{"cohort_start_date"}, but another date column in the outcome
cohort can be used.}

\item{outcomeWashout}{Number of days before target cohort entry used to
exclude people with a prior outcome. \code{Inf} excludes people with any prior
outcome before index; \code{0} applies no pre-index washout.}

\item{censorOnCohortExit}{If TRUE, an individual's follow up will be
censored at their target cohort exit date.}

\item{censorOnDate}{If not NULL, an individual's follow up will be censored
at the given date. This can be a scalar Date or the name of a date column in
the target cohort table.}

\item{weight}{If not NULL, the name of a numeric column in the target cohort
table containing observation weights to use in the Kaplan-Meier estimation.}

\item{followUpDays}{Number of days to follow up individuals (lower bound 1,
upper bound Inf). Follow-up is censored at this value.}

\item{strata}{A list of target cohort column names to stratify by. Each
element can be one column name or a character vector of column names for a
combined stratum, for example \code{list("sex", c("age_group", "sex"))}.}

\item{eventGap}{Days between time points for which to report survival
events, which are grouped into the specified intervals.}

\item{estimateGap}{Days between time points for which to report survival
estimates. First day will be day zero with risk estimates provided
for times up to the end of follow-up, with a gap in days equivalent
to estimateGap.}

\item{restrictedMeanFollowUp}{Number of days of follow-up to use when
calculating restricted mean survival. See Details.}

\item{minimumSurvivalDays}{Minimum number of days required for the main cohort
to contribute to the analysis.}
}
\value{
An \code{omopgenerics::summarised_result} object with result types
\code{survival_estimates}, \code{survival_events}, \code{survival_summary}, and
\code{survival_attrition} when available.
}
\description{
Estimate Kaplan-Meier survival for one or more target cohorts and outcome
cohorts in an OMOP Common Data Model reference. The target cohort defines
the population at risk and the index date for follow-up. The outcome cohort
defines the event of interest.
}
\details{
The returned object is an \code{omopgenerics::summarised_result} containing
survival estimates, event counts, summary statistics, and attrition. Use
\code{asSurvivalResult()} when you want a wider, survival-specific view for manual
inspection or downstream modelling.

\code{restrictedMeanFollowUp} defines the time horizon used for the restricted
mean survival time. It is calculated as the area under the survival curve up
to that horizon. If \code{restrictedMeanFollowUp = NULL}, the horizon is left to
the underlying survival summary. In stratified analyses, this can use a
common maximum follow-up time across the fitted curves. A stratum with
shorter observed follow-up may therefore have its last survival estimate
carried forward and integrated beyond its own maximum follow-up. This means
restricted mean survival can be larger than the observed follow-up time for
that stratum, and comparisons across strata may be misleading. Set a common
clinically meaningful value that is supported by follow-up in all groups when
restricted mean survival will be compared across cohorts or strata. If the
requested horizon is beyond the available follow-up for a curve, the
restricted mean is reported as missing.
}
\examples{
\donttest{
cdm <- mockMGUS2cdm()
surv <- estimateSingleEventSurvival(
  cdm = cdm,
  targetCohortTable = "mgus_diagnosis",
  targetCohortId = 1,
  outcomeCohortTable = "death_cohort",
  outcomeCohortId = 1,
  eventGap = 7
)
}

}
