Title:	Estimate Survival from Common Data Model Cohorts
Version:	1.0.2
Description:	Estimate survival using data mapped to the Observational Medical Outcomes Partnership common data model. Survival can be estimated based on user-defined study cohorts.
License:	Apache License (≥ 2)
Encoding:	UTF-8
RoxygenNote:	7.3.2
Imports:	broom, CDMConnector (≥ 2.0.0), checkmate, cli, clock, DBI, dplyr, glue, magrittr, omopgenerics (≥ 1.1.0), PatientProfiles (≥ 1.3.1), purrr, rlang (≥ 0.4.11), survival (≥ 3.7.0), stats, stringr, tibble, tidyr
Suggests:	testthat (≥ 3.0.0), CodelistGenerator, roxygen2, knitr, tictoc, rmarkdown, ggplot2, patchwork, cmprsk, duckdb, gt, flextable, scales, visOmopResults (≥ 1.0.0)
Config/testthat/edition:	3
Config/testthat/parallel:	true
VignetteBuilder:	knitr
URL:	https://darwin-eu-dev.github.io/CohortSurvival/
NeedsCompilation:	no
Packaged:	2025-06-16 09:32:24 UTC; spet5356
Author:	Kim López-Güell [aut, cre], Edward Burn [aut], Marti Catala [aut], Xintong Li [aut], Danielle Newby [aut], Nuria Mercade-Besora [aut]
Maintainer:	Kim López-Güell <kim.lopez@spc.ox.ac.uk>
Repository:	CRAN
Date/Publication:	2025-06-16 10:00:02 UTC

CohortSurvival: Estimate Survival from Common Data Model Cohorts

Description

Estimate survival using data mapped to the Observational Medical Outcomes Partnership common data model. Survival can be estimated based on user-defined study cohorts.

Author(s)

Maintainer: Kim López-Güell kim.lopez@spc.ox.ac.uk (ORCID)

Authors:

• Edward Burn edward.burn@ndorms.ox.ac.uk (ORCID)

• Marti Catala marti.catalasabate@ndorms.ox.ac.uk (ORCID)

• Xintong Li xintong.li@ndorms.ox.ac.uk (ORCID)

• Danielle Newby danielle.newby@ndorms.ox.ac.uk (ORCID)

• Nuria Mercade-Besora nuria.mercadebesora@ndorms.ox.ac.uk (ORCID)

See Also

Useful links:

• https://darwin-eu-dev.github.io/CohortSurvival/

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

Value

The result of calling rhs(lhs).

Add survival information to a cohort table

Description

Add survival information to a cohort table

Usage

addCohortSurvival(
  x,
  cdm,
  outcomeCohortTable,
  outcomeCohortId = 1,
  outcomeDateVariable = "cohort_start_date",
  outcomeWashout = Inf,
  censorOnCohortExit = FALSE,
  censorOnDate = NULL,
  followUpDays = Inf,
  name = NULL
)

Arguments

Value

Two additional columns will be added to x. The "time" column will contain number of days to censoring. The "status" column will indicate whether the patient had the event (value: 1), or did not have the event (value: 0)

Examples

cdm <- mockMGUS2cdm()
cdm$mgus_diagnosis <- cdm$mgus_diagnosis %>%
  addCohortSurvival(
    cdm = cdm,
    outcomeCohortTable = "death_cohort",
    outcomeCohortId = 1
  )
  

A tidy implementation of the summarised_characteristics object.

Description

A tidy implementation of the summarised_characteristics object.

Usage

asSurvivalResult(result)

Arguments

Value

A tibble with a tidy version of the summarised_characteristics object.

Examples

cdm <- mockMGUS2cdm()
surv <- estimateSingleEventSurvival(
  cdm = cdm,
  targetCohortTable = "mgus_diagnosis",
  targetCohortId = 1,
  outcomeCohortTable = "death_cohort",
  outcomeCohortId = 1,
  eventGap = 7
) %>%
  asSurvivalResult()

