% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/findShortestPaths.R
\name{findShortestPaths}
\alias{findShortestPaths}
\title{Identify Shortest Paths Between Node Sets in a KEGG-Derived Network}
\usage{
findShortestPaths(
  network_table,
  source_nodes,
  target_nodes,
  mode = c("out", "in", "all"),
  output = c("path_list", "network_matrix"),
  name = FALSE,
  distance_threshold = Inf,
  betweenness = FALSE,
  reactant_filter = FALSE
)
}
\arguments{
\item{network_table}{A 3-column matrix or data.frame of edges with columns
\code{source}, \code{target}, \code{interaction_type}, typically from
\code{buildKeggNetwork()} or \code{buildCrossSpeciesNetwork()}.}

\item{source_nodes}{Character vector of KEGG node IDs to use as path sources.}

\item{target_nodes}{Character vector of KEGG node IDs to use as path targets.}

\item{mode}{Character; direction mode passed to \code{igraph} shortest-path
and distance functions. One of:
\describe{
\item{\code{"out"}}{Shortest-path search follows edge direction.}
\item{\code{"in"}}{Shortest-path search is computed against edge direction (reverse direction).}
\item{\code{"all"}}{Ignore edge direction during shortest-path search
(graph treated as undirected). For \code{output = "network_matrix"},
interaction types are still recovered from the original network edge
annotation.}
}}

\item{output}{Character; output format:
\itemize{
\item \code{"path_list"} - list of shortest paths per source-target pair.
\item \code{"network_matrix"} - 3-column edge list (source, target, interaction_type).
}}

\item{name}{Logical; if \code{TRUE} and \code{output = "path_list"}, node
IDs are converted to KEGG names or symbols via \pkg{KEGGREST}.}

\item{distance_threshold}{Numeric; only source-target pairs with
shortest-path distance \eqn{\le} this value are processed (default \code{Inf}).}

\item{betweenness}{Logical (default \code{FALSE}). If \code{TRUE}, when more than
one shortest path of the same length exists for a given source-target pair,
a single path is selected by ranking candidate shortest paths by node betweenness.}

\item{reactant_filter}{Logical (default \code{FALSE}). If \code{TRUE},
shortest paths are filtered to keep only paths whose consecutive
compound-compound transitions are supported by KEGG reaction data.
This step issues repeated KEGG API queries and may be slow for large
path sets.}
}
\value{
Depending on \code{output}:
\itemize{
\item \code{"path_list"} - named list; each element is one or more shortest
paths (character vectors of node IDs or names).
\item \code{"network_matrix"} - 3-column matrix of unique edges traversed
by the identified shortest paths. Edges are returned in path order,
and \code{interaction_type} is assigned from the original network
edge annotation.
}
}
\description{
Computes shortest paths between specified source and target node sets
in a KEGG-based network. Source nodes are often KEGG KOs/genes
(upstream biological functions) and target nodes are often KEGG compounds
(downstream metabolites), but this is a recommended usage pattern rather
than a strict requirement.
}
\details{
Valid source-target pairs are first filtered by graph distance, and paths
can be returned either as path lists or as a condensed edge list.

The function:
\itemize{
\item Accepts \code{matrix} or \code{data.frame} input and internally
standardizes it to a character edge table.
\item Builds a directed \pkg{igraph} graph from \code{network_table} and
computes pairwise shortest-path distances (breadth-first search on
this unweighted graph).
\item Stops if any node is present in both \code{source_nodes} and
\code{target_nodes}, because the distance from a node to itself is 0
and is not allowed in this workflow.
\item Keeps only mapped source-target pairs with finite distance within
\code{distance_threshold}; unreachable pairs (\code{Inf}) and pairs
longer than the threshold are filtered out and not processed further.
\item If \code{mode = "all"}, shortest-path search ignores edge direction.
However, for \code{output = "network_matrix"}, the returned
\code{interaction_type} values are still recovered from the original
directed edge annotation in \code{network_table}, including reverse
matching when needed.
\item If \code{reactant_filter = TRUE}, candidate shortest paths are
further filtered by checking whether consecutive compound-compound
transitions are supported by KEGG reaction data.
}
}
\note{
Name/symbol conversion relies on the KEGG REST API and can be slow for large
node sets. The internal 6-step cutoff is empirical and intended to prevent
excessive enumeration of very long shortest paths. When \code{betweenness = TRUE},
enumerating all shortest paths for tie-breaking may increase runtime and memory use.
}
\examples{
## Load the precomputed example network; see buildKeggNetwork() for its construction
data(MetaPathNet_example_network)
## Use the precomputed object as the example network_table
net_trp_mixed <- MetaPathNet_example_network

## 2) Define source and target nodes of interest in this network
## Source/target can be any KEGG node types, but they must be mapped in the network
## and should not overlap (same node cannot be both source and target).
source_nodes <- c("K00486", "K00453", "K00463",
                  "K01667", "K01696", "K01610", "K01695")
target_nodes <- c("cpd:C00078", "cpd:C00328", "cpd:C00780",
                  "cpd:C00463", "cpd:C00108", "cpd:C00458", "cpd:C00336")

map_src <- findMappedNodes(source_nodes, net_trp_mixed)
map_tgt <- findMappedNodes(target_nodes, net_trp_mixed)

## 3) Optional: inspect shortest-path distances between mapped node sets
## (useful for checking connectivity before extracting shortest paths)
dist_trp <- networkDistances(
  network_table = net_trp_mixed,
  source_nodes  = map_src$mapped_nodes,
  target_nodes  = map_tgt$mapped_nodes,
  name          = FALSE
)

## 4) Extract shortest paths as annotated path list
## Pairs that are unreachable (Inf distance) or above the distance threshold
## are filtered internally.
paths_trp_mixed_list <- findShortestPaths(
  network_table      = net_trp_mixed,
  source_nodes       = map_src$mapped_nodes,
  target_nodes       = map_tgt$mapped_nodes,
  mode               = "out",
  output             = "path_list",
  name               = FALSE,
  distance_threshold = 6
)

## 5) Extract a subnetwork containing all edges used in the selected shortest paths
paths_trp_mixed <- findShortestPaths(
  network_table      = net_trp_mixed,
  source_nodes       = map_src$mapped_nodes,
  target_nodes       = map_tgt$mapped_nodes,
  mode               = "out",
  output             = "network_matrix",
  name               = FALSE
)

}
