\name{data.norm}
\alias{data.norm}
\title{
Perform intensity normalization, outlier detection and feature pairs selection
}
\description{
Intensity data from multiple samples is used to normalize each feature intensity. The resulting intensities 
are then used to compute the sample outlier scores based on the lower quantiles and the total number of features 
with zero intensity. Finally, the correlation values of each feature pair is computed and only those pairs 
that pass the defined filter thresholds (i.e. low retention time difference, m/z difference and/or high correlation) are included for further analysis.
}
\usage{
data.norm(datalist, std.outliers = 3, zero.missing = TRUE, min.corr = .75, max.rt = 3, mode = "", mz.tol = 1e-3, adducts = c(), fplot = TRUE)
}
\arguments{
  \item{datalist }{ LC-MS feature data set either created by the user or loaded from an XCMS object (see \code{xcms.import}).}
  \item{std.outliers }{ samples having a standardized outlier score over this value are excluded.}
  \item{zero.missing }{ logical, intensity equal to 0 is considered as a missing value.}
  \item{min.corr }{ correlation threshold. Feature pairs with an intensity correlation below this value are excluded.}
  \item{max.rt }{ retention time difference threshold. Feature pairs with a retention time difference over this value are excluded.}
  \item{mode }{ ionization mode. Three accepted values: "", "+" and "-". "+" and "-" turn on m/z filtering after correlation computation to check if m/z differeces between feature pairs match the expected differences for isotopic or adduct patterns (\code{mz.tol} must be provided).}
  \item{mz.tol }{ tolerance for M/Z values. It must be provided when mode="+" or mode="-".}
  \item{adducts }{ user provided adduct list.}
  \item{fplot }{ logical, if \code{'TRUE'} summary figures are plotted.}
}
\details{
\code{datalist} should be imported from a XCMS object using \code{\link{xcms.import}}. It can also be provided by the user 
creating a list with two arguments: (1) \code{data}, a data.frame where rows correspond to features and the first two columns 
correspond to the m/z and retention time values, respectively. The remaining columns correspond to the feature intensities for 
each of the analyzed samples, with sample names in their respective headers and, (2) \code{class}, a vector containing the group 
label of each sample. The values of the \code{min.corr} and \code{min.rt} arguments determine the inclusion/exclusion thresholds for feature pairs. Only feature pairs 
having an intensity correlation value over \code{min.corr} and a retention time difference below \code{max.rt} will be returned for further analysis. When \code{mode} is turned on 
(mode="+" or mode="-") feature pair m/z differences must match the expected differences for any isotopic or adduct pattern. If the user wants to provide its own 
adduct list it must be added through the \code{adducts} argument. \code{adducts} must be a list() object with two vectors named \code{labels} 
(i.e. \code{c("[M+H]", "[M+2H]", "[M+3H]", "[M+NH4]")}) and \code{masses}(i.e. \code{c(1.00728, 2.0145, 3.0218, 18.0338)}). [M+H] and [M-H] are respectively mandatory for positive 
and negative ionization modes.
}
\value{
A list containing the following names:
  \item{data }{ intensity matrix where rows correspond to features and columns to included samples.}
  \item{class }{ sample phenotypes.}
  \item{mz }{ m/z values of each feature.}
  \item{rt }{ retention time values of each feature.}
  \item{feature.set }{ a five-column matrix with the data corresponding to the feature pairs that passed the filters.}
  \item{outliers }{ indexes of the excluded samples.}
  \item{scores }{ outlier scores of each sample.}
}
\author{A.Alonso, et al. Grup de Recerca de Reumatologia 2010, bioinformatics@urr.cat.}
\seealso{\code{\link{xcms.import}}, \code{\link{isotope.search}}, \code{\link{adduct.search}}, \code{\link{printresults}}, \code{\link{plotcompound}}.}
\examples{
## Load example data
data(astream.data,package="AStream")
## data.norm using default parameters
feat <- data.norm(input)
## Shows selected feature pairs
feat$feature.set[1:min(15,dim(feat$feature.set)[1]), ]
# data.norm changing the default parameters and without outlier detection
feat <- data.norm(input, std.outliers = -1, min.corr = 0.90, max.rt = 2)
# data.norm using m/z differences pre-filtering and the default adduct list
feat <- data.norm(input, min.corr = 0.7, mode = "+", mz.tol = 1e-2, adducts = c())
}