Heatmap: Constructor method for Heatmap class

View source: R/Heatmap-class.R

HeatmapR Documentation

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),
    border = NA,
    border_gp = gpar(col = "black"),
    cell_fun = NULL,
    layer_fun = NULL,
    jitter = FALSE,
    
    row_title = character(0),
    row_title_side = c("left", "right"),
    row_title_gp = gpar(fontsize = 13.2),
    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 = 13.2),
    column_title_rot = 0,
    
    cluster_rows = TRUE,
    cluster_row_slices = 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 = is.logical(cluster_rows) || is.function(cluster_rows),
    row_dend_gp = gpar(),
    cluster_columns = TRUE,
    cluster_column_slices = 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 = is.logical(cluster_columns) || is.function(cluster_columns),
    
    row_order = NULL,
    column_order = NULL,
    
    row_labels = rownames(matrix),
    row_names_side = c("right", "left"),
    show_row_names = TRUE,
    row_names_max_width = unit(6, "cm"),
    row_names_gp = gpar(fontsize = 12),
    row_names_rot = 0,
    row_names_centered = FALSE,
    column_labels = colnames(matrix),
    column_names_side = c("bottom", "top"),
    show_column_names = TRUE,
    column_names_max_height = unit(6, "cm"),
    column_names_gp = gpar(fontsize = 12),
    column_names_rot = 90,
    column_names_centered = FALSE,
    
    top_annotation = NULL,
    bottom_annotation = NULL,
    left_annotation = NULL,
    right_annotation = NULL,
    
    km = 1,
    split = NULL,
    row_km = km,
    row_km_repeats = 1,
    row_split = split,
    column_km = 1,
    column_km_repeats = 1,
    column_split = NULL,
    gap = unit(1, "mm"),
    row_gap = unit(1, "mm"),
    column_gap = unit(1, "mm"),
    show_parent_dend_line = ht_opt$show_parent_dend_line,
    
    heatmap_width = unit(1, "npc"),
    width = NULL,
    heatmap_height = unit(1, "npc"),
    height = NULL,
    
    show_heatmap_legend = TRUE,
    heatmap_legend_param = list(title = name),
    
    use_raster = NULL,
    raster_device = c("png", "jpeg", "tiff", "CairoPNG", "CairoJPEG", "CairoTIFF", "agg_png"),
    raster_quality = 1,
    raster_device_param = list(),
    raster_resize_mat = FALSE,
    raster_by_magick = requireNamespace("magick", quietly = TRUE),
    raster_magick_filter = NULL,
    
    post_fun = NULL)

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 can be interpolated. Pass to ColorMapping. For more details and examples, please refer to https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#colors .

name

Name of the heatmap. By default the heatmap 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). The value should be specified by gpar and fill parameter is ignored.

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.

border

Whether draw border. The value can be logical or a string of color.

border_gp

Graphic parameters for the borders. If you want to set different parameters for different heatmap slices, please consider to use decorate_heatmap_body.

cell_fun

Self-defined function to add graphics on each cell. Seven parameters will be passed into this function: j, i, x, y, width, height, fill which are column index, row index in matrix, coordinate of the cell, the width and height of the cell and the filled color. x, y, width and height are all unit objects.

layer_fun

Similar as cell_fun, but is vectorized. Check https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#customize-the-heatmap-body .

jitter

Random shifts added to the matrix. The value can be logical or a single numeric value. It it is TRUE, random values from uniform distribution between 0 and 1e-10 are generated. If it is a numeric value, the range for the uniform distribution is (0, jitter). It is mainly to solve the problem of "Error: node stack overflow" when there are too many identical rows/columns for plotting the dendrograms. ADD: From version 2.5.6, the error of node stack overflow has been fixed, now this argument is ignored.

row_title

Title on the row.

row_title_side

Will the title be put on the left or right of the heatmap?

row_title_gp

Graphic parameters for row title.

row_title_rot

Rotation of row title.

column_title

Title on the column.

column_title_side

Will the title be put on the top or bottom of the heatmap?

column_title_gp

Graphic parameters for column title.

column_title_rot

Rotation of column titles.

cluster_rows

If the value is a logical, it controls whether to make cluster on rows. The value can also be a hclust or a dendrogram which already contains clustering. Check https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#clustering .

cluster_row_slices

