Title: Decorate a 'ggplot' with Associated Information
Version: 0.2.8
Description: For many times, we are not just aligning plots as what 'cowplot' and 'patchwork' did. Users would like to align associated information that requires axes to be exactly matched in subplots, e.g. hierarchical clustering with a heatmap. Inspired by the 'Method 2' in 'ggtree' (G Yu (2018) <doi:10.1093/molbev/msy194>), 'aplot' provides utilities to aligns associated subplots to a main plot at different sides (left, right, top and bottom) with axes exactly matched.
Depends: R (≥ 4.1.0)
Imports: ggfun (≥ 0.1.3), ggplot2, ggplotify, patchwork, magrittr, methods, utils, yulab.utils (≥ 0.1.9), pillar
Suggests: ggtree
URL: https://github.com/YuLab-SMU/aplot, https://yulab-smu.top/aplot/
License: Artistic-2.0
Encoding: UTF-8
RoxygenNote: 7.3.2
NeedsCompilation: no
Packaged: 2025-07-02 04:14:36 UTC; HUAWEI
Author: Guangchuang Yu ORCID iD [aut, cre], Shuangbin Xu ORCID iD [ctb], Thomas Hackl [ctb]
Maintainer: Guangchuang Yu <guangchuangyu@gmail.com>
Repository: CRAN
Date/Publication: 2025-07-02 04:50:10 UTC

aplot: Decorate a 'ggplot' with Associated Information

Description

For many times, we are not just aligning plots as what 'cowplot' and 'patchwork' did. Users would like to align associated information that requires axes to be exactly matched in subplots, e.g. hierarchical clustering with a heatmap. Inspired by the 'Method 2' in 'ggtree' (G Yu (2018) doi:10.1093/molbev/msy194), 'aplot' provides utilities to aligns associated subplots to a main plot at different sides (left, right, top and bottom) with axes exactly matched.

Author(s)

Maintainer: Guangchuang Yu guangchuangyu@gmail.com (ORCID)

Other contributors:

See Also

Useful links:

as.patchwork

Description

as.patchwork

Usage

as.patchwork(x, align = getOption("aplot_align", default = "xy"))

Arguments

x

object

align

"x","y","xy","none", align the axis of x/y or not.

construct a 'gglist' object

Description

constructure a 'gglist' object that contains a list of plots ('gglist') and parameters (via '...'), the object can be displayed via the 'plot_list()' function.

Usage

gglist(gglist, ...)

Arguments

gglist

a list of plots

...

parameters for plotting the 'gglist'

Value

gglist object

Author(s)

Guangchuang Yu

This function converts 'gglist' object to grob (i.e. gtable object)

Description

title gglistGrob

Usage

gglistGrob(x)

Arguments

x

A 'gglist' object

Value

A 'gtable' object

plot-insertion

Description

insert an associated plot to left, right, top and bottom of a main plot

Usage

insert_left(.data, plot, width = 1)

insert_right(.data, plot, width = 1)

insert_top(.data, plot, height = 1)

insert_bottom(.data, plot, height = 1)

Arguments

.data

an 'aplot' or 'gg' object

plot

a 'gg' plot to be inserted

width

relative width to the main plot

height

relative height to the main plot

Details

The first input serve as a main plot, and other plots can be progressively inserted to different sides on left, right, top and bottom.

Value

an 'aplot' object

Author(s)

Guangchuang Yu

Examples

library(ggplot2)
library(aplot)

p <- ggplot(mtcars, aes(mpg, disp)) + geom_point()
p2 <- ggplot(mtcars, aes(mpg)) + 
    geom_density(fill='steelblue', alpha=.5) + 
        ggfun::theme_noxaxis()
p3 <- ggplot(mtcars, aes(x=1, y=disp)) + 
    geom_boxplot(fill='firebrick', alpha=.5) + 
    theme_void()
ap <- p %>% 
    insert_top(p2, height=.3) %>% 
    insert_right(p3, width=.1)

ap
ap[2, 1] <- ap[2, 1] + theme_bw()
ap[2, 1] <- ap[2, 1] + 
            aes(color = as.factor(am)) + 
            scale_color_manual(values = c('steelblue', 'darkgreen'))
ap[1, 1] <- ap[1, 1] + theme(axis.line.x.bottom=element_line())
ap

plot a list of ggplot objects

Description

plot a list of ggplot objects using patchwork, similar to 'cowplot::plot_grid(plotlist)'

Usage

plot_list(
  ...,
  gglist = NULL,
  ncol = NULL,
  nrow = NULL,
  byrow = NULL,
  widths = NULL,
  heights = NULL,
  guides = NULL,
  labels = NULL,
  tag_levels = NULL,
  tag_size = 14,
  design = NULL,
  output = "patchwork"
)

Arguments

...

list of plots to be arranged

gglist

(optional) list of plots

ncol

number of columns

nrow

number of rows

byrow

If "FALSE" the plots will be filled in in column-major order

widths

relative widths

heights

relative heights

guides

A string specifying how guides should be treated in the layout.

labels

manual specified labels to label plots

tag_levels

format to label plots, will be disable if 'labels' is not NULL

tag_size

size of tags

design

specification of the location of areas in the layout

output

one of 'gglist' or 'patchwork'

Value

composite plot

Author(s)

Guangchuang Yu

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

ggfun

ggrange, xrange, yrange

ggplot2

ggsave

magrittr

%>%

display x or y axis label as an ordinary text, so that the label will not be aligned with axis label of another plot

Description

display x or y axis label as an ordinary text, so that the label will not be aligned with axis label of another plot

Usage

xlab2(label, fontsize = 11, ...)

ylab2(label, fontsize = 11, ...)

Arguments

label

axis label

fontsize

fontsize of the label

...

additional parameter passed to 'gpar'

Value

gg object with new label

Author(s)

Guangchuang Yu

xlim2

Description

set axis limits (x or y) of a 'ggplot' object (left hand side of '+') based on the x ('xlim2') or y ('ylim2') limits of another 'ggplot' object (right hand side of '+'). This is useful for using 'cowplot' or 'patchwork' to align 'ggplot' objects.

Usage

xlim2(gg, limits = NULL)

ylim2(gg, limits = NULL)

Arguments

gg

ggplot object

limits

vector of limits. If NULL, determine from 'gg'.

Value

ggplot2 object with new limits

Author(s)

Guangchuang Yu

Examples

library(ggplot2)
library(aplot)
p1 <- ggplot(mtcars, aes(cyl)) + geom_bar()
p2 <- ggplot(subset(mtcars, cyl != 4), aes(cyl)) + geom_bar()
p2 + xlim2(p1)