<!--
%\VignetteEngine{knitr}
%\VignetteIndexEntry{Difference to older versions}
-->
Difference to Older Versions of ComplexHeatmap Package
=================================================
**Author**: Zuguang Gu ( z.gu@dkfz.de )
**Date**: `r Sys.Date()`
**Package version**: `r installed.packages()["ComplexHeatmap", "Version"]`
---------------------------------------
<style type="text/css">
h1, h2, h3, h4, h5 {
line-height: 120%;
}
</style>
From version 1.99.0 of **ComplexHeatmap**, there are big changes to the older versions. The major
functionalities are still the same, but it is not 100% compatible. This vignette lists the
changes between the new and old versions.
## Heatmap() function
- New arguments `column_km` and `column_split` to split heatmap by columns. The old `km` and `split`
are renamed to `row_km` and `row_split`, although `km` and `split` are still usable.
- A new argument `border` controls the border of the heatmap body. If heatmap is split into slices,
all the slices will have borders.
- Row title and column title allow background color by e.g. `column_title_gp = gpar(fill = ...)`.
- `cluster_rows` and `cluster_columns` also allow objects which can be converted to `dendrogram`.
- If `cluster_rows` and `cluster_columns` are provided as clustering object, dendrogram reordering
is turned off by default.
- Add examples of how to integrate seriation.
(https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#heatmap-seriation)
- Row names and column names allow rotation by `row_names_rot` and `column_names_rot`.
- New arguments `row_labels` and `column_labels` which can be set to replace row names and column
names on the heatmap.
- When heatmap is split and clustering is performed, there is a parent dendrogram which is
calculated from mean values in slices and put on top of the children dendrograms. There is a dashed
line showing the part of the parent dendrogram and emphasizing the dendrogram is combined from
several dendrograms.
- Remove `combined_name_fun` argument and control the titles for the heatmap slices directly by
`row_title` and `column_title`. The two arguments support a string template which is convinient to
control the title for each slice.
(https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#titles-for-splitting)
- New argument `layer_fun` is a vectorized version of `cell_fun`. This functionality is too
low-level and normally users will not use it.
(https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#customize-the-heatmap-body)
- New arguments `width`, `heatmap_width`, `height`, `heatmap_height` to control the size of the
heatmap.
(https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#size-of-the-heatmap)
- New arguments `left_annotation` and `right_annotation`, which means row annotations can be components
of the heatmap, just like column annotations.
- Remove `top_annotation_height` and `bottom_annotation_height`. The height of annotations should be
set in `HeatmapAnnotation()` function now.
## HeatmapAnnotation() function
- All annotations have default width/height now. E.g. the column simple annotation has height of 5mm
and the column barplot annotation has height of 1cm.
- Provide more annotation functions: `anno_empty()`, `anno_simple`, `anno_image()`, `anno_block()`,
`anno_lines()`, `anno_joyplot()`, `anno_horizon()`, `anno_summary()`, `anno_zoom()`.
(https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html)
- The size of the annotations are better to be set in the annotation functions, e.g.
`anno_points(..., height = )`, but you can still set `annotation_height`.
- The axis for the annotations (e.g. `anno_points()`, ...) can be controlled by the `axis_param`
argument in the annotation function.
- `anno_link()` is now renamed to `anno_mark()`. This annotation has default width and no need to
manually calcualte.
- `anno_text()`: the size of the annotation is automatically calculated.
- By default, the annotation names and axes are drawn and the space for them are also taken into
account for the layout of the final heatmap.
- Two `HeatmapAnnotation` objects can be added as a single `HeatmapAnnotation` object by `c()`.
(https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html#heatmap-annotation-utility-function)
- No need to use `row_anno_*()` functions, now `anno_*()` functions can automatically check whether
they are in column annotations or row annotations.
## A list of heatmaps
- Heatmaps and annotations can be concatenated vertically by `%v%`.
(https://jokergoo.github.io/ComplexHeatmap-reference/book/a-list-of-heatmaps.html#vertical-concatenation)
- More arguments for the main heatmap can be controlled directly in `draw()`.
(https://jokergoo.github.io/ComplexHeatmap-reference/book/a-list-of-heatmaps.html#control-main-heatmap-in-draw-function)
- Global options can be temporarily set in `draw()`. (https://jokergoo.github.io/ComplexHeatmap-reference/book/a-list-of-heatmaps.html#change-parameters-globally, the last paragraph.)
- Annotations and column names are nicely adjusted.
(https://jokergoo.github.io/ComplexHeatmap-reference/book/a-list-of-heatmaps.html#annotations-as-components-are-adjusted)
## Legends
- Legends are re-implemented as a `gTree` object internally. `Legend()` and `packLegend()` all
returns a `Legends` object. This object can be treated as a single graphic element and can be drawn by
specifying the positions on the viewport. (https://jokergoo.github.io/ComplexHeatmap-reference/book/legends.html)
- Positions of legend labels are automatically adjusted if they overlap.
- A list of legends are automatically wrapped into multiple columns or rows if they are too long and
exceed the plotting region.
## oncoPrint() function
- It automatially tests whether functions in `alter_fun` are vectorized.
- The oncoPrint barplot annotations are now controlled by `anno_oncoprint_barplot()` and they are
basically normal heatmap annotations. Also axis is controlled in `anno_oncoprint_barplot()`.
- `barplot_ignore` is removed and the subset of alterations in directly controlled in
`anno_oncoprint_barplot()`.
- Similar as `Heatmap()`, all the argument related to the size of annotations are removed and they
should be set directly in `HeatmapAnnotation()` or `anno_oncoprint_barplot()`.
- New arguments `remove_empty_rows` and `remove_empty_columns`. If the number of rows and columns
gets smaller, all the oncoPrint components (e.g. row names, annotations) will be adjusted as well.
- `oncoPrint()` now returns a `Heatmap` object which can be concatenated to other
heatmaps/annotations horizontally or vertically.
## densityHeatmap() function
- Columns can be clustered by the Kolmogorov-Smirnov distance between distributions.
- `densityHeatmap()` returns a vertical heatmap that more heatmaps and annotations can concatenate
to it vertically.
## UpSet() function
- Add a new `UpSet()` function to make UpSet plots and can be concatenated to other heatmaps/annotations. (https://jokergoo.github.io/ComplexHeatmap-reference/book/upset-plot.html)
