%
% NOTE -- ONLY EDIT THE .Rnw FILE!!!  The .tex file is
% likely to be overwritten.
%
% \VignetteIndexEntry{Processing Tandem-MS and MS$^n$ data with with xcms}
% \VignetteKeywords{preprocess, analysis, tandemms}
% \VignettePackage{xcms}
\documentclass[12pt]{article}

\usepackage{hyperref}

\newcommand{\Robject}[1]{{\texttt{#1}}}
\newcommand{\Rfunction}[1]{{\texttt{#1}}}
\newcommand{\Rpackage}[1]{{\textit{#1}}}
\newcommand{\Rclass}[1]{{\textit{#1}}}
\newcommand{\Rmethod}[1]{{\textit{#1}}}
\newcommand{\Rfunarg}[1]{{\textit{#1}}}

\textwidth=6.2in
\textheight=8.5in
%\parskip=.3cm
\oddsidemargin=.1in
\evensidemargin=.1in
\headheight=-.3in

\begin{document}
\title{Processing Tandem-MS and MS$^n$ data with with xcms}
\author{S. Neumann, J. Kutzera}
\maketitle

\section*{Introduction}

This document describes how to use \Rpackage{xcms}
for processing of Tandem-MS and MS$^n$ data from e.g.\ triple-quad,
QTOF, ion trap or orbitrap mass spectrometers.

% <<LibraryPreload, echo = FALSE, results = hide>>=
<<LibraryPreload>>=
library(xcms)
library(msdata)
@

\section{Raw Data File Preparation}

The \Rpackage{xcms} package reads full-scan LC/MS data and associated
Tandem-MS and MS$^n$ spectra from mzData files only.

For the purposes of demonstration, we will use a some sample files
included in this package.

The (truncated) raw data files are contained in the \texttt{data}
directory.  To access the mzData files, we first locate the
\textit{data} directory in the \Rpackage{xcms} package.

%FileFilter -in HAM_004_641fE_pDDIT.mzData -rt 1190:1310 -int 100000: -mz 500:850 -out extracted.mzData

<<RawFiles>>=
mzdatapath <- system.file("iontrap", package = "msdata")
list.files(mzdatapath, recursive = TRUE)
@

\section{Accessing, combining and Visualising MS$^n$ spectra}

The MS$^n$ spectra are read into xcms just like plain LC-MS files.
Inclusion of the additional scans has to be explicitely enabled. The
xcmsRaw summary shows the additional content:

<<FileIO>>=
library(xcms)
mzdatafiles <- list.files(mzdatapath, recursive = TRUE, full.names = TRUE)
xraw <- xcmsRaw(mzdatafiles[1], includeMSn=TRUE)
xraw
@

There is also a new peak picker, which actually returns all parent
ions as annotated in the mzData / mzXML files. A warning will be
issued if this is not present, either because of a poor converter or
if xraw is read from a CDF file:

<<SpectraSelection>>=
peaks <- findPeaks(xraw, method="MS1")
@

By giving larger windows, subsets of spectra can be returned,
and these can be combined to obtain so called compound spectra
containing e.g. MS$^2$ to MS$^5$.

% <<SpectraCombining>>=
% #xnew <- getScan(xraw)
% #xnew2 <- combineScans(xnew)
% @

\section{xcmsFragments}

A xcmsFragments-Object contains a Table with informations about all
Peaks from MS1 to MSn of one Experiment, including mz-value,
retensiontime, MSlevel, and parentpeak. The data can be used for
visualization or (later) computing alignments between different
Experiments. The object is created as empty and can be filled with
collect(). This method requires a peaktable or a xcmsSet for the
MS1peaks and the original xcmsRaw for the msn-Data.

<<SpectraSelection>>=
xs <- xcmsSet(mzdatafiles, method="MS1")
xfrag <- xcmsFragments(xs)
xfrag
@

plotTree prints out a simplyfied tree of the Peaks in the Object. The
user can define borders for the retensionTime and for the MassRange,
he can also print the tree for a single MS1-Peak.

Finally, to visualise the fragmentation tree, a textual representation
is available. Additionally, all specified scans
can be passed to \Rpackage{Rgraphviz}.

\begin{figure}
\begin{minipage}[b]{0.49\linewidth}
<<TextTree, echo=FALSE>>=
plotTree(xfrag,xcmsFragmentPeakID=6, textOnly=TRUE)
@
\end{minipage}
\caption{\label{treeplot} The MS$^n$ fragmentation tree for the MS1
  peak Nr. 6.}
\end{figure}

\end{document}