SingleAnnotation: Constructor Method for SingleAnnotation Class

In jokergoo/ComplexHeatmap: Make Complex Heatmaps

Constructor Method for SingleAnnotation Class

Description

Constructor Method for SingleAnnotation Class

Usage

SingleAnnotation(name, value, col, fun,
    label = NULL,
    na_col = "grey",
    which = c("column", "row"),
    show_legend = TRUE,
    gp = gpar(col = NA),
    border = FALSE,
    legend_param = list(),
    show_name = TRUE,
    name_gp = gpar(fontsize = 12),
    name_offset = NULL,
    name_side = ifelse(which == "column", "right", "bottom"),
    name_rot = NULL,
    simple_anno_size = ht_opt$simple_anno_size,
    width = NULL, height = NULL)

Arguments

name	Name for the annotation. If it is not specified, an internal name is assigned.
value	A vector or a matrix of discrete or continuous values.
col	Colors corresponding to value. If the mapping is discrete, the value of col should be a named vector; If the mapping is continuous, the value of col should be a color mapping function.
fun	A user-defined function to add annotation graphics. The argument of this function should be at least a vector of index that corresponds to rows or columns. Normally the function should be constructed by AnnotationFunction if you want the annotation supports splitting. See **Details** for more explanation.
label	Label for the annotation. By default is the annotation name.
na_col	Color for NA values in the simple annotations.
which	Whether the annotation is a row annotation or a column annotation?
show_legend	If it is a simple annotation, whether show legend in the final heatmap?
gp	Since simple annotation is represented as rows of grids. This argument controls graphic parameters for the simple annotation. The fill parameter is ignored here.
border	border, only work for simple annotation
legend_param	Parameters for the legend. See color_mapping_legend,ColorMapping-method for all possible options.
show_name	Whether show annotation name?
name_gp	Graphic parameters for annotation name.
name_offset	Offset to the annotation, a unit object.
name_side	'right' and 'left' for column annotations and 'top' and 'bottom' for row annotations
name_rot	Rotation of the annotation name.
simple_anno_size	size of the simple annotation.
width	The width of the plotting region (the viewport) that the annotation is drawn. If it is a row annotation, the width must be an absolute unit.
height	The height of the plotting region (the viewport) that the annotation is drawn. If it is a column annotation, the width must be an absolute unit.

Details

A single annotation is a basic unit of complex heatmap annotations where the heamtap annotations are always a list of single annotations. An annotation can be simply heatmap-like (here we call it simple annotation) or more complex like points, lines, boxes (for which we call it complex annotation).

In the SingleAnnotation constructor, value, col, na_col are used to construct a anno_simple annotation funciton which is generated internally by AnnotationFunction. The legend of the simple annotation can be automatcally generated,

For construcing a complex annotation, users need to use fun which is a user-defind function. Normally it is constucted by AnnotationFunction. One big advantage for using AnnotationFunction is the annotation function or the graphics drawn by the annotation function can be split according to row splitting or column splitting of the heatmap. Users can also provide a "pure" function which is a normal R function for the fun argument. The function only needs one argument which is a vector of index for rows or columns depending whether it is a row annotation or column annotation. The other two optional arguments are the current slice index and total number of slices. See **Examples** section for an example. If it is a normal R function, it will be constructed into the AnnotationFunction-class object internally.

The SingleAnnotation-class is a simple wrapper on top of AnnotationFunction-class only with annotation name added.

The class also stored the "extended area" relative to the area for the annotation graphics. The extended areas are those created by annotation names and axes.

Value

A SingleAnnotation-class object.

Author(s)

Zuguang Gu <[e-mail]>

See Also

There are following built-in annotation functions that can be directly used to generate complex annotations: anno_simple, anno_points, anno_lines, anno_barplot, anno_histogram, anno_boxplot, anno_density, anno_text, anno_joyplot, anno_horizon, anno_image, anno_block, anno_summary and anno_mark.

Examples

ha = SingleAnnotation(value = 1:10)
draw(ha, test = "single column annotation")

m = cbind(1:10, 10:1)
colnames(m) = c("a", "b")
ha = SingleAnnotation(value = m)
draw(ha, test = "matrix as column annotation")

anno = anno_barplot(matrix(nc = 2, c(1:10, 10:1)))
ha = SingleAnnotation(fun = anno)
draw(ha, test = "anno_barplot as input")

fun = local({
    # because there variables outside the function for use, we put it a local environment
    value = 1:10
    function(index, k = 1, n = 1) {
        pushViewport(viewport(xscale = c(0.5, length(index) + 0.5), yscale = range(value)))
        grid.points(seq_along(index), value[index])
        grid.rect()
        if(k == 1) grid.yaxis()
        popViewport()
    }
})
ha = SingleAnnotation(fun = fun, height = unit(4, "cm"))
draw(ha, index = 1:10, test = "self-defined function")

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