\HeaderA{mas5}{MAS 5.0 Expression Measure}{mas5}
\aliasA{xpsMAS5}{mas5}{xpsMAS5}
\aliasA{xpsMAS5-methods}{mas5}{xpsMAS5.Rdash.methods}
\keyword{manip}{mas5}
\begin{Description}\relax
This function converts a \code{\LinkA{DataTreeSet}{DataTreeSet}} into an \code{\LinkA{ExprTreeSet}{ExprTreeSet}}
using the XPS implementation of Affymetrix's MAS 5.0 expression measure.
\end{Description}
\begin{Usage}
\begin{verbatim}
mas5(xps.data,
     filename   = character(0),
     filedir    = getwd(),
     tmpdir     = "",
     normalize  = FALSE,
     sc         = 500,
     option     = "transcript",
     exonlevel  = "",
     update     = FALSE,
     xps.scheme = NULL,
     add.data   = TRUE,
     verbose    = TRUE)

xpsMAS5(object, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{xps.data}] object of class \code{DataTreeSet}.
\item[\code{filename}] file name of ROOT data file.
\item[\code{filedir}] system directory where ROOT data file should be stored.
\item[\code{tmpdir}] optional temporary directory where temporary ROOT files should be stored.
\item[\code{normalize}] logical. If \code{TRUE} scale normalization is used after an \code{ExprTreeSet} is obtained.
\item[\code{sc}] value at which all arrays will be scaled to.
\item[\code{option}] option determining the grouping of probes for summarization, one of 
\sQuote{transcript}, \sQuote{exon}, \sQuote{probeset}; exon arrays only.
\item[\code{exonlevel}] exon annotation level determining which probes should be used for summarization;
exon/genome arrays only.
\item[\code{update}] logical. If \code{TRUE} the existing ROOT data file \code{filename} will be updated.
\item[\code{xps.scheme}] optional alternative \code{SchemeTreeSet}.
\item[\code{add.data}] logical. If \code{TRUE} expression data will be included as slot \code{data}.
\item[\code{verbose}] logical, if \code{TRUE} print status information.
\item[\code{object}] object of class \code{DataTreeSet}.
\item[\code{...}] arguments \code{filename},\code{filedir},\code{tmpdir},\code{option},\code{exonlevel},\code{xps.scheme}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
This function computes the Affymetrix MAS 5.0 expression measure as implemented in XPS.
Although this implementation is based on the Affymetrix \sQuote{sadd\_whitepaper.pdf}, it 
can be used to compute an expression level for both expression arrays and exon arrays. 
For exon arrays it is necessary to supply the requested \code{option} and \code{exonlevel}.

Following \code{option}s are valid for exon arrays:
\Tabular{ll}{
\code{transcript}: & expression levels are computed for transcript clusters,
i.e. probe sets containing the same \sQuote{transcript\_cluster\_id}. \\
\code{exon}: & expression levels are computed for exon clusters,
i.e. probe sets containing the same \sQuote{exon\_id}, where each exon cluster
consists of one or more \code{probeset}s. \\
\code{probeset}: & expression levels are computed for individual probe sets,
i.e. for each \sQuote{probeset\_id}. \\
}
Following \code{exonlevel} annotations are valid for exon arrays:
\Tabular{lll}{
& \code{core}:& probesets supported by RefSeq and full-length GenBank transcripts. \\
& \code{metacore}:& core meta-probesets. \\
& \code{extended}:& probesets with other cDNA support. \\
& \code{metaextended}:& extended meta-probesets. \\
& \code{full}:& probesets supported by gene predictions only. \\
& \code{metafull}:& full meta-probesets. \\
& \code{affx}:& standard AFFX controls. \\
& \code{all}:& combination of above (including affx).
}
Following \code{exonlevel} annotations are valid for whole genome arrays:
\Tabular{lll}{
& \code{core}:& probesets with category \sQuote{unique}, \sQuote{similar} and \sQuote{mixed}. \\
& \code{metacore}:& probesets with category \sQuote{unique} only. \\
& \code{affx}:& standard AFFX controls. \\
& \code{all}:& combination of above (including affx).
}
Exon levels can also be combined, with following combinations being most useful:
\Tabular{ll}{
\code{exonlevel="metacore+affx"}:  & core meta-probesets plus AFFX controls \\
\code{exonlevel="core+extended"}: & probesets with cDNA support \\
\code{exonlevel="core+extended+full"}:  & supported plus predicted probesets \\
}

Exon level annotations are described in the Affymetrix whitepaper 
\sQuote{exon\_probeset\_trans\_clust\_whitepaper.pdf}.

If \code{normalize=TRUE} then the expression levels will be scaled to \code{sc}. 
For \code{sc=0} the expression levels will be scaled to the mean expression level.

If \code{update=TRUE} then the existing \code{\LinkA{ROOT}{ROOT}} file \code{filename} will be
updated, however, this is usually only recommended as option for function \code{\LinkA{express}{express}}.

In order to use an alternative \code{\LinkA{SchemeTreeSet}{SchemeTreeSet}} set the corresponding SchemeTreeSet 
\code{xps.scheme}.

\code{xpsMAS5} is the \code{DataTreeSet} method called by function \code{mas5}, however, 
expression levels will not be scaled to a common mean expression level.
\end{Details}
\begin{Value}
An \code{\LinkA{ExprTreeSet}{ExprTreeSet}}
\end{Value}
\begin{Note}\relax
In contrast to function \code{mas5}, expression levels computed with \code{xpsMAS5} 
will not be scaled to a common mean expression level.
\end{Note}
\begin{Author}\relax
Christian Stratowa
\end{Author}
\begin{References}\relax
Affymetrix (2002) Statistical Algorithms Description Document, Affymetrix Inc., 
Santa Clara, CA, whitepaper.
\url{http://www.affymetrix.com/support/technical/whitepapers/sadd_whitepaper.pdf}

Affymetrix (2005) Exon Probeset Annotations and Transcript Cluster Groupings, Affymetrix Inc., 
Santa Clara, CA, exon\_probeset\_trans\_clust\_whitepaper.pdf.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{express}{express}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## first, load ROOT scheme file and ROOT data file
scheme.test3 <- root.scheme(paste(.path.package("xps"),"schemes/SchemeTest3.root",sep="/"))
data.test3 <- root.data(scheme.test3, paste(.path.package("xps"),"rootdata/DataTest3_cel.root",sep="/"))

data.mas5 <- mas5(data.test3,"tmp_Test3MAS5",tmpdir="",normalize=TRUE,sc=500,update=TRUE,verbose=FALSE)

## get data.frame
expr.mas5 <- validData(data.mas5)
head(expr.mas5)

## plot results
if (interactive()) {
boxplot(data.mas5)
boxplot(log2(expr.mas5))
}

rm(scheme.test3, data.test3)
gc()
\end{ExampleCode}
\end{Examples}

