% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/annotateOrigin.R
\name{annotateOrigin}
\alias{annotateOrigin}
\title{Annotate KO Origin (Host vs Bacteria) and Optionally Export to Cytoscape}
\usage{
annotateOrigin(
  network_table,
  bacteria_codes = NULL,
  name = FALSE,
  export_cytoscape = FALSE,
  compound_color = "#9DC7DD",
  hsa_color = "#C45745",
  micro_color = "#9ED17B",
  hsa_micro_color = "#B57F60",
  other_color = "#D1C2C2",
  network_title = "",
  collection_title = ""
)
}
\arguments{
\item{network_table}{A MetaPathNet-style network with at least two columns:
\code{source} and \code{target}. If a third column is present, it is
interpreted as \code{interaction_type}.}

\item{bacteria_codes}{Optional character vector of KEGG bacterial organism
codes. Restricts the \code{"bacteria"} and \code{"hsa&bacteria"} classes
to this set. If \code{NULL}, all KEGG bacterial organism codes are used.}

\item{name}{Logical. If \code{TRUE}, node display names are converted from
KEGG entries. For KO nodes, \code{SYMBOL} is preferred and \code{NAME}
is used as a fallback. For non-KO nodes, the KEGG \code{NAME} field is
used. If \code{FALSE}, KEGG IDs are retained as labels.}

\item{export_cytoscape}{Logical. If \code{TRUE}, the annotated network is
exported to Cytoscape and styled by origin class. If \code{FALSE}, only
the annotation table is returned.}

\item{compound_color}{Hex colour for compound nodes.}

\item{hsa_color}{Hex colour for KO nodes classified as \code{"hsa"}.}

\item{micro_color}{Hex colour for KO nodes classified as
\code{"bacteria"}.}

\item{hsa_micro_color}{Hex colour for KO nodes classified as
\code{"hsa&bacteria"}.}

\item{other_color}{Hex colour for KO nodes classified as \code{"other"}.}

\item{network_title}{Character string specifying the Cytoscape network
title. Used only when \code{export_cytoscape = TRUE}.}

\item{collection_title}{Character string specifying the Cytoscape collection
title. Used only when \code{export_cytoscape = TRUE}.}
}
\value{
A node-level data frame with columns:
\itemize{
\item \code{id}: KEGG node identifier.
\item \code{type}: coarse node type (\code{"KO"}, \code{"Compound"},
or \code{"Other"}).
\item \code{name}: display label containing the KEGG ID or converted
KEGG name or symbol.
\item \code{origin}: inferred origin class (\code{"compound"},
\code{"hsa"}, \code{"bacteria"}, \code{"hsa&bacteria"}, or
\code{"other"}).
}

If \code{export_cytoscape = TRUE}, the function also creates and styles a
Cytoscape network as a side effect and returns the annotation table
invisibly.
}
\description{
Annotates nodes in a MetaPathNet-style network with inferred biological
origin, focusing on KEGG Orthology (KO) nodes. KO origin is classified as
human-only (\code{"hsa"}), bacteria-only (\code{"bacteria"}),
shared (\code{"hsa&bacteria"}), or \code{"other"} based on KEGG annotations.
Compound nodes are assigned the separate class \code{"compound"}.
}
\details{
The primary output is a node-level annotation table containing the node ID,
type, display name, and origin. Cytoscape export is optional and can be
enabled to visualise the annotated network with origin-based node colours.

KO origin is inferred from KEGG \code{GENES} annotations retrieved with
\code{KEGGREST::keggGet()}:
\itemize{
\item \code{"hsa"} if \code{hsa} is present and no selected bacterial
organism code is detected.
\item \code{"bacteria"} if at least one selected bacterial organism code
is detected and \code{hsa} is absent.
\item \code{"hsa&bacteria"} if both \code{hsa} and at least one selected
bacterial organism code are detected.
\item \code{"other"} if none of the above can be established.
}

The \code{bacteria_codes} argument can be used to restrict the bacterial
origin class to a user-defined organism panel, such as cohort-specific
microbes. If \code{bacteria_codes = NULL}, all KEGG bacterial organism
codes are used.

If the KEGG genome or bacterial genome-group information cannot be
retrieved, the function issues a warning instead of stopping. In this case,
KO nodes linked exclusively to \code{hsa} are classified as \code{"hsa"},
while other KO nodes are classified as \code{"other"}.

Cytoscape version 3.9.0 or later must be running when
\code{export_cytoscape = TRUE}.

Reverse duplicated edges are collapsed for Cytoscape display when they
share the same supported metabolic interaction type.
}
\examples{
\donttest{
## 1) Load the precomputed mixed human-E. coli example network
data(MetaPathNet_example_network)
net_trp_mixed <- MetaPathNet_example_network

## 2) Build a shortest-path subnetwork for origin annotation
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)

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,
  distance_threshold = 6
)

## 3) Return the annotation table while retaining KEGG IDs as labels
origin_paths_trp_mixed <- annotateOrigin(
  network_table    = paths_trp_mixed,
  bacteria_codes   = NULL,
  name             = FALSE,
  export_cytoscape = FALSE
)

head(origin_paths_trp_mixed)
}

}
\seealso{
\code{\link{annotateKoClass}} for KO functional class annotation, and
\code{\link{viewNetworkCy}} for generic Cytoscape rendering.
}
