heatmap {apcluster} | R Documentation

## Plot Heatmap

### Description

Functions for Plotting of Heatmap

### Usage

    ## S4 method for signature 'ExClust,missing'
    heatmap(x, y, ...)
    ## S4 method for signature 'ExClust,matrix'
    heatmap(x, y, ...)
    ## S4 method for signature 'ExClust,Matrix'
    heatmap(x, y, ...)
    ## S4 method for signature 'ExClust,sparseMatrix'
    heatmap(x, y, ...)
    ## S4 method for signature 'AggExResult,missing'
    heatmap(x, y, ...)
    ## S4 method for signature 'AggExResult,matrix'
    heatmap(x, y, Rowv=TRUE, Colv=TRUE,
        sideColors=NULL, col=heat.colors(12),
        base=0.05,  add.expr, margins=c(5, 5, 2),
        cexRow=max(min(35 / nrow(y), 1), 0.1),
        cexCol=max(min(35 / ncol(y), 1), 0.1), main=NULL, dendScale=1,
        barScale=1, legend=c("none", "col"), ...)
    ## S4 method for signature 'matrix,missing'
    heatmap(x, y, ...)
    ## S4 method for signature 'missing,matrix'
    heatmap(x, y, ...)

### Arguments

`x` | a clustering result object of class `APResult`, `ExClust`, or `AggExResult`; for compatibility, `x` may also be a similarity matrix (see details below).
`y` | a similarity matrix

`sideColors`

character vector of colors to be used for plotting color bars that visualize clusters of the finest clustering level in `x`. This is done in a fashion similar to using `RowSideColors` or `ColSideColors` in the standard `heatmap` function. However, color bars are plotted either on both sides or not at all. The `sideColors` argument determines the coloring of both horizontal and vertical bars. If `sideColors` is shorter than the number of clusters in the finest clustering level, `sideColors` is recycled. In any case, a minimum number of two colors (two elements of sideColors) is required. If `NA`, no color bars are plotted. If `NULL` (default), color bars are only plotted if the finest cluster level does not only consist of single samples. In this case, the `rainbow` function is used to compute the vector of colors which is shuffled such that dissimilar colors are placed next to each other in the color bar.

`col` | color ramp used for the heatmap image; see `image`

`Rowv`

determines whether or not a row dendrogram should be plotted. If `FALSE` or `NA`, no row dendrogram is plotted. In any other case, a row dendrogram is plotted unless the number of clusters in the finest clustering level is less than 2. Note that, in the latter case, the actual values in `Rowv` are ignored, so this argument cannot be used to supply a previously computed dendrogram or re-ordering of elements as in the standard `heatmap` function.

`Colv` | determines whether or not a column dendrogram should be plotted. Fully analogous to `Rowv`, except that column dendrograms are never plotted if the similarity matrix `y` is non-quadratic.
`base` | fraction of height used for the very first join in dendrograms; see `coerce-methods`.
`add.expr,margins,cexRow,cexCol,main` | largely analogous to the standard `heatmap` function; to omit row/column labeling, set `cexRow`/`cexCol` to `0`. The default for `margins` is a vector of length 3, where the third element is the right-hand side margin for the color legend (see `legend` argument). It remains unused (and can also be omitted) if no color legend is plotted.
`dendScale` | factor scaling the width of vertical and height of horizontal dendrograms; values have to be larger than 0 and no larger than 2. The default is 1 which corresponds to the same size as the dendrograms plot by the standard `heatmap` function
`barScale` | factor scaling the width of color bars; values have to be larger than 0 and no larger than 4. The default is 1 which corresponds to half the width of the color bars plot by the standard `heatmap` function
`legend` | if `"col"`, then a color legend similar to `filled.contour` is added on the right-hand side of the heatmap plot; if `"none"` (default), no such legend is added.
`...` | see details below

### Details

