% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/trans_metab.R
\name{trans_metab}
\alias{trans_metab}
\title{Create \code{trans_metab} object for metabolite analysis.}
\description{
This class is a wrapper for a series of metabolite analysis, including origin inference.
}
\examples{

## ------------------------------------------------
## Method `trans_metab$new`
## ------------------------------------------------

data(soil_metab)
data(soil_microb)
t1 <- trans_metab$new(metab = soil_metab, microb = soil_microb)

## ------------------------------------------------
## Method `trans_metab$cal_match`
## ------------------------------------------------

\dontrun{
t1$cal_match()
}

## ------------------------------------------------
## Method `trans_metab$cal_origin`
## ------------------------------------------------

\dontrun{
t1$cal_origin()
t1$cal_origin(match_col = c("names", "HMDB_ID", "KEGG_ID"))
}

## ------------------------------------------------
## Method `trans_metab$cal_origin_network`
## ------------------------------------------------

\dontrun{
t1$cal_origin_network()
}

## ------------------------------------------------
## Method `trans_metab$cal_pathway`
## ------------------------------------------------

\dontrun{
# KEGG pathway mapping (online)
t1$cal_pathway()

# KEGG pathway mapping (local database)
t1$cal_pathway(db_type = "kegg", db_path = "kegg_pathway_db.RData")
}

## ------------------------------------------------
## Method `trans_metab$cal_pathway_enrich`
## ------------------------------------------------

\dontrun{
t1$cal_pathway()
target <- rownames(t1$data_metab$otu_table)[1:10]
t1$cal_pathway_enrich(target_metabs = target)
}

## ------------------------------------------------
## Method `trans_metab$plot_pathway_enrich`
## ------------------------------------------------

\dontrun{
t1$cal_pathway()
target <- rownames(t1$data_metab$otu_table)[1:10]
t1$cal_pathway_enrich(target_metabs = target)
t1$plot_pathway_enrich()
}

## ------------------------------------------------
## Method `trans_metab$cal_pathway_network`
## ------------------------------------------------

\dontrun{
t1$cal_pathway()
target <- rownames(t1$data_metab$otu_table)[1:50]
t1$cal_pathway_enrich(target_metabs = target)
net <- t1$cal_pathway_network()
}
}
\section{Methods}{
\subsection{Public methods}{
\itemize{
\item \href{#method-trans_metab-new}{\code{trans_metab$new()}}
\item \href{#method-trans_metab-cal_match}{\code{trans_metab$cal_match()}}
\item \href{#method-trans_metab-cal_origin}{\code{trans_metab$cal_origin()}}
\item \href{#method-trans_metab-cal_origin_network}{\code{trans_metab$cal_origin_network()}}
\item \href{#method-trans_metab-cal_pathway}{\code{trans_metab$cal_pathway()}}
\item \href{#method-trans_metab-cal_pathway_enrich}{\code{trans_metab$cal_pathway_enrich()}}
\item \href{#method-trans_metab-plot_pathway_enrich}{\code{trans_metab$plot_pathway_enrich()}}
\item \href{#method-trans_metab-cal_pathway_network}{\code{trans_metab$cal_pathway_network()}}
\item \href{#method-trans_metab-clone}{\code{trans_metab$clone()}}
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-trans_metab-new"></a>}}
\if{latex}{\out{\hypertarget{method-trans_metab-new}{}}}
\subsection{Method \code{new()}}{
Create the \code{trans_metab} object.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{trans_metab$new(metab = NULL, microb = NULL)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{metab}}{default NULL; metabolite data. A \code{\link{microtable}} object or data.frame object.
If the input is a data.frame object, the function can judge whether it is abundance table and preprocess the data.}

\item{\code{microb}}{default NULL; A \code{\link{microtable}} object.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
\code{data_metab} and \code{data_microb} stored in the object.
}
\subsection{Examples}{
\if{html}{\out{<div class="r example copy">}}
\preformatted{data(soil_metab)
data(soil_microb)
t1 <- trans_metab$new(metab = soil_metab, microb = soil_microb)
}
\if{html}{\out{</div>}}

}

}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-trans_metab-cal_match"></a>}}
\if{latex}{\out{\hypertarget{method-trans_metab-cal_match}{}}}
\subsection{Method \code{cal_match()}}{
Matching compound names against the database from TidyMass2 (DOI: 10.1038/s41467-026-68464-7) to facilitate the acquisition of standardized nomenclature.
An alternative way is to use MetaboAnalyst website (https://www.metaboanalyst.ca/faces/upload/ConvertView.xhtml).
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{trans_metab$cal_match(
  database_path = "./metorigindb_split_202602",
  method = "jw",
  maxDist = 0.3,
  ...
)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{database_path}}{default "./metorigindb_split_202602"; directory path of the downloaded database. 
Please download the pre-collated metorigindb database (RData format) from zenodo (https://zenodo.org/records/18618912) and extract the compressed archive.}

\item{\code{method}}{default "jw"; method of approximate string matching. Default "jw" is Jaro-Winkler distance.
See the \code{method} parameter of \code{amatch} function in stringdist package.}

\item{\code{maxDist}}{default 0.3; See the \code{maxDist} parameter of \code{amatch} function in stringdist package.}

\item{\code{...}}{parameters passed to \code{amatch} function of stringdist package.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
\code{res_match} table stored in the object.
}
\subsection{Examples}{
\if{html}{\out{<div class="r example copy">}}
\preformatted{\dontrun{
t1$cal_match()
}
}
\if{html}{\out{</div>}}

}

}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-trans_metab-cal_origin"></a>}}
\if{latex}{\out{\hypertarget{method-trans_metab-cal_origin}{}}}
\subsection{Method \code{cal_origin()}}{
Metabolite origin inference based on the preprocessed database from TidyMass2 (DOI: 10.1038/s41467-026-68464-7)
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{trans_metab$cal_origin(
  database_path = "./metorigindb_split_202602",
  match_col = "names",
  match_names_distance = 0,
  bac_level = "Genus"
)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{database_path}}{default "./metorigindb_split_202602"; directory path of the downloaded database. 
Please download the pre-collated metorigindb database (RData format) from zenodo (https://zenodo.org/records/18618912) and extract the compressed archive.}

\item{\code{match_col}}{default "names"; How to match to the data of metorigindb. Default "names" means using the input names of metabolites.
If the table has other columns like "HMDB_ID" or "KEGG_ID", the user can provide more items, like c("names", "HMDB_ID").}

\item{\code{match_names_distance}}{default 0; distance threshold used if the \code{res_match_table} is found in the object, 
which is calculated from the \code{cal_match} function. Available for the "names" option in \code{match_col} parameter.}

\item{\code{bac_level}}{default "Genus"; which bacteria level is used to parse the taxa in the \code{data_microb} of object.
The function can automatically match the taxa those found in the input data.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
\code{res_origin_rawtable} table and \code{res_origin_list} list stored in the object.
   \code{res_origin_rawtable} is the origin table extracted from the metorigindb database based on the match of name or other ID.
   In \code{res_origin_list}, name is the metabolite; each element is the taxa that may produce the metabolite.
}
\subsection{Examples}{
\if{html}{\out{<div class="r example copy">}}
\preformatted{\dontrun{
t1$cal_origin()
t1$cal_origin(match_col = c("names", "HMDB_ID", "KEGG_ID"))
}
}
\if{html}{\out{</div>}}

}

}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-trans_metab-cal_origin_network"></a>}}
\if{latex}{\out{\hypertarget{method-trans_metab-cal_origin_network}{}}}
\subsection{Method \code{cal_origin_network()}}{
Metabolite-bacteria network based on the \code{res_origin_list} data from the \code{cal_origin} function
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{trans_metab$cal_origin_network()}\if{html}{\out{</div>}}
}

\subsection{Returns}{
\code{igraph} format network.
}
\subsection{Examples}{
\if{html}{\out{<div class="r example copy">}}
\preformatted{\dontrun{
t1$cal_origin_network()
}
}
\if{html}{\out{</div>}}

}

}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-trans_metab-cal_pathway"></a>}}
\if{latex}{\out{\hypertarget{method-trans_metab-cal_pathway}{}}}
\subsection{Method \code{cal_pathway()}}{
Map metabolites to pathways based on a database (KEGG, MetaCyc, Reactome, or custom).
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{trans_metab$cal_pathway(
  db_type = c("kegg", "metacyc", "reactome", "custom")[1],
  db_path = NULL,
  id_type = NULL,
  save_db = FALSE
)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{db_type}}{default "kegg"; pathway database type, one of "kegg", "metacyc", "reactome", "custom".}

\item{\code{db_path}}{default NULL; pathway database file path (RData format). 
For KEGG: if NULL, will attempt to fetch from KEGG REST API.
For MetaCyc/Reactome/Custom: must provide local database file path.}

\item{\code{id_type}}{default NULL; column name in tax_table containing metabolite IDs.
If NULL, will be automatically set based on db_type: "KEGG_ID" for kegg, "METACYC_ID" for metacyc, 
"REACTOME_ID" for reactome, "CUSTOM_ID" for custom.}

\item{\code{save_db}}{default FALSE; whether save the fetched database (KEGG) to the local folder.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
\code{res_pathway_map} (data.frame) stored in the object. 
   Contains columns: pathway_id, pathway_name, metab_id, metab_name.
}
\subsection{Examples}{
\if{html}{\out{<div class="r example copy">}}
\preformatted{\dontrun{
# KEGG pathway mapping (online)
t1$cal_pathway()

# KEGG pathway mapping (local database)
t1$cal_pathway(db_type = "kegg", db_path = "kegg_pathway_db.RData")
}
}
\if{html}{\out{</div>}}

}

}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-trans_metab-cal_pathway_enrich"></a>}}
\if{latex}{\out{\hypertarget{method-trans_metab-cal_pathway_enrich}{}}}
\subsection{Method \code{cal_pathway_enrich()}}{
Perform pathway enrichment analysis for target metabolites using Fisher's exact test.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{trans_metab$cal_pathway_enrich(
  target_metabs = NULL,
  background_metabs = NULL,
  p_adjust_method = "BH",
  p_cutoff = 0.05,
  min_metab_count = 3
)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{target_metabs}}{character vector; target metabolite names (row names in tax_table), 
e.g., differential metabolites. If NULL, will use all metabolites in the pathway mapping.}

\item{\code{background_metabs}}{character vector; background metabolite names (row names in tax_table). 
If NULL, will use all metabolites in the pathway mapping result.}

\item{\code{p_adjust_method}}{default "BH"; p-value adjustment method. See \code{p.adjust} function.}

\item{\code{p_cutoff}}{default 0.05; significance threshold for adjusted p-value.}

\item{\code{min_metab_count}}{default 3; minimum number of background metabolites in a pathway for enrichment test.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
\code{res_pathway_enrich} data.frame stored in the object.
   Contains: pathway_id, pathway_name, metab_count, background_count, 
   enrichment_factor, p_value, p_adjust, significant.
}
\subsection{Examples}{
\if{html}{\out{<div class="r example copy">}}
\preformatted{\dontrun{
t1$cal_pathway()
target <- rownames(t1$data_metab$otu_table)[1:10]
t1$cal_pathway_enrich(target_metabs = target)
}
}
\if{html}{\out{</div>}}

}

}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-trans_metab-plot_pathway_enrich"></a>}}
\if{latex}{\out{\hypertarget{method-trans_metab-plot_pathway_enrich}{}}}
\subsection{Method \code{plot_pathway_enrich()}}{
Visualize pathway enrichment analysis results.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{trans_metab$plot_pathway_enrich(
  plot_type = c("bubble", "bar")[1],
  top_n = 20,
  color_by = "p_adjust",
  size_by = "metab_count",
  order_by = "p_adjust",
  color_gradient_low = "#132B43",
  color_gradient_high = "#56B1F7"
)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{plot_type}}{default "bubble"; plot type, "bubble" or "bar".}

\item{\code{top_n}}{default 20; number of top pathways to display.}

\item{\code{color_by}}{default "p_adjust"; column name for color mapping.}

\item{\code{size_by}}{default "metab_count"; column name for size mapping (only for bubble plot).}

\item{\code{order_by}}{default "p_adjust"; column name for ordering pathways.}

\item{\code{color_gradient_low}}{default "#132B43"; color for low values (e.g., high p-value = not significant).}

\item{\code{color_gradient_high}}{default "#56B1F7"; color for high values (e.g., low p-value = significant).}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
ggplot2 object.
}
\subsection{Examples}{
\if{html}{\out{<div class="r example copy">}}
\preformatted{\dontrun{
t1$cal_pathway()
target <- rownames(t1$data_metab$otu_table)[1:10]
t1$cal_pathway_enrich(target_metabs = target)
t1$plot_pathway_enrich()
}
}
\if{html}{\out{</div>}}

}

}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-trans_metab-cal_pathway_network"></a>}}
\if{latex}{\out{\hypertarget{method-trans_metab-cal_pathway_network}{}}}
\subsection{Method \code{cal_pathway_network()}}{
Build metabolite-pathway network based on pathway mapping and enrichment results.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{trans_metab$cal_pathway_network(
  significant_only = TRUE,
  p_cutoff = 0.05,
  use_enrichment = TRUE
)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{significant_only}}{default TRUE; whether to use only significant enriched pathways.}

\item{\code{p_cutoff}}{default 0.05; p-value cutoff for significant pathways (used only when significant_only = TRUE).}

\item{\code{use_enrichment}}{default TRUE; whether to require enrichment results. If FALSE, build network from all pathway mappings.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
\code{igraph} object representing metabolite-pathway bipartite network.
}
\subsection{Examples}{
\if{html}{\out{<div class="r example copy">}}
\preformatted{\dontrun{
t1$cal_pathway()
target <- rownames(t1$data_metab$otu_table)[1:50]
t1$cal_pathway_enrich(target_metabs = target)
net <- t1$cal_pathway_network()
}
}
\if{html}{\out{</div>}}

}

}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-trans_metab-clone"></a>}}
\if{latex}{\out{\hypertarget{method-trans_metab-clone}{}}}
\subsection{Method \code{clone()}}{
The objects of this class are cloneable with this method.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{trans_metab$clone(deep = FALSE)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{deep}}{Whether to make a deep clone.}
}
\if{html}{\out{</div>}}
}
}
}