Estimate survival for a given event and competing risk of interest using cohorts in the OMOP Common Data Model

Description

Estimate survival for a given event and competing risk of interest using cohorts in the OMOP Common Data Model

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,
  followUpDays = Inf,
  strata = NULL,
  eventGap = 30,
  estimateGap = 1,
  restrictedMeanFollowUp = NULL,
  minimumSurvivalDays = 1
)

Arguments

Value

tibble with survival information for desired cohort, including: time, people at risk, survival probability, cumulative incidence, 95 CIs, strata and outcome. A tibble with the number of events is outputted as an attribute of the output

Examples

cdm <- mockMGUS2cdm()
surv <- estimateCompetingRiskSurvival(
  cdm = cdm,
  targetCohortTable = "mgus_diagnosis",
  targetCohortId = 1,
  outcomeCohortTable = "progression",
  outcomeCohortId = 1,
  competingOutcomeCohortTable = "death_cohort",
  competingOutcomeCohortId = 1,
  eventGap = 7
)

Estimate survival for a given event of interest using cohorts in the OMOP Common Data Model

Description

Estimate survival for a given event of interest using cohorts in the OMOP Common Data Model

Usage

estimateSingleEventSurvival(
  cdm,
  targetCohortTable,
  outcomeCohortTable,
  targetCohortId = NULL,
  outcomeCohortId = NULL,
  outcomeDateVariable = "cohort_start_date",
  outcomeWashout = Inf,
  censorOnCohortExit = FALSE,
  censorOnDate = NULL,
  followUpDays = Inf,
  strata = NULL,
  eventGap = 30,
  estimateGap = 1,
  restrictedMeanFollowUp = NULL,
  minimumSurvivalDays = 1
)

Arguments

Value

tibble with survival information for desired cohort, including: time, people at risk, survival probability, cumulative incidence, 95 CIs, strata and outcome. A tibble with the number of events is outputted as an attribute of the output

Examples

cdm <- mockMGUS2cdm()
surv <- estimateSingleEventSurvival(
  cdm = cdm,
  targetCohortTable = "mgus_diagnosis",
  targetCohortId = 1,
  outcomeCohortTable = "death_cohort",
  outcomeCohortId = 1,
  eventGap = 7
)

Create mock CDM reference with survival::mgus2 dataset

Description

Create mock CDM reference with survival::mgus2 dataset

Usage

mockMGUS2cdm()

Value

CDM reference containing data from the survival::mgus2 dataset

Examples

 
cdm <- mockMGUS2cdm()
cdm$person

Additional arguments for the function tableSurvival()

Description

It provides a list of allowed inputs for .option argument in tableSurvival and their given default value.

Usage

optionsTableSurvival()

Value

The default .options named list.

Examples

{
optionsTableSurvival()
}

Plot survival results

Description

Plot survival results

Usage

plotSurvival(
  result,
  ribbon = TRUE,
  facet = NULL,
  colour = NULL,
  cumulativeFailure = FALSE,
  riskTable = FALSE,
  riskInterval = 30,
  logLog = FALSE,
  timeScale = "days"
)

Arguments

Value

A plot of survival probabilities over time

Examples

cdm <- mockMGUS2cdm()
surv <- estimateSingleEventSurvival(cdm,
                                    targetCohortTable = "mgus_diagnosis",
                                    outcomeCohortTable = "death_cohort")
plotSurvival(surv)

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

omopgenerics

attrition, bind, cohortCodelist, cohortCount, exportSummarisedResult, importSummarisedResult, settings, suppress

Table with survival events

Description

Table with survival events

Usage

riskTable(
  x,
  eventGap = NULL,
  header = c("estimate"),
  type = "gt",
  groupColumn = NULL,
  .options = list()
)

Arguments

Value

A tibble containing the risk table information (n_risk, n_events, n_censor) for all times within the event gap specified.

Examples

