Type:	Package
Title:	Analyzes Real-World Treatment Patterns of a Study Population of Interest
Version:	3.1.0
Maintainer:	Maarten van Kessel <m.l.vankessel@erasmusmc.nl>
Description:	Computes treatment patterns within a given cohort using the Observational Medical Outcomes Partnership (OMOP) common data model (CDM). As described in Markus, Verhamme, Kors, and Rijnbeek (2022) <doi:10.1016/j.cmpb.2022.107081>.
URL:	https://github.com/darwin-eu/TreatmentPatterns, https://darwin-eu-dev.github.io/TreatmentPatterns/
BugReports:	https://github.com/darwin-eu/TreatmentPatterns/issues
Language:	en-US
Depends:	R (≥ 4.2)
Imports:	checkmate, dplyr, stringr, utils, stats, Andromeda, tidyr, R6, sunburstR, networkD3, htmlwidgets, ggplot2, dbplyr, jsonlite
Suggests:	knitr, rmarkdown, tibble, testthat (≥ 3.0.0), usethis, Eunomia, CDMConnector, DatabaseConnector (≥ 6.0.0), SqlRender, CohortGenerator, ResultModelManager, webshot2, CirceR, duckdb, DBI, withr, plotly, PaRe
License:	Apache License (≥ 2)
Encoding:	UTF-8
RoxygenNote:	7.3.2
VignetteBuilder:	knitr
Config/testthat/edition:	3
Config/testthat/parallel:	true
Collate:	'CDMInterface.R' 'TreatmentPatterns-package.R' 'TreatmentPatternsResults.R' 'attrition.R' 'computePathways.R' 'constructPathways.R' 'createSankeyDiagram.R' 'createSunburstPlot.R' 'executeTreatmentPatterns.R' 'export.R' 'exportPatientLevel.R' 'getResultsDataModelSpecification.R' 'ggSunburst.R' 'plotEventDuration.R'
NeedsCompilation:	no
Packaged:	2025-06-03 14:01:36 UTC; mvankessel
Author:	Aniek Markus [aut], Maarten van Kessel [cre]
Repository:	CRAN
Date/Publication:	2025-06-03 14:50:08 UTC

TreatmentPatterns: Analyzes Real-World Treatment Patterns of a Study Population of Interest

Description

Computes treatment patterns within a given cohort using the Observational Medical Outcomes Partnership (OMOP) common data model (CDM). As described in Markus, Verhamme, Kors, and Rijnbeek (2022) doi:10.1016/j.cmpb.2022.107081.

Author(s)

Maintainer: Maarten van Kessel m.l.vankessel@erasmusmc.nl (ORCID)

Authors:

• Aniek Markus (ORCID)

See Also

Useful links:

• https://github.com/darwin-eu/TreatmentPatterns

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

• Report bugs at https://github.com/darwin-eu/TreatmentPatterns/issues

TreatmentPatternsResults Class

Description

Houses the results of a TreatmentPatterns analysis. Each field corresponds to a file. Plotting methods are provided.

Active bindings

Methods

Public methods

• TreatmentPatternsResults$new()

• TreatmentPatternsResults$saveAsZip()

• TreatmentPatternsResults$saveAsCsv()

• TreatmentPatternsResults$uploadResultsToDb()

• TreatmentPatternsResults$load()

• TreatmentPatternsResults$plotSunburst()

• TreatmentPatternsResults$plotSankey()

• TreatmentPatternsResults$plotEventDuration()

• TreatmentPatternsResults$clone()

Method new()

Initializer method

Usage

TreatmentPatternsResults$new(
  attrition = NULL,
  metadata = NULL,
  treatmentPathways = NULL,
  summaryEventDuration = NULL,
  countsAge = NULL,
  countsSex = NULL,
  countsYear = NULL,
  cdmSourceInfo = NULL,
  analyses = NULL,
  arguments = NULL,
  filePath = NULL
)

Arguments

