%\VignetteIndexEntry{Introduction to the plotAlongChrom function}
%\VignetteDepends{tilingArray,RColorBrewer}
%\VignettePackage{tilingArray}
% 
\documentclass[11pt,a4wide]{article}
\usepackage[margin=2cm,nohead]{geometry}
\usepackage{color}
\definecolor{darkblue}{rgb}{0.0,0.0,0.75}
\usepackage[%
baseurl={http://www.bioconductor.org},%
pdftitle={Introduction to the plotAlongChrom function},%
pdfauthor={Zhenyu Xu},%
pdfsubject={tilingArray},%
pdfkeywords={Bioconductor},%
pagebackref,bookmarks,colorlinks,linkcolor=darkblue,citecolor=darkblue,%
pagecolor=darkblue,raiselinks,plainpages,pdftex]{hyperref}
\usepackage{Sweave}
\SweaveOpts{keep.source=TRUE,eps=FALSE,include=FALSE,width=5,height=5} 
%------------------------------------------------------------
% newcommand
%------------------------------------------------------------
\newcommand{\Robject}[1]{\texttt{#1}}
\newcommand{\Rpackage}[1]{\textit{#1}}
\newcommand{\Rclass}[1]{\textit{#1}}
\newcommand{\Rfunction}[1]{{\small\texttt{#1}}}
\newcommand{\mbs}[1]{{\mbox{\scriptsize #1}}}

\newcommand{\myincfig}[3]{%
  \begin{figure}[htbp]
    \begin{center}
      \includegraphics[width=#2]{#1}
      \caption{\label{#1}#3}
    \end{center}
  \end{figure}
}
\begin{document}

%------------------------------------------------------------
\title{Introduction to the plotAlongChrom function}
%------------------------------------------------------------
\author{zhenyu}

\maketitle

%----------------------------------------
\section{Introduction to the example data}
%----------------------------------------
The purpose of this vignette is to demonstrate some of the functionalities of the 
\Rfunction{plotAlongChrom} in the \Rpackage{tilingArray}
package. We use a small subset data from an expression profiling paper \cite{Xu2009}; The data
only include the region from 35000bp to 50000bp in yeast chromosome one. Expression profiling 
is done in YPE and YPD conditions, 3 replicates each. Further information about the experimental design 
can be found at the paper website {http://steinmetzlab.embl.de/NFRsharing/}.
<<load, results=hide>>=
library("grid")
library("RColorBrewer")
library("tilingArray")
@ 
<<errorReporting, echo=FALSE>>=
options(error=recover, warn=0, digits=3)
@ 
<<showTilingArrayData>>=
data("segnf")
class(segnf)
ls(segnf)
segnf$"1.+"
head(segnf$"1.+"@y)
dim(segnf$"1.+"@y)
head(segnf$"1.+"@x)
length(segnf$"1.+"@x)
segnf$"1.+"@logLik
segnf$"1.+"@nrSegments
head(segnf$"1.+"@breakpoints[[segnf$"1.+"@nrSegments]])
@ 
The \Robject{segnf} object is an environment which contains two objects of class \Rclass{segmentation}.    
\Robject{segnf} is the output of the \Rfunction{segChrom} in the \Rpackage{tilingArray} package.
The \Rclass{segmentation} object in \Robject{segnf} stores the probe expression information in the slot
\Robject{y}. As can be seen, it contains 1775 probes and 6 array hybes in two conditions. The genomic
coordinates where the probes aligned to is stored in the slot \Robject{x}. The order of the slot \Robject{x}
is the same as the probe row order in slot \Robject{y}. The segment boundary information is stored 
in the slot \Robject{breakpoints} which is a list that contains all the optimal placement of 1 segment to the
designate number(here in this data set is 17) of segments for this data. A log likelihood
score for each placement is stored in slot \Robject{logLik} from which the best one is choosen and stored
in the slot \Robject{nrSegments}. Further information about how the segmentation algorithm works, please 
read the vignette segmentation demo.

<<gffSub>>=
data(gffSub)
head(gffSub)
@
The \Robject{gffSub} object is a data frame that contains the SGD annotated features of the region 35000bp-50000bp
for yeast chromosome one.

%----------------------------------------
\section{Visualizing the expression profiling with the plotAlongChrom function}
%----------------------------------------
The function \Rfunction{plotAlongChrom} accepts an environment as its
first argument, which is expected to contain objects of class
\Rclass{segmentation} with names given by 
\Robject{paste(chr, c("+", "-"), sep=".")}, where \Robject{chr} is the
chromosome identifier. 

The following code generates Figure~\ref{plotAlongChrom-alongChromDot1}, a dot plot that averaged across all hybes.
<<alongChromDot1,fig=TRUE, eps=FALSE, include=FALSE, width=16, height=6,echo=TRUE>>=
grid.newpage()
plotAlongChrom(segnf,chr=1, coord=c(35000,50000),what="dots", gff=gffSub)
@
\myincfig{plotAlongChrom-alongChromDot1}{0.96\textwidth}{% 
Along-chromosome dot plot of the averaged value across all hybes.}

We could also make separate dot plot for different hybes by setting the parameter \textit{sepPlot} as TRUE. The 
following code generates Figure~\ref{plotAlongChrom-alongChromDot2} that plots the expression separately for the two 
conditions.
<<alongChromDot2,fig=TRUE, eps=FALSE, include=FALSE, width=16, height=8,echo=TRUE>>=
segObj = new.env(parent = baseenv())
nmLabel = colnames(segnf$"1.+"@y)
lab = gsub("\\d","",nmLabel)
for(nm in paste(1,c("+","-"),sep=".")){
    s = get(nm,env = segnf)
    rpY =  tapply(1:length(lab),lab,function(i)rowMeans(s@y[,i]))
    s@y = do.call(cbind,rpY)
    assign(nm,s,segObj)
}
grid.newpage()
plotAlongChrom(segObj,chr=1, coord=c(35000,50000),what="dots", gff=gffSub,sepPlot = T)
@

\myincfig{plotAlongChrom-alongChromDot2}{0.96\textwidth}{% 
Along-chromosome dot plot of the averaged value among different replicates for YPD and YPE condition.}
 
However, with the number of hybes increases, it is very hard to see the difference 
in dot plots in a normal screen. Thus, if the number of hybes is more than 4, the function will 
force to take the average. A better alternative of displaying multiple hybes is to use the heatmap.        
The following code generates Figure~\ref{plotAlongChrom-alongChromHeatmap1} that makes the heatmap plot.
<<alongChromHeatmap1,fig=TRUE, eps=FALSE, include=FALSE, width=16, height=6>>=
grid.newpage() 
plotAlongChrom(segnf,chr=1, coord=c(35000,50000),what="heatmap", gff=gffSub,
         rowNamesHeatmap=nmLabel,makeRasterImage=FALSE)
@

\myincfig{plotAlongChrom-alongChromHeatmap1}{0.96\textwidth}{% 
Along-chromosome heatmap plot of all the replicates in YPD and YPE condition.}
 
Start with R 2.11.0, the \Rpackage{grid} package introduced the raster array image function 
\Rfunction{grid.raster} which is a faster and efficient way of generating heatmap images. From R 2.11.0, The  
\Rpackage{tilingArray} package will use the \Rfunction{grid.raster} function as default to make heatmap
images replacing the previous \Rfunction{grid.rect} function. The choice between the two drawing functions
can be changed by the parameter \textit{makeRasterImage}. The following code generates 
Figure~\ref{plotAlongChrom-alongChromHeatmap2} that makes the raster heatmap plot.

<<alongChromHeatmap2,fig=TRUE, eps=FALSE, include=FALSE, width=16, height=6>>=
grid.newpage() 
plotAlongChrom(segnf,chr=1, coord=c(35000,50000),what="heatmap", gff=gffSub,
         rowNamesHeatmap=nmLabel,makeRasterImage=TRUE)
@

\myincfig{plotAlongChrom-alongChromHeatmap2}{0.96\textwidth}{% 
Along-chromosome raster heatmap plot of all the replicates in YPD and YPE condition.}

The color gradient of the heatmap could be changed by the parameter \textit{colHeatmap}.
The following code generates Figure~\ref{plotAlongChrom-alongChromHeatmap3} 
that makes the raster heatmap plot using a blue color gradient.
<<alongChromHeatmap3,fig=TRUE, eps=FALSE, include=FALSE, width=16, height=6>>=
grid.newpage() 
plotAlongChrom(segnf,chr=1, coord=c(35000,50000),what="heatmap", gff=gffSub,
         rowNamesHeatmap=nmLabel,makeRasterImage=TRUE,
         colHeatmap = colorRamp(brewer.pal(9, "Blues")))
@

\myincfig{plotAlongChrom-alongChromHeatmap3}{0.96\textwidth}{% 
Along-chromosome raster heatmap plot of all the replicates in YPD and YPE condition with a blue 
color gradient.}

%------------------------------------------------------------
\begin{thebibliography}{10}

\bibitem{Xu2009} Zhenyu Xu, Wu Wei, Julien Gagneur, Fabiana Perocchi, 
Sandra Clauder-Munster, Jurgi Camblong, Elisa Guffanti, Francoise Stutz, 
Wolfgang Huber and Lars M. Steinmetz \newblock Bidirectional promoters generate 
pervasive transcription in yeast.  \newblock \textit{Nature}, 2009.

\end{thebibliography}
\end{document}
