Learn R
ComplexHeatmap (version 1.10.2)

Heatmap: Constructor method for Heatmap class

Description

Constructor method for Heatmap class

Usage

Heatmap(matrix, col, name,
    na_col = "grey",
    color_space = "LAB",
    rect_gp = gpar(col = NA),
    cell_fun = function(j, i, x, y, width, height, fill) NULL,
    row_title = character(0),
    row_title_side = c("left", "right"),
    row_title_gp = gpar(fontsize = 14),
    row_title_rot = switch(row_title_side[1], "left" = 90, "right" = 270),
    column_title = character(0),
    column_title_side = c("top", "bottom"),
    column_title_gp = gpar(fontsize = 14),
    column_title_rot = 0,
    cluster_rows = TRUE,
    clustering_distance_rows = "euclidean",
    clustering_method_rows = "complete",
    row_dend_side = c("left", "right"),
    row_dend_width = unit(10, "mm"),
    show_row_dend = TRUE,
    row_dend_reorder = TRUE,
    row_dend_gp = gpar(),
    row_hclust_side = row_dend_side,
    row_hclust_width = row_dend_width,
    show_row_hclust = show_row_dend,
    row_hclust_reorder = row_dend_reorder,
    row_hclust_gp = row_dend_gp,
    cluster_columns = TRUE,
    clustering_distance_columns = "euclidean",
    clustering_method_columns = "complete",
    column_dend_side = c("top", "bottom"),
    column_dend_height = unit(10, "mm"),
    show_column_dend = TRUE,
    column_dend_gp = gpar(),
    column_dend_reorder = TRUE,
    column_hclust_side = column_dend_side,
    column_hclust_height = column_dend_height,
    show_column_hclust = show_column_dend,
    column_hclust_gp = column_dend_gp,
    column_hclust_reorder = column_dend_reorder,
    row_order = NULL,
    column_order = NULL,
    row_names_side = c("right", "left"),
    show_row_names = TRUE,
    row_names_max_width = unit(4, "cm"),
    row_names_gp = gpar(fontsize = 12),
    column_names_side = c("bottom", "top"),
    show_column_names = TRUE,
    column_names_max_height = unit(4, "cm"),
    column_names_gp = gpar(fontsize = 12),
    top_annotation = new("HeatmapAnnotation"),
    top_annotation_height = top_annotation@size,
    bottom_annotation = new("HeatmapAnnotation"),
    bottom_annotation_height = bottom_annotation@size,
    km = 1,
    split = NULL,
    gap = unit(1, "mm"),
    combined_name_fun = function(x) paste(x, collapse = "/"),
    width = NULL,
    show_heatmap_legend = TRUE,
    heatmap_legend_param = list(title = name, color_bar = "discrete"),
    use_raster = FALSE,
    raster_device = c("png", "jpeg", "tiff", "CairoPNG", "CairoJPEG", "CairoTIFF"),
    raster_quality = 1,
    raster_device_param = list())

Arguments

