8 Operators

In ggalign, operators are used to manage and manipulate the plot elements in various layouts. These operators help you build complex visualizations by adding, modifying, or removing elements across multiple plots or annotations in a layout. You may be familiar with the + and & operators, this section will expand on their usage, as well as introduce the subtraction operator (-) and how to apply it in different contexts.

Addition Operator (+): Adds elements to the active plot in the active layout.
Logical AND Operator (&): Applies elements to all plots in the layout.
Subtraction Operator (-): Allows you to add elements or modify them across multiple plots in the layout

Code

library(ggalign)
#> Loading required package: ggplot2
set.seed(123)
small_mat <- matrix(rnorm(56), nrow = 7)
rownames(small_mat) <- paste0("row", seq_len(nrow(small_mat)))
colnames(small_mat) <- paste0("column", seq_len(ncol(small_mat)))

8.1 Addition operator

+: adds elements to the active plot in the active layout.

The + operator is straightforward and should be used as needed.

In stack_layout(), a nested layout will only occur if you pass a quad_layout() into stack_layout() (Chapter 7). If the active context in the stack_layout() is quad_layout(), this quad_layout() is treated as the active layout, and the + operator will add elements to it, following the same principles as in quad_layout(). Otherwise, the stack_layout() itself is treated as the active layout, and the + operator will add elements directly to this plot.

stack_alignh(small_mat) +
    align_dendro() +
    geom_point() +
    ggheatmap() +
    theme(axis.text.x = element_text(angle = -60, hjust = 0)) +
    anno_right() +
    align_dendro()
#> → heatmap built with `geom_tile()`

In quad_layout(), four nested layouts are available for annotations: top, left, bottom, and right. If no active annotation is set, quad_layout() treat itself as the active layout. Since there is only one main plot in the quad_layout(), the main plot is always treated as the active plot in this context. Otherwise, the active annotation is treated as the active layout, and the + operator will add elements to it, following the same principles as in stack_layout().

ggheatmap(small_mat) +
    scale_fill_viridis_c() +
    anno_left(size = 0.2) +
    align_dendro() +
    anno_right(size = 0.2) +
    align_dendro()
#> → heatmap built with `geom_tile()`

8.2 logical AND operator

&: applies elements to all plots in the layout including plots in the nested layout.

The & operator works similarly to patchwork, applying an element across all plots in a layout. Since & has lower precedence than +, it’s generally best to use it at the end of an expression or you should wrap it in parentheses when needed.

# Initialize the heatmap
ggheatmap(small_mat) +
    # initialize the left annotation
    anno_left(size = 0.2) +
    # Add a dendrogram in the left annotation and split the dendrogram into 3 groups
    align_dendro(aes(color = branch), k = 3L) +
    anno_right(size = 0.2) +
    # Add a dendrogram in the right annotation and split the dendrogram into 3 groups
    align_dendro(aes(color = branch), k = 3L) &
    # Set color scale for all plots
    scale_color_brewer(palette = "Dark2")
#> → heatmap built with `geom_tile()`

8.3 Subtraction operator

The - operator is more powerful than the & operator, enabling flexible addition of elements to multiple plots. While its use might initially seem unintuitive, the reason behind this is that - shares the same precedence group as +, which allows it to seamlessly combine with +.

8.3.1 `quad_layout()`

For ggheatmap()/quad_layout(), if the active context is the ggheatmap()/quad_layout() itself (no active annotation), the - operator behaves similarly to &. It applies the specified elements to all plots within the layout.

# Initialize the heatmap
ggheatmap(small_mat) +
    # initialize the left annotation
    anno_left(size = 0.2) +
    align_dendro(aes(color = branch), k = 3L) +
    anno_right(size = 0.2) +
    align_dendro(aes(color = branch), k = 3L) +
    # Remove any active annotation
    quad_active() -
    # Set color scale for all plots, since the active layout is the `ggheatmap()`/`quad_layout()`
    scale_color_brewer(palette = "Dark2")
#> → heatmap built with `geom_tile()`

If the active layout is an annotation stack, the - operator will only add the elements to all plots in the active annotation stack:

ggheatmap(small_mat) +
    # initialize the left annotation
    anno_left(size = 0.2) +
    align_dendro(aes(color = branch), k = 3L) +
    align_dendro(aes(color = branch), k = 3L) -
    # Modify the the color scales of all plots in the left annotation
    scale_color_brewer(palette = "Dark2")
#> → heatmap built with `geom_tile()`

8.3.2 `stack_layout()`

For stack_layout(), if the active layout is the stack_layout() itself, - applies the elements to all plots in the layout except the nested ggheatmap()/quad_layout().

stack_alignv(small_mat) +
    align_dendro() +
    ggtitle("I'm from the parent stack") +
    ggheatmap() +
    # remove any active context
    stack_active() +
    align_dendro() +
    ggtitle("I'm from the parent stack") -
    # Modify the the color scales of all plots in the stack layout except the heatmap layout
    scale_color_brewer(palette = "Dark2") -
    # set the background of all plots in the stack layout except the heatmap layout
    theme(plot.background = element_rect(fill = "red"))
#> → heatmap built with `geom_tile()`

When the active layout is the nested ggheatmap()/quad_layout(), the - operator applies the elements to this nested layout, following the same principles as in the Section 8.3.1.

Want apply elements for plots in both stack_layout() and the nested ggheatmap()/quad_layout() at the same time? refer to the following section.

8.4 `with_quad()`

