1  Introduction

The ggalign package provides an integrative framework for composable visualization, enabling the construction of complex multi-plot layouts—including insets, circular arrangements, and multi-panel compositions. Built on the grammar of graphics, it introduces intuitive tools to align, stack, and nest plots, making it easy to link related views, overlay clustering results, or highlight shared patterns.

Designed for high-dimensional data contexts such as genomics, transcriptomics, and microbiome studies, ggalign simplifies the creation of richly annotated, publication-ready figures from diverse visual components.

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

At the heart of ggalign is an object-oriented Layout system that integrates seamlessly with ggplot2. It provides three core layout types:

  • StackLayout: Stacks plots horizontally or vertically.
  • QuadLayout: Arranges plots in four quadrants (top, left, bottom, right) around a central plot.
  • CircleLayout: Positions plots in a circular pattern.

Each layout supports both discrete (e.g., categories) and continuous (e.g., numerical) data, and includes specialized alignment functions:

For StackLayout:

  • stack_discrete(): Align discrete variable along the stack.
  • stack_continuous(): Align continuous variable along the stack.
  • stack_layout(): A unified interface that handles both discrete and continuous data.

For QuadLayout:

  • quad_continuous()/ggside(): Align continuous variables in both horizontal and vertical directions.
  • quad_discrete(): Align discrete variables in both horizontal and vertical directions.
  • quad_layout(): A general function that adapts to both data types and directions.

For CircleLayout:

  • circle_discrete(): Align discrete variable in the circle.
  • circle_continuous(): Align continuous variable in the circle.
  • circle_layout(): A unified interface for both cases.

Note: Throughout this book, we refer to the main layout functions—stack_layout(), quad_layout(), and circle_layout()—as the primary interfaces, even when using their specialized variants.

General design of ggalign