% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/trans_norm.R
\name{trans_norm}
\alias{trans_norm}
\title{Feature abundance normalization/transformation.}
\description{
Feature abundance normalization/transformation for a microtable object or data.frame object.
}
\examples{

## ------------------------------------------------
## Method `trans_norm$new`
## ------------------------------------------------

library(microeco)
data(dataset)
t1 <- trans_norm$new(dataset = dataset)

## ------------------------------------------------
## Method `trans_norm$norm`
## ------------------------------------------------

newdataset <- t1$norm(method = "clr")
newdataset <- t1$norm(method = "log")
}
\section{Methods}{
\subsection{Public methods}{
\itemize{
\item \href{#method-trans_norm-new}{\code{trans_norm$new()}}
\item \href{#method-trans_norm-norm}{\code{trans_norm$norm()}}
\item \href{#method-trans_norm-clone}{\code{trans_norm$clone()}}
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-trans_norm-new"></a>}}
\if{latex}{\out{\hypertarget{method-trans_norm-new}{}}}
\subsection{Method \code{new()}}{
Get a transposed abundance table if the input is microtable object. In the table, rows are samples, and columns are features. 
  This can make the further operations same with the traditional ecological methods.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{trans_norm$new(dataset = NULL)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{dataset}}{the \code{\link{microtable}} object or \code{data.frame} object. 
If it is \code{data.frame} object, please make sure that rows are samples, and columns are features.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
\code{data_table}, stored in the object.
}
\subsection{Examples}{
\if{html}{\out{<div class="r example copy">}}
\preformatted{library(microeco)
data(dataset)
t1 <- trans_norm$new(dataset = dataset)
}
\if{html}{\out{</div>}}

}

}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-trans_norm-norm"></a>}}
\if{latex}{\out{\hypertarget{method-trans_norm-norm}{}}}
\subsection{Method \code{norm()}}{
Normalization/transformation methods.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{trans_norm$norm(
  method = "rarefy",
  sample.size = NULL,
  rngseed = 123,
  replace = TRUE,
  pseudocount = 1,
  intersect.no = 10,
  ct.min = 1,
  condition = NULL,
  MARGIN = NULL,
  logbase = 2,
  CSS_p = NULL,
  ...
)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{method}}{default "rarefy"; See the following available options. \cr 
\cr 
Methods for normalization:
\itemize{
  \item \code{"rarefy"}: classic rarefaction based on the R \code{sample} function.
  \item \code{"SRS"}: scaling with ranked subsampling method based on the SRS package provided by Lukas Beule and Petr Karlovsky (2020) <doi:10.7717/peerj.9593>.
  \item \code{"clr"}: Centered log-ratio normalization <ISBN:978-0-412-28060-3> <doi: 10.3389/fmicb.2017.02224>. 
            It is defined:  \deqn{clr_{ki} = \log\frac{x_{ki}}{g(x_i)}}
            where \eqn{x_{ki}} is the abundance of \eqn{k}th feature in sample \eqn{i}, \eqn{g(x_i)} is the geometric mean of abundances for sample \eqn{i}.
            A pseudocount need to be added to deal with the zero. For more information, please see the 'clr' method in \code{decostand} function of vegan package.
  \item \code{"rclr"}: Robust centered log-ratio normalization <doi:10.1128/msystems.00016-19>.
            It is defined:  \deqn{rclr_{ki} = \log\frac{x_{ki}}{g(x_i > 0)}}
            where \eqn{x_{ki}} is the abundance of \eqn{k}th feature in sample \eqn{i}, \eqn{g(x_i > 0)} is the geometric mean of abundances (> 0) for sample \eqn{i}.
            In rclr, zero values are kept as zeroes, and not taken into account.
  \item \code{"GMPR"}: Geometric mean of pairwise ratios <doi: 10.7717/peerj.4600>. 
            For a given sample \eqn{i}, the size factor \eqn{s_i} is defined:
                \deqn{s_i =  \biggl( {\displaystyle\prod_{j=1}^{n} Median_{k|c_{ki}c_{kj} \ne 0} \lbrace \dfrac{c_{ki}}{c_{kj}} \rbrace} \biggr) ^{1/n}}
            where \eqn{k} denotes all the features, and \eqn{n} denotes all the samples. 
            For sample \eqn{i}, \eqn{GMPR = \frac{x_{i}}{s_i}}, where \eqn{x_i} is the feature abundances of sample \eqn{i}.
  \item \code{"CSS"}: Cumulative sum scaling normalization based on the \code{metagenomeSeq} package <doi:10.1038/nmeth.2658>.
            For a given sample \eqn{j}, the scaling factor \eqn{s_{j}^{l}} is defined:
                \deqn{s_{j}^{l} = {\displaystyle\sum_{i|c_{ij} \leqslant q_{j}^{l}} c_{ij}}}
            where \eqn{q_{j}^{l}} is the \eqn{l}th quantile of sample \eqn{j}, that is, in sample \eqn{j} there are \eqn{l} features with counts smaller than \eqn{q_{j}^{l}}.
            \eqn{c_{ij}} denotes the count (abundance) of feature i in sample \eqn{j}.
            For \eqn{l} = 0.95\eqn{m} (feature number), \eqn{q_{j}^{l}} corresponds to the 95th percentile of the count distribution for sample \eqn{j}.
            Normalized counts \eqn{\tilde{c_{ij}} = (\frac{c_{ij}}{s_{j}^{l}})(N)}, where \eqn{N} is an appropriately chosen normalization constant.
  \item \code{"TSS"}: Total sum scaling. Abundance is divided by the sequencing depth.
            For a given sample \eqn{j}, normalized counts is defined:
                \deqn{\tilde{c_{ij}} = \frac{c_{ij}}{\sum_{i=1}^{N_{j}} c_{ij}}}
            where \eqn{c_{ij}} is the counts of feature \eqn{i} in sample \eqn{j}, and \eqn{N_{j}} is the feature number of sample \eqn{j}.
  \item \code{"eBay"}: Empirical Bayes approach to normalization <10.1186/s12859-020-03552-z>. 
            The implemented method is not tree-related. In the output, the sum of each sample is 1.
  \item \code{"TMM"}: Trimmed mean of M-values method based on the \code{normLibSizes} function of \code{edgeR} package <doi: 10.1186/gb-2010-11-3-r25>.
  \item \code{"DESeq2"}: Median ratio of gene counts relative to geometric mean per gene based on the DESeq function of \code{DESeq2} package <doi: 10.1186/s13059-014-0550-8>.
            This option can invoke the \code{trans_diff} class and extract the normalized data from the original result.
            Note that either \code{group} or \code{formula} should be provided.
            The scaling factor is defined:
                \deqn{s_{j} = Median_{i} \frac{c_{ij}}{\bigl( {\prod_{j=1}^{n} c_{ij}} \bigr) ^{1/n}}}
            where \eqn{c_{ij}} is the counts of feature \eqn{i} in sample \eqn{j}, and \eqn{n} is the total sample number.
  \item \code{"Wrench"}: Group-wise and sample-wise compositional bias factor <doi: 10.1186/s12864-018-5160-5>.
            Note that condition parameter is necesary to be passed to \code{condition} parameter in \code{wrench} function of Wrench package.
            As the input data must be microtable object, so the input condition parameter can be a column name of \code{sample_table}.
            The scaling factor is defined:
                \deqn{s_{j} = \frac{1}{p} \sum_{ij} W_{ij} \frac{X_{ij}}{\overline{X_{i}}}}
            where \eqn{X_{ij}} represents the relative abundance (proportion) for feature \eqn{i} in sample \eqn{j},
            \eqn{\overline{X_{i}}} is the average proportion of feature \eqn{i} across the dataset,
            \eqn{W_{ij}} represents a weight specific to each technique, and \eqn{p} is the feature number in sample.
  \item \code{"RLE"}: Relative log expression. 
}
Methods based on \code{decostand} function of vegan package:
\itemize{
  \item \code{"total"}: divide by margin total (default MARGIN = 1, i.e. rows - samples in \code{data_table} of the object).
     The default MARGIN = 1 generates results commonly referred to as relative abundance.
  \item \code{"max"}: divide by margin maximum (default MARGIN = 2, i.e. columns - features).
  \item \code{"frequency"}:     divide by margin total and multiply by the number of non-zero items (default MARGIN = 2).    
  \item \code{"normalize"}:  make margin sum of squares equal to one (default MARGIN = 1).
  \item \code{"range"}: standardize values into range 0...1 (default MARGIN = 2). If all values are constant, they will be transformed to 0.
  \item \code{"standardize"}: scale x to zero mean and unit variance (default MARGIN = 2).
  \item \code{"pa"}: scale x to presence/absence scale (0/1).
  \item \code{"chi.square"}: see the detailed "chi.square" documents in vegan package.
  \item \code{"hellinger"}: square root of \code{method = "total"}.
  \item \code{"log"}: logarithmic transformation.
}
Other methods for transformation:
\itemize{
  \item \code{"AST"}: Arc sine square root transformation.
}}

\item{\code{sample.size}}{default NULL; libray size for rarefaction when method = "rarefy" or "SRS". If not provided, use the minimum number across all samples. 
For "SRS" method, this parameter is passed to \code{Cmin} parameter of \code{SRS} function of SRS package.}

\item{\code{rngseed}}{default 123; random seed. Available when method = "rarefy" or "SRS".}

\item{\code{replace}}{default TRUE; see \code{\link{sample}} for the random sampling; Available when \code{method = "rarefy"}.}

\item{\code{pseudocount}}{default 1; add pseudocount for those features with 0 abundance when \code{method = "clr"}.}

\item{\code{intersect.no}}{default 10; the intersecting taxa number between paired sample for \code{method = "GMPR"}.}

\item{\code{ct.min}}{default 1; the minimum number of counts required to calculate ratios for \code{method = "GMPR"}.}

\item{\code{condition}}{default NULL; Only available when \code{method = "Wrench"}. 
This parameter is passed to the \code{condition} parameter of \code{wrench} function in Wrench package
It must be a column name of \code{sample_table} or a vector with same length of samples.}

\item{\code{MARGIN}}{default NULL; 1 = samples, and 2 = features of abundance table; only available when method comes from \code{decostand} function of vegan package.
If MARGIN is NULL, use the default value in decostand function.}

\item{\code{logbase}}{default 2; The logarithm base.}

\item{\code{CSS_p}}{default NULL; the pth quantile passed to the p augument of the \code{cumNorm} function when method = "CSS".
Default NULL means the default \code{cumNormStatFast} function is used to calculate the quantile.}

\item{\code{...}}{parameters pass to \code{vegan::decostand},
or \code{edgeR::normLibSizes} when method = "TMM" or "RLE", 
or \code{trans_diff} class when method = "DESeq2",
or \code{wrench} function of Wrench package when method = "Wrench".}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
new microtable object or data.frame object.
}
\subsection{Examples}{
\if{html}{\out{<div class="r example copy">}}
\preformatted{newdataset <- t1$norm(method = "clr")
newdataset <- t1$norm(method = "log")
}
\if{html}{\out{</div>}}

}

}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-trans_norm-clone"></a>}}
\if{latex}{\out{\hypertarget{method-trans_norm-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_norm$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>}}
}
}
}
