plot3: Plotting functions
In msberends/plot3: Creating 'ggplot2' Plots With Less Code

Description Usage Arguments Details Comparison with the ggplot2 package

text text

plot3(
  .data,
  type = "column",
  x = NULL,
  y = NULL,
  category = NULL,
  facet = NULL,
  title = NULL,
  subtitle = NULL,
  tag = NULL,
  caption = NULL,
  bins = NULL,
  category.focus = NULL,
  category.sort = TRUE,
  colour = getOption("plot2.colours", "certe"),
  colour.extended_spectrum = FALSE,
  colour.fill = NULL,
  colour.opacity = 0,
  datalabels = TRUE,
  datalabels.fill = "white",
  datalabels.round = if_else(y.percent, 1, 2),
  datalabels.size = 3,
  decimal_comma = uses_decimal_comma(),
  facet.bold = TRUE,
  facet.drop = FALSE,
  facet.fill = NULL,
  facet.fixed_y = FALSE,
  facet.italic = FALSE,
  facet.margin = 8,
  facet.nrow = NULL,
  facet.position = "top",
  facet.relative = FALSE,
  facet.repeat_lbls_x = TRUE,
  facet.repeat_lbls_y = TRUE,
  facet.size = 10,
  facet.sort = TRUE,
  horizontal = FALSE,
  jitter_seed = 1,
  legend.barheight = 5,
  legend.barwidth = 1,
  legend.italic = FALSE,
  legend.position = "top",
  legend.reverse = NULL,
  legend.title = "",
  linetype = 1,
  markdown = TRUE,
  na.replace = "(onbekend)",
  na.rm = FALSE,
  print = FALSE,
  reverse = horizontal,
  size = ifelse(type %in% c("point", "jitter", "boxplot", "violin"), 2, 0.75),
  stacked = FALSE,
  stackedpercent = FALSE,
  subtitle.maxlength = 60,
  summarise_function = base::sum,
  text.factor = 1,
  text.font_family = "Calibri",
  theme = theme_minimal2(),
  title.maxlength = 60,
  width = ifelse(type %in% c("jitter", "boxplot", "violin"), 0.75, 0.5),
  x.date_breaks = "1 day",
  x.date_labels = "d mmm",
  x.expand = 0.5,
  x.lbl_align = NULL,
  x.lbl_angle = 0,
  x.lbl_italic = FALSE,
  x.limits = NULL,
  x.max_items = Inf,
  x.max_txt = "(rest, x{n})",
  x.position = "bottom",
  x.remove = FALSE,
  x.sort = TRUE,
  x.title = NULL,
  y.24h = FALSE,
  y.age = FALSE,
  y.breaks = NULL,
  y.expand = 0.25,
  y.labels = NULL,
  y.limits = NULL,
  y.percent = FALSE,
  y.percent_break = 10,
  y.position = "left",
  y.remove = FALSE,
  y.title = NULL,
  y.trans = "identity",
  ...
)

## Default S3 method:
plot3(
  x,
  y = NULL,
  type = "p",
  xlim = NULL,
  ylim = NULL,
  log = "",
  main = NULL,
  sub = NULL,
  xlab = NULL,
  ylab = NULL,
  ann = par("ann"),
  axes = TRUE,
  frame.plot = axes,
  panel.first = NULL,
  panel.last = NULL,
  asp = NA,
  xgap.axis = NA,
  ygap.axis = NA,
  ...
)

## S3 method for class 'grouped_df'
plot3(.data, ..., category = NULL)

## S3 method for class 'ggplot'
plot3(plot, type, ...)

## S3 method for class 'sf'
plot3(
  .data,
  ...,
  datalabels = FALSE,
  legend.position = "right",
  colour = "grey50",
  y.expand = 0,
  x.expand = 0
)