Method saveAsZip()

Save the results as a zip-file.

Usage

TreatmentPatternsResults$saveAsZip(path, name, verbose = TRUE)

Arguments

Returns

self

Method saveAsCsv()

Save the results as csv-files.

Usage

TreatmentPatternsResults$saveAsCsv(path, verbose = TRUE)

Arguments

Returns

self

Method uploadResultsToDb()

Upload results to a resultsDatabase using ResultModelManager.

Usage

TreatmentPatternsResults$uploadResultsToDb(
  connectionDetails,
  schema,
  prefix = "tp_",
  overwrite = TRUE,
  purgeSiteDataBeforeUploading = FALSE
)

Arguments

Returns

self

Method load()

Load data from files.

Usage

TreatmentPatternsResults$load(filePath)

Arguments

Returns

self

Method plotSunburst()

Wrapper for TreatmentPatterns::createSunburstPlot(), but with data filtering step.

Usage

TreatmentPatternsResults$plotSunburst(
  age = "all",
  sex = "all",
  indexYear = "all",
  nonePaths = FALSE,
  ...
)

Arguments

Returns

htmlwidget

Method plotSankey()

Wrapper for TreatmentPatterns::createSankeyDiagram(), but with data filtering step.

Usage

TreatmentPatternsResults$plotSankey(
  age = "all",
  sex = "all",
  indexYear = "all",
  nonePaths = FALSE,
  ...
)

Arguments

Returns

htmlwidget

Method plotEventDuration()

Wrapper for TreatmentPatterns::plotEventDuration().

Usage

TreatmentPatternsResults$plotEventDuration(...)

Arguments

Returns

ggplot

Method clone()

The objects of this class are cloneable with this method.

Usage

TreatmentPatternsResults$clone(deep = FALSE)

Arguments

computePathways

Description

Compute treatment patterns according to the specified parameters within specified cohorts.

Usage

computePathways(
  cohorts,
  cohortTableName,
  cdm = NULL,
  connectionDetails = NULL,
  cdmSchema = NULL,
  resultSchema = NULL,
  analysisId = 1,
  description = "",
  tempEmulationSchema = NULL,
  startAnchor = "startDate",
  windowStart = 0,
  endAnchor = "endDate",
  windowEnd = 0,
  minEraDuration = 0,
  splitEventCohorts = NULL,
  splitTime = NULL,
  eraCollapseSize = 30,
  combinationWindow = 30,
  minPostCombinationDuration = 30,
  filterTreatments = "First",
  maxPathLength = 5,
  overlapMethod = "truncate",
  concatTargets = TRUE
)

Arguments

Value

(Andromeda::andromeda()) andromeda object containing non-sharable patient level data outcomes.

Examples

ableToRun <- all(
  require("CirceR", character.only = TRUE, quietly = TRUE),
  require("CDMConnector", character.only = TRUE, quietly = TRUE),
  require("TreatmentPatterns", character.only = TRUE, quietly = TRUE),
  require("dplyr", character.only = TRUE, quietly = TRUE)
)

if (ableToRun) {
  library(TreatmentPatterns)
  library(CDMConnector)
  library(dplyr)

  withr::local_envvar(
    R_USER_CACHE_DIR = tempfile(),
    EUNOMIA_DATA_FOLDER = Sys.getenv("EUNOMIA_DATA_FOLDER", unset = tempfile())
  )

  tryCatch(
    {
      if (Sys.getenv("skip_eunomia_download_test") != "TRUE") {
        CDMConnector::downloadEunomiaData(overwrite = TRUE)
      }
    },
    error = function(e) NA
  )

  con <- DBI::dbConnect(duckdb::duckdb(), dbdir = eunomiaDir())
  cdm <- cdmFromCon(con, cdmSchema = "main", writeSchema = "main")

  cohortSet <- readCohortSet(
    path = system.file(package = "TreatmentPatterns", "exampleCohorts")
  )

  cdm <- generateCohortSet(
    cdm = cdm,
    cohortSet = cohortSet,
    name = "cohort_table"
  )

  cohorts <- cohortSet %>%
    # Remove 'cohort' and 'json' columns
    select(-"cohort", -"json") %>%
    mutate(type = c("event", "event", "event", "event", "exit", "event", "event", "target")) %>%
    rename(
      cohortId = "cohort_definition_id",
      cohortName = "cohort_name",
    ) %>%
    select("cohortId", "cohortName", "type")

  outputEnv <- computePathways(
    cohorts = cohorts,
    cohortTableName = "cohort_table",
    cdm = cdm
  )

  Andromeda::close(outputEnv)
  DBI::dbDisconnect(con, shutdown = TRUE)
}

