Build a nested CASE-WHEN censor expression

Description

Build a nested CASE-WHEN censor expression

Usage

.buildCensorExpression(
  censorOnCohortExit,
  hasCensorDate,
  hasFollowUpLimit,
  followUpDays
)

Drop a vector of temp tables (best-effort, errors silenced)

Description

Drop a vector of temp tables (best-effort, errors silenced)

Usage

.dropTempTables(connection, dbms, tempEmulationSchema, tables)

Execute pre-rendered SQL statements and return the final result set

Description

Execute pre-rendered SQL statements and return the final result set

Usage

.executeSurvivalSql(
  connection,
  sql,
  dbms,
  tempEmulationSchema,
  hasChunking,
  chunkSize,
  tempResult
)

Generate unique temp-table names for a single run

Description

Generate unique temp-table names for a single run

Usage

.generateTempNames()

Resolve DBMS from a DatabaseConnector connection

Description

Resolve DBMS from a DatabaseConnector connection

Usage

.getDbms(connection)

Return the parameterised SQL template

Description

Age / gender columns are included only when the corresponding @include_age / @include_gender flags are TRUE. The person-table JOIN is included when @include_demographics is TRUE.

Usage

.getSurvivalSqlTemplate()

Validate survival-specific inputs

Description

Validate survival-specific inputs

Usage

.validateSurvivalInputs(
  outcomeDateVariable,
  chunkSize,
  outcomeWashout,
  minDaysToEvent,
  followUpDays
)

Calculate survival data for a cohort

Description

Calculate survival data for a cohort

Usage

addCohortSurvival(
  connection,
  cdmDatabaseSchema,
  cohortDatabaseSchema,
  targetCohortTable,
  targetCohortId,
  outcomeCohortTable,
  outcomeCohortId = 1,
  outcomeDatabaseSchema = cohortDatabaseSchema,
  outcomeDateVariable = "cohort_start_date",
  outcomeWashout = Inf,
  minDaysToEvent = 0,
  censorOnCohortExit = FALSE,
  censorOnDate = NULL,
  followUpDays = Inf,
  includeAge = FALSE,
  includeGender = FALSE,
  observationPeriodTable = "observation_period",
  tempEmulationSchema = NULL,
  chunkSize = NULL,
  addDay = FALSE
)

Arguments

Value

Data frame with columns subject_id, time, status and optionally age_years and/or gender.

Kaplan–Meier survival by simple strata (gender and/or age groups)

Description

Compute Kaplan–Meier (KM) survival curves overall and, optionally, by simple strata derived from an existing gender column and/or an age_group built from list-of-range breaks using age_years. Results are returned per stratum plus an "overall" entry. Additionally, log-rank tests (overall and pairwise) are computed when strata are specified.

Usage

singleEventSurvival(
  survivalData,
  timeScale = "days",
  model = "km",
  covariates = NULL,
  strata = NULL,
  ageBreaks = list(c(0, 18), c(19, 45), c(46, 65), c(66, Inf)),
  times = NULL,
  probs = c(0.75, 0.5, 0.25),
  confInt = 0.95,
  confType = "log"
)

Arguments

Details

• Input follow-up time is supplied in days and internally rescaled to the requested timeScale for reporting ("days", "weeks", "months", "years").

• If "age_group" is included in strata, you must provide an age_years column. Age-group labels are generated from ageBreaks (e.g., 0-18, 19-45, 46-65, ⁠66+⁠), where each element is a numeric range c(min_age, max_age). Use Inf for open-ended upper bounds.

• Stratification is simple: groups are created from observed levels of gender and/or derived age_group. If both are requested, they are handled separately (gender OR age_group), not jointly. A one-sample KM curve is fit for each non-empty group, plus an "overall" curve for the full data.

• Confidence intervals are controlled by confType and confInt and are passed to survival::survfit().

• The model argument controls which survival estimator is fitted:

  • "km": non-parametric Kaplan–Meier estimate via ggsurvfit::survfit().

  • "cox": Cox PH model via survival::coxph() + survival::survfit(). Without covariates the Breslow baseline hazard is used. When covariates are provided, the survival curve is evaluated at the covariate means.

  • "weibull", "exponential", "lognormal", "loglogistic": AFT parametric models via survival::survreg(). S(t) is evaluated analytically at observed event times. Pointwise CIs are not available for parametric models (lower/upper are NA).

• covariates is used only for Cox and parametric models.

• times and probs control quantile extraction; probs defaults to c(0.75, 0.5, 0.25) (q75, median, q25).

• When strata are specified, a log-rank test is performed to compare survival curves across groups within each stratifier (gender and/or age_group). The overall test and pairwise tests are included in the returned object as tibbles.

Value

A list of class singleEventSurvival. See Returned object.

Returned object

A list of class singleEventSurvival. Elements include:

• Per-stratum entries named like "gender=F", "gender=M", "age_group=18-44", etc., and an "overall" element.

Each stratum element contains:

• data: a tibble with KM step data: time, n_risk, n_event, n_censor, survival, std_err, optional lower, upper (when confInt > 0), and derived hazard, cum_hazard, cum_event, cum_censor.

• summary: a list with n, events, censored, medianSurvival, q25Survival, q75Survival, meanSurvival, and timeScale.

Additionally, if gender is in strata, a logrank_test_gender element is included; if age_group is in strata, a logrank_test_age_group element is included. Each contains:

• testType: "overall" or "pairwise"

• stratum1, stratum2: labels of compared strata

• chisq: chi-square test statistic

• df: degrees of freedom

• pvalue: p-value for the test