Add a trelliscope facet to a ggplot

Usage

facet_panels(
  facets,
  scales = "same",
  add_plot_metrics = FALSE,
  unfacet = c("none", "line", "point"),
  unfacet_col = "gray",
  unfacet_alpha = 0.4,
  data = ggplot2::waiver()
)

Arguments

facets: A formula to facet the panels on. Similar to ggplot2::facet_wrap()'s `facets``
scales: Should scales be the same ("same", the default), free ("free"), or sliced ("sliced"). May provide a single string or two strings, one for the X and Y axis respectively.
add_plot_metrics: Should metrics about each panel be automatically calculated? These metrics are based on the context of what is being plotted, e.g. correlation coefficient if plot is a scatterplot.
unfacet: Specifies whether to "unfacet" the data such that all of the data appears in the background of the plot. Options are "none" (default), "line" or "point". The latter two options will add either a line or point layer, grouped by the faceting variables, underneath each panel. This is useful for time series plots for viewing each panel in relation to others.
unfacet_col: The color to use for the "unfacet" lines or points.
unfacet_alpha: The alpha to use for the "unfacet" lines or points.
data: data used for faceting. Defaults to the main data argument to ggplot2::ggplot().

Examples

# You can run facet_panels() just like how you would run facet_wrap()
library(ggplot2)

if (FALSE) {
ggplot(gap, aes(year, life_exp)) +
  geom_point() +
  facet_panels(vars(country, continent))
}

# facet_panels can also be a jumping off point into setting up a more
# developed trelliscope by passing into `as_panels_df()` to create a nested
# trelliscope data frame for additional editing.
library(ggplot2)
library(dplyr)

panel_dat <- (
  ggplot(gap, aes(year, life_exp)) +
  geom_point() +
  facet_panels(vars(country, continent))
) |>
  as_panels_df()

trell_df <- panel_dat |>
  as_trelliscope_df(name = "life expectancy", path = "gapminder") |>
  set_default_layout(ncol = 4)

if (FALSE) {
view_trelliscope(trell_df)
}