Legend {ComplexHeatmap} | R Documentation

## Make a Single Legend

### Description

Make a Single Legend

### Usage

    Legend(at, labels = at, col_fun, name = NULL, grob = NULL,
        break_dist = NULL, nrow = NULL, ncol = 1, by_row = FALSE,
        grid_height = unit(4, "mm"),
        grid_width = unit(4, "mm"),
        gap = unit(2, "mm"), column_gap = gap, row_gap = unit(0, "mm"),
        labels_gp = gpar(fontsize = 10), labels_rot = 0,
        border = NULL, background = "#EEEEEE",
        type = "grid", graphics = NULL, legend_gp = gpar(),
        pch = 16, size = unit(2, "mm"),
        legend_height = NULL, legend_width = NULL,
        direction = c("vertical", "horizontal"),
        title = "", title_gp = gpar(fontsize = 10, fontface = "bold"),
        title_position = c("topleft", "topcenter", "leftcenter", "lefttop", "leftcenter-rot", "lefttop-rot"),
        title_gap = unit(2, "mm"))

### Arguments

`at` | Breaks of the legend. The values can be either numeric or character. If it is not specified, the values of `labels` are taken as labels.
`labels` | Labels corresponding to `at`. If it is not specified, the values of `at` are taken as labels.
`col_fun` | A color mapping function which is used to make a continuous legend. Use `colorRamp2` to generate the color mapping function. If `at` is missing, the breaks recorded in the color mapping function are used for `at`.
`name` | Name of the legend, internally used.
`grob` | The legend body can be specified by a pre-constructed `grob` object.
`break_dist` | A zooming factor to control relative distance of two neighbouring break values.The length of it should be `length(at) - 1` or a scalar.
`nrow` | For legend which is represented as grids, `nrow` controls number of rows of the grids if the grids are arranged into multiple rows.
`ncol` | Similar as `nrow`, `ncol` controls number of columns of the grids if the grids are arranged into multiple columns. Note at a same time only one of `nrow` and `ncol` can be specified.
`by_row` | Are the legend grids arranged by rows or by columns?
`grid_height` | The height of legend grid. It can also control the height of the continuous legend if it is horizontal.
`grid_width` | The width of legend grid. It can also control the width of the continuous legend if it is vertical.
`gap` | If legend grids are put into multiple rows or columns, this controls the gap between neighbouring rows or columns, measured as a `unit` object.
`column_gap` | The same as `gap`.
`row_gap` | Space between legend rows.
`labels_gp` | Graphic parameters for labels.
`labels_rot` | Text rotation for labels. It should only be used for horizontal continuous legend.
`border` | Color of legend grid borders. It also works for the ticks in the continuous legend.
`background` | Background colors for the grids. It is used when points and lines are the legend graphics.
`type` | Type of legends. The value can be one of `grid`, `points`, `lines` and `boxplot`.
`graphics` | Self-defined graphics for legends. The value should be a list of functions. Each function should accept four argumets: `x` and `y`: positions of the legend grid (center point), `w` and `h`: width and height of the legend grid.
`legend_gp` | Graphic parameters for the legend grids. You should control the filled color of the legend grids by `gpar(fill = ...)`.
`pch` | Type of points if points are used as legend. Note you can use single-letter as pch, e.g. `pch = 'A'`. There are three additional integers that are valid for `pch`: 26 and 27 for single diagonal lines and 28 for double diagonal lines.
`size` | Size of points.
`legend_height` | Height of the whole legend body. It is only used for vertical continous legend.
`legend_width` | Width of the whole legend body. It is only used for horizontal continous legend.
`direction` | Direction of the legend, vertical or horizontal?
`title` | Title of the legend.
`title_gp` | Graphic parameters of the title.
`title_position` | Position of title relative to the legend. `topleft`, `topcenter`, `leftcenter-rot` and `lefttop-rot` are only for vertical legend and `leftcenter`, `lefttop` are only for horizontal legend.
`title_gap` | Gap between title and the legend body.

### Details

Most of the argument can also be set in `heatmap_legend_param` argument in `Heatmap` or `annotation_legend_param` argument in `HeatmapAnnotation` to configure legend styles for heatmap and annotations.

### Value

A `Legends-class` object.

### See Also

`packLegend` packs multiple legends into one `Legends-class` object.

See examples of configuring legends: https://jokergoo.github.io/ComplexHeatmap-reference/book/legends.html

### Examples

    lgd = Legend(labels = month.name[1:6], title = "foo", legend_gp = gpar(fill = 1:6))
    draw(lgd, test = "add labels and title")

    require(circlize)
    col_fun = colorRamp2(c(0, 0.5, 1), c("blue", "white", "red"))
    lgd = Legend(col_fun = col_fun, title = "foo")
    draw(lgd, test = "only col_fun")

    col_fun = colorRamp2(c(0, 0.5, 1), c("blue", "white", "red"))
    lgd = Legend(col_fun = col_fun, title = "foo", at = c(0, 0.1, 0.15, 0.5, 0.9, 0.95, 1))
    draw(lgd, test = "unequal interval breaks")

[Package ComplexHeatmap version 2.10.0 Index]