Title: Reveal a 'ggplot' Incrementally
Version: 0.1.4
Description: Provides functions that make it easy to reveal 'ggplot2' graphs incrementally. The functions take a plot produced with 'ggplot2' and return a list of plots showing data incrementally by panels, layers, groups, the values in an axis or any arbitrary aesthetic.
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 7.3.2.9000
Imports: cli, dplyr, ggplot2, ggplotify, rlang, stringr, tidyr
Suggests: testthat (≥ 3.0.0), withr, vdiffr, mockery
Config/testthat/edition: 3
URL: http://www.weverthon.com/ggreveal/, https://github.com/weverthonmachado/ggreveal
BugReports: https://github.com/weverthonmachado/ggreveal/issues
NeedsCompilation: no
Packaged: 2024-11-10 15:10:07 UTC; Macha010
Author: Weverthon Machado ORCID iD [aut, cre, cph]
Maintainer: Weverthon Machado <weverthonmachado@gmail.com>
Repository: CRAN
Date/Publication: 2024-11-10 17:10:06 UTC

Reveal plot by aes

Description

Turns a ggplot into a list of plots, showing data incrementally by an arbitrary aesthetic.

Usage

reveal_aes(p, aes = "group", order = NULL, max = 20)

Arguments

p

A ggplot2 object

aes

which aesthetic to reveal E.g.: group, colour, shape, linetype

order

(optional) A numeric vector specifying in which order to reveal levels of the specified aesthetic.

For example, if aes='shape' and the plot uses three shapes, order = c(3, 2, 1) will invert the order in which they are revealed.

Any shape not included in the vector will be omitted from the incremental plots. E.g.: with order = c(3, 1), the second shape is not shown.

By default, the first plot is blank, showing layout elements (title, legends, axes, etc) but no data. To omit the blank plot, include -1: e.g. order = c(-1, 3, 1), or order = -1.

max

maximum number of unique levels of aesthetic to be used

Value

A list of ggplot2 objects, which can be passed to reveal_save()

Examples

# Create full plot
library(ggplot2)

 p <- mtcars |>
   ggplot(aes(mpg, wt,
              color = factor(vs),
              group = factor(vs))) +
   geom_point(aes(shape=factor(am)), size=2) +
   geom_smooth(method="lm",
               formula = 'y ~ x',
               linewidth=1) 
 p

 plot_list <- reveal_aes(p, "shape")
 plot_list[[1]]
 plot_list[[2]]
 plot_list[[3]]
 plot_list[[4]]


# Save plots
reveal_save(plot_list, "myplot.png", width = 8, height = 4, path = tempdir())

# Clean temp files
file.remove(list.files(path = tempdir(), pattern = "myplot", full.names = TRUE))

Reveal plot by group

Description

Turns a ggplot into a list of plots, showing data incrementally by groups. Note that if the group aesthetic is not explicitly defined in the original plot, ggplot2 will set it to the interaction of all discrete variables (see ggplot2::aes_group_order).

Usage

reveal_groups(p, order = NULL)

Arguments

p

A ggplot2 object

order

(optional) A numeric vector specifying in which order to reveal the groups

For example, if there are three groups in the plot, order = c(3, 2, 1) will invert the order in which they are revealed.

Any group not included in the vector will be omitted from the incremental plots. E.g.: with order = c(3, 1), the second group is not shown.

By default, the first plot is blank, showing layout elements (title, legends, axes, etc) but no data. To omit the blank plot, include -1: e.g. order = c(-1, 3, 1), or order = -1.

Value

A list of ggplot2 objects, which can be passed to reveal_save()

Examples

# Create full plot
library(ggplot2)
data("mtcars")

p <- mtcars |>
  ggplot(aes(mpg, wt,
             color = factor(vs),
             group = factor(vs))) +
  geom_point() +
  geom_smooth(method="lm",
              formula = 'y ~ x',
              linewidth=1) +
  facet_wrap(~am)
p

plot_list <- reveal_groups(p)
plot_list[[1]]
plot_list[[2]]
plot_list[[3]]

# Save plots
reveal_save(plot_list, "myplot.png", width = 8, height = 4, path = tempdir())

# Clean temp files
file.remove(list.files(path = tempdir(), pattern = "myplot", full.names = TRUE))

Reveal plot by layer

Description

Turns a ggplot into a list of plots, showing data incrementally by layers.

Usage

reveal_layers(p, order = NULL)

Arguments

p

A ggplot2 object

order

(optional) A numeric vector specifying in which order to reveal the layers

For example, if there are three layers in the plot, order = c(3, 2, 1) will invert the order in which they are revealed.

Any layer not included in the vector will be omitted from the incremental plots. E.g.: with order = c(3, 1), the second layer is not shown.

By default, the first plot is blank, showing layout elements (title, legends, axes, etc) but no data. To omit the blank plot, include -1: e.g. order = c(-1, 3, 1), or order = -1.

Value

A list of ggplot2 objects, which can be passed to reveal_save()

