%\VignetteIndexEntry{Advanced topics: Customizing arrayQualityMetrics reports and programmatic processing of the output}
%\VignetteDepends{CCl4,vsn}
%\VignettePackage{arrayQualityMetrics}
%\VignetteEngine{knitr::knitr}

\documentclass[11pt]{article}

<<style, eval=TRUE, echo=FALSE, results="asis">>=
knitr::opts_chunk$set(message=FALSE, warning=FALSE, error=FALSE, tidy=FALSE) # turn off verbosity
BiocStyle:::latex()
@

\begin{document}

\bioctitle[Advanced topics]%
    {Advanced topics: Customizing arrayQualityMetrics reports and programmatic processing of the output}
\author{Audrey Kauffmann, Wolfgang Huber}
\maketitle
\tableofcontents

<<dummy1, include=FALSE>>=
##options(error=recover)
options(bitmapType = "cairo")
.HaveDummy = !interactive()
  if(.HaveDummy) pdf("dummy.pdf")
@ 

%--------------------------------------------------
\section{Introduction}
%--------------------------------------------------
If you are new to this package, then please consult the vignette
\emph{Introduction: microarray quality assessment with arrayQualityMetrics}.

This vignette addresses advanced topics. It explains how to customize
the report by selecting specific modules and sections, or by adding
your own ones. Furthermore, we will see how to (programmatically)
postprocess the results of the outlier detection, or how to adapt the
detection criteria to your needs.

\emph{Terminology:} In the documentation of this package, we
refer to a \emph{module} as a self-contained element of a report that
investigates one particular quality metric. A module consists of a
figure and an explanatory text. It may also contain a data structure
(an object of class \Rclass{outlierDetection}) that
marks a subset of the arrays in the dataset as outliers
according to the particular metric investigated in the module.  We
refer to a \emph{section} as a collection of one or more modules that
are thematically related.

For the following examples, let us load the needed packages and some data.

<<loading, results="hide">>=
library("arrayQualityMetrics")
library("ALLMLL")
data("MLL.A")
@


%--------------------------------------------------
\section{Data preparation}
%--------------------------------------------------
Some of the computations that are needed for the modules are common
between several modules, and thus we perform them once,
beforehand. These functions are called \Rfunction{prepdata} and
\Rfunction{prepaffy}, and we refer to their manual page for 
details. For example,

<<DataPreparation>>=
preparedData = prepdata(expressionset = MLL.A, 
                        intgroup = c(), 
                        do.logtransform = TRUE)
@ 

The arguments \Robject{intgroup} and \Robject{do.logtransform} are the
same as for \Rfunction{arrayQualityMetrics}, but in
\Rfunction{prepdata} they have no defaults, so we need to set them
explicitely.

%--------------------------------------------------
\section{Module generating functions}
%--------------------------------------------------
The package contains a variety of functions that compute modules, and they are
listed on a manual page which you can access by typing:

<<boxplot, eval=FALSE>>=
?aqm.boxplot
@ 

Here, let us create a report with only two quality metrics modules: 
boxplots and density plots.

<<metrics>>=
bo = aqm.boxplot(preparedData)
de = aqm.density(preparedData)
qm = list("Boxplot" = bo, "Density" = de)
@ 

The objects \Robject{bo} and \Robject{de} are of class
\Rclass{aqmReportModule}; please consult the class' manual page for
more information.

If you want to create your own modules, please have a look at the code
for the various existing functions for this purpose, and adapt it.
The function \Rfunction{aqm.pca} is a good place to start.

%--------------------------------------------------
\section{Outlier detection}
%--------------------------------------------------
Some of the modules perform outlier detection. For instance, in the
default report produced by \Rfunction{arrayQualityMetrics}, the
module headed \emph{Boxplots} is followed by one headed \emph{Outlier
  detection for Boxplots}. In the corresponding
\Rclass{aqmReportModule} object, this is reflected by a non-trivial
value for the slot named \Robject{outliers}:
%
<<booutliers>>=
bo@outliers
@ 
%
The slot named \Robject{statistic} contains, for each array, a
single number based on which outlier detection is performed.  For
instance, in the case of \Robject{bo}, the slot
\Robject{bo@outliers@statistic} is the Kolmogorov-Smirnov statistic
for the comparison between each array's intensity distribution and the
distribution of the pooled data. The slot \Robject{threshold} contains
the threshold against which the valuess of \Robject{statistic} were
compared. Arrays with a value of \Robject{statistic} greather than
\Robject{threshold} are called outliers. Their indices are listed in
the vector \Robject{which}.  Finally, the slot \Robject{description}
contains a textual description of the definition of
\Robject{statistic} and indicates how the \Robject{threshold} was chosen.

The actual details of outlier detection are different for each report
module, and are documented in the figure caption of the report
module. For more information, please look at the code of
the report module generating function of interest -- for instance, at the first few
lines of the \Rfunction{boxplot} function. The code there uses the helper
functions \Rfunction{outliers} and \Rfunction{boxplotOutliers}, which
are documented in their manual pages.

%--------------------------------------------------
\section{Rendering the report}
%--------------------------------------------------
A report is rendered by calling the function
\Rfunction{aqm.writereport} with a list of \Rclass{aqmReportModule}
objects.

<<shortReport>>=
outdir = tempdir()
aqm.writereport(modules = qm, reporttitle = "My example", outdir = outdir, 
                arrayTable = pData(MLL.A))
outdir
@ 

Point your browser to the \texttt{index.html} file in that directory.

%--------------------------------------------------
\subsection*{Session Info}
%--------------------------------------------------
<<dummy2, include=FALSE>>=
if(.HaveDummy) dev.off()
@ 


<<pkgs, echo=FALSE, results="asis">>=
toLatex(sessionInfo())
@

\end{document}