\HeaderA{diffreport-methods}{Create report of analyte differences}{diffreport.Rdash.methods}
\aliasA{diffreport}{diffreport-methods}{diffreport}
\aliasA{diffreport,xcmsSet-method}{diffreport-methods}{diffreport,xcmsSet.Rdash.method}
\keyword{methods}{diffreport-methods}
\keyword{file}{diffreport-methods}
\begin{Description}\relax
Create a report showing the most significant differences between
two sets of samples. Optionally create extracted ion chromatograms
for the most significant differences.
\end{Description}
\begin{Arguments}
\begin{ldescription}
\item[\code{object}] the \code{xcmsSet} object
\item[\code{class1}] character vector with the first set of sample classes to be
compared

\item[\code{class2}] character vector with the second set of sample classes to be
compared

\item[\code{filebase}] base file name to save report, \code{.tsv} file and \code{\_eic}
will be appended to this name for the tabular report and EIC
directory, respectively. if blank nothing will be saved

\item[\code{eicmax}] number of the most significantly different analytes to create
EICs for

\item[\code{eicwidth}] width (in seconds) of EICs produced

\item[\code{sortpval}] logical indicating whether the reports should be sorted by
p-value

\item[\code{classeic}] character vector with the sample classes to include in the EICs

\item[\code{metlin}] mass uncertainty to use for generating link to Metlin metabolite
database. the sign of the uncertainty indicates negative or
positive mode data for M+H or M-H calculation. a value of FALSE
or 0 removes the column

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
This method handles creation of summary reports with statistics
about which analytes were most significantly different between
two sets of samples. It computes Welch's two-sample t-statistic
for each analyte and ranks them by p-value. It returns a summary
report that can optionally be written out to a tab-separated file.

Additionally, it does all the heavy lifting involved in creating
superimposed extracted ion chromatograms for a given number of
analytes.  It does so by reading the raw data files assoicated
with the samples of interest one at a time. As it does so, it
prints the name of the sample it is currently reading. Depending
on the number and size of the samples, this process can take a
long time.

If a base file name is provided, the report (see Value section)
will be saved to a tab separated file. If EICs are generated,
they will be saved as 640x480 PNG files in a newly created
subdirectory. The numbered file names correspond to the rows in
the report.

Chromatographic traces in the EICs are colored and labeled by
their sample class. Sample classes take their color from the
current palette. The color a sample class is assigned is dependent
its order in the \code{xcmsSet} object, not the order given in
the class arguments. Thus \code{levels(sampclass(object))[1]}
would use color \code{palette()[1]} and so on. In that way, sample
classes maintian the same color across any number of different
generated reports.
\end{Details}
\begin{Value}
A data frame with the following columns:

\begin{ldescription}
\item[\code{fold}] mean fold change (always greater than 1, see \code{tstat} for
which set of sample classes was higher)

\item[\code{tstat}] Welch's two sample t-statistic, positive for analytes having
greater intensity in \code{class2}, negative for analytes having
greater intensity in \code{class1}

\item[\code{pvalue}] p-value of t-statistic
\item[\code{mzmed}] median m/z of peaks in the group
\item[\code{mzmin}] minimum m/z of peaks in the group
\item[\code{mzmax}] maximum m/z of peaks in the group
\item[\code{rtmed}] median retention time of peaks in the group
\item[\code{rtmin}] minimum retention time of peaks in the group
\item[\code{rtmax}] maximum retention time of peaks in the group
\item[\code{npeaks}] number of peaks assigned to the group
\item[\code{Sample Classes}] number samples from each sample class represented in the group

\item[\code{...}] one column for every sample class
\item[\code{Sample Names}] integrated intensity value for every sample
\item[\code{...}] one column for every sample
\end{ldescription}
\end{Value}
\begin{Section}{Methods}
\describe{
\item[object = "xcmsSet"] \code{diffreport(object, class1 = levels(sampclass(object))[1], 
                   class2 = levels(sampclass(object))[2], 
                   filebase = character(), eicmax = 0, eicwidth = 200,
                   sortpval = TRUE, classeic = c(class1,class2),
                   metlin = FALSE)}

}
\end{Section}
\begin{SeeAlso}\relax
\code{\LinkA{xcmsSet-class}{xcmsSet.Rdash.class}},
\code{\LinkA{mt.teststat}{mt.teststat}},
\code{\LinkA{palette}{palette}}
\end{SeeAlso}

