1  Introduction

The ggalign package provides a flexible and powerful framework for composable visualization, making it easy to build complex multi-plot layouts—such as insets, multi-panel views, and circular compositions.

Built on top of the grammar of graphics, ggalign introduces intuitive tools to align, stack, and nest plots in a way that preserves relationships between data sources—ideal for visualizing shared patterns, clustering results, or coordinated subplots.

Designed for high-dimensional data common in fields like genomics, transcriptomics, and microbiome research, ggalign helps you create publication-ready figures by composing diverse plots into cohesive, structured layouts.

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 Plot Composition

The ggalign package supports two primary modes of composing plots:

  • Data-Free Composition – for visually arranging independent plots.

  • Data-Aware Composition – for aligning plots based on shared data structure.

Each mode serves different purposes and offers tools tailored for its use case.

1.2.1 Data-Free Composition: Simple Plot Arrangement

Data-free composition represents traditional plot arrangement where independent plots are spatially arranged without data relationships. This paradigm is conceptually aligned with tools like patchwork or cowplot, but ggalign provides finer control over alignment, spacing, and legend management, enabling more precise and expressive layout designs.

1.2.1.1 What Is Data-Free Composition for?

Use data-free composition when you want to:

  • Visually compare results from different models or datasets.

  • Combine summary, diagnostic, and metadata plots in figure panels.

  • Annotate plots with separate diagrams, legends, or auxiliary views.

  • Create layout templates that work across a variety of inputs.

This approach gives you full spatial control while preserving each plot’s independence. Because there’s no need to reconcile axes, or scales, it’s straightforward and versatile for many common multi-plot needs.

1.2.1.2 What Will You Learn?

This part is divided into chapters, each addressing a specific graphical challenge. This is not an exhaustive or exclusive categorization but rather a practical guide to help you navigate common tasks in data-free plot composition.

1.2.2 Data-Aware Composition: Integrated Data Visualization

This part introduces another core feature of the ggalign package: data-aware composition. Unlike data-free composition, which focuses solely on the visual arrangement of plots without considering shared data values, data-aware composition aligns plots based on common data characteristics—such as shared axis scales or categorical factors. This enables precise alignment of related plots where data correspondence matters.

1.2.2.1 When to Use Data-Aware Composition

Choose this mode when the alignment of plots must reflect relationships in the data—for example:

  • Aligning a heatmap with a bar plot showing row-wise summaries.

  • Linking boxplots to clustered groups in an ordination plot.

  • Displaying annotations or tree structures beside data panels

1.2.2.2 What Will You Learn?

This part is divided into sections that will guide you through:

  • Exploring the Layout system and its core types.

  • Understanding key concepts of data-aware composition.

  • Learning how to align plots based on shared data features.

  • Managing discrete and continuous data for alignment.

  • Using grouping, ordering, and clustering to organize observations.

  • Adding supporting visual elements like dendrograms and annotations.