\documentclass[12pt]{article}
% \VignetteEngine{knitr::knitr} 
% \VignetteIndexEntry{Introduction for heatmap3 package}
% \VignettePackage{heatmap3}
\textwidth 6.75in
\textheight 9.5in
\topmargin -.875in
\oddsidemargin -.06in
\evensidemargin -.06in

\usepackage{hyperref}

\hypersetup{
    colorlinks=true, %set true if you want colored links
    linktoc=all,     %set to all if you want both sections and subsections linked
    linkcolor=blue,  %choose some color if you want links to stand out
}

\begin{document}
\title{Introduction for heatmap3 package}
\author{Shilin Zhao}
\maketitle
\tableofcontents

<<setting, echo=FALSE, cache=FALSE>>=
options(width=58)
@

\section{Example}
Simulate a gene expression data set with 40 probes and 25 samples. These samples are divided into 3 groups, 5 in control group, 10 in treatment A and 10 in treatment B group. We will use the groups as categorical phenotype and we assume there is one continuous phenotype. Then we will annotate the two phenotypes in heatmap result.

Here we provided two samples:
The first example is simple. It generated the color bar as lengend, ploted row side color bars with two columns, didn't plot row dendrogram, and some cells at the bottom left were labeled by specified colors.
The second example ploted color bars and its legend to display a continuous variable in row side, texted labels with specified colors, ploted column side phenotype annotation. Then we provided a cutoff height so that the samples will be cut into different clusters by the cutoff. And statistic tests for annotations in different groups will be performed and the result will be returned.
<<heatmap3Example, tidy=T,warning=FALSE>>=
library(heatmap3)
example(heatmap3)
@

\section{Highlights}

\begin{itemize}
  \item Completely compatible with the original R function heatmap. You don't need to learn anything new or change your old commands to use it.
  \item Provides highly customizable function interface so that the users can use their own functions to generate legend or side annotation. And two convenient example functions were also provided. 
  \item Provides a height cutoff so that the samples will be cut into different clusters by the cutoff and labeled by different colors. And then statistic tests for the distribution of annotations in different clusters will be performed. 
  \item More convenient coloring features: Provides color legend for the input matrix automatically. A more fancy color series is set as default color. You can balance the colors in color legend so that you can ensure the median color will represent the 0 value.
  \item More powerful labeling features: The labels in axis could be labeled with colors. The side color bars support more than one column of colors.
  \item The color legend, column and row side color bars can exist in the same figure, which can't be done in other heatmap compatible packages.
  \item Improvement in parameters: Pearson correlation is set as default method; the agglomeration method for clustering now can be specified; the input values can be transformed into matrix automatically if it is a data.frame.
\end{itemize}

\section{Usage}
The main function is heatmap3, which was generate form the R function heatmap. So it is completely compatible with the original R function heatmap. You can use your commands for heatmap in heatmap3 as well. And you can use ?heatmap3 to get help for its new parameters. Here I just listed some of the new parameters for your information.
\begin{itemize}
  \item legendfun: function used to generate legend in top left of the figure. More details will be discussed below.
  \item ColSideFun and ColSideAnn: function used to generate annotation and labeling figure in column side. The users can use any plot functions to generate their own figure. More details will be discussed below.
  \item ColSideCut: the value to be used in cutting coloum dendrogram. The dendrogram and annotation will be divided into different parts and labeled respectively.
  \item method: the agglomeration method to be used by hclust function.
  \item ColAxisColors, RowAxisColors: integer indicating which column of ColSideColors or RowSideColors will be used as colors for labels in axis.
  \item showColDendro, showRowDendro: logical indicating if the column or row dendrogram should be plotted.
\end{itemize}

A very important new feature in heatmap3 is the legendfun and ColSideFun parameter. You can generate your own legend in the top left of the figure by legendfun. And generate your own sample annotation in column side. Here we provided a function called showLegend as an example. 
<<showLegend, tidy=T, eval=T>>=
library(heatmap3)
showLegend
@
This function is very simple. It first generates a empty figure and then uses the R function legend to generate legend. So you can simplely write your own function to show legend or something else in the top left of the figure. Here is an example for showLegend function.
<<showLegendExample, tidy=T>>=
example(showLegend)
@
We also provided a showAnn function as an example to show column side annotation.
<<showAnnExample, tidy=T>>=
example(showAnn)
@
\end{document}