% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/networkDistances.R
\name{networkDistances}
\alias{networkDistances}
\title{Calculate Shortest-Path Distances Between Node Sets in a KEGG-Based Network}
\usage{
networkDistances(
  network_table,
  mode = c("out", "in", "all"),
  source_nodes,
  target_nodes,
  name = FALSE
)
}
\arguments{
\item{network_table}{A 3-column matrix or data.frame of edges
(\code{source}, \code{target}, \code{interaction_type}), typically produced
by \code{buildKeggNetwork()}. Entries should use KEGG-style node identifiers.}

\item{mode}{Character, passed to \code{igraph::distances()}.
Default \code{"out"}. One of:
\describe{
\item{\code{"out"}}{Distances follow edge direction.}
\item{\code{"in"}}{Distances are computed against edge direction (reverse direction).}
\item{\code{"all"}}{Distances ignore edge direction (treat the graph as undirected).}
}}

\item{source_nodes}{Character vector of source nodes. Use \code{"all"}
to include all non-compound nodes if \code{target_nodes = "all"}.
Otherwise, \code{"all"} includes all nodes present in the network.}

\item{target_nodes}{Character vector of target nodes. Use \code{"all"}
to include all compound-like nodes (\code{cpd:}, \code{dr:},
\code{gl:}) if \code{source_nodes = "all"}. Otherwise, \code{"all"}
includes all nodes present in the network.}

\item{name}{Logical (default \code{FALSE}). If \code{TRUE}, row and column
labels are converted to KEGG names via \code{KEGGREST::keggGet()}.}
}
\value{
A numeric matrix of shortest-path distances. Rows correspond to
source nodes and columns to target nodes.
}
\description{
Compute shortest-path distances between selected source and target nodes
in a KEGG-based network produced by \code{buildKeggNetwork()} (or related
functions). Source nodes are often KEGG KOs (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{
The function builds a directed \pkg{igraph} object from the first two columns
of \code{network_table} and computes pairwise shortest-path distances using
\code{igraph::distances()}. For unweighted networks such as MetaPathNet edge
lists, distance lengths are computed with a breadth-first search strategy.

Compound-like node IDs supplied as \code{"Cxxxxx"} or \code{"cpd:Cxxxxx"}
are treated equivalently and internally harmonised to \code{"cpd:Cxxxxx"}.

If both \code{source_nodes = "all"} and \code{target_nodes = "all"}, the
function automatically assigns non-compound nodes (e.g. KOs/genes) as sources
and compound-like nodes (\code{cpd:}, \code{dr:}, \code{gl:}) as targets.

If any node is present in both the mapped source and target sets, the function
stops and reports the overlapping node(s), because distance from a node to
itself is 0 and is not allowed in this workflow.

Distances equal to \code{Inf} indicate unreachable source-target pairs under
the selected \code{mode}, i.e. no valid path exists between those nodes in
the current network direction setting.

If \code{name = TRUE}, \code{KEGGREST::keggGet()} is used to retrieve KEGG
names. This may be slow for large node sets.
}
\examples{
## 1) Load the precomputed example network; see buildKeggNetwork() for its construction
data(MetaPathNet_example_network)

## 2) Define node sets of interest in this network
##    - source_nodes: KOs representing enzymes/genes of interest in Trp/kynurenine biology
##    - target_nodes: KEGG compounds representing metabolites of interest in the same context
##    Note: networkDistances can accept any node types, but source/target must be disjoint:
##          if a node is in both sets, the function stops because self-distance is 0.
source_nodes <- c("K00486", "K00453", "K00463", "K09093", "K01667")
target_nodes <- c("cpd:C00078", "cpd:C00328", "cpd:C00780", "cpd:C00463")

## Keep only nodes that are present in the network (avoid "not mapped" errors)
map_src <- findMappedNodes(source_nodes, MetaPathNet_example_network)
map_tgt <- findMappedNodes(target_nodes, MetaPathNet_example_network)

## 3) Compute the shortest-path distance matrix
dist_trp <- networkDistances(
  network_table = MetaPathNet_example_network,
  source_nodes  = map_src$mapped_nodes,
  target_nodes  = map_tgt$mapped_nodes,
  name          = FALSE
)

dist_trp

}
\seealso{
\code{\link{buildKeggNetwork}}, \code{\link[igraph]{distances}}
}
