ggalign

This package 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, publication-quality visualizations while still using the familiar grammar of ggplot2.

Why use ggalign?

ggalign focuses on aligning observations across multiple plots. It leverages the "number of observations" in the vctrs package or NROW() function to maintain consistency in plot organization.

If you’ve ever struggled with aligning plots with self-contained ordering (like dendrogram), or applying consistent grouping or ordering across multiple plots (e.g., with k-means clustering), ggalign is designed to make this easier. The package integrates seamlessly with ggplot2, providing the flexibility to use its geoms, scales, and other components for complex visualizations.

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

Learning ggalign

1. The complete tutorial is available at: https://yunuuuu.github.io/ggalign-book/

2. For the full reference documentation, visit: https://yunuuuu.github.io/ggalign/

Compare with other similar tools

		ggalign	marsilea	ComplexHeatmap	ggtree+aplot
Language		R	Python	R	R
User Interface		Declarative	Declarative	Functional	Declarative
Plot System		ggplot2 (Advanced plot system built on grid system)	Matplotlib	grid	ggplot2 (Advanced plot system built on grid system)
Focus		Composable Visualization	Composable Visualization	Heatmap	tree Data
StackLayout		✅	✅	✅	✅
QuadLayout		✅	✅	Heatmap Only (discrete variables)	Cannot arrange multiple QuadLayouts
CircleLayout		Arc with angle >= 90	❌	❌	✅
CrossLayout		✅	❌	❌	❌
Alignment	One-to-One	✅	✅	✅	✅
	One-to-Many	✅	❌	❌	❌
	Many-to-One	✅	❌	❌	❌
	Cross	✅	❌	❌	❌
Ease of Use		Easy for ggplot2 users	Easy for python user	Easy for for grid user	Easy for ggplot2 users
Fully Compatible with ggplot2		✅	❌	❌	Limited Geometric layers support in CircleLayout

---

Specification	ggalign	marsilea	ComplexHeatmap	ggtree+aplot
Data input	Various, and can be easily extended	fixed	fixed	Various, and can be easily extended
Plot Type	Wide variety, provided by ggplot2	Many, but limited	Many, but limited	Limited Geometric layers support in CircleLayout
Reorder observations	✅	✅	Heatmap Only (Cannot be used in Stack Layout)	✅
Group observations into different panels	✅	✅	Heatmap Only (Cannot be used in Stack Layout)	❌
Clustering algorithm	Kmeans,Hierarchical Clustering and arbitary algorithm	❌	Kmeans,Hierarchical Clustering, but can provide clustering group directly	❌
Legends Creation	Automatic	Manual	Limited automatic, requires manual add	Automatic
Legends Position	Anywhere, can be controlled for a single plot	?	Four sides, can only be placed on one side at a time	Anywhere
Scientific Color Palettes	Many	Limited	Limited	Many
Dendrogram	Tree from Both hclust or ape	hclust only	hclust only (Cannot be used in StackLayout)	Tree from Both hclust or ape
Tanglegram	✅	❌	❌	❌
3D Heatmap	✅	❌	✅	❌
Oncoplot	✅	✅	✅	❌
UpSet plot	✅	✅	✅	❌

Acknowledgements

I would like to express my sincere gratitude to the contributors of the ggplot2 project for providing a powerful and flexible framework for data visualization in R. Their work laid the foundation for the functionality and design of this package. I would also like to thank the patchwork project, from which the core coding for the plot composer was adapted. The patchwork library provided a useful mechanism for combining and aligning plots, which was modified to suit the needs of this package. Without the contributions of these open-source projects, this package would not have been possible.

Additionally, I would like to extend my heartfelt thanks to @teunbrand, who has fulfilled my numerous feature requests, and assisted with the integration of new functions into ggplot2.