% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/permutePaths.R
\name{permutePaths}
\alias{permutePaths}
\title{Permutation Test of Shortest-Path Structure Between Node Sets}
\usage{
permutePaths(
  network_table,
  source_nodes,
  target_nodes,
  n_perm = 10000,
  mode = c("out", "in", "all"),
  plot = FALSE,
  return_perm = FALSE
)
}
\arguments{
\item{network_table}{A 3-column matrix or data.frame representing
directed network edges. Columns must correspond to
\code{source}, \code{target}, and \code{interaction_type}.}

\item{source_nodes}{Character vector of KEGG node IDs used as
\emph{sources} in the permutation test.}

\item{target_nodes}{Character vector of KEGG node IDs used as
\emph{targets} in the permutation test.}

\item{n_perm}{Integer. Number of permutations used to build the null
distribution of mean shortest-path lengths (default: \code{10000}).}

\item{mode}{Character. Direction parameter passed to
\code{igraph::distances()}. 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 (graph treated as undirected).}
}}

\item{plot}{Logical (default: \code{FALSE}). If \code{TRUE}, a histogram
and density curve of permuted mean shortest-path lengths is plotted,
with a vertical line for the observed mean and an annotated p-value.}

\item{return_perm}{Logical (default: \code{FALSE}). If \code{FALSE},
only summary statistics are returned. If \code{TRUE}, the raw
permutation means are returned in addition to the summary.}
}
\value{
If \code{return_perm = FALSE}, a data.frame with one row:
\describe{
\item{observed_sp}{Observed mean shortest-path length
(finite distances only; unreachable pairs are excluded).}
\item{mean_perm_sp}{Mean of permuted mean shortest-path lengths
under the null (finite values only).}
\item{p_value}{Empirical one-sided p-value
\eqn{P(\text{random mean} < \text{observed mean})}.}
\item{n_perm}{Number of permutations used.}
}

If \code{return_perm = TRUE}, a list with:
\describe{
\item{stats}{The summary data.frame described above.}
\item{random_sp}{Numeric vector of permuted mean shortest-path
lengths (finite values only).}
}
}
\description{
Performs a permutation-based test on the mean shortest-path length
between a set of source nodes and target nodes within a KEGG-derived
network. The observed mean shortest-path distance is compared to a null
distribution obtained by repeatedly sampling random source and target sets
of the same size and node-type composition from the same network.
}
\details{
Internally, the function:
\itemize{
\item identifies supported node types in \code{network_table},
currently KEGG Orthology nodes (\code{"K"} prefix) and
KEGG compound nodes (\code{"cpd:"} prefix);
\item maps the user-supplied source and target nodes onto the network;
\item removes unreachable pairs (distance = \code{Inf}) when calculating
observed and permuted mean distances;
\item derives an empirical one-sided p-value from the proportion of
permuted means that are smaller than the observed mean.
}

Source and target node sets are user-defined and may contain supported KEGG
node types according to the biological question being addressed. A smaller
mean shortest-path length indicates tighter connectivity. Therefore, the
reported p-value tests whether random source-target sets tend to be
\emph{more tightly connected} than the observed set
(\eqn{P(\text{random mean} < \text{observed mean})}).
}
\section{Plotting}{

If \code{plot = TRUE}, a \pkg{ggplot2}-based histogram + density overlay
of the permutation distribution is printed. For custom visualisation,
set \code{return_perm = TRUE} and use the \code{random_sp} vector
together with \code{stats} in your own plotting code.
}

\examples{
## 1) Prepare a mixed human–E. coli network focused on tryptophan-related pathways
## Human: tryptophan metabolism + selected signaling pathways
## Load the precomputed example network; see buildKeggNetwork() for its construction
data(MetaPathNet_example_network)

## Combine host and microbe networks into one edge list
net_trp_mixed <- MetaPathNet_example_network

## 2) Define source and target node sets for the Trp/kynurenine/serotonin context
source_nodes <- c(
  "K00486",  # kynurenine 3-monooxygenase
  "K00453",  # tryptophan 2,3-dioxygenase
  "K00463",  # indoleamine 2,3-dioxygenase
  "K01667",  # kynureninase
  "K01696",  # tryptophan synthase beta chain
  "K01695"   # tryptophan synthase alpha chain
)

target_nodes <- c(
  "cpd:C00078",  # L-tryptophan
  "cpd:C00328",  # L-kynurenine
  "cpd:C00780",  # serotonin
  "cpd:C00463",  # indole
  "cpd:C00108"   # anthranilate
)

## 3) Permutation test on mean shortest-path length between the two node sets
perm_trp <- permutePaths(
  network_table = net_trp_mixed, # mixed hsa/eco Trp + immune-related network
  source_nodes  = source_nodes,
  target_nodes  = target_nodes,
  n_perm        = 100,           # increase (e.g. 10000) for more stable inference
  mode          = "out",
  plot          = FALSE,         # show permutation distribution
  return_perm   = TRUE           # keep individual permuted means
)

## 4) View summary statistics
perm_trp$stats

}
\seealso{
\code{\link{networkDistances}} for shortest-path distance matrices,
\code{\link{findShortestPaths}} for explicit shortest paths,
\code{\link{buildKeggNetwork}}, \code{\link{buildCrossSpeciesNetwork}} for
KEGG-based network construction.
}