The with_quad() function adjusts the context in which elements are applied in ggheatmap()/quad_layout(). It allows you to control how objects such as themes, scales, and other plot modifications are applied to specific annotation stacks or the main plot, without changing the currently active context.

This function accepts three arguments:

x: An object which can be added to the plot.
position: A string containing one or more of "t", "l", "b", and "r" specifies the context for applying x.
main: A single boolean value indicates whether x should also apply to the main plot within ggheatmap()/quad_layout(). Only used when position is not NULL.

8.4.1 `quad_layout()`

Default Behavior by wrapping object with with_quad():

When ggheatmap()/quad_layout() has no active annotation stack, objects added via + or - operate normally without with_quad().
When the active annotation stack is set, with_quad() ensures the applied object also modifies:
- The main plot (by default).
- Opposite annotation stacks when using -.

By wrapping object with with_quad(), the + operator will apply the object not only to the active plot in the annotation stack, but also to the main plot unless specified by main argument otherwise.

ggheatmap(small_mat) +
    # initialize the left annotation
    anno_left(size = 0.2) +
    align_dendro() +
    # apply the object not only to the active plot in the annotation stack, but
    # also to the main plot
    with_quad(theme(plot.background = element_rect(fill = "red")))
#> → heatmap built with `geom_tile()`

By wrapping object with with_quad(), the - operator will apply the object not only to that annotation stack but also to the opposite one (i.e., bottom if top is active, and vice versa). In these cases, the object will also be applied to the main plot by default unless specified by main argument otherwise.

ggheatmap(small_mat) +
    # initialize the left annotation
    anno_left(size = 0.2) +
    align_dendro(aes(color = branch), k = 3L) +
    # Change the active layout to the left annotation
    anno_top(size = 0.2) +
    align_dendro(aes(color = branch), k = 3L) +
    anno_bottom(size = 0.2) +
    align_dendro(aes(color = branch), k = 3L) -
    # Modify the theme of all plots in the bottom and the opposite annotation
    # in this way, the `main` argument by default would be `TRUE`
    with_quad(theme(plot.background = element_rect(fill = "red")))
#> → heatmap built with `geom_tile()`

The position argument can be a string containing one or more of "t", "l", "b", and "r", indicating which annotation stack should be used as the context. When the position argument is manually set, the default value of the main argument will be FALSE.

ggheatmap(small_mat) +
    # initialize the left annotation
    anno_left(size = 0.2) +
    align_dendro(aes(color = branch), k = 3L) +
    # initialize the top annotation
    anno_top(size = 0.2) +
    align_dendro(aes(color = branch), k = 3L) +
    # initialize the bottom annotation
    anno_bottom(size = 0.2) +
    align_dendro(aes(color = branch), k = 3L) -
    # Modify the background of all plots in the left and top annotation
    with_quad(theme(plot.background = element_rect(fill = "red")), "tl")
#> → heatmap built with `geom_tile()`

Setting position to NULL change the context to the ggheatmap()/quad_layout() itself.

ggheatmap(small_mat) +
    # initialize the left annotation
    anno_left(size = 0.2) +
    align_dendro() +
    # we apply the theme to the main plot only
    with_quad(theme(plot.background = element_rect(fill = "red")), NULL)
#> → heatmap built with `geom_tile()`

ggheatmap(small_mat) +
    # initialize the left annotation
    anno_left(size = 0.2) +
    align_dendro(aes(color = branch), k = 3L) +
    # initialize the top annotation
    anno_top(size = 0.2) +
    align_dendro(aes(color = branch), k = 3L) +
    # initialize the bottom annotation
    anno_bottom(size = 0.2) +
    align_dendro(aes(color = branch), k = 3L) -
    # Modify the background of all plots
    with_quad(theme(plot.background = element_rect(fill = "red")), NULL)
#> → heatmap built with `geom_tile()`

8.4.2 `stack_layout()`

When the active layout is the stack_layout() itself, by default, by wrapping object with with_quad(), - operator will apply changes to all plots along the stack_layout(), which means if the stack layout is in horizontal, - operator will also add the element to the left and right annotation, if the stack layout is in vertical, - operator will also add element to the top and bottom annotation. In these cases, the object will also be applied to the main plot by default unless specified by main argument otherwise.

stack_alignv(small_mat) +
    align_dendro() +
    ggtitle("I'm from the parent stack") +
    ggheatmap() +
    anno_top() +
    align_dendro() +
    ggtitle("I'm from the nested heatmap") +
    # remove any active context
    stack_active() +
    align_dendro() +
    ggtitle("I'm from the parent stack") -
    # Modify the the color scales of all plots in the stack layout except the heatmap layout
    scale_color_brewer(palette = "Dark2") -
    # set the background of all plots in the stack layout (including plots in the heatmap layout)
    with_quad(theme(plot.background = element_rect(fill = "red")))
#> → heatmap built with `geom_tile()`

+ operator won’t do anything special when the active layout is the stack_layout() itself.

When the active layout is the nested ggheatmap()/quad_layout(), the +/- operator applies the elements to this nested layout, following the same principles as for ggheatmap()/quad_layout().

8.1 Addition operator

8.2 logical AND operator

8.3 Subtraction operator

8.3.1 quad_layout()

8.3.2 stack_layout()

8.4 with_quad()

8.4.1 quad_layout()

8.4.2 stack_layout()

8.3.1 `quad_layout()`

8.3.2 `stack_layout()`

8.4 `with_quad()`

8.4.1 `quad_layout()`

8.4.2 `stack_layout()`