<!--
%\VignetteEngine{knitr}
%\VignetteIndexEntry{1. Introduction to ComplexHeatmap package}
-->

Introduction to ComplexHeatmap package
========================================

**Author**: Zuguang Gu ( z.gu@dkfz.de )

**Date**: `r Sys.Date()`

-------------------------------------------------------------

```{r global_settings, echo = FALSE, message = FALSE}
library(markdown)
options(markdown.HTML.options = c(options('markdown.HTML.options')[[1]], "toc"))

library(knitr)
knitr::opts_chunk$set(
    error = FALSE,
    tidy  = FALSE,
    message = FALSE,
    fig.align = "center",
    fig.width = 5,
    fig.height = 5)
options(markdown.HTML.stylesheet = "custom.css")

options(width = 100)
```

Complex heatmaps are efficient to visualize associations 
between different sources of data sets and reveal potential structures. 
Here the **ComplexHeatmap** package provides a highly flexible way to arrange 
multiple heatmaps and supports self-defined annotation graphics.

## General design

Generally, a heatmap list contains several heatmaps and row annotations.

```{r design, echo = FALSE, fig.width = 10, fig.height = 5}
source("design.R")
```

Surrounding the heatmap list,
there are legends for heatmaps and annotations, also there are titles which are placed
on the four sides of the heatmap list. And for each heatmap, there are also different components
surrounding the heatmap body.

The **ComplexHeatmap** package is implemented in an object-oriented way. To describe a heatmap list, 
there are following classes:

- `Heatmap` class: a single heatmap containing heatmap body, row/column names, titles, dendrograms and column annotations.
- `HeatmapList` class: a list of heatmaps and row annotations.
- `HeatmapAnnotation` class: defines a list of row annotations and column annotations.

There are also several internal classes:

- `SingleAnnotation` class: defines a single row annotation or column annotation.
- `ColorMapping` class: mapping from values to colors.

**ComplexHeatmap** is implemented under **grid** system, so users should know basic **grid** functionality
to get full use of the package.

## Vignettes

There are several vignettes in the package. Each vignette focuses on one specific topic. Following
lists the general topics discussed in these vignettes:

  1. [**Making a Single Heatmap**](s2.single_heatmap.html)

    This vignette introduces the basic configuration for making a single heatmap. Similar as other
    R functions/packages, the basic usage is quite similar, but there are several unique features
    for **ComplexHeamtap** package.
    - Works both for numeric matrix and character matrix.
    - For numeric matrix which contains continuous values, the package allows a color mapping function
      which can give more accurate colors and be robust to outliers.
    - Highly flexible for clustering. You can define the distance method for clustering by:
          * a pre-defined distance such as "euclidean" or "pearson",
          * a self-defined function which calculates distance from a matrix,
          * a self-defined function which calculates distance from two vectors.
        
        You can define the clustering method by:
          * a clustering function such as `diana()` from **cluster** package
          * a `hclust` or `dendrogram` object.
    - `NA` is allowed for clustering and heatmap visualization.
    - Dendrogram and dimension names can be put on any side of the heatmap.
    - Rows on the heatmap can be split by `cutree`, by `kmeans` or by a data frame which contains 
      different levels that split the heatmap.
    - The heatmap body itself can be completely self-defined.

  2. [**Making a List of Heatmaps**](s3.a_list_of_heatmaps.html)

    This vignette introduces how to concatenate a list of heatmaps and how adjustment is applied to keep
    the correspondence of the heatmaps.

  3. [**Heatmap Annotations**](s4.heatmap_annotation.html)

    This vignette introduces the concept of the heatmap annotation and demonstrates how to make simple annotations
    as well as complex annotations. Also, the vignette explains the difference between column annotations
    and row annotations.

  4. [**Heatmap and Annotation Legends**](s5.legend.html)

    This vignette introduces how to configurate the heatmap legend and annotation legend, also
    how to add self-defined legends.

  5. [**Heatmap Decoration**](s6.heatmap_decoration.html)

    This vignette introduces methods to add more self-defined graphics to the heatmaps after the heatmaps
    are generated.

  6. [**Interactive with Heatmaps**](s7.interactive.html)

    How to select a region in the heatmap to retrieve the sub-matrix.
  
  7. [**OncoPrint**](s8.oncoprint.html)

    How to make an oncoPrint.

  8. [**Examples**](s9.examples.html)

    More simulated and real-world examples are shown in this vignette.

In the supplementaries of [the ComplexHeatmap paper](http://bioinformatics.oxfordjournals.org/content/early/2016/05/20/bioinformatics.btw313.abstract), there are four comprehensive examples which are applied
on real-world high-throughput datasets. [The examples can be found here.](http://jokergoo.github.io/supplementary/ComplexHeatmap-supplementary1-4/index.html)

Also [my blog](http://jokergoo.github.io/blog.html) has some examples and tips for making better complex heatmaps.