%\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%;

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.
- 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.
- New argument `layer_fun` is a vectorized version of `cell_fun`. This functionality is too
  low-level and normally users will not use it.
- New arguments `width`, `heatmap_width`, `height`, `heatmap_height` to control the size of the
- 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()`.
- 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()`.
- 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%`.
- More arguments for the main heatmap can be controlled directly in `draw()`.
- 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.

## 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
- 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)