NMF (version 0.2.2)

aheatmap: Annotated Heatmaps

Description

The function aheatmap plots high-quality heatmaps, with a detailed legend and unlimited annotation tracks for both columns and rows. The annotations are coloured differently according to their type (factor or numeric covariate). Although it uses grid graphics, the generated plot is compatible with base layouts such as the ones defined with 'mfrow' or layout, enabling the easy drawing of multiple heatmaps on a single a plot -- at last!.

Usage

aheatmap(x, color = "-RdYlBu2:100", breaks = NA,
    border_color = NA, cellwidth = NA, cellheight = NA,
    scale = "none", Rowv = TRUE, Colv = TRUE,
    revC = identical(Colv, "Rowv") || is_NA(Rowv) || (is.integer(Rowv) && 
        length(Rowv) > 1) || is(Rowv, "silhouette"),
    distfun = "euclidean", hclustfun = "complete",
    reorderfun = function(d, w) reorder(d, w),
    treeheight = 50, legend = TRUE, annCol = NA,
    annRow = NA, annColors = NA, annLegend = TRUE,
    labRow = NULL, labCol = NULL, subsetRow = NULL,
    subsetCol = NULL, txt = NULL, fontsize = 10,
    cexRow = min(0.2 + 1/log10(nr), 1.2),
    cexCol = min(0.2 + 1/log10(nc), 1.2), filename = NA,
    width = NA, height = NA, main = NULL, sub = NULL,
    info = NULL, verbose = getOption("verbose"),
    gp = gpar())

Arguments

x

numeric matrix of the values to be plotted. An ExpressionSet objects can also be passed, in which case the expression values are plotted (exprs(x)).

color