matrix
a matrix. Either numeric or character. If it is a simple vector, it will be converted to a one-column matrix.
col
a vector of colors if the color mapping is discrete or a color mapping function if the matrix is continuous numbers (should be generated by colorRamp2. If the matrix is continuous, the value can also be a vector of colors so that colors will be interpolated. Pass to ColorMapping.
name
name of the heatmap. The name is used as the title of the heatmap legend.
na_col
color for NA values.
rect_gp
graphic parameters for drawing rectangles (for heatmap body).
color_space
the color space in which colors are interpolated. Only used if matrix is numeric and col is a vector of colors. Pass to colorRamp2.
cell_fun
self-defined function to add graphics on each cell. Seven parameters will be passed into this function: i, j, x, y, width, height, fill which are row index, column index in matrix, coordinate of the middle points in the heatmap body viewport, the width and height of the cell and the filled color. x, y, width and height are all unit objects.
row_title
title on row.
row_title_side
will the title be put on the left or right of the heatmap?
row_title_gp
graphic parameters for drawing text.
row_title_rot
rotation of row titles. Only 0, 90, 270 are allowed to set.
column_title
title on column.
column_title_side
will the title be put on the top or bottom of the heatmap?
column_title_gp
graphic parameters for drawing text.
column_title_rot
rotation of column titles. Only 0, 90, 270 are allowed to set.
cluster_rows
If the value is a logical, it means whether make cluster on rows. The value can also be a hclust or a dendrogram that already contains clustering information. This means you can use any type of clustering methods and render the dendrogram object with self-defined graphic settings.
clustering_distance_rows
it can be a pre-defined character which is in ("euclidean", "maximum", "manhattan", "canberra", "binary", "minkowski", "pearson", "spearman", "kendall"). It can also be a function. If the function has one argument, the input argument should be a matrix and the returned value should be a dist object. If the function has two arguments, the input arguments are two vectors and the function calculates distance between these two vectors.
clustering_method_rows
method to make cluster, pass to hclust.
row_dend_side
should the row cluster be put on the left or right of the heatmap?
row_dend_width
width of the row cluster, should be a unit object.
show_row_dend
whether show row clusters.
row_dend_gp
graphics parameters for drawing lines. If users already provide a dendrogram object with edges rendered, this argument will be ignored.
row_dend_reorder
apply reordering on rows. The value can be a logical value or a vector which contains weight which is used to reorder rows
row_hclust_side
deprecated, use row_dend_side instead
row_hclust_width
deprecated, use row_dend_width instead
show_row_hclust
deprecated, use show_row_dend instead
row_hclust_gp
deprecated, use row_dend_gp instead
row_hclust_reorder
deprecated, use row_dend_reorder instead
cluster_columns
whether make cluster on columns. Same settings as cluster_rows.
clustering_distance_columns
same setting as clustering_distance_rows.
clustering_method_columns
method to make cluster, pass to hclust.
column_dend_side
should the column cluster be put on the top or bottom of the heatmap?
column_dend_height
height of the column cluster, should be a unit object.
show_column_dend
whether show column clusters.
column_dend_gp
graphic parameters for drawling lines. Same settings as row_dend_gp.
column_dend_reorder
apply reordering on columns. The value can be a logical value or a vector which contains weight which is used to reorder columns
column_hclust_side
deprecated, use column_dend_side instead
column_hclust_height
deprecated, use column_dend_height instead
show_column_hclust
deprecated, use show_column_dend instead
column_hclust_gp
deprecated, use column_dend_gp instead
column_hclust_reorder
deprecated, use column_dend_reorder instead
row_order
order of rows. It makes it easy to adjust row order for a list of heatmaps if this heatmap is selected as the main heatmap. Manually setting row order should turn off clustering
column_order
order of column. It makes it easy to adjust column order for both matrix and column annotations.
row_names_side
should the row names be put on the left or right of the heatmap?
show_row_names
whether show row names.
row_names_max_width
maximum width of row names viewport. Because some times row names can be very long, it is not reasonable to show them all.
row_names_gp
graphic parameters for drawing text.
column_names_side
should the column names be put on the top or bottom of the heatmap?
column_names_max_height
maximum height of column names viewport.
show_column_names
whether show column names.
column_names_gp
graphic parameters for drawing text.
top_annotation
a HeatmapAnnotation object which contains a list of annotations.
top_annotation_height
total height of the column annotations on the top.
bottom_annotation
a HeatmapAnnotation object.
bottom_annotation_height
total height of the column annotations on the bottom.
km
do k-means clustering on rows. If the value is larger than 1, the heatmap will be split by rows according to the k-means clustering. For each row-clusters, hierarchical clustering is still applied with parameters above.
split
a vector or a data frame by which the rows are split. But if cluster_rows is a clustering object, split can be a single number indicating rows are to be split according to the split on the tree.
gap
gap between row-slices if the heatmap is split by rows, should be unit object.
combined_name_fun
if the heatmap is split by rows, how to make a combined row title for each slice? The input parameter for this function is a vector which contains level names under each column in split.
width
the width of the single heatmap, should be a fixed unit object. It is used for the layout when the heatmap is appended to a list of heatmaps.
show_heatmap_legend
whether show heatmap legend?
heatmap_legend_param
a list contains parameters for the heatmap legend. See color_mapping_legend,ColorMapping-method for all available parameters.
use_raster
whether render the heatmap body as a raster image. It helps to reduce file size when the matrix is huge.
raster_device
graphic device which is used to generate the raster image
raster_quality
a value set to larger than 1 will improve the quality of the raster image.
raster_device_param
a list of further parameters for the selected graphic device

Value

Details

The initialization function only applies parameter checking and fill values to each slot with proper ones. Then it will be ready for clustering and layout.

Following methods can be applied on the Heatmap-class object:

The constructor function pretends to be a high-level graphic function because the show method of the Heatmap-class object actually plots the graphics.

Examples

Run this code
mat = matrix(rnorm(80, 2), 8, 10)
mat = rbind(mat, matrix(rnorm(40, -2), 4, 10))
rownames(mat) = letters[1:12]
colnames(mat) = letters[1:10]

require(circlize)

Heatmap(mat)
Heatmap(mat, col = colorRamp2(c(-3, 0, 3), c("green", "white", "red")))
Heatmap(mat, name = "test")
Heatmap(mat, column_title = "blablabla")
Heatmap(mat, row_title = "blablabla")
Heatmap(mat, column_title = "blablabla", column_title_side = "bottom")
Heatmap(mat, column_title = "blablabla", column_title_gp = gpar(fontsize = 20, 
    fontface = "bold"))
Heatmap(mat, cluster_rows = FALSE)
Heatmap(mat, clustering_distance_rows = "pearson")
Heatmap(mat, clustering_distance_rows = function(x) dist(x))
Heatmap(mat, clustering_distance_rows = function(x, y) 1 - cor(x, y))
Heatmap(mat, clustering_method_rows = "single")
Heatmap(mat, row_dend_side = "right")
Heatmap(mat, row_dend_width = unit(1, "cm"))
Heatmap(mat, row_names_side = "left", row_dend_side = "right", 
    column_names_side = "top", column_dend_side = "bottom")
Heatmap(mat, show_row_names = FALSE)

mat2 = mat
rownames(mat2) = NULL
colnames(mat2) = NULL
Heatmap(mat2)

Heatmap(mat, row_names_gp = gpar(fontsize = 20))
Heatmap(mat, km = 2)
Heatmap(mat, split = rep(c("A", "B"), 6))
Heatmap(mat, split = data.frame(rep(c("A", "B"), 6), rep(c("C", "D"), each = 6)))
Heatmap(mat, split = data.frame(rep(c("A", "B"), 6), rep(c("C", "D"), each = 6)), 
    combined_name_fun = function(x) paste(x, collapse = ""))

annotation = HeatmapAnnotation(df = data.frame(type = c(rep("A", 6), rep("B", 6))))
Heatmap(mat, top_annotation = annotation)

annotation = HeatmapAnnotation(df = data.frame(type1 = rep(c("A", "B"), 6), 
    type2 = rep(c("C", "D"), each = 6)))
Heatmap(mat, bottom_annotation = annotation)

annotation = data.frame(value = rnorm(10))
annotation = HeatmapAnnotation(df = annotation)
Heatmap(mat, top_annotation = annotation)

annotation = data.frame(value = rnorm(10))
value = 1:10
ha = HeatmapAnnotation(df = annotation, points = anno_points(value), 
    annotation_height = c(1, 2))
Heatmap(mat, top_annotation = ha, top_annotation_height = unit(2, "cm"), 
    bottom_annotation = ha)

# character matrix
mat3 = matrix(sample(letters[1:6], 100, replace = TRUE), 10, 10)
rownames(mat3) = {x = letters[1:10]; x[1] = "aaaaaaaaaaaaaaaaaaaaaaa";x}
Heatmap(mat3, rect_gp = gpar(col = "white"))

mat = matrix(1:9, 3, 3)
rownames(mat) = letters[1:3]
colnames(mat) = letters[1:3]

Heatmap(mat, rect_gp = gpar(col = "white"), 
    cell_fun = function(i, j, x, y, width, height, fill) {
        grid.text(mat[i, j], x = x, y = y)
    },
    cluster_rows = FALSE, cluster_columns = FALSE, row_names_side = "left", 
    column_names_side = "top")

Run the code above in your browser using DataCamp Workspace