% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/buildCompoundEgoNetwork.R
\name{buildCompoundEgoNetwork}
\alias{buildCompoundEgoNetwork}
\title{Build compound-centred ego subnetworks across KEGG organisms}
\usage{
buildCompoundEgoNetwork(
  compounds,
  organism_codes,
  path_type = c("metabolic", "signaling", "integrated"),
  order = 2,
  mode = c("out", "all", "in")
)
}
\arguments{
\item{compounds}{Character vector of KEGG compound identifiers. Only IDs in
the formats \code{"Cxxxxx"} or \code{"cpd:Cxxxxx"} are accepted; any other
format results in an error.}

\item{organism_codes}{Character vector of one or more KEGG organism codes
(e.g. \code{"hsa"}, \code{"eco"}, \code{"bsu"}). For each organism, the
function identifies pathways containing the input compounds and builds an
ego subnetwork restricted to those pathways.}

\item{path_type}{Character; type of pathways to include when building the
organism-specific networks. One of:
\itemize{
\item \code{"metabolic"}: use only metabolic pathways.
\item \code{"signaling"}: use only signaling pathways.
\item \code{"integrated"}: use both metabolic and signaling pathways.
}
The classification is derived from \code{\link{getPathIDs}}.}

\item{order}{Integer (default: \code{2}). Maximum graph distance (number of
edges) used in \code{\link{buildEgoNetwork}} to define the ego neighbourhood
around the seed compounds. Must be a single positive integer (\eqn{\ge} 1).}

\item{mode}{Character; directionality of the ego search, passed to
\code{\link{buildEgoNetwork}} and ultimately \code{igraph::ego}. One of:
\itemize{
\item \code{"out"} (default): nodes reachable downstream from the seeds.
\item \code{"in"}: nodes from which the seeds are reachable.
\item \code{"all"}: treat edges as undirected for distance calculations.
}}
}
\value{
A character matrix with three columns:
\describe{
\item{source}{Source node of each edge in the combined ego subnetwork.}
\item{target}{Target node of each edge in the combined ego subnetwork.}
\item{interaction_type}{Interaction or edge type, as returned by
\code{\link{buildKeggNetwork}} (e.g. \code{"k_compound:reversible"},
\code{"k_activation"}, etc.).}
}
If no ego subnetworks can be generated for the given inputs, the function
stops with an error.
}
\description{
Builds a compound-centred ego subnetwork around one or more KEGG
compounds across one or several organisms. The resulting network is
returned as a MetaPathNet-style edge list (3-column matrix) that can be
used directly for visualisation or further network analysis.
}
\details{
Organism-specific ego subnetworks are merged, deduplicated, and returned as
a single combined network.

Internally, compound–pathway mapping is performed via KEGG REST / KGML
queries (using a non-exported helper), then routed through
\code{\link{buildKeggNetwork}} and \code{\link{buildEgoNetwork}}. These details
are handled automatically and do not require user intervention.
}
\examples{
\dontrun{
## Requires extensive KEGG API querying; runtime depends on server response
## 1) Define Trp/kynurenine/serotonin/anthranilate seeds
seed_compounds <- c(
  "cpd:C00078",  # L-tryptophan
  "cpd:C00328",  # L-kynurenine
  "cpd:C00780",  # serotonin
  "cpd:C00108"   # anthranilate
)

## 2) Build ego network (order = 2, metabolic pathways, human only)
ego_trp_hsa <- buildCompoundEgoNetwork(
  compounds      = seed_compounds,
  organism_codes = "hsa",
  path_type      = "metabolic",
  order          = 2,
  mode           = "out"
)

## 3) (Optional) Visualise in Cytoscape
## Cytoscape must be open and running
viewNetworkCy(
  network_table    = ego_trp_hsa,
  name             = TRUE,
  category         = TRUE,
  network_title    = "Human metabolic ego network",
  collection_title = "MetaPathNet_Examples"
)
}

}
\seealso{
\code{\link{getPathIDs}},
\code{\link{buildKeggNetwork}},
\code{\link{buildEgoNetwork}}
}