Examples

# Create full plot
library(ggplot2)
data("mtcars")

p <- mtcars |>
  ggplot(aes(mpg, wt,
             color = factor(vs),
             group = factor(vs))) +
  geom_point() +
  geom_smooth(method="lm",
              formula = 'y ~ x',
              linewidth=1) +
  facet_wrap(~am)
p

plot_list <- reveal_layers(p)
plot_list[[1]]
plot_list[[2]]
plot_list[[3]]

# Save plots
reveal_save(plot_list, "myplot.png", width = 8, height = 4, path = tempdir())

# Clean temp files
file.remove(list.files(path = tempdir(), pattern = "myplot", full.names = TRUE))

Reveal plot by panel

Description

Turns a ggplot into a list of plots, showing data incrementally by panels.

Usage

reveal_panels(p, order = NULL, what = c("data", "everything"))

Arguments

p

A ggplot2 object

order

(optional) A numeric vector specifying in which order to reveal the panels

For example, if there are three panels in the plot, order = c(3, 2, 1) will invert the order in which they are revealed.

Any panel not included in the vector will be omitted from the incremental plots. E.g.: with order = c(3, 1), the second panel is not shown.

By default, the first plot is blank, showing layout elements (title, legends, axes, etc) but no data. To omit the blank plot, include -1: e.g. order = c(-1, 3, 1), or order = -1.

what

(optional) one of "data" or "everything".' With "data" (the default), the basic graph layout, including axes and facet labels, is shown from the start, and only the data points are shown incrementally. With "everything", the entire panels are shown incrementally.

Value

A list of ggplot2 objects, which can be passed to reveal_save()

Examples

# Create full plot
library(ggplot2)
data("mtcars")

p <- mtcars |>
  ggplot(aes(mpg, wt,
             color = factor(vs),
             group = factor(vs))) +
  geom_point() +
  geom_smooth(method="lm",
              formula = 'y ~ x',
              linewidth=1) +
  facet_wrap(~am)
p

# Only data
plot_list <- reveal_panels(p, what = "data")
plot_list[[1]]
plot_list[[2]]
plot_list[[3]]

# Everything
plot_list <- reveal_panels(p, what = "everything")
plot_list[[1]]
plot_list[[2]]
plot_list[[3]]

# Save plots
reveal_save(plot_list, "myplot.png", width = 8, height = 4, path = tempdir())

# Clean temp files
file.remove(list.files(path = tempdir(), pattern = "myplot", full.names = TRUE))

Saves incremental plots

Description

Saves incremental plots

Usage

reveal_save(plot_list, basename, ...)

Arguments

plot_list

A list of plots created by one of the ⁠reveal_*⁠ functions (e.g. reveal_groups(), reveal_layers(), reveal_aes()]

basename

The base file name that will be used for saving.

...

Additional arguments (e.g. width, height) to be passed to ggplot2::ggsave()

Value

The paths of the saved plots, invisibly

Examples

# Create full plot
library(ggplot2)
data("mtcars")

p <- mtcars |>
  ggplot(aes(mpg, wt,
             color = factor(vs),
             group = factor(vs))) +
  geom_point() +
  geom_smooth(method="lm",
              formula = 'y ~ x',
              linewidth=1) +
  facet_wrap(~am)
p

plot_list <- reveal_groups(p)
plot_list[[1]]
plot_list[[2]]
plot_list[[3]]

# Save plots
reveal_save(plot_list, "myplot.png", width = 8, height = 4, path = tempdir())

# Clean temp files
file.remove(list.files(path = tempdir(), pattern = "myplot", full.names = TRUE))

Reveal plot by axis

Description

Turns a ggplot into a list of plots, showing data incrementally by the categories in the x or y axis.

Usage

reveal_x(p, order = NULL)

reveal_y(p, order = NULL)

Arguments

p

A ggplot2 object

order

(optional) A numeric vector specifying in which order to reveal the categories

For example, if there are three categories in the axis, order = c(3, 2, 1) will invert the order in which they are revealed.

Any category not included in the vector will be omitted from the incremental plots. E.g.: with order = c(3, 1), the second category is not shown.

By default, the first plot is blank, showing layout elements (title, legends, axes, etc) but no data. To omit the blank plot, include -1: e.g. order = c(-1, 3, 1), or order = -1.

Value

A list of ggplot2 objects, which can be passed to reveal_save()

Examples

# Create full plot
library(ggplot2)
data("mtcars")

p <- mtcars |>
  ggplot(aes(factor(vs), 
             color = gear,
             fill= gear, 
             group = gear)) +
  geom_bar() +
  facet_wrap(~am)
p

plot_list <- reveal_x(p)
plot_list[[1]]
plot_list[[2]]
plot_list[[3]]

# Save plots
reveal_save(plot_list, "myplot.png", width = 8, height = 4, path = tempdir())

# Clean temp files
file.remove(list.files(path = tempdir(), pattern = "myplot", full.names = TRUE))