If rows are split into slices, whether perform clustering on the slice means?

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 perform hierarchical clustering, pass to hclust.

row_dend_side

Should the row dendrogram be put on the left or right of the heatmap?

row_dend_width

Width of the row dendrogram, should be a unit object.

show_row_dend

Whether show row dendrogram?

row_dend_gp

Graphic parameters for the dendrogram segments. If users already provide a dendrogram object with edges rendered, this argument will be ignored.

row_dend_reorder

Apply reordering on row dendrograms. The value can be a logical value or a vector which contains weight which is used to reorder rows. The reordering is applied by reorder.dendrogram.

cluster_columns

Whether make cluster on columns? Same settings as cluster_rows.

cluster_column_slices

If columns are split into slices, whether perform clustering on the slice means?

clustering_distance_columns

Same setting as clustering_distance_rows.

clustering_method_columns

Method to perform hierarchical clustering, pass to hclust.

column_dend_side

Should the column dendrogram 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 dendrogram?

column_dend_gp

Graphic parameters for dendrogram segments. Same settings as row_dend_gp.

column_dend_reorder

Apply reordering on column dendrograms. Same settings as row_dend_reorder.

row_order

Order of rows. Manually setting row order turns off clustering.

column_order

Order of column.

row_labels

Optional row labels which are put as row names in the heatmap.

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.

row_names_gp

Graphic parameters for row names.

row_names_rot

Rotation of row names.

row_names_centered

Should row names put centered?

column_labels

Optional column labels which are put as column names in the heatmap.

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.

column_names_rot

Rotation of column names.

column_names_centered

Should column names put centered?

top_annotation

A HeatmapAnnotation object.

bottom_annotation

A HeatmapAnnotation object.

left_annotation

It should be specified by rowAnnotation.

right_annotation

it should be specified by rowAnnotation.

km

Apply 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 slice, 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 to split the dendrogram by cutree.

row_km

Same as km.

row_km_repeats

Number of k-means runs to get a consensus k-means clustering. Note if row_km_repeats is set to more than one, the final number of groups might be smaller than row_km, but this might means the original row_km is not a good choice.

row_split

Same as split.

column_km

K-means clustering on columns.

column_km_repeats

Number of k-means runs to get a consensus k-means clustering. Similar as row_km_repeats.

column_split

Split on columns. For heatmap splitting, please refer to https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#heatmap-split .

gap

Gap between row slices if the heatmap is split by rows. The value should be a unit object.

row_gap

Same as gap.

column_gap

Gap between column slices.

show_parent_dend_line

When heatmap is split, whether to add a dashed line to mark parent dendrogram and children dendrograms?

width

Width of the heatmap body.

height

Height of the heatmap body.

heatmap_width

Width of the whole heatmap (including heatmap components)

heatmap_height

Height of the whole heatmap (including heatmap components). Check https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#size-of-the-heatmap .

show_heatmap_legend

Whether show heatmap legend?

heatmap_legend_param

A list contains parameters for the heatmap legends. 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. If number of rows or columns is more than 2000, it is by default turned on. Note if cell_fun is set, use_raster is enforced to be FALSE.

raster_device

Graphic device which is used to generate the raster image.

raster_quality

A value larger than 1.

raster_device_param

A list of further parameters for the selected graphic device. For raster image support, please check https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#heatmap-as-raster-image .

raster_resize_mat

Whether resize the matrix to let the dimension of the matrix the same as the dimension of the raster image? The value can be logical. If it is TRUE, mean is used to summarize the sub matrix which corresponds to a single pixel. The value can also be a summary function, e.g. max.

raster_by_magick

Whether to use image_resize to scale the image.

raster_magick_filter

Pass to filter argument of image_resize. A character scalar and all possible values are in filter_types. The default is "Lanczos".

post_fun

A function which will be executed after the heatmap list is drawn.

Details

The initialization function only applies parameter checking and fill values to the slots with some validation.

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

  • show,Heatmap-method: draw a single heatmap with default parameters

  • draw,Heatmap-method: draw a single heatmap.

  • + or %v% append heatmaps and annotations to a list of heatmaps.

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

Value

A Heatmap-class object.

Author(s)

Zuguang Gu <z.gu@dkfz.de>

See Also

https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html

Examples

# There is no example
NULL


jokergoo/ComplexHeatmap documentation built on Sept. 24, 2024, 4:48 p.m.