color_mapping_legend-ColorMapping-method {ComplexHeatmap} | R Documentation

## Draw legend based on color mapping

### Description

Draw legend based on color mapping

### Usage

    ## S4 method for signature 'ColorMapping'
    color_mapping_legend(object, ...,
        plot = TRUE,
        title = object@name,
        title_gp = gpar(fontsize = 10, fontface = "bold"),
        title_position = c("topleft", "topcenter", "leftcenter", "lefttop"),
        color_bar = object@type,
        grid_height = unit(4, "mm"),
        grid_width = unit(4, "mm"),
        border = NULL,
        at = object@levels,
        labels = at,
        labels_gp = gpar(fontsize = 10),
        nrow = NULL,
        ncol = 1,
        by_row = FALSE,
        legend_height = NULL, legend_width = NULL,
        legend_direction = c("vertical", "horizontal"),
        param = NULL)

### Arguments

`object` | a `ColorMapping-class` object.
`plot` | whether to plot or just return the size of the legend viewport.
`title` | title of the legend, by default it is the name of the legend
`title_gp` | graphical parameters for legend title
`title_position` | position of the title
`color_bar` | a string of "continous" or "discrete". If the mapping is continuous, whether show the legend as discrete color bar or continuous color bar
`grid_height` | height of each legend grid.
`grid_width` | width of each legend grid.
`border` | color for legend grid borders.
`at` | break values of the legend
`labels` | labels corresponding to break values
`labels_gp` | graphcial parameters for legend labels
`nrow` | if there are too many legend grids, they can be put as an array, this controls number of rows
`ncol` | if there are too many legend grids, they can be put as an array, this controls number of columns
`by_row` | when there are multiple columns for legends, whether to arrange them by rows.
`legend_height` | height of the legend, only works when `color_bar` is `continuous` and `direction` is `vertical`
`legend_width` | width of the legend, only works when `color_bar` is `continuous` and `direction` is `horizontal`
`legend_direction` | when `color_bar` is `continuous`, should the legend be vertical or horizontal? When `color_bar` is `discrete`, should the items in the legend proceed vertically or horizontally?
`param` | will be parsed if the parameters are specified as a list
`...` | pass to `viewport`.

### Details

A viewport is created which contains a legend title, legend grids and corresponding labels.

This function will be improved in the future to support more types of legends.

### Value

A `grob` object which contains the legend

### Author(s)

Zuguang Gu <z.gu@dkfz.de>

### Examples

    # discrete color mapping for characters
    cm = ColorMapping(name = "test",
        colors = c("blue", "white", "red"),
        levels = c("a", "b", "c"))
    grid.newpage()
    color_mapping_legend(cm)

    # discrete color mapping for numeric values
    cm = ColorMapping(name = "test",
        colors = c("blue", "white", "red"),
        levels = c(1, 2, 3))
    grid.newpage()
    color_mapping_legend(cm)

    # continuous color mapping
    require(circlize)
    cm = ColorMapping(name = "test",
        col_fun = colorRamp2(c(0, 0.5, 1), c("blue", "white", "red")))
    grid.newpage()
    color_mapping_legend(cm, title_gp = gpar(fontsize = 16))

[Package ComplexHeatmap version 1.20.0 Index]