Title: Create Overlapping Stacked Plots
Version: 0.4.1
Description: Easily create overlapping grammar of graphics plots for scientific data visualization. This style of plotting is particularly common in climatology and oceanography research communities.
License: MIT + file LICENSE
URL: https://ggstackplot.kopflab.org/, https://github.com/kopflab/ggstackplot
BugReports: https://github.com/kopflab/ggstackplot/issues
Encoding: UTF-8
RoxygenNote: 7.3.2
Depends: R (≥ 4.1.0)
Imports: rlang, cli, methods, lifecycle, tidyselect, dplyr, tidyr, ggplot2, cowplot, RColorBrewer
Suggests: knitr, rmarkdown, testthat (≥ 3.0.0), vdiffr, scales, pangaear
Config/testthat/edition: 3
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2025-01-31 08:40:12 UTC; sk
Author: Sebastian Kopf ORCID iD [aut, cre, cph], Tristan Caro ORCID iD [aut], Jamie McFarlin ORCID iD [aut], Jon Raberg ORCID iD [aut]
Maintainer: Sebastian Kopf <sebastian.kopf@colorado.edu>
Repository: CRAN
Date/Publication: 2025-01-31 09:00:02 UTC

ggstackplot: Create Overlapping Stacked Plots

Description

Easily create overlapping grammar of graphics plots for scientific data visualization. This style of plotting is particularly common in climatology and oceanography research communities.

Details

[Stable]

Have you ever wanted to create (partly) overlapping line plots with matched color-coding of the data and axes? These kinds of plots are common in climatology and oceanography research but there is not an easy way to create them with ggplot facets. The ggstackplot package builds on ggplot2 to provide a straightforward approach to building these kinds of plots while retaining the powerful grammar of graphics approach of ggplots. Check out the functionality provided by ggstackplots at https://ggstackplot.kopflab.org

Author(s)

Maintainer: Sebastian Kopf sebastian.kopf@colorado.edu (ORCID) [copyright holder]

Authors:

See Also

Useful links:

Stack a ggplot

Description

Use ggstackplot() to generate a stackplot. If you need more fine control, use prepare_stackplot() and assemble_stackplot() individually. To explore examples of all the different features, check out the vignette("explore", "ggstackplot") or the online documentation.

Usage

ggstackplot(
  data,
  x,
  y,
  remove_na = TRUE,
  color = NA,
  palette = NA,
  both_axes = FALSE,
  alternate_axes = TRUE,
  switch_axes = FALSE,
  overlap = 0,
  simplify_shared_axis = TRUE,
  shared_axis_size = 0.2,
  template = ggplot() + geom_line() + geom_point() + theme_stackplot(),
  add = list(),
  debug = FALSE
)

prepare_stackplot(
  data,
  x,
  y,
  remove_na = TRUE,
  color = NA,
  palette = NA,
  both_axes = FALSE,
  alternate_axes = TRUE,
  switch_axes = FALSE,
  template = ggplot() + geom_line() + geom_point() + theme_stackplot(),
  add = list(),
  debug = FALSE
)

assemble_stackplot(
  prepared_stackplot,
  overlap = 0,
  simplify_shared_axis = TRUE,
  shared_axis_size = 0.15,
  debug = FALSE
)

Arguments

data

the data frame to plot

x

the x variable(s) to plot, accepts dplyr::select() syntax. The order of variables is plotted from left to right (if multiple x).

y

the y variable(s) to plot, accepts dplyr::select() syntax. The order of variables in plotted from top to bottom (if multiple y).

remove_na

whether to remove NA values in the x/y plot, setting this to FALSE can lead to unintended side-effects for interrupted lines so check your plot carefully if you change this

color

which color to make the plots (also sets the plotwide color and fill aesthetics, overwrite in individual geoms in the template to overwrite this aesthetic), either one value for or one color per variable. Pick NA to not set colors (in case you want to use them yourself in the aesthetics).

palette

which color to make the plots defined with an RColorBrewer palette (RColorBrewer::display.brewer.all()). You can only use color or palette parameter, not both.

both_axes

whether to have the stacked axes on both sides (overrides alternate_axes and switch_axes)

alternate_axes

whether to alternate the sides on which the stacked axes are plotted

switch_axes

whether to switch the stacked axes. Not switching means that for vertical stacks the plot at the bottom has the y-axis always on the left side; and for horizontal stacks that the plot on the left has the x-axis on top. Setting switch_axes = TRUE, leads to the opposite.

overlap

fractional overlap between adjacent plots. The max of 1 means plots are perfectly overlaid. The min of 0 means there is no overlap. If providing multiple values, must be 1 less than the number of stacked plots (since it's describing the overlap/gap between adjacent plots). By default there is no overlap between plots

simplify_shared_axis

whether to simplify the shared axis to only be on the last plot (+ first plot if a duplicate secondary axis is set)

shared_axis_size

if simplify_shared_axes is true, this determines the size of the shared axis relative to the size of a single plot

template

a template plot (ggplot object) to use for the stacked plots

add

a list of ggplot component calls to add to specific panel plots, either by panel variable name (named list) or index (unnamed list)

debug

[Experimental] debug flag to print the stackplot tibble and gtable intermediates

prepared_stackplot

a nested data frame, the output from prepare_stackplot()

Details

ggstackplot() stacks a ggplot template with the provided data and parameters. It returns a plot object generated by cowplot::plot_grid()).

prepare_stackplot() is usually not called directly but can be used to assemble the parts of a stackplot first and then look at them or edit them individually before combining them with ⁠assemble_stackplot()]⁠. Returns a nested data frame with all stacked variables (.var), their plot configuration, data, plot object, and theme object.

assemble_stackplot() is usually not called directly but can be used to manually combine a stackplot tibble (typically created by prepare_stockplot()). Returns a plot object generated by cowplot::plot_grid()).

Value

ggstackplot() returns a ggplot with overlayed plot layers

prepare_stackplot() returns a tibble with all plot components

assemble_stackplot() returns a ggplot with overlayed plot layers

Examples

# 1 step stackplot (most common use)
mtcars |>
  ggstackplot(
    x = mpg,
    y = c(`weight [g]` = wt, qsec, drat, disp),
    palette = "Set1",
    overlap = c(1, 0, 0.3)
  )

# 2 step stackplot
mtcars |>
  prepare_stackplot(
    x = mpg,
    y = c(`weight [g]` = wt, qsec, drat, disp),
    palette = "Set1"
  ) |>
  assemble_stackplot(overlap = c(1, 0, 0.3))


# many more examples available in the vignette
vignette("ggstackplot")

Recommended base theme for stacked gg plots

Description

Returns a basic ggplot2 theme that extends ggplot2::theme_bw() with a transparent plot background to make sure overlapping plots do not cover each other up.

Usage

theme_stackplot()

Value

ggplot2::theme() object

Examples

library(ggplot2)
template <- ggplot() + geom_line() + theme_stackplot()

ggstackplot(
  data = mtcars,
  x = mpg, y = c(wt, qsec, drat),
  color = c("#E41A1C", "#377EB8", "#4DAF4A"),
  template = template
)