`type`	1-character string giving the type of plot desired. The following values are possible, for details, see `plot`: `"p"` for points, `"l"` for lines, `"b"` for both points and lines, `"c"` for empty points joined by lines, `"o"` for overplotted points and lines, `"s"` and `"S"` for stair steps and `"h"` for histogram-like vertical lines. Finally, `"n"` does not produce any points or lines.
`x`	the `x` and `y` arguments provide the x and y coordinates for the plot. Any reasonable way of defining the coordinates is acceptable. See the function `xy.coords` for details. If supplied separately, they must be of the same length.
`y`	the `x` and `y` arguments provide the x and y coordinates for the plot. Any reasonable way of defining the coordinates is acceptable. See the function `xy.coords` for details. If supplied separately, they must be of the same length.
`...`	other graphical parameters (see `par` and section ‘Details’ below).
`xlim`	the x limits (x1, x2) of the plot. Note that `x1 > x2` is allowed and leads to a ‘reversed axis’. The default value, `NULL`, indicates that the range of the finite values to be plotted should be used.
`ylim`	the y limits of the plot.
`log`	a character string which contains `"x"` if the x axis is to be logarithmic, `"y"` if the y axis is to be logarithmic and `"xy"` or `"yx"` if both axes are to be logarithmic.
`main`	a main title for the plot, see also `title`.
`sub`	a sub title for the plot.
`xlab`	a label for the x axis, defaults to a description of `x`.
`ylab`	a label for the y axis, defaults to a description of `y`.
`ann`	a logical value indicating whether the default annotation (title and x and y axis labels) should appear on the plot.
`axes`	a logical value indicating whether both axes should be drawn on the plot. Use graphical parameter `"xaxt"` or `"yaxt"` to suppress just one of the axes.
`frame.plot`	a logical indicating whether a box should be drawn around the plot.
`panel.first`	an ‘expression’ to be evaluated after the plot axes are set up but before any plotting takes place. This can be useful for drawing background grids or scatterplot smooths. Note that this works by lazy evaluation: passing this argument from other `plot` methods may well not work since it may be evaluated too early.
`panel.last`	an expression to be evaluated after plotting has taken place but before the axes, title and box are added. See the comments about `panel.first`.
`asp`	the y/x aspect ratio, see `plot.window`.
`xgap.axis`	the x/y axis gap factors, passed as `gap.axis` to the two `axis()` calls (when `axes` is true, as per default).
`ygap.axis`	the x/y axis gap factors, passed as `gap.axis` to the two `axis()` calls (when `axes` is true, as per default).

The plot3() function uses the ggplot2 package for plotting and provides:

A convenient wrapper around many ggplot2 functions such as ggplot(), geom_col(), facet_wrap(), labs(), etc.
Writing as few lines of codes as possible
A drop-in replacement for most plot() calls
Benefits from Excel: the y axis starts at 0, the y scale contains extra space to read all data points, date breaks can be written in a readable format such as "d mmm yyyy", and data labels can easily be printed
Easy plotting in three 'directions': x (the regular x axis), category (replaces 'fill' and 'colour') and facet
Easy way for sorting data in may ways (such as on alphabet, numeric value, frequency, original data order), by setting a single argument for the 'direction': x.sort, category.sort and facet.sort
Easy limiting values for x by setting code{x.max_items
Markdown support for any label, with any theme
An extra clean, minimalistic theme with a lot of whitespace that is ideal for printing

The plot3() function is arguably what the qplot() function of the ggplot2 package could have been.

Comparison with the `ggplot2` package

The ggplot2 package provides a wide range of functions for very advanced plotting, but it lacks convenience for simple plotting. For example, a common data set could look like this:

df
#>   carmodel            mpg
#>   <chr>             <dbl>
#> 1 Mazda RX4          21.0
#> 2 Mazda RX4 Wag      21.0
#> 3 Datsun 710         22.8
#> 4 Hornet 4 Drive     21.4

The ggplot2 package sets no default for plotting types, requiring you to type at least:

1 2	ggplot(df) + geom_col(aes(x = carmodel, y = mpg))

That's a lot of code containing three functions for something so obvious. Any addition (labels, scales, etc.) would require you to write more functions and their parameters. The plot3() function guesses what you want to do and contains many parameters to alter your plots. In other words, the ggplot2 package requires you to write many functions and parameters for plotting, the plot3() function only requires you to write the parameters that are not already set:

1 2	df %>% plot3()

Moreover, the ggplot2 package requires a data.frame as input or forces input to a data.frame. The plot3() function uses S3 classes for extensions, allowing base plot() users to change their plots to ggplot2 plots by literally adding one number to the function they are calling. And plot3() functions are even extendible with new plot3() functions and with other packages.