% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/buildEgoNetwork.R
\name{buildEgoNetwork}
\alias{buildEgoNetwork}
\title{Extract an Ego Subnetwork from a Metabolic / Signalling Network}
\usage{
buildEgoNetwork(
  network_table,
  nodes,
  order = 2,
  mode = c("out", "all", "in"),
  mindist = 0,
  output = c("matrix", "vector")
)
}
\arguments{
\item{network_table}{A three-column matrix or data.frame representing a
directed network. The first three columns must correspond to
\code{source}, \code{target}, and \code{interaction_type} (e.g. output of
\code{buildKeggNetwork()}).}

\item{nodes}{Character vector of one or more node IDs (e.g.
\code{"cpd:C00078"}). Values must match the node names used in the network
(case sensitive); leading/trailing whitespace is trimmed. Compound IDs
supplied as \code{"Cxxxxx"} are internally harmonised to
\code{"cpd:Cxxxxx"}.}

\item{order}{Integer (default \code{2}). Maximum graph distance (in number
of edges) from the ego nodes to include in the neighbourhood. Must be a
single positive integer \eqn{\ge 1}.}

\item{mode}{Character. Directionality of the search, passed to
\code{igraph::ego()}:
\itemize{
\item \code{"out"} (default): include nodes reachable by following edge
direction outward from the ego node(s).
\item \code{"in"}: include nodes that can reach the ego node(s)
(against edge direction).
\item \code{"all"}: ignore edge direction for neighbourhood expansion
(treat the graph as undirected for this search).
}}

\item{mindist}{Integer (default \code{0}). Minimum graph distance from the
ego nodes to include (also passed to \code{igraph::ego()}). Must satisfy
\eqn{0 \le mindist \le order}.}

\item{output}{Character. Type of result:
\itemize{
\item \code{"matrix"} (default): 3-column edge list
(\code{source}, \code{target}, \code{interaction_type}) for the
induced subgraph on the ego neighbourhood.
\item \code{"vector"}: character vector of unique node IDs present in
the ego subnetwork.
}}
}
\value{
If \code{output = "matrix"}, a character matrix with columns
\code{source}, \code{target}, \code{interaction_type} representing the
induced subnetwork on all nodes within \code{[mindist, order]} of the ego
nodes (according to \code{mode}). If no edges are found, an empty
3-column matrix with these columns is returned.

If \code{output = "vector"}, a character vector of unique node IDs in the
ego subnetwork is returned.
}
\description{
Builds an ego (neighbourhood) subnetwork around one or more seed nodes in a
directed network, up to a user-defined distance (\code{order}). In graph
terminology, \emph{ego} refers to the focal node(s) used as the starting
point(s), and the function returns the local network around them. This is
useful to inspect which nodes connect to a selected compound, KO, or other
node(s) within a chosen radius in a pathway- or organism-specific network.
}
\details{
The default output is a 3-column MetaPathNet-style edge list
(\code{source}, \code{target}, \code{interaction_type}); alternatively, the
function can return only the unique node vector of the ego neighbourhood.

Internally, the function:
\enumerate{
\item checks and normalizes \code{network_table} and input \code{nodes};
\item builds a directed \code{igraph} object from the first three columns;
\item maps the requested ego nodes to existing vertex names (with a message
for nodes not found);
\item uses \code{igraph::ego()} to collect all vertices within
\code{[mindist, order]} of the mapped egos;
\item returns either the induced edge list (\code{"matrix"}) or the node
set (\code{"vector"}).
}

For large networks and high values of \code{order}, ego subnetworks can
become large and slower to generate. It is often practical to start with
\code{order = 1} or \code{2} and increase only if needed.
}
\examples{
## Example — Ego subnetwork around tryptophan-related metabolites in a mixed hsa/eco network

## 1) Build a mixed host–microbe network for tryptophan-related metabolism
## Load the precomputed example network; see buildKeggNetwork() for its construction
data(MetaPathNet_example_network)

## Combined host–microbe network
net_trp_mixed <- MetaPathNet_example_network

## 2) Extract an ego subnetwork around key metabolites used as seed nodes
## (tryptophan, serotonin, and indole are central compounds in the example storyline)
ego_trp_compounds <- buildEgoNetwork(
  network_table = net_trp_mixed,
  nodes         = c(
    "cpd:C00078",  # L-tryptophan
    "cpd:C00780",  # serotonin
    "cpd:C00463"   # indole
  ),
  order   = 2,
  mode    = "out",
  mindist = 0,
  output  = "matrix"
)

}
\references{
Ego-network (ego graph) concept is standard in social/network analysis; see
Wasserman S, Faust K (1994). \emph{Social Network Analysis: Methods and Applications}.
Cambridge University Press.

The neighbourhood extraction in this function is implemented with
\code{igraph::ego()} from the \pkg{igraph} package.
}
\seealso{
\code{\link[igraph]{ego}},
\code{\link[igraph]{induced_subgraph}},
\code{\link{enrichPathway}},
\code{\link{viewNetworkR}}
}
