1  Introduction

ggalign extends ggplot2 by providing advanced tools for aligning and organizing multiple plots, particularly those that automatically reorder observations, such as dendrogram. It offers fine control over layout adjustment and plot annotations, enabling you to create complex visualizations while leveraging the familiar grammar of ggplot2.

1.1 Installation

You can install ggalign from CRAN using:

install.packages("ggalign")

Alternatively, install the development version from r-universe with:

install.packages("ggalign",
    repos = c("https://yunuuuu.r-universe.dev", "https://cloud.r-project.org")
)

or from GitHub with:

# install.packages("remotes")
remotes::install_github("Yunuuuu/ggalign")

1.2 General design

The core feature of ggalign lies in its integration of the grammar of graphics into advanced visualization through its object-oriented Layout system. The package provides two main Layout classes:

  • the StackLayout class: Put plots horizontally or vertically.
  • the QuadLayout class: Arranges plots in the four quadrants (top, left, bottom, right) around a main plot. This layout is ideal for designs that require supplementary plots or annotations surrounding a central figure.

Both Layout classes support the alignment of observations (ordinal variable). Observations refer to data points or samples, allowing for consistent alignment of corresponding data across multiple plots when using the same axis values. Depending on whether you want to align observations across multiple plots within the layout, the following variants are available:

For StackLayout:

  • stack_align(): Align the observations along the stack.
  • stack_free(): Does not align the observations.

For QuadLayout:

  • quad_free/ggside: Never align observations.
  • quad_alignh: Align observations in the horizontal direction.
  • quad_alignv: Align observations in the vertical direction.
  • quad_alignb: Align observations in both horizontal and vertical directions.

General design of ggalign

1.3 Getting Started

library(ggalign)
#> Loading required package: ggplot2

The usage of ggalign is simple if you’re familiar with ggplot2 syntax, the typical workflow includes:

  1. Initialize the layout using:
  • stack_layout(): Arrange Plots Horizontally or Vertically
    • cross_align: Arrange Plots Crosswise Horizontally or Vertically
  • quad_layout(): Arrange Plots in the Quad-Side of a main plot
    • ggheatmap(): Create a Complex Heatmap.
    • ggoncoplot(): Create OncoPrint Visualizations from Genetic Alteration Data
  1. Customize the layout with:
  • align_group(): Group observations into panel with a group variable.
  • align_kmeans(): Group observations into panel by kmeans.
  • align_order(): Reorder layout observations based on statistical weights or by manually specifying the observation index.
  • align_hclust(): Reorder or group observations based on hierarchical clustering.
  • align_reorder: Reorder observations using an arbitrary statistical function.
  1. Adding plots with
  • ggfree(): Initialize a ggplot object without aligning the observations.
  • ggalign(): Initialize a ggplot object and align the observations.
  • align_dendro(): Add a dendrogram to the plot, and reorder or group observations based on hierarchical clustering.
  • align_line()/align_range(): Add a plot to annotate selected observations.
  • ggcross(): Initialize a ggplot object to connect two different layout crosswise.
  1. Layer additional ggplot2 elements such as geoms, stats, or scales.
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)))

Every *_layout() function accepts default data, which will be inherited by all plots within the layout.

Here’s a simple example:

stack_alignv(small_mat) +
    align_dendro() +
    theme(axis.text.y = element_text())
1
We initialize a vertical stack.
2
Reorder the observations based on hierarchical clustering and add a dendrogram tree.
3
Add y-axis text.

This produces a simple dendrogram. By default, stack_alignv() removes the axis text on the axis used for aligning observations. This is because it’s often unclear which plot should display the axis text, as typically, we want it to appear in only one plot. However, you can easily use the theme() function to control where the axis text appears.

Internally, align_dendro() will reorder the observations based on the dendrogram, and other plots in the layout will follow this ordering.

stack_alignv(small_mat) +
    align_dendro() +
    ggalign(data = rowSums) +
    geom_bar(aes(.discrete_x, value), stat = "identity") +
    theme(axis.text.y = element_text())
1
We initialize a vertical stack.
2
Reorder the observations based on hierarchical clustering and add a dendrogram tree.
3
Create a new ggplot in the layout, and use data based on the sum of the layout data.
4
Add a bar layer.
5
Add y-axis text.

The data in the underlying ggplot object of ggalign() function contains at least following columns (more details will be introduced in the Section 5.1):

  • .panel: the group panel for the aligned axis. It means x-axis for vertical stack layout, y-axis for horizontal stack layout.
  • .x/y and .discrete_x/.discrete_y: an integer index of x/y coordinates and a factor of the data labels (only applicable when names exists).
  • .names and .index: A character names (only applicable when names exists) and an integer of index of the original data.
  • value: the actual value (only applicable if data is a matrix or atomic vector).

It is recommended to use .x/.y, or .discrete_x/.discrete_y as the x/y mapping.

align_dendro() can also split the observations into groups.

stack_alignv(small_mat) +
    align_dendro(k = 3) +
    ggalign(data = rowSums) +
    geom_bar(aes(.discrete_x, value, fill = .panel), stat = "identity") +
    scale_fill_brewer(palette = "Dark2", name = "Group") +
    theme(axis.text.y = element_text())
1
We initialize a vertical stack.
2
Reorder and group the observations based on hierarchical clustering, and add a dendrogram tree.
3
Create a new ggplot in the layout, and use data based on the sum of the layout data.
4
Add a bar layer.
5
Add fill mapping scale.
6
Add y-axis text.

One common visualization associated with the dendrogram is the heatmap. You can use ggheatmap() to initialize a heatmap layout. When grouping the observations using align_dendro(k = 3), a special column named branch is added, which you can use to color the dendrogram tree.

ggheatmap(small_mat) +
    anno_left() +
    align_dendro(aes(color = branch), k = 3) +
    scale_fill_brewer(palette = "Dark2")
#> → heatmap built with `geom_tile()`
1
We initialize a heatmap layout.
2
we initialize an annotation in the left side of the heatmap body, and set it as the active context, in this way, all following addition will be directed to the left annotation.
3
Reorder and group the observations based on hierarchical clustering, and add a dendrogram tree, coloring the tree by branch.
4
Add fill mapping scale.

ggheatmap() will automatically add axis text in the heatmap body, so you don’t need to manually adjust axis text visibility using theme(axis.text.x = element_text())/theme(axis.text.y = element_text()).

Having explored the core principles of ggalign, you should now be familiar with its basic workflow. In the next chapter, we’ll introduce the StackLayout functionality, a powerful tool for arranging multiple plots in a stacked fashion—either horizontally or vertically—while maintaining full control over their alignment. We’ll explore how stack_layout() and its various functions can give you even greater flexibility in creating sophisticated layouts.