cdm <- mockMGUS2cdm()
surv <- estimateSingleEventSurvival(cdm,
                                    targetCohortTable = "mgus_diagnosis",
                                    outcomeCohortTable = "death_cohort")
riskTable(surv)

Table with survival summary

Description

Table with survival summary

Usage

tableSurvival(
  x,
  times = NULL,
  timeScale = "days",
  header = c("estimate"),
  type = "gt",
  groupColumn = NULL,
  .options = list()
)

Arguments

Value

A tibble containing a summary of observed survival in the required units

Examples

cdm <- mockMGUS2cdm()
surv <- estimateSingleEventSurvival(cdm,
                                    targetCohortTable = "mgus_diagnosis",
                                    outcomeCohortTable = "death_cohort")
tableSurvival(surv, times = c(50,100,365))

Tidy eval helpers

Description

This page lists the tidy eval tools reexported in this package from rlang. To learn about using tidy eval in scripts and packages at a high level, see the dplyr programming vignette and the ggplot2 in packages vignette. The Metaprogramming section of Advanced R may also be useful for a deeper dive.

• The tidy eval operators ⁠{{⁠, ⁠!!⁠, and ⁠!!!⁠ are syntactic constructs which are specially interpreted by tidy eval functions. You will mostly need ⁠{{⁠, as ⁠!!⁠ and ⁠!!!⁠ are more advanced operators which you should not have to use in simple cases.

  The curly-curly operator ⁠{{⁠ allows you to tunnel data-variables passed from function arguments inside other tidy eval functions. ⁠{{⁠ is designed for individual arguments. To pass multiple arguments contained in dots, use ... in the normal way.

  my_function <- function(data, var, ...) {
    data %>%
      group_by(...) %>%
      summarise(mean = mean({{ var }}))
  }
  

• enquo() and enquos() delay the execution of one or several function arguments. The former returns a single expression, the latter returns a list of expressions. Once defused, expressions will no longer evaluate on their own. They must be injected back into an evaluation context with ⁠!!⁠ (for a single expression) and ⁠!!!⁠ (for a list of expressions).

  my_function <- function(data, var, ...) {
    # Defuse
    var <- enquo(var)
    dots <- enquos(...)
  
    # Inject
    data %>%
      group_by(!!!dots) %>%
      summarise(mean = mean(!!var))
  }
  

  In this simple case, the code is equivalent to the usage of ⁠{{⁠ and ... above. Defusing with enquo() or enquos() is only needed in more complex cases, for instance if you need to inspect or modify the expressions in some way.

• The .data pronoun is an object that represents the current slice of data. If you have a variable name in a string, use the .data pronoun to subset that variable with [[.

  my_var <- "disp"
  mtcars %>% summarise(mean = mean(.data[[my_var]]))
  

• Another tidy eval operator is ⁠:=⁠. It makes it possible to use glue and curly-curly syntax on the LHS of =. For technical reasons, the R language doesn't support complex expressions on the left of =, so we use ⁠:=⁠ as a workaround.

  my_function <- function(data, var, suffix = "foo") {
    # Use `{{` to tunnel function arguments and the usual glue
    # operator `{` to interpolate plain strings.
    data %>%
      summarise("{{ var }}_mean_{suffix}" := mean({{ var }}))
  }
  

• Many tidy eval functions like dplyr::mutate() or dplyr::summarise() give an automatic name to unnamed inputs. If you need to create the same sort of automatic names by yourself, use as_label(). For instance, the glue-tunnelling syntax above can be reproduced manually with:

  my_function <- function(data, var, suffix = "foo") {
    var <- enquo(var)
    prefix <- as_label(var)
    data %>%
      summarise("{prefix}_mean_{suffix}" := mean(!!var))
  }
  

  Expressions defused with enquo() (or tunnelled with ⁠{{⁠) need not be simple column names, they can be arbitrarily complex. as_label() handles those cases gracefully. If your code assumes a simple column name, use as_name() instead. This is safer because it throws an error if the input is not a name as expected.

Value

No return value, called for side effects