Estimate cumulative incidence with a competing outcome

Estimate time-to-event probabilities for one or more target cohorts when an event of interest can be precluded by a competing outcome. The target cohort defines the population at risk and the index date for follow-up. The outcome cohort defines the event of interest and the competing outcome cohort defines the event that prevents the event of interest from subsequently occurring.

Usage

estimateCompetingRiskSurvival(
  cdm,
  targetCohortTable,
  outcomeCohortTable,
  competingOutcomeCohortTable,
  targetCohortId = NULL,
  outcomeCohortId = NULL,
  outcomeDateVariable = "cohort_start_date",
  outcomeWashout = Inf,
  competingOutcomeCohortId = NULL,
  competingOutcomeDateVariable = "cohort_start_date",
  competingOutcomeWashout = Inf,
  censorOnCohortExit = FALSE,
  censorOnDate = NULL,
  weight = NULL,
  followUpDays = Inf,
  strata = NULL,
  eventGap = 30,
  estimateGap = 1,
  restrictedMeanFollowUp = NULL,
  minimumSurvivalDays = 1,
  results = c("probability", "events", "summary", "attrition"),
  outcomeTie = c("outcome", "competingOutcome"),
  censorTie = c("event", "censor")
)

Arguments

cdm

A CDM reference created by CDMConnector.

targetCohortTable

Name of the cohort table containing the target cohorts. The table must be present in cdm and contain standard OMOP cohort columns.

outcomeCohortTable

Name of the cohort table containing the outcome of interest.

competingOutcomeCohortTable

Name of the cohort table containing the competing outcome.

targetCohortId

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

outcomeCohortId

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

outcomeDateVariable

Variable containing the outcome event date. This is usually "cohort_start_date", but another date column in the outcome cohort can be used.

outcomeWashout

Number of days before target cohort entry used to exclude people with a prior outcome. Inf excludes people with any prior outcome before index; 0 applies no pre-index washout. The default is Inf.

competingOutcomeCohortId

Competing outcome cohorts to include. It can either be a cohort_definition_id value or a cohort_name. Multiple ids are allowed. If NULL, all competing outcome cohorts in competingOutcomeCohortTable are used.

competingOutcomeDateVariable

Variable containing the competing outcome event date.

competingOutcomeWashout

Number of days before target cohort entry used to exclude people with a prior competing outcome. Inf excludes people with any prior competing outcome before index; 0 applies no pre-index washout. The default is Inf.

censorOnCohortExit

If TRUE, an individual's follow up will be censored at their target cohort exit date.

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.

weight

If not NULL, the name of a numeric column in the target cohort table containing observation weights.

followUpDays

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

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 list("sex", c("age_group", "sex")).

eventGap

Days between time points for which to report survival events, which are grouped into the specified intervals.

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.

restrictedMeanFollowUp

Number of days of follow-up to use when calculating restricted mean summaries. See Details.

minimumSurvivalDays

Minimum number of days required for the main cohort to contribute to the analysis.

results

Result components to return. Choose any combination of "probability", "events", "summary", and "attrition". By default all components are returned. "probability" represents cumulative-incidence estimates for the outcome and competing outcome.

outcomeTie

How to resolve the outcome of interest and competing outcome occurring on the same day. Use "outcome" (the default) or "competingOutcome".

censorTie

How to resolve an event occurring on the same day as a censoring boundary. Use "event" (the default) to count the event or "censor" to censor the record at that time.

Value

An omopgenerics::summarised_result object with result types survival_estimates, survival_events, survival_summary, and survival_attrition when available.

Details

The estimates from competing-risk analyses should be interpreted as cumulative incidence probabilities for the outcome and competing outcome, not as ordinary Kaplan-Meier survival probabilities. The returned object is an omopgenerics::summarised_result containing cumulative incidence estimates, event counts, summary statistics, and attrition. Use asSurvivalResult() for a wider, survival-specific view.

outcomeWashout and competingOutcomeWashout default to Inf. Therefore, unless they are explicitly changed, target cohort records with any prior outcome of the corresponding type are excluded from the analysis.

The default same-day hierarchy is outcome of interest, competing outcome, then censoring. Thus, when all three occur on the same day, the outcome of interest is counted. Censoring includes the end of the observation period, target cohort exit, censorOnDate, and followUpDays.

Use outcomeTie to choose whether the outcome of interest or competing outcome wins when both occur on the same day. Use censorTie to choose whether a same-day event or censoring boundary wins. The censoring rule is applied first: with censorTie = "censor", a three-way tie is censored; with censorTie = "event", outcomeTie decides which event is counted.

restrictedMeanFollowUp defines the time horizon used for the restricted mean summary. If 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 estimate carried forward and integrated beyond its own maximum follow-up. This means restricted mean summaries 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 means 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()
#> duckdb keeps downloaded extensions and secrets in a temporary directory:
#> ℹ /tmp/RtmpvdDdf9/duckdb
#> This is removed when the R session ends.
#> • Extensions are re-downloaded each session.
#> • Secrets are lost.
#> ℹ Run duckdb(shared_home = TRUE) (or create ~/.duckdb) to keep them (suitable for most users).
#> ℹ Run duckdb(shared_home = FALSE) to accept the temporary directory (and silence this message).
#> ℹ See ?duckdb_storage for details and alternatives.
#> Creating a new cdm
#> Uploading table person (1384 rows) - [1/7]
#> Uploading table observation_period (1384 rows) - [2/7]
#> Uploading table visit_occurrence (1 rows) - [3/7]
#> Uploading table death_cohort (963 rows) - [4/7]
#> Uploading table mgus_diagnosis (1384 rows) - [5/7]
#> Uploading table progression (115 rows) - [6/7]
#> Uploading table progression_type (230 rows) - [7/7]
surv <- estimateCompetingRiskSurvival(
  cdm = cdm,
  targetCohortTable = "mgus_diagnosis",
  targetCohortId = 1,
  outcomeCohortTable = "progression",
  outcomeCohortId = 1,
  competingOutcomeCohortTable = "death_cohort",
  competingOutcomeCohortId = 1,
  eventGap = 7
)
#> ℹ `outcomeWashout` was not provided and defaults to "Inf".
#> ℹ People with any outcome before target cohort entry will be excluded from the
#>   analysis.
#> ℹ `competingOutcomeWashout` was not provided and defaults to "Inf".
#> ℹ People with any competing outcome before target cohort entry will be excluded
#>   from the analysis.
#> ℹ Getting survival for target cohort 'mgus_diagnosis', outcome cohort
#>   'progression' and competing outcome cohort 'death_cohort'
#> Getting overall estimates
#> `eventgap`, `outcome_washout`, `censor_on_cohort_exit`, `follow_up_days`, and
#> `minimum_survival_days` cast to character.
# }