% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/EventSequenceGraph.R
\name{buildEventSequenceGraph}
\alias{buildEventSequenceGraph}
\title{Build an event sequence graph from pathway analysis results.}
\usage{
buildEventSequenceGraph(
  cpResults,
  generationSet,
  maxSteps = NULL,
  minCount = 1
)
}
\arguments{
\item{cpResults}{A list returned by \code{\link{executeCohortPathways}}.
Must contain at least \code{pathwaysAnalysisPathsData},
\code{pathwayAnalysisCodesLong}, and \code{isCombo}.}

\item{generationSet}{A data frame with at least two columns:
\code{cohortId} (integer) and \code{cohortName} (character).
Used to map event cohort IDs to descriptive names.}

\item{maxSteps}{(Optional) Maximum number of steps to include. If \code{NULL}
(default), all non-empty steps are used.}

\item{minCount}{(Default = 1) Minimum patient count for a pathway to be
included in the output.}
}
\value{
A list of class \code{"event_sequence_graph"} with components
\code{graph} (igraph object), \code{sequences}, \code{summary}, and
\code{eventNameLookup}.
}
\description{
Takes the output of \code{\link{executeCohortPathways}} and a cohort name
mapping, decodes the bitmask-encoded combo IDs into human-readable event
names, and builds a directed \pkg{igraph} graph representing event
transitions across pathway steps.

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

The returned object includes:
\itemize{
\item \strong{graph}: A directed, weighted \code{\link[igraph]{igraph}}
object. Vertex attributes: \code{name}, \code{eventName},
\code{step}, \code{count}, \code{share}. Edge attributes:
\code{weight} (= patient count), \code{probability},
\code{sourceStep}, \code{targetStep}.
\item \strong{sequences}: The fully decoded pathway sequences with a
human-readable \code{pathway} string column.
\item \strong{summary}: High-level statistics (total pathways, patients,
depth, unique events, vertex/edge counts).
\item \strong{eventNameLookup}: Named character vector mapping combo IDs
to event names.
}
}
\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)
}

}
