guides
By default, ggheatmap() will collect all guide legends
on the side from which they originate.
heatmap_collect_all_guides <- ggheatmap(small_mat, width = 2, height = 2L) +
scale_fill_viridis_c(name = "I'm from heatmap body") +
theme(axis.text.x = element_text(angle = -60, hjust = 0)) +
anno_top() +
align_dendro(aes(color = branch), k = 3L) +
scale_color_brewer(
name = "I'm from top annotation", palette = "Dark2",
guide = guide_legend(position = "right")
) +
anno_left() +
align_dendro(aes(color = branch), k = 3L) +
scale_color_brewer(
name = "I'm from left annotation", palette = "Dark2",
guide = guide_legend(position = "top", direction = "vertical")
) +
anno_bottom() +
align_dendro(aes(color = branch), k = 3L) +
scale_color_brewer(
name = "I'm from bottom annotation", palette = "Dark2",
guide = guide_legend(position = "left")
) +
anno_right() +
align_dendro(aes(color = branch), k = 3L) +
scale_color_brewer(
name = "I'm from right annotation", palette = "Dark2",
guide = guide_legend(position = "bottom", direction = "vertical")
) &
theme(plot.margin = margin())
heatmap_collect_all_guides
#> → heatmap built with `geom_tile()`
Use the guides argument control which side of guide
legends should be gathered. In the following example, we’ll collect the
guide legends only on the top and bottom
sides:
heatmap_collect_all_guides +
# reset the active context to the heatmap layout
quad_active() -
# we set global `guides` argument for the heatmap layout
# we only collect guides in the top and bottom side
plot_align(guides = "tb")
#> → heatmap built with `geom_tile()`
You can also apply the plot_align() function directly to
specific plots:
heatmap_collect_all_guides +
# reset the active context to the heatmap layout
quad_active() -
# we set global `guides` argument for the heatmap layout
# we only collect guides in the top and bottom side
plot_align(guides = "tb") +
# `+` apply it to the current active plot
# for the heatmap body, we collect guide in the right side
plot_align(guides = "r")
#> → heatmap built with `geom_tile()`
The guide legends within the annotation stack are first collected by
the stack_layout() itself and then passed to the overall
heatmap layout for further integration. By default, it inherits the
guides arguments from the heatmap layout. See following
example:
heatmap_collect_all_guides +
# reset the active context to the heatmap layout
quad_active() -
# we set global `guides` argument for the heatmap layout
# we only collect guides in the top and bottom side
plot_align(guides = "tb") +
# we ensure the active context is in the bottom annotation
# By default, it inherits "guides" argument from the heamtap layout, which
# means it'll collect "guides" in the top and bottom side
anno_bottom() +
# for the dendrogram in the bottom annotation, we collect guide in the left side
plot_align(guides = "l")
#> → heatmap built with `geom_tile()`
Here, the guide legend is collected by the bottom annotation but will
not be collected by the heatmap layout since the heatmap layout only
gathers guides from the top and bottom. In
this way, the guide legends of the annotation stack will be put around
the annotation stack layout.
To override this guide collection behavior for the heatmap
annotation, you can use the free_guides argument of the
quad_anno()/anno_*() function. This differs
from the guides argument in plot_align(),
which controls the behavior for the plots in the layout. The
free_guides argument specifies which guide legends from the
annotation stack layout should be collected by the heatmap layout.
heatmap_collect_all_guides +
# reset the active context to the heatmap layout
quad_active() -
# we set global `guides` argument for the heatmap layout
# we only collect guides in the top and bottom side
plot_align(guides = "tb") +
# we also collect guides in the left side for the bottom annotation stack
# layout in the heatmap layout
anno_bottom(free_guides = "l") +
# for the dendrogram in the bottom annotation, we collect guide in the left side
plot_align(guides = "l")
#> → heatmap built with `geom_tile()`
Note: The heatmap layout will only collect guide legends from the
annotation stack if the stack layout collects its own guides first.
free_spaces
By default, ggheatmap() will align all elements of the
plot, which can sometimes lead to unwanted spacing. Consider the
following example:
ggheatmap(small_mat) +
scale_fill_viridis_c() +
anno_top(size = unit(30, "mm")) +
align_dendro() +
scale_y_continuous(
expand = expansion(),
labels = ~ paste("very very long labels", .x)
) +
anno_left(unit(20, "mm")) +
align_dendro()
#> → heatmap built with `geom_tile()`
In this case, the left annotation stack is positioned far from the
heatmap body due to the wide axis labels in the top annotation stack.
This occurs because the top annotation stack is aligned with the heatmap
body. To fix this, you can remove the left borders around the panel of
the top annotation stack by setting free_spaces = "l".
ggheatmap(small_mat) +
scale_fill_viridis_c() +
anno_top(size = unit(30, "mm")) -
plot_align(free_spaces = "l") +
align_dendro() +
scale_y_continuous(
expand = expansion(),
labels = ~ paste("very long labels", .x)
) +
anno_left(unit(20, "mm")) +
align_dendro()
#> → heatmap built with `geom_tile()`
One useful way to utilize free_spaces is to position the
guide legends next to the annotations. (Note the guide legend from the
bottom annotation):
heatmap_collect_all_guides +
# we only collect guides in the top and bottom side
quad_active() -
plot_align(guides = "tb") +
# 1. in the bottom annotation stack layout, we collect the legends in the
# left side
# 2. we remove the spaces of the left border in the annotation
anno_bottom() -
plot_align(guides = "l", free_spaces = "l")
#> → heatmap built with `geom_tile()`
In ggheatmap()/quad_layout(), the behavior
of the free_spaces and free_labs arguments
differs from guides arguments in plot_align()
when inheriting from the parent layout: - For top and
bottom annotations, it inherits from the left (“l”) and
right (“r”) axes. - For left and right
annotations, it inherits from the top (“t”) and bottom (“b”) axes.
free_labs
By default, we won’t align the axis titles.
ggheatmap(small_mat) +
scale_fill_viridis_c() +
ylab("Heatmap title") +
anno_top(size = unit(30, "mm")) +
align_dendro() +
ylab("Annotation title")
#> → heatmap built with `geom_tile()`
To align axis titles, you can set free_labs = NULL.
Alternatively, A single string containing one or more of axis positions
(“t”, “l”, “b”, “r”) to indicate which axis titles should be free from
alignment.
ggheatmap(small_mat) -
plot_align(free_labs = NULL) +
scale_fill_viridis_c() +
ylab("Heatmap title") +
anno_top(size = unit(30, "mm")) +
align_dendro() +
ylab("Annotation title")
#> → heatmap built with `geom_tile()`
