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
)

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.

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.

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.

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.

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()
#> 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
)
#> ℹ 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.
# }