OdysseusPathwayModule: Cohort Pathway Analysis with Pre-Index Event Support

Description

Provides cohort pathway analysis for Observational Medical Outcomes Partnership (OMOP) Common Data Model databases, including both standard (post-index) and pre-index pathway analyses. The pre-index analysis identifies sequences of events occurring in a lookback window before the target cohort index date. Built on the 'CohortPathways' analysis framework originally developed by Christopher Knoll and the Observational Health Data Sciences and Informatics community through 'WebAPI'. Methodological background and the originating implementation are described in https://github.com/OHDSI/CohortPathways.

Author(s)

Maintainer: Alexander Alexeyuk AlexanderAlexeyuk@gmail.com

Build a named lookup vector: character(comboId) -> "EventA + EventB"

Description

Build a named lookup vector: character(comboId) -> "EventA + EventB"

Usage

.buildEventNameLookup(codesLong, generationSet)

Build an event sequence graph from pathway analysis results.

Description

Takes the output of executeCohortPathways and a cohort name mapping, decodes the bitmask-encoded combo IDs into human-readable event names, and builds a directed igraph graph representing event transitions across pathway steps.

Nodes in the graph represent unique (event, step) combinations. Edges represent directed transitions between consecutive steps, weighted by patient counts and annotated with transition probabilities.

The returned object includes:

• graph: A directed, weighted igraph object. Vertex attributes: name, eventName, step, count, share. Edge attributes: weight (= patient count), probability, sourceStep, targetStep.

• sequences: The fully decoded pathway sequences with a human-readable pathway string column.

• summary: High-level statistics (total pathways, patients, depth, unique events, vertex/edge counts).

• eventNameLookup: Named character vector mapping combo IDs to event names.

Usage

buildEventSequenceGraph(
  cpResults,
  generationSet,
  maxSteps = NULL,
  minCount = 1
)

Arguments

Value

A list of class "event_sequence_graph" with components graph (igraph object), sequences, summary, and eventNameLookup.

Examples

if (requireNamespace("igraph", quietly = TRUE)) {
  cpResults <- list(
    pathwaysAnalysisPathsData = data.frame(
      pathwayAnalysisGenerationId = c(1L, 1L),
      targetCohortId = c(10L, 10L),
      step1 = c(2L, 4L),
      step2 = c(4L, NA_integer_),
      countValue = c(10L, 5L)
    ),
    pathwayAnalysisCodesLong = data.frame(
      pathwayAnalysisGenerationId = c(1L, 1L),
      code = c(2L, 4L),
      targetCohortId = c(10L, 10L),
      eventCohortId = c(1L, 2L),
      isCombo = c(0L, 0L),
      numberOfEvents = c(1L, 1L)
    ),
    isCombo = data.frame(
      targetCohortId = c(10L, 10L),
      comboId = c(2L, 4L),
      numberOfEvents = c(1L, 1L),
      isCombo = c(0L, 0L)
    )
  )

  generationSet <- data.frame(
    cohortId = c(1L, 2L, 10L),
    cohortName = c("Celecoxib", "Diclofenac", "NSAIDs")
  )

  esg <- buildEventSequenceGraph(cpResults, generationSet)
  esg$summary
  igraph::gorder(esg$graph)
}

Execute cohort pathway analysis.

Description

Runs the cohort pathways on all instantiated combinations of target and event cohorts. Assumes the cohorts have already been instantiated.

Supports two analysis types:

• "post-index" (default): events occurring after the target cohort index date (within the target cohort period).

• "pre-index": events occurring before the target cohort index date, in a configurable lookback window. For example, what events occurred in the 365 days before cohort entry.

Target and event cohorts can reside in different schemas/tables:

• cohortDatabaseSchema / cohortTableName for target cohorts.

• outcomeDatabaseSchema / outcomeTableName for event (outcome) cohorts. If not specified, defaults to the same as the target.

Usage

executeCohortPathways(
  connectionDetails = NULL,
  connection = NULL,
  cohortDatabaseSchema,
  cohortTableName = "cohort",
  outcomeDatabaseSchema = cohortDatabaseSchema,
  outcomeTableName = cohortTableName,
  tempEmulationSchema = getOption("sqlRenderTempEmulationSchema"),
  targetCohortIds,
  eventCohortIds,
  analysisType = "post-index",
  lookbackStartDay = -365,
  lookbackEndDay = -1,
  minCellCount = 5,
  allowRepeats = FALSE,
  maxDepth = 5,
  collapseWindow = 30
)

Arguments

Value

                 A list of data frames containing pathway analysis results.

Examples

if (requireNamespace("Eunomia", quietly = TRUE) &&
    exists("createCohorts", where = asNamespace("Eunomia"), inherits = FALSE)) {
  connectionDetails <- Eunomia::getEunomiaConnectionDetails()
  createCohorts <- get("createCohorts", envir = asNamespace("Eunomia"))
  createCohorts(connectionDetails)

  postIndexResults <- executeCohortPathways(
    connectionDetails = connectionDetails,
    cohortDatabaseSchema = "main",
    cohortTableName = "cohort",
    targetCohortIds = 4,
    eventCohortIds = c(1, 2, 3),
    maxDepth = 3
  )

  preIndexResults <- executeCohortPathways(
    connectionDetails = connectionDetails,
    cohortDatabaseSchema = "main",
    cohortTableName = "cohort",
    targetCohortIds = 4,
    eventCohortIds = c(1, 2, 3),
    analysisType = "pre-index",
    lookbackStartDay = -365,
    lookbackEndDay = -1,
    maxDepth = 3
  )

  names(postIndexResults)
  names(preIndexResults)
}

Plot an event sequence graph.

Description

Produces a layered plot of the event sequence graph using plot.igraph. Nodes are laid out by step (left to right), with edge widths proportional to patient counts and node sizes proportional to event counts within each step.

Usage

## S3 method for class 'event_sequence_graph'
plot(
  x,
  colorPalette = NULL,
  edgeWidthRange = c(0.5, 8),
  vertexSizeRange = c(8, 25),
  vertexLabelCex = 0.7,
  main = "Event Sequence Graph",
  ...
)

Arguments

Value

Invisibly returns the igraph object.

Examples

if (requireNamespace("igraph", quietly = TRUE)) {
  cpResults <- list(
    pathwaysAnalysisPathsData = data.frame(
      pathwayAnalysisGenerationId = c(1L, 1L),
      targetCohortId = c(10L, 10L),
      step1 = c(2L, 4L),
      step2 = c(4L, NA_integer_),
      countValue = c(10L, 5L)
    ),
    pathwayAnalysisCodesLong = data.frame(
      pathwayAnalysisGenerationId = c(1L, 1L),
      code = c(2L, 4L),
      targetCohortId = c(10L, 10L),
      eventCohortId = c(1L, 2L),
      isCombo = c(0L, 0L),
      numberOfEvents = c(1L, 1L)
    ),
    isCombo = data.frame(
      targetCohortId = c(10L, 10L),
      comboId = c(2L, 4L),
      numberOfEvents = c(1L, 1L),
      isCombo = c(0L, 0L)
    )
  )

  generationSet <- data.frame(
    cohortId = c(1L, 2L, 10L),
    cohortName = c("Celecoxib", "Diclofenac", "NSAIDs")
  )

  esg <- buildEventSequenceGraph(cpResults, generationSet)
  plot(esg)
}