createSankeyDiagram

Description

Create sankey diagram.

Usage

createSankeyDiagram(
  treatmentPathways,
  groupCombinations = FALSE,
  colors = NULL,
  ...
)

Arguments

Value

(htmlwidget)

Examples

# Dummy data, typically read from treatmentPathways.csv
treatmentPathways <- data.frame(
  pathway = c("Acetaminophen", "Acetaminophen-Amoxicillin+Clavulanate",
           "Acetaminophen-Aspirin", "Amoxicillin+Clavulanate", "Aspirin"),
  freq = c(206, 6, 14, 48, 221),
  sex = rep("all", 5),
  age = rep("all", 5),
  index_year = rep("all", 5)
)

createSankeyDiagram(treatmentPathways)

createSunburstPlot

Description

New sunburstPlot function

Usage

createSunburstPlot(treatmentPathways, groupCombinations = FALSE, ...)

Arguments

Value

(htmlwidget)

Examples

# Dummy data, typically read from treatmentPathways.csv
treatmentPatwhays <- data.frame(
  pathway = c("Acetaminophen", "Acetaminophen-Amoxicillin+Clavulanate",
           "Acetaminophen-Aspirin", "Amoxicillin+Clavulanate", "Aspirin"),
  freq = c(206, 6, 14, 48, 221),
  sex = rep("all", 5),
  age = rep("all", 5),
  index_year = rep("all", 5)
)

createSunburstPlot(treatmentPatwhays)

executeTreatmentPatterns

Description

Compute treatment patterns according to the specified parameters within specified cohorts. For more customization, or investigation of patient level outcomes, you can run computePathways and export separately.

Usage

executeTreatmentPatterns(
  cohorts,
  cohortTableName,
  cdm = NULL,
  connectionDetails = NULL,
  cdmSchema = NULL,
  resultSchema = NULL,
  tempEmulationSchema = NULL,
  minEraDuration = 0,
  eraCollapseSize = 30,
  combinationWindow = 30,
  minCellCount = 5
)

Arguments

Value

TreatmentPatternsResults

Examples

ableToRun <- all(
  require("CirceR", character.only = TRUE, quietly = TRUE),
  require("CDMConnector", character.only = TRUE, quietly = TRUE),
  require("TreatmentPatterns", character.only = TRUE, quietly = TRUE),
  require("dplyr", character.only = TRUE, quietly = TRUE)
)

if (require("CirceR", character.only = TRUE, quietly = TRUE)) {
  library(TreatmentPatterns)
  library(CDMConnector)
  library(dplyr)

  withr::local_envvar(
    R_USER_CACHE_DIR = tempfile(),
    EUNOMIA_DATA_FOLDER = Sys.getenv("EUNOMIA_DATA_FOLDER", unset = tempfile())
  )

  tryCatch(
    {
      if (Sys.getenv("skip_eunomia_download_test") != "TRUE") {
        CDMConnector::downloadEunomiaData(overwrite = TRUE)
      }
    },
    error = function(e) NA
  )

  con <- DBI::dbConnect(duckdb::duckdb(), dbdir = eunomiaDir())
  cdm <- cdmFromCon(con, cdmSchema = "main", writeSchema = "main")

  cohortSet <- readCohortSet(
    path = system.file(package = "TreatmentPatterns", "exampleCohorts")
  )

  cdm <- generateCohortSet(
    cdm = cdm,
    cohortSet = cohortSet,
    name = "cohort_table"
  )

  cohorts <- cohortSet %>%
    # Remove 'cohort' and 'json' columns
    select(-"cohort", -"json") %>%
    mutate(type = c("event", "event", "event", "event", "exit", "event", "event", "target")) %>%
    rename(
      cohortId = "cohort_definition_id",
      cohortName = "cohort_name",
    ) %>%
    select("cohortId", "cohortName", "type")

  executeTreatmentPatterns(
    cohorts = cohorts,
    cohortTableName = "cohort_table",
    cdm = cdm
  )

  DBI::dbDisconnect(con, shutdown = TRUE)
}

export

Description

Export andromeda generated by computePathways object to sharable csv-files and/or a zip archive.

Usage

export(
  andromeda,
  outputPath = NULL,
  ageWindow = 10,
  minCellCount = 5,
  censorType = "minCellCount",
  archiveName = NULL,
  nonePaths = FALSE,
  stratify = FALSE
)

Arguments

Value

TreatmentPatternsResults object

Examples

ableToRun <- all(
  require("CirceR", character.only = TRUE, quietly = TRUE),
  require("CDMConnector", character.only = TRUE, quietly = TRUE),
  require("TreatmentPatterns", character.only = TRUE, quietly = TRUE),
  require("dplyr", character.only = TRUE, quietly = TRUE)
)

if (ableToRun) {
  library(TreatmentPatterns)
  library(CDMConnector)
  library(dplyr)

  withr::local_envvar(
    R_USER_CACHE_DIR = tempfile(),
    EUNOMIA_DATA_FOLDER = Sys.getenv("EUNOMIA_DATA_FOLDER", unset = tempfile())
  )

  tryCatch({
    if (Sys.getenv("skip_eunomia_download_test") != "TRUE") {
      CDMConnector::downloadEunomiaData(overwrite = TRUE)
    }
  }, error = function(e) NA)

  con <- DBI::dbConnect(duckdb::duckdb(), dbdir = eunomiaDir())
  cdm <- cdmFromCon(con, cdmSchema = "main", writeSchema = "main")

  cohortSet <- readCohortSet(
    path = system.file(package = "TreatmentPatterns", "exampleCohorts")
  )

  cdm <- generateCohortSet(
    cdm = cdm,
    cohortSet = cohortSet,
    name = "cohort_table"
  )

  cohorts <- cohortSet %>%
    # Remove 'cohort' and 'json' columns
    select(-"cohort", -"json") %>%
    mutate(type = c("event", "event", "event", "event", "exit", "event", "event", "target")) %>%
    rename(
      cohortId = "cohort_definition_id",
      cohortName = "cohort_name",
    ) %>%
    select("cohortId", "cohortName", "type")

  outputEnv <- computePathways(
    cohorts = cohorts,
    cohortTableName = "cohort_table",
    cdm = cdm
  )

  results <- export(
    andromeda = outputEnv
  )

  Andromeda::close(outputEnv)
  DBI::dbDisconnect(con, shutdown = TRUE)
}

exportPatientLevel

Description

Exports patient-level files for custom data analysis.

Usage

exportPatientLevel(andromeda, outputPath)

Arguments

Value

NULL

Examples

if (interactive()) {
  library(CDMConnector)
  library(DBI)
  library(TreatmentPatterns)

  con <- DBI::dbConnect(duckdb::duckdb(), dbdir = CDMConnector::eunomiaDir())
  cdm <- cdmFromCon(con, cdmSchema = "main", writeSchema = "main")

  cohortSet <- readCohortSet(
    path = system.file(package = "TreatmentPatterns", "exampleCohorts")
  )

  cdm <- generateCohortSet(
    cdm = cdm,
    cohortSet = cohortSet,
    name = "cohort_table"
  )

  cohorts <- cohortSet %>%
    # Remove 'cohort' and 'json' columns
    select(-"cohort", -"json") %>%
    mutate(type = c("event", "event", "event", "event", "exit", "event", "event", "target")) %>%
    rename(
      cohortId = "cohort_definition_id",
      cohortName = "cohort_name",
    ) %>%
    select("cohortId", "cohortName", "type")

  outputEnv <- computePathways(
    cohorts = cohorts,
    cohortTableName = "cohort_table",
    cdm = cdm
  )

  exportPatientLevel(outputEnv, tempdir())
}

getResultsDataModelSpecifications

Description

Gets the results data model specifications of TreatmentPatterns.

Usage

getResultsDataModelSpecifications()

Value

data.frame

Examples

{
getResultsDataModelSpecifications()
}

ggSunburst

Description

ggSunburst

Usage

ggSunburst(treatmentPathways, groupCombinations = FALSE, unit = "percent")

Arguments

Value

(gg, ggplot)

Examples

# Dummy data, typically read from treatmentPathways.csv
treatmentPatwhays <- data.frame(
  pathway = c("Acetaminophen", "Acetaminophen-Amoxicillin+Clavulanate",
           "Acetaminophen-Aspirin", "Amoxicillin+Clavulanate", "Aspirin"),
  freq = c(206, 6, 14, 48, 221),
  sex = rep("all", 5),
  age = rep("all", 5),
  index_year = rep("all", 5)
)

ggSunburst(treatmentPatwhays)

plotEventDuration

Description

plotEventDuration

Usage

plotEventDuration(
  eventDurations,
  minCellCount = 0,
  treatmentGroups = "both",
  eventLines = NULL,
  includeOverall = TRUE
)

Arguments

Value

ggplot

Examples

ableToRun <- all(
  require("CirceR", character.only = TRUE, quietly = TRUE),
  require("CDMConnector", character.only = TRUE, quietly = TRUE),
  require("TreatmentPatterns", character.only = TRUE, quietly = TRUE),
  require("dplyr", character.only = TRUE, quietly = TRUE)
)

if (ableToRun) {
  withr::local_envvar(
    R_USER_CACHE_DIR = tempfile(),
    EUNOMIA_DATA_FOLDER = Sys.getenv("EUNOMIA_DATA_FOLDER", unset = tempfile())
  )

  tryCatch({
    if (Sys.getenv("skip_eunomia_download_test") != "TRUE") {
      CDMConnector::downloadEunomiaData(overwrite = TRUE)
    }
  }, error = function(e) NA)

  con <- DBI::dbConnect(duckdb::duckdb(), dbdir = eunomiaDir())
  cdm <- cdmFromCon(con, cdmSchema = "main", writeSchema = "main")

  cohortSet <- readCohortSet(
    path = system.file(package = "TreatmentPatterns", "exampleCohorts")
  )

  cdm <- generateCohortSet(
    cdm = cdm,
    cohortSet = cohortSet,
    name = "cohort_table"
  )

  cohorts <- cohortSet %>%
    # Remove 'cohort' and 'json' columns
    select(-"cohort", -"json") %>%
    mutate(type = c("event", "event", "event", "event", "exit", "event", "event", "target")) %>%
    rename(
      cohortId = "cohort_definition_id",
      cohortName = "cohort_name",
    ) %>%
    select("cohortId", "cohortName", "type")

  outputEnv <- computePathways(
    cohorts = cohorts,
    cohortTableName = "cohort_table",
    cdm = cdm
  )

  results <- export(outputEnv)

  plotEventDuration(
    eventDurations = results$summary_event_duration,
    minCellCount = 5,
    treatmentGroups = "group",
    eventLines = 1:4,
    includeOverall = FALSE
  )

  Andromeda::close(outputEnv)
  DBI::dbDisconnect(con, shutdown = TRUE)
}