The `heatmap` functions provide plotting of heatmaps from several different types of input object. The implementation is similar to the standard graphics function `heatmap`. Plotting heatmaps via the `plot` command as available in previous versions of this package is still available for backward compatibility.

If `heatmap` is called for objects of classes `APResult` or `ExClust`, a heatmap of the similarity matrix in slot `sim` of the parameter `x` is created with clusters grouped together and highlighted in different colors. The order of clusters is determined by running `aggExCluster` on the clustering result `x`. This variant of `heatmap` returns an invisible `AggExResult` object.

If `heatmap` is called for an `AggExResult` object that contains all levels of clustering, the heatmap is displayed with the corresponding clustering dendrogram. If the `AggExResult` object is the result of running `aggExCluster` on a prior clustering result, the same heatmap plot is produced as if `heatmap` had been called on this prior clustering result, however, returning the cluster hierarchy's `dendrogram`. In the latter case, color bars are plotted to visualize the prior clustering result (see description of argument `sideColors` above).

All variants described above only work if the input object `x` contains a slot `sim` with the similarity matrix (which is only the case if the preceding clustering method has been called with `includeSim=TRUE`). In case the slot `sim` of `x` does not contain the similarity matrix, the similarity matrix must be supplied as second argument `y`.

All variants described above internally use `heatmap` with signature `AggExResult,matrix`, so all arguments list above can be used for all variants, as they are passed through using the `...` argument. All other arguments, analogously to the standard `heatmap` function, are passed on to the standard function `image`. This is particularly useful for using alternative color schemes via the `col` argument.

The two variants with one of the two arguments being a matrix and one being missing are just wrappers around the standard `heatmap` function with the aim to provide compatibility with this standard case.

### Value

see details above

### Note

Similarity matrices can be supplied in dense or sparse format. Note, however, that sparse matrices are converted to full dense matrices before plotting heatmaps which may lead to memory and/or performance bottlenecks for larger data sets.

### Author(s)

Ulrich Bodenhofer, Andreas Kothmeier & Johannes Palme apcluster@bioinf.jku.at

### References

http://www.bioinf.jku.at/software/apcluster

Bodenhofer, U., Kothmeier, A., and Hochreiter, S. (2011) APCluster: an R package for affinity propagation clustering. Bioinformatics 27, 2463-2464. DOI: 10.1093/bioinformatics/btr406.

### See Also

`APResult`, `AggExResult`, `ExClust`, `apcluster`, `apclusterL`, `aggExCluster`, `cutree-methods`, `plot-methods`

### Examples

    ## create two Gaussian clouds
    cl1 <- cbind(rnorm(50, 0.2, 0.05), rnorm(50, 0.8, 0.06))
    cl2 <- cbind(rnorm(50, 0.7, 0.08), rnorm(50, 0.3, 0.05))
    x <- rbind(cl1, cl2)

    ## run affinity propagation using negative squared Euclidean
    apres <- apcluster(negDistMat(r=2), x, p=-0.1)

    ## plot heatmap clustering run
    heatmap(apres)

    ## rerun affinity propagation
    ## reuse similarity matrix from previous run
    apres2 <- apcluster(s=apres@sim, q=0.6)

    ## plot heatmap of second run
    heatmap(apres2, apres@sim)

    ## with alternate heatmap coloring, alternating color bars, and no dendrograms
    heatmap(apres2, apres@sim, Rowv=NA, Colv=NA,
            sideColors=c("darkgreen", "yellowgreen"), col=terrain.colors(12))

    ## perform agglomerative clustering of affinity propagation clusters
    aggres1 <- aggExCluster(apres@sim, apres2)

    ## plot heatmap
    heatmap(cutree(aggres1, 2), apres@sim)

    ## perform agglomerative clustering of whole data set
    aggres2 <- aggExCluster(negDistMat(r=2), x)

    ## show heatmap along with dendrogram
    heatmap(aggres2)

[Package apcluster version 1.4.7 Index]