colour specification for the heatmap. Default to palette '-RdYlBu2:100', i.e. reversed palette 'RdYlBu2' (a slight modification of RColorBrewer's palette 'RdYlBu') with 100 colors. Possible values are:

• a character/integer vector of length

breaks

a sequence of numbers that covers the range of values in x and is one element longer than color vector. Used for mapping values to colors. Useful, if needed to map certain values to certain colors. If value is NA then the breaks are c

border_color

color of cell borders on heatmap, use NA if no border should be drawn.

cellwidth

individual cell width in points. If left as NA, then the values depend on the size of plotting window.

cellheight

individual cell height in points. If left as NA, then the values depend on the size of plotting window.

scale

character indicating how the values should scaled in either the row direction or the column direction. Note that the scaling is performed after row/column clustering, so that it has no effect on the row/column ordering. Possible values are:

Rowv

clustering specification(s) for the rows. It allows to specify the distance/clustering/ordering/display parameters to be used for the rows only. Possible values are:

• TRUEorNULL(to be consistent with

Colv

clustering specification(s) for the columns. It accepts the same values as argument Rowv (modulo the expected length for vector specifications), and allow specifying the distance/clustering/ordering/display parameters to be used for

revC

a logical that specify if the row order defined by Rowv should be reversed. This is mainly used to get the rows displayed from top to bottom, which is not the case by default. Its default value is computed at runtime, to suit

distfun

default distance measure used in clustering rows and columns. Possible values are:

• all the distance methods supported bydist(e.g. "euclidean" or "maximum").
• all correlation methods supporte

hclustfun

default clustering method used to cluster rows and columns. Possible values are:

• a method name (a character string) supported byhclust(e.g.'average').
• an object of class

reorderfun

default dendrogram reordering function, used to reorder the dendrogram, when either Rowv or Colv is a numeric weight vector, or provides or computes a dendrogram. It must take 2 parameters: a dendrogram, and a weight vect

subsetRow

Specification of subsetting the rows before drawing the heatmap. Possible values are:

• an integer vector of length > 1 specifying the indexes of the rows to keep;
• a character vector of length > 1 specyfing the names of the rows to

subsetCol

Specification of subsetting the columns before drawing the heatmap. It accepts the similar values as subsetRow. See details above.

txt

character matrix of the same size as x, that contains text to display in each cell. NA values are allowed and are not displayed. See demo for an example.

treeheight

how much space (in points) should be used to display dendrograms. If specified as a single value, it is used for both dendrograms. A length-2 vector specifies separate values for the row and column dendrogram respectively. Default value: 50 points

legend

boolean value that determines if a colour ramp for the heatmap's colour palette should be drawn or not. Default is TRUE.

annCol

specifications of column annotation tracks displayed as coloured rows on top of the heatmaps. The annotation tracks are drawn from bottom to top. A single annotation track can be specified as a single vector; multiple tracks are specified as a lis

annRow

specifications of row annotation tracks displayed as coloured columns on the left of the heatmaps. The annotation tracks are drawn from left to right. The same conversion, renaming and colouring rules as for argument annCol apply.

annColors

list for specifying annotation track colors manually. It is possible to define the colors for only some of the annotations. Check examples for details.

annLegend

boolean value specifying if the legend for the annotation tracks should be drawn or not. Default is TRUE.

labRow

labels for the rows.

labCol

labels for the columns. See description for argument labRow for a list of the possible values.

fontsize

base fontsize for the plot

cexRow

fontsize for the rownames, specified as a fraction of argument fontsize.

cexCol

fontsize for the colnames, specified as a fraction of argument fontsize.

main

Main title as a character string or a grob.

sub

Subtitle as a character string or a grob.

info

(experimental) Extra information as a character vector or a grob. If info=TRUE, information about the clustering methods is displayed at the bottom of the plot.

filename

file path ending where to save the picture. Currently following formats are supported: png, pdf, tiff, bmp, jpeg. Even if the plot does not fit into the plotting window, the file size is calculated so that the plot would fit there, unless specifie

width

manual option for determining the output file width in

height

manual option for determining the output file height in inches.

verbose

if TRUE then verbose messages are displayed and the borders of some viewports are highlighted. It is entended for debugging purposes.

gp

graphical parameters for the text used in plot. Parameters passed to grid.text, see gpar.

PDF graphic devices

if plotting on a PDF graphic device -- started with pdf, one may get generate a first blank page, due to internals of standard functions from the grid package that are called by aheatmap. The NMF package ships a custom patch that fixes this issue. However, in order to comply with CRAN policies, the patch is not applied by default and the user must explicitly be enabled it. This can be achieved on runtime by either setting the NMF specific option 'grid.patch' via nmf.options(grid.patch=TRUE), or on load time if the environment variable 'R_PACKAGE_NMF_GRID_PATCH' is defined and its value is something that is not equivalent to FALSE (i.e. not '', 'false' nor 0).

Details

The development of this function started as a fork of the function pheatmap from the pheatmap package, and provides several enhancements such as:

• argument names match those used in the base functionheatmap;
• unlimited number of annotation forbothcolumns and rows, with simplified and more flexible interface;
• easy specification of clustering methods and colors;
• return clustering data, as well as grid grob object.

Please read the associated vignette for more information and sample code.

Examples

# roxygen generated flag
options(R_CHECK_RUNNING_EXAMPLES_=TRUE)

## See the demo 'aheatmap' for more examples:
demo('aheatmap')

# Generate random data
n <- 50; p <- 20
x <- abs(rmatrix(n, p, rnorm, mean=4, sd=1))
x[1:10, seq(1, 10, 2)] <- x[1:10, seq(1, 10, 2)] + 3
x[11:20, seq(2, 10, 2)] <- x[11:20, seq(2, 10, 2)] + 2
rownames(x) <- paste("ROW", 1:n)
colnames(x) <- paste("COL", 1:p)

## Default heatmap
aheatmap(x)

## Distance methods
aheatmap(x, Rowv = "correlation")
aheatmap(x, Rowv = "man") # partially matched to 'manhattan'
aheatmap(x, Rowv = "man", Colv="binary")

# Generate column annotations
annotation = data.frame(Var1 = factor(1:p %% 2 == 0, labels = c("Class1", "Class2")), Var2 = 1:10)
aheatmap(x, annCol = annotation)