% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mapReaction.R
\name{mapReaction}
\alias{mapReaction}
\title{Map reaction IDs to MetaPathNet-style networks}
\usage{
mapReaction(reaction_ids, source = c("rhea", "metacyc", "kegg"))
}
\arguments{
\item{reaction_ids}{Character vector of reaction identifiers.}

\item{source}{Character string indicating the origin of the reaction IDs.
Supported values are:
\itemize{
\item \code{"rhea"}    - Rhea reaction IDs (digits only, no prefix).
\item \code{"metacyc"} - MetaCyc reaction IDs.
\item \code{"kegg"}    - KEGG reaction IDs (e.g. \code{"R01302"} or \code{"rn:R01302"}).
}}
}
\value{
A character matrix with three columns:
\describe{
\item{source}{Source node ID (compound, KO, or compound name for
non-KEGG reactions).}
\item{target}{Target node ID.}
\item{interaction_type}{For KEGG-mapped reactions, values such as
\code{"k_compound:reversible"} or
\code{"k_compound:irreversible"}; for reactions without KEGG
mapping, \code{"external"}.}
}
If no valid reactions can be converted, an empty 3-column matrix is returned
and a warning is issued.
}
\description{
\code{mapReaction()} converts reaction identifiers into the standard
MetaPathNet 3-column edge list format
(\code{source}, \code{target}, \code{interaction_type}).
}
\details{
The function supports direct KEGG reaction IDs, as well as external reaction
identifiers from Rhea and MetaCyc. For external sources, it uses the
MetaNetX SPARQL endpoint as a neutral layer to translate reaction IDs into
KEGG reaction IDs where possible. KEGG-mapped reactions are then converted
into MetaPathNet-style KO–compound edges. If no KEGG mapping is available,
MetaNetX reaction equations are used to generate fallback compound-to-compound
edges.

For \code{source = "kegg"}, reaction IDs are converted directly using KEGG
reaction entries. Reaction equations are parsed to infer substrates,
products, and directionality. KEGG Orthology (KO) identifiers are retrieved
preferentially from the reaction \code{ORTHOLOGY} field, and if unavailable,
the function falls back to reaction-to-enzyme and enzyme-to-KO mapping.

For \code{source = "rhea"} and \code{source = "metacyc"}, the function first
queries MetaNetX to identify corresponding MetaNetX reactions, then attempts
to recover KEGG reaction IDs. KEGG-mapped reactions follow the same semantics
as the metabolic layer of MetaPathNet: compounds are coded as
\code{"cpd:Cxxxxx"}, KOs as \code{"Kxxxxx"}, and directionality
(\code{reversible} vs \code{irreversible}) is derived from the KEGG
\code{EQUATION} field.

Reactions without KEGG mapping are represented as compound-to-compound
relations, using human-readable compound names as node IDs and
\code{"external"} as interaction type. This preserves reaction information
while clearly marking the non-KEGG origin of these edges.
}
\examples{
\donttest{
## NOTE: The following examples require live access to KEGG REST and/or the
## MetaNetX SPARQL endpoint.

## 1) Map a MetaCyc reaction and inspect the returned MetaPathNet-style edges
trp_metacyc_edges <- mapReaction(
  reaction_ids = "TRYPTOPHAN-RXN",
  source       = "metacyc"
)

## 2) Map a Rhea reaction
rhea16505_edges <- mapReaction(
  reaction_ids = "16505",
  source       = "rhea"
)

## 3) Map KEGG reaction IDs directly
tma_edges <- mapReaction(
  reaction_ids = c("R05623", "R10285"),
  source       = "kegg"
)
}

}
\seealso{
\code{\link{buildKeggNetwork}}, \code{\link{buildCrossSpeciesNetwork}}
}
