no_names <- small_mat
colnames(no_names) <- NULL
ggheatmap(no_names) + scale_x_continuous()
#> → heatmap built with `geom_tile()`
10 Difference with ggplot2
ggalign focuses on aligning observations across multiple plots. While it builds on the ggplot2 framework, there are key differences in how scales, facets, and coordinates are handled in alignment axes. This vignette highlights these syntax differences.
The following syntax applies to all align_* functions that add a plot area, and to the main plot in quad_layout() when alignment is needed.
10.1 Axes used for alignment
Axes used for alignment in ggalign refer to: - x-axis in vertical stack layouts
x-axis in horizontal stack layouts
x- and y- axes in the
quad_layout()main plot
ggalign introduces special syntax and handling for these axes, differing from the default behavior in ggplot2. These adjustments ensure that observations are properly aligned and operations are user-friendly.
10.2 Position Scales
To better fit the alignment-based layout, ggalign introduces adjustments to breaks, labels, and expand arguments.
10.2.1 breaks
breaks and labels are typically handled similarly to discrete scales, as we focus on aligning observations (which should be regarded as discrete variables); no matter what you use is continuous scale or discrete scale.
breaks should be one of:
- `NULL` for no breaks
- `waiver()` for the default breaks (the full data index or `NULL` if no
data names and `labels` is `waiver()`)
- A character vector of breaks (rownames / colunames of the matrix).
- A numeric vector of data index (must be an integer).
- A function that takes the data names or the data index as input and
returns breaks as output. Also accepts rlang lambda function notation. Default breaks without names:
No breaks:
ggheatmap(small_mat) + scale_x_continuous(breaks = NULL)
#> → heatmap built with `geom_tile()`
ggheatmap(small_mat, filling = FALSE) +
geom_tile(aes(.discrete_x, .discrete_y, fill = value)) +
scale_x_discrete(breaks = NULL)
Character-based breaks use data names (or indices if names are absent)
ggheatmap(small_mat) +
scale_x_continuous(breaks = c("column3", "column5")) +
anno_top() +
align_dendro(k = 3L)
#> → heatmap built with `geom_tile()`
ggheatmap(small_mat, filling = FALSE) +
geom_tile(aes(.discrete_x, .discrete_y, fill = value)) +
scale_x_discrete(breaks = c("column3", "column5")) +
anno_top() +
align_dendro(k = 3L)
Integer-based breaks are interpreted as data indices:
ggheatmap(small_mat) +
scale_x_continuous(breaks = c(3, 5)) +
anno_top() +
align_dendro(k = 3L)
#> → heatmap built with `geom_tile()`
ggheatmap(small_mat, filling = FALSE) +
geom_tile(aes(.discrete_x, .discrete_y, fill = value)) +
scale_x_discrete(breaks = c(3, 5)) +
anno_top() +
align_dendro(k = 3L)
Floating numbers are invalid for breaks:
ggheatmap(small_mat) + scale_x_continuous(breaks = c(3.5, 5))
#> → heatmap built with `geom_tile()`
#> Error in `scale_x_continuous()`:
#> ! Can't convert from `breaks` <double> to <integer> due to loss of precision.
#> • Locations: 1To interpret integers as plot-specific coordinate indices, wrap them with I():
ggheatmap(small_mat) +
scale_x_continuous(breaks = I(3:4)) +
anno_top() +
align_dendro(k = 3L)
#> → heatmap built with `geom_tile()`
10.2.2 labels
labels should be one of:
- `NULL` for no labels
- `waiver()` for the default labels (data names)
- A character vector giving labels (must be same length as breaks)
- An expression vector (must be the same length as breaks). See `?plotmath`
for details.
- A function that takes the data names (or data index if data has no names)
as input and returns labels as output. This can be also a rlang lambda
function.The default labels are the data names (or indices if names are absent):
ggheatmap(small_mat) + scale_x_continuous() +
anno_top() +
align_dendro(k = 3L)
#> → heatmap built with `geom_tile()`
No labels:
ggheatmap(small_mat) +
scale_x_continuous(labels = NULL) +
anno_top() +
align_dendro(k = 3L)
#> → heatmap built with `geom_tile()`
Character labels will be reordered based on the data’s ordering:
ggheatmap(small_mat) +
scale_x_continuous(labels = letters[seq_len(ncol(small_mat))]) +
anno_top() +
align_dendro(k = 3L)
#> → heatmap built with `geom_tile()`
To retain the original order of character labels, wrap them with I():
ggheatmap(small_mat) +
scale_x_continuous(labels = I(letters[seq_len(ncol(small_mat))])) +
anno_top() +
align_dendro(k = 3L)
#> → heatmap built with `geom_tile()`
By default, labels correspond to breaks:
ggheatmap(small_mat) +
scale_x_continuous(breaks = c(5, 3), labels = c("a", "b"))
#> → heatmap built with `geom_tile()`
To override the default matching, wrap the labels vector with I():
ggheatmap(small_mat) +
scale_x_continuous(breaks = c(5, 3), labels = I(c("a", "b")))
#> → heatmap built with `geom_tile()`
10.2.3 expand
By default, we utilize zero expansion for the aligned axis. This is typically the desired setting. If you wish to introduce expansion, you must manually adjust it and apply it to each plot to ensure proper axis alignment.
ggheatmap(small_mat) +
scale_x_continuous(expand = expansion(mult = 0.1)) +
anno_top() +
align_dendro(aes(color = branch), k = 3L) +
scale_x_continuous(expand = expansion(mult = 0.1))
#> → heatmap built with `geom_tile()`
You can utilize ggh4x::facetted_pos_scales() to set scales for each panel.
10.3 theme
Although ggplot2 does not officially support vectorized input for theme elements, we can still utilize it. ggalign extends this feature, allowing theme elements to be vectorized and applied across panels.
ggheatmap(small_mat) +
theme(
axis.text.x = element_text(
colour = c(rep("red", 4), rep("blue", 5))
),
axis.ticks.x = element_line(
colour = c(rep("red", 4), rep("blue", 5))
),
axis.ticks.length.x = unit(rep(c(1, 4), times = c(4, 5)), "mm")
) +
anno_top() +
align_dendro(aes(color = branch), k = 3L) +
scale_y_continuous(expand = expansion()) &
theme(plot.margin = margin())
#> Warning: Vectorized input to `element_text()` is not officially supported.
#> ℹ Results may be unexpected or may change in future versions of ggplot2.
#> → heatmap built with `geom_tile()`
10.4 Facets
When working with facets, manual configuration of the panel using the facet_*() functions is not possible since the internal structure will use facet_grid() to set the row/column groups defined by align_*() functions. However, you can still use facet_grid() or facet_null() (if no panel) to control other arguments except aligned panels (rows in horizontal stack layout or cols in vertical stack layout, or both rows and cols in heatmap body).
A common use case is to modify the panel strip text. The default theme (theme_ggalign()) will always remove the panel strip text, you can override this behaviour with theme(strip.text = element_text()) to add the panel title in the plot area.
ggheatmap(small_mat) +
facet_grid(labeller = labeller(.column_panel = function(x) letters[as.integer(x)])) +
theme(strip.text = element_text()) +
anno_top() +
align_kmeans(centers = 3L)
#> → heatmap built with `geom_tile()`
10.5 Coords
Currently, only cartesian coordinate can be used to align axis well. Internally, the limits will always be set to the number of observations, with an additional range expansion of 0.5 added on both ends.