Package 'plot2'

Title: A Plotting Assistant for Fast 'ggplot2' Visualisations
Description: A streamlined extension of 'ggplot2' designed to simplify and accelerate the creation of data visualisations. 'plot2' automates common tasks such as axis handling, plot type selection, and data transformation, allowing users to create complex, publication-ready plots with minimal code. It integrates seamlessly with the tidyverse and retains full compatibility with 'ggplot2', while offering additional conveniences like enhanced sorting, faceting, and custom theming.
Authors: Matthijs S. Berends [aut, cre], Erwin E. A. Hassing [aut, ctb]
Maintainer: Matthijs S. Berends <[email protected]>
License: GPL-2
Version: 1.99.1.9000
Built: 2026-11-19 13:36:51 UTC
Source: https://github.com/msberends/plot2

Help Index


Add Additional Mapping

Description

This function can be used to adjust the mapping of a plot.

Usage

add_mapping(plot, ...)

Arguments

plot

A ggplot2 plot.

...

Arguments passed on to ggplot2::aes().

Examples

p <- iris |> plot2(Sepal.Length, Sepal.Width, Species, zoom = TRUE)
p

p |> add_mapping(shape = Species)

Add Plot Element

Description

Quickly and conveniently add a new 'geom' to an existing plot2/ggplot model. Like plot2(), these functions support tidy evaluation, meaning that variables can be unquoted. Better yet, they can contain any function with any output length, or any vector. They can be added using the pipe (new base R's ⁠|>⁠ or tidyverse's ⁠%>%⁠).

Usage

add_type(plot, type = NULL, mapping = aes(), ..., data = NULL, move = 0)

add_line(
  plot,
  y = NULL,
  x = NULL,
  colour = getOption("plot2.colour", "ggplot2"),
  linetype,
  linewidth,
  ...,
  inherit.aes = NULL,
  move = 0,
  legend.value = NULL
)

add_point(
  plot,
  y = NULL,
  x = NULL,
  colour = getOption("plot2.colour", "ggplot2"),
  size,
  shape,
  ...,
  inherit.aes = NULL,
  move = 0,
  legend.value = NULL
)

add_col(
  plot,
  y = NULL,
  x = NULL,
  colour = getOption("plot2.colour", "ggplot2"),
  colour_fill,
  width,
  ...,
  inherit.aes = NULL,
  move = 0,
  legend.value = NULL
)

add_errorbar(
  plot,
  min,
  max,
  colour = getOption("plot2.colour", "ggplot2"),
  width = 0.5,
  ...,
  inherit.aes = NULL,
  move = 0
)

add_smooth(
  plot,
  y = NULL,
  x = NULL,
  colour = getOption("plot2.colour", "ggplot2"),
  linetype,
  linewidth,
  formula,
  method,
  se,
  ...,
  inherit.aes = NULL,
  move = 0,
  legend.value = NULL
)

add_sf(
  plot,
  sf_data,
  colour = getOption("plot2.colour_sf", "grey50"),
  colour_fill = getOption("plot2.colour_sf_fill", getOption("plot2.colour", "ggplot2")),
  size = 2,
  linewidth = 0.1,
  datalabels = NULL,
  datalabels.colour = "black",
  datalabels.size = 3,
  datalabels.angle = 0,
  datalabels.font = getOption("plot2.font"),
  datalabels.nudge_y = 0,
  ...,
  inherit.aes = FALSE
)

Arguments

plot

A ggplot2 plot.

type

A ggplot2 geom name, all geoms are supported. Full function names can be used (e.g., "geom_line"), but they can also be abbreviated (e.g., "l", "line"). These geoms can be abbreviated by their first character: area ("a"), boxplot ("b"), column ("c"), histogram ("h"), jitter ("j"), line ("l"), point ("p"), ribbon ("r"), violin ("v").

mapping

A mapping created with aes() to pass on to the geom.

data

Data to use in mapping.

move

Number of layers to move the newly added geom down; the sign is ignored. For example, move = 1 (or move = -1) places the new geom directly below the layer that was on top before it was added. Use move_layer() for other changes in the order of layers.

x, y

aesthetic arguments

colour, colour_fill

colour of the line or column, will be evaluated with get_colour(). If colour_fill is missing but colour is given, colour_fill will inherit the colour set with colour.

linetype, linewidth, shape, size, width, ...

Arguments passed on to the geom.

inherit.aes

A logical to indicate whether the default aesthetics should be inherited, rather than combining with them.

legend.value

Text to show in an additional legend that will be created. Since ggplot2 does not actually support this, it may give some false-positive warnings or messages, such as "Removed 1 row containing missing values or values outside the scale range".

min, max

minimum (lower) and maximum (upper) values of the error bars

formula

Formula to use in smoothing function, eg. y ~ x, y ~ poly(x, 2), y ~ log(x). NULL by default, in which case method = NULL implies formula = y ~ x when there are fewer than 1,000 observations and formula = y ~ s(x, bs = "cs") otherwise.

method

Smoothing method (function) to use, accepts either NULL or a character vector, e.g. "lm", "glm", "gam", "loess" or a function, e.g. MASS::rlm or mgcv::gam, stats::lm, or stats::loess. "auto" is also accepted for backwards compatibility. It is equivalent to NULL.

For method = NULL the smoothing method is chosen based on the size of the largest group (across all panels). stats::loess() is used for less than 1,000 observations; otherwise mgcv::gam() is used with formula = y ~ s(x, bs = "cs") with method = "REML". Somewhat anecdotally, loess gives a better appearance, but is O(N2)O(N^{2}) in memory, so does not work for larger datasets.

If you have fewer than 1,000 observations but want to use the same gam() model that method = NULL would use, then set ⁠method = "gam", formula = y ~ s(x, bs = "cs")⁠.

se

Display confidence band around smooth? (TRUE by default, see level to control.)

sf_data

an 'sf' data.frame

datalabels

a column of sf_data to add as label below the points

datalabels.colour, datalabels.size, datalabels.angle, datalabels.font

properties of datalabels

datalabels.nudge_y

if datalabels is not NULL, the amount of vertical adjustment of the datalabels in the units of the coordinate reference system (positive value: more to the North, negative value: more to the South), e.g. metres for EPSG:28992 and degrees for EPSG:4326. The default is 0.

Details

The function add_line() will add:

The function add_errorbar() only adds error bars to the y values, see Examples.

Value

a ggplot object

Examples

p <- iris |>
  plot2(x = Sepal.Length,
        y = Sepal.Width,
        category = Species,
        zoom = TRUE)
  
# if not specifying x or y, current plot data are taken
p |> add_line()

p |> add_smooth()
  
# single values for add_line() will plot 'hline' or 'vline'
# even considering the `category` if set
p |> 
  add_line(y = mean(Sepal.Width))

# set `colour` to ignore existing colours
# and use `legend.value` to add a legend
p |> 
  add_line(y = mean(Sepal.Width),
           colour = "red",
           legend.value = "Average")

# also works with facets
iris |>
  plot2(x = Sepal.Length,
        y = Sepal.Width,
        facet = Species) |>
  add_line(y = mean(Sepal.Width),
           legend.value = "Average")

p |>
  add_point(x = median(Sepal.Length),
            y = median(Sepal.Width),
            shape = 13,
            size = 25,
            show.legend = FALSE)
  
# multiple values will plot multiple lines
p |> 
  add_line(y = quantile(Sepal.Width, c(0.25, 0.5, 0.75)),
           colour = c("red", "black", "red"),
           linewidth = 1)
  
# use move to move the new layer down
p |> 
  add_point(size = 5,
            colour = "lightgrey",
            move = -1)

# providing x and y will just plot the points as new data,
p |> 
  add_point(y = 2:4,
            x = 5:7,
            colour = "red",
            size = 5)

# any mathematical transformation of current values is supported
df <- data.frame(var_1 = c(1:100),
                 var_2 = rnorm(100, 100, 25),
                 var_3 = rep(LETTERS[1:5], 5))
df |>
  plot2(var_1, var_2) |> 
  add_line(y = mean(var_2), 
           linetype = 3,
           legend.value = "Average") |>
  add_col(y = var_2 / 5,
          width = 0.25,
          colour = "blue",
          legend.value = "This *is* **some** symbol: $beta$")

# plotting error bars was never easier
library("dplyr", warn.conflicts = FALSE)
df2 <- df |> 
  as_tibble() |> 
  slice(1:25) |>
  filter(var_1 <= 50) |> 
  mutate(error1 = var_2 * 0.9,
         error2 = var_2 * 1.1)

df2 |> 
  plot2(var_1, var_2, var_3, type = "col", datalabels = FALSE, alpha = 0.25, width = 0.75) |> 
  # adding error bars was never easier - just reference the lower and upper values
  add_errorbar(error1, error2)

# adding sf objects is just as convenient as all else
if (requireNamespace("sf", quietly = TRUE)) {
  netherlands |> 
    plot2(colour_fill = "viridis", colour_transparency = 0.75) |>
    # add the same sf object, but now with empty fill and other options
    add_sf(netherlands,
           colour = "black",
           colour_fill = NA,
           linetype = 2,
           linewidth = 0.5)
}

Create Interactive Plotly

Description

Transform a ggplot2/plot2 object to an interactive plot using the Plotly R Open Source Graphing Library.

Usage

as_plotly(plot, ...)

plotly_style(plot, ...)

Arguments

plot

A ggplot2 plot.

...

In case of as_plotly(): arguments to pass on to layout() to change the Plotly layout object

In case of plotly_style(): arguments to pass on to style() to change the Plotly style object

Examples

if (requireNamespace("plotly", quietly = TRUE)) {
  mtcars |>
    plot2(mpg, hp) |> 
    as_plotly()
}
if (requireNamespace("plotly", quietly = TRUE)) {
  mtcars |>
    plot2(mpg, hp) |> 
    as_plotly(dragmode = "pan") |>
    plotly_style(marker.line.color = "red",
                 hoverinfo = "y")
}

Spider (Radar) Coordinate System for ggplot2

Description

coord_spider() implements a new spider / radar coordinate system using a linear (non-munched) polar-like transform. It is intended for spider charts where connected paths are drawn as straight chords between axes (not circular arcs), and where background grid rings are polygons (not circles). Compared to ggplot2::coord_radial(), this coordinate system:

  • uses is_linear() = TRUE to prevent path "munching" into arcs;

  • supports a polygonal background grid (rings + spokes);

  • optionally draws axis labels (theta) and radial (r) labels using grid grobs in the panel background.

Typical usage is to map a discrete variable (categories) to x (theta) and a continuous variable (scores) to y (radius), then draw a polygon with geom_polygon().

plot2() uses this novel coordinate system to plot spider plots, created using plot2(..., type = "spider").

Usage

coord_spider(
  theta = "x",
  start = 0,
  clip = "off",
  inner.radius = 0,
  outer.radius = 0.8,
  axis_labels = TRUE,
  axis_label_size = 9,
  axis_label_pad_mm = 1,
  r_labels = TRUE,
  r_label_size = 8,
  r_label_pad_mm = 0
)

CoordSpider

Arguments

theta

Character scalar specifying which position aesthetic is interpreted as the angular coordinate (theta). Must be "x" or "y". In the common spider-chart case, use theta = "x" with a discrete x scale (categories around the circle) and a continuous y scale (radius). Setting theta = "y" swaps these roles.

start

Numeric scalar giving the angular offset in radians for the first axis. Angles increase according to the direction field stored in the coord (this implementation fixes direction = 1 internally). With start = 0, the first axis is at 12 o'clock (positive vertical). Use start = pi/2 to rotate the first axis to 3 o'clock, etc.

clip

Character scalar passed through to the coordinate system to control clipping of grobs to the panel. Use "on" to clip all drawing (including axis labels drawn in render_bg()) to the panel region, and "off" to allow grobs to extend outside the panel. When clip = "on", labels that lie beyond the panel boundary will be cut off, so in that case it is recommended to set outer.radius < 1 to reserve headroom inside the panel.

inner.radius

Numeric scalar in [0, 1) specifying the inner radius of the spider coordinate system as a fraction of the panel radius. Values greater than 0 create a "donut" / hollow centre. The data radius is linearly rescaled onto [inner.radius, outer.radius].

outer.radius

Numeric scalar in (0, 1] specifying the maximum radius used for drawing the spider geometry as a fraction of the panel radius. Setting outer.radius < 1 shrinks the spider grid and data polygon inward, thereby reserving whitespace inside the panel for labels while keeping clip = "on". This is the preferred way to create consistent headroom independent of plot margins and device size.

axis_labels

Logical; if TRUE, draw the theta-axis labels (typically the discrete category labels) at the ends of the spokes using grid::textGrob in the panel background. Labels are taken from the trained discrete limits of the theta scale.

axis_label_size

Numeric scalar giving the font size (in points) for theta-axis labels drawn when axis_labels = TRUE.

axis_label_pad_mm

Numeric scalar giving the outward padding (in mm) applied to theta-axis labels beyond the spoke endpoints. This padding is applied in npc coordinates via grid::unit(). Increase this to separate labels from the grid. When clip = "on", excessive padding may push labels outside the panel and cause clipping; prefer reducing padding or decreasing outer.radius' in that case.

r_labels

Logical; if TRUE, draw radial (r / y-scale) labels along the "upper" spoke (the spoke at angle start, i.e. 12 o'clock when start = 0). Breaks and labels are taken from the trained radial scale (typically the y scale when theta = "x"). This means user-supplied scale_y_continuous(breaks = ...) will control both the grid rings and the printed radial labels.

r_label_size

Numeric scalar giving the font size (in points) for radial labels drawn when r_labels = TRUE.

r_label_pad_mm

Numeric scalar giving the horizontal padding (in mm) applied to radial labels from the upper spoke. Use positive values to move labels to the right of the spoke. With clip = "on", large padding can cause clipping; consider smaller padding and/or smaller outer.radius.

Value

A ggproto object that inherits from ggplot2::Coord. This object is used by ggplot2 to transform data coordinates and to render the panel background (grid rings/spokes and optional axis labels).

Examples

# Example data: one observation across five metrics.
# 'metric' is the discrete theta axis, 'value' is the radial axis.
library(ggplot2)

df <- data.frame(
  metric = c("Final exam grade",
             "Midterm grade",
             "Assignments completed",
             "Hours studying",
             "Classes attended"),
  value = c(70, 60, 10, 15, 25))
df

ggplot(df, aes(metric, value, group = 1)) +
    # Spider/Radar plots only require geom_polygon() with coord_spider():
    geom_polygon(colour = "red", fill = NA, linewidth = 1) +
    coord_spider()
    
ggplot(df, aes(metric, value, group = 1)) +
    geom_polygon(colour = "red", fill = NA, linewidth = 1) +
    geom_point(colour = "red", size = 3) +
    coord_spider(inner.radius = 0.25,
                 r_label_pad_mm = 2) +
    scale_y_continuous(limits = c(0, 100),
                       breaks = c(0, 25, 50, 75, 100)) +
    theme(panel.grid.major.y = element_line(colour = "blue"))
    
df |>
  plot2(type = "spider")

Interactively Create a plot2

Description

This Shiny app allows for interactive creation of a plot2.

Usage

create_interactively(
  data = NULL,
  css_code = NULL,
  logo_path = system.file("logo.svg", package = "plot2"),
  pretty_labels = FALSE,
  hide_generated_code = FALSE,
  hide_export_buttons = NULL,
  upload_tab = FALSE,
  run = interactive()
)

Arguments

data

A data set to load, offered as 'Provided' in the data set selector. The generated code refers to it by its name, e.g. df |> plot2() for create_interactively(data = df). Not strictly required: in an interactive session, all data frames in the global environment are offered as well, together with the data sets of base R, plot2, ggplot2 and dplyr. Outside an interactive session (such as on a server), data frames in the global environment are not offered, so that the app does not expose what the hosting script has loaded.

css_code

Additional CSS code to load in the app.

logo_path

Path to the logo shown in the app. Default to the plot2 logo. Use NULL to not use a logo.

pretty_labels

A logical to switch to pretty, readable labels, instead of argument names in code style.

hide_generated_code

A logical to hide generated code.

hide_export_buttons

A logical to hide export buttons and functionality. TRUE will hide the elements completely, NULL will show a clickable text to expand buttons (default), FALSE will show the expanded buttons.

upload_tab

A logical to allow uploading data files. When TRUE, an Upload tab is added to the sidebar, with format-specific options for text (CSV, TSV, TXT), spreadsheet (Excel, OpenDocument), statistical software (SPSS, Stata, SAS, Minitab), Parquet, Feather, JSON, YAML, XML and HTML files; the data set selector then also offers "Upload data set...". R serialisation files (.rds, .rda) are not accepted, since reading them can run code: pass such data with the data argument instead. When FALSE (default), the app offers no way to upload files. Uploading requires the readxl package, and per format the package that reads it; administrators can install all of them with plot2:::install_shiny_deps().

run

A logical to run the app (default in an interactive session). Use run = FALSE to get the app object instead, for example to deploy it on a server, see Deployment.

Details

create_interactively.jpg

The app builds a plot2() call from the chosen settings, shows the plot and the code, and explains in a panel below the code what plot2() decided by itself.

Value

With run = TRUE, nothing (the app runs until it is closed). With run = FALSE, an app object of class shiny.appobj that can be run with shiny::runApp() or deployed.

Deployment

The app can run on a server for several users (e.g. Shiny Server or Posit Connect), with an app.R such as:

library(plot2)
create_interactively(run = FALSE)

On a server, the app treats everything a visitor types or sends as untrusted:

  • Settings are converted to values or checked expressions; nothing typed is run as R code. Calculations in the column selectors may only use a fixed list of computing functions (such as log(), mean() and n_distinct()), and the call is evaluated apart from the global environment, so it cannot reach other objects of the R process.

  • Data frames in the global environment are offered only in an interactive session; pass data with data to offer it on a server.

  • Uploads are only possible with upload_tab = TRUE; R serialisation files are never accepted. The maximum upload size is Shiny's own (option shiny.maxRequestSize, 5 MB by default).

  • Each session keeps its own plot, and raster exports are limited to 40 megapixels.

Each plot is computed in the R process of the app, so a visitor can still ask for plots that take long to compute, e.g. with very large data or a very small binwidth. Use the limits of the hosting platform (e.g. timeouts and the number of processes) as for any Shiny app.

Examples

## Not run: 

create_interactively()

iris |> create_interactively()

# With the upload tab for importing external data files:
create_interactively(upload_tab = TRUE)

# The app object, e.g. for app.R on a server:
app <- create_interactively(run = FALSE)

## End(Not run)

Use Decimal Comma?

Description

These functions determine which characters the decimal mark and big mark should be that are used in plotting. They base the determination on getOption("OutDec"), which is also what base::format() uses.

Usage

dec_mark()

big_mark()

Details

If the option "plot2.decimal.mark" is set, that value will be used for dec_mark() if it is either a comma or a full stop.

At default, big_mark() returns a full stop if dec_mark() returns a comma, and a space otherwise. If the option "plot2.big.mark" is set, that value will be used if it is either a comma (",") or a full stop (".") or a space (" ") or an empty character ("").

Examples

# at default, this follows `getOption("OutDec")`:
dec_mark()
# and big_mark() returns a space if dec_mark() returns ".":
big_mark()

# you you can set options to alter behaviour:
options(plot2.decimal.mark = ",", plot2.big.mark = ".")
dec_mark()
big_mark()

options(plot2.decimal.mark = ",", plot2.big.mark = NULL)
dec_mark()
big_mark()

options(plot2.big.mark = ",")
dec_mark()
big_mark()

# clean up
options(plot2.decimal.mark = NULL, plot2.big.mark = NULL)

Get (and Register) Colours from R, Viridis and More

Description

Retrieves, expands, and prints colours or palettes from R, viridisLite, or user-defined sources, with support for registering and unregistering custom colour sets for (automatic) reuse in plots.

Usage

get_colour(x, length = 1, transparency = 0)

register_colour(...)

unregister_colour(regex)

add_white(x, white)

Arguments

x

Colour or colour palette name. Input can be:

  • One of the colourblind-safe viridisLite palettes:

    • "viridis"

    • "magma"

    • "inferno"

    • "plasma"

    • "cividis"

    • "rocket"

    • "mako"

    • "turbo"

  • "ggplot2", which gives the colours that ggplot2 itself would use, i.e. the same as not setting a colour

  • One of the built-in R palettes from grDevices::palette.pals(), such as "R4", "Okabe-Ito" or "Tableau 10", or one of "topo", "heatmap", "rainbow", "terrain", "greyscale", "grayscale"

  • One of the built-in colours() in R (even case-insensitive), such as "bisque", "cornsilk4", "lightcoral", "salmon2", "slateblue"

  • One of the pre-registered colours using register_colour() (case-insensitive)

An invalid colour gives a warning and is replaced by grey, while valid colours and names are kept. A single unknown name, such as a mistyped palette, is replaced by the default colours. register_colour() gives an error for invalid colours.

length

Size of the vector to be returned.

transparency

Amount of transparency (0 = solid, 1 = fully transparent).

...

Named vectors with known, valid colours. They must be coercible with get_colour().

regex

A regular expression to unregister colours.

white

A number between ⁠[0, 1]⁠ to add white to x.

Details

Limitless Palette Length

A palette from R will be expanded where needed, so even get_colour("R4", length = 20) will work, despite "R4" only supporting a maximum of eight colours.

Registering Colours In Another Package

To register/unregister colours in another package, add something like this to a package file R/zzz.R:

#' @importFrom plot2 register_colour
.onLoad <- function(...) {
  register_colour(
    my_colour1  = "#007A8A",
    my_colour2  = "#2E8540",
    my_colour3  = "#5B3FA8",
    my_colours  = c("my_colour1", "my_colour2", "my_colour3"))

  # set as default upon package load
  options(plot2.colour = "my_colours",
          plot2.colour_font_secondary = "my_colour1")
}

#' @importFrom plot2 unregister_colour
.onUnload <- function(...) {
  unregister_colour("^my_colour") # this is a regular expression
  options(plot2.colour = NULL,
          plot2.colour_font_secondary = NULL)
}

Do not forget to add plot2 to ⁠Imports:⁠ in the DESCRIPTION file of your package.

Value

get_colour() returns a character vector in HTML format (i.e., "#AABBCC") with new class colour. register_colour() and unregister_colour() are called for their side effect and return NULL invisibly.

Examples

get_colour(c("red", "tan1", "#ffa", "FFAA00"))

par(mar = c(0.5, 2.5, 1.5, 0)) # set plot margins for below plots

# all colourblind-safe colour palettes from the famous viridisLite package
barplot(1:7,
        col = get_colour("viridis", 7))
barplot(1:7,
        col = get_colour("magma", 7))

barplot(8:1,
        col = get_colour("R4", 8),
        main = "Some palettes have only 8 colours...")
barplot(20:1,
        col = get_colour("R4", 20),
        main = "Not anymore!")


# Registering Colours --------------------------------------------------

# to register colours, use named input - the values will be evaluated
# with get_colour()
get_colour("red123")
register_colour(red123 = "red", red456 = "#ff0000", red789 = "f00")
get_colour("red123")
get_colour("red456")
get_colour("red789")

# you can also register a group name
register_colour(red_group = c("red123", "ff4400", "red3", "red4"))
get_colour("red_group")
get_colour("red_group", 3)

# Registering colours is ideal for your (organisational) style in plots.
# Let's say these are your style:
register_colour(navy_blue = "#1F3A93",
                burnt_orange = "#D35400",
                forest_green = "#2C6F47",
                goldenrod_yellow = "#DAA520",
                slate_grey = "#708090",
                plum_purple = "#8E4585")

# Then register the whole colour list too:
register_colour(my_organisation = c("navy_blue", "burnt_orange",
                                    "forest_green", "goldenrod_yellow",
                                    "slate_grey", "plum_purple"))
# Check that it works:
get_colour("my_organisation", length = 6)

# Now use it in plots as you like:
iris |>
  plot2(x = Species, y = where(is.double), colour = "my_organisation")

# Or even set the option to use it in any future plot:
options(plot2.colour = "my_organisation")

iris |>
  plot2(x = Species, y = where(is.double))

# reset option again
options(plot2.colour = NULL)

# unregister colours with a regular expression on their names
unregister_colour("^red")
unregister_colour("^my_organisation$")


# Use add_white() to add white to existing colours:
colours <- get_colour("R4", 6)
colours
add_white(colours, 0.25)
add_white(colours, 0.5)
add_white(colours, 0.75)

add_white("red", 0)     # 100% red
add_white("red", 1/256)
add_white("red", 1/128)
add_white("red", 1/64)
add_white("red", 1/32)
add_white("red", 1/16)
add_white("red", 1/8)
add_white("red", 1/4)
add_white("red", 1/2)
add_white("red", 1)     # 100% white

Get Plot Title

Description

Get the title of the plot, or a default value. If the title is not set in a plot, this function tries to generate one from the plot mapping.

Usage

get_plot_title(plot, valid_filename = TRUE, default = NULL)

Arguments

plot

A ggplot2 plot.

valid_filename

A logical to indicate whether the returned value should be a valid filename, defaults to TRUE.

default

The default value, if a plot title is absent.

Examples

without_title <- plot2(mtcars)
with_title <- plot2(mtcars, title = "Plotting **mpg** vs. **cyl**!")

# default is a guess:
get_plot_title(without_title)
get_plot_title(without_title, valid_filename = FALSE)
get_plot_title(with_title)
get_plot_title(with_title, valid_filename = FALSE)

# unless 'default' is set (only affects plots without title):
get_plot_title(without_title, default = "title")
get_plot_title(with_title, default = "title")

Label Currencies

Description

Format numbers as currency, rounding values to dollars or cents using a convenient heuristic.

Usage

euros(x, big.mark = big_mark(), decimal.mark = dec_mark(), ...)

dollars(x, big.mark = big_mark(), decimal.mark = dec_mark(), ...)

Arguments

x

Values.

big.mark

Thousands separator, defaults to big_mark().

decimal.mark

Decimal mark, defaults to dec_mark().

...

Any argument to give to the geom. This will override automatically-set settings for the geom.

Details

The euro sign of euros() cannot be encoded by the default pdf() device. To save such plots as PDF, use the Cairo device, e.g. ggplot2::ggsave("plot.pdf", device = grDevices::cairo_pdf), or in R Markdown the chunk option dev = "cairo_pdf".

Examples

euros(c(1500, 2499.5))
dollars(c(1500, 2499.5))

profit <- data.frame(group = LETTERS[1:4],
                     profit = runif(4, 10000, 25000))

# the default pdf() and postscript() devices cannot draw the euro sign;
# use e.g. cairo_pdf(), png() or the RStudio plot pane instead
if (!names(grDevices::dev.cur()) %in% c("pdf", "postscript")) {
  profit |>
    plot2(y.labels = euros,
          datalabels = FALSE)
}
if (!names(grDevices::dev.cur()) %in% c("pdf", "postscript")) {
  profit |>
    plot2(y.labels = euros,
          datalabels.format = euros)
}

Convert Markdown to Plotmath Expression

Description

This function converts common markdown language to an R plotmath expression. plot2() uses this function internally to convert plot titles and axis titles.

Usage

md_to_expression(x)

Arguments

x

Text to convert. Each element is converted separately.

Details

This function only supports common markdown (italic, bold, bold-italic, subscript, superscript), but also supports some additional functionalities for more advanced expressions using R plotmath. Please see Examples.

Text between dollar signs is used as plotmath, as in Pandoc: the opening $ must be followed and the closing $ preceded by a non-space character, and the closing $ must not be followed by a digit. A single $ ("Costs in $") or amounts such as "$5 to $10" therefore stay text. Apostrophes and backslashes in the text are kept.

In plot2(), this function can be also set to argument category.labels to print the data values as expressions:

  • plot2(..., category.labels = md_to_expression)

Value

An expression if x is length 1, or a list of expressions otherwise

Examples

# use '*' for italics, not '_', to prevent conflicts with variable naming
md_to_expression("this is *italic* text, this is _not italic_ text")

md_to_expression("this is **bold** text")

md_to_expression("this is ***bold and italic*** text")

# subscript and superscript can be done in HTML or markdown with curly brackets:
md_to_expression("this is some<sub>subscripted text</sub>, this is also_{subscripted} text")
md_to_expression("this is some<sup>superscripted text</sup>, this is also^{superscripted} text")

# use $...$ to use any plotmath expression as-is (see ?plotmath):
md_to_expression("text $omega$ text, $a[x]$")

mtcars |>
  plot2(mpg, hp,
        title = "*These are* the **Greek** lower $omega$ and upper $Omega$",
        x.title = "x_{mpg}",
        y.title = "y_{hp}")
        
mtcars |> 
  plot2(mpg, hp,
        title = "$f[X](x)==frac(1, sigma*sqrt(2*pi))*plain(e)^{frac(-(x-mu)^2, 2*sigma^2)}$",
        subtitle = "Some insane $widehat(plotmath)$ title")

Move a ggplot Layer

Description

Use this function to move a certain plot layer up or down.

Usage

move_layer(plot, move = -1, layer = length(plot$layers))

Arguments

plot

A ggplot object.

move

Number of layers to move layer: a negative value moves it down (drawn earlier, so below other layers), a positive value moves it up. The new position is limited to the existing layers. Defaults to -1, one layer down.

layer

The number of the layer to move, defaults to the top layer.

Value

A ggplot object with the layers in the new order.

Examples

p <- plot2(iris, Sepal.Length, Sepal.Width, colour = "grey75") |>
  add_line(y = mean(Sepal.Width), colour = "red", linewidth = 2)

# the line is drawn on top of the points
p

# move the line one layer down, below the points
move_layer(p)

Example Geography Data Set: the Netherlands

Description

A data set containing the geometries of the twelve provinces of the Netherlands, according to Statistics Netherlands (2021).

Usage

netherlands

Format

A data.frame with 12 observations and 3 variables:

  • province
    name of the Dutch province

  • area_km2
    area in square kilometres

  • geometry
    geometry of the province, of class sfc_MULTIPOLYGON/sfc


Create a ggplot in a Single Call

Description

plot2() creates a complete ggplot in one call. It takes the place of the usual combination of ggplot(), aes(), a ⁠geom_*()⁠ function, scales, labels and a theme, and of the data preparation that often precedes it with group_by(), count(), mutate() or summarise(): calculations can be given in the arguments directly, such as y = n() or x = format(date, "%Y").

Besides data frames, plot2() accepts vectors, matrices, formulas, 'sf' objects and other classes; see plot2-methods.

Usage

plot2(
  .data,
  x = NULL,
  y = NULL,
  category = NULL,
  facet = NULL,
  type = NULL,
  x.title = TRUE,
  y.title = TRUE,
  category.title = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  tag = NULL,
  title.linelength = 60,
  title.colour = getOption("plot2.colour_font_primary", "black"),
  subtitle.linelength = 60,
  subtitle.colour = getOption("plot2.colour_font_secondary", "grey35"),
  na.replace = "",
  na.rm = FALSE,
  facet.position = "top",
  facet.colour_fill = NULL,
  facet.bold = TRUE,
  facet.italic = FALSE,
  facet.size = 10,
  facet.margin = 8,
  facet.repeat_labels_x = TRUE,
  facet.repeat_labels_y = NULL,
  facet.fixed_y = NULL,
  facet.fixed_x = NULL,
  facet.drop = FALSE,
  facet.nrow = NULL,
  facet.relative = FALSE,
  x.date_breaks = NULL,
  x.date_labels = NULL,
  x.date_remove_years = NULL,
  category.focus = NULL,
  colour = getOption("plot2.colour", "ggplot2"),
  colour_fill = NULL,
  colour_transparency = 0,
  x.label_angle = 0,
  x.label_align = NULL,
  x.label_italic = FALSE,
  x.remove = FALSE,
  x.position = "bottom",
  x.max_items = NULL,
  x.max_txt = "(rest, x%n)",
  category.max_items = Inf,
  category.max_txt = "(rest, x%n)",
  facet.max_items = Inf,
  facet.max_txt = "(rest, x%n)",
  x.breaks = NULL,
  x.n_breaks = NULL,
  x.transform = "identity",
  x.expand = NULL,
  x.limits = NULL,
  x.labels = NULL,
  x.character = NULL,
  x.drop = FALSE,
  x.zoom = NULL,
  y.remove = FALSE,
  y.24h = FALSE,
  y.age = FALSE,
  y.scientific = NULL,
  y.percent = NULL,
  y.percent_break = NULL,
  y.breaks = NULL,
  y.n_breaks = NULL,
  y.limits = NULL,
  y.labels = NULL,
  y.expand = NULL,
  y.transform = "identity",
  y.position = "left",
  y.zoom = FALSE,
  y_secondary = NULL,
  y_secondary.type = NULL,
  y_secondary.title = TRUE,
  y_secondary.colour = NULL,
  y_secondary.colour_fill = NULL,
  y_secondary.scientific = NULL,
  y_secondary.percent = FALSE,
  y_secondary.labels = NULL,
  category.type = "colour",
  category.labels = NULL,
  category.percent = FALSE,
  category.breaks = NULL,
  category.limits = NULL,
  category.expand = 0,
  category.midpoint = NULL,
  category.transform = "identity",
  category.date_breaks = NULL,
  category.date_labels = NULL,
  category.character = NULL,
  x.sort = NULL,
  category.sort = TRUE,
  facet.sort = TRUE,
  x.complete = NULL,
  category.complete = NULL,
  facet.complete = NULL,
  datalabels = NULL,
  datalabels.round = ifelse(isTRUE(y.percent), 2, 1),
  datalabels.format = "%n",
  datalabels.colour = "grey25",
  datalabels.colour_fill = NULL,
  datalabels.size = (3 * text_factor),
  datalabels.angle = 0,
  datalabels.lineheight = 1,
  datalabels.percent_by = "x",
  decimal.mark = dec_mark(),
  big.mark = big_mark(),
  summarise_function = NULL,
  stacked = FALSE,
  stacked_fill = FALSE,
  horizontal = FALSE,
  reverse = horizontal,
  smooth = NULL,
  smooth.method = NULL,
  smooth.formula = NULL,
  smooth.se = TRUE,
  smooth.level = 0.95,
  smooth.alpha = NULL,
  smooth.linewidth = NULL,
  smooth.linetype = NULL,
  smooth.colour = NULL,
  size = NULL,
  linetype = 1,
  linewidth = NULL,
  binwidth = NULL,
  width = NULL,
  jitter_seed = NA,
  violin_scale = "count",
  legend = NULL,
  legend.position = NULL,
  legend.title = NULL,
  legend.reverse = FALSE,
  legend.nrow = NULL,
  legend.barheight = 6,
  legend.barwidth = 1.5,
  legend.nbin = 300,
  legend.italic = FALSE,
  sankey_node_width = 0.15,
  sankey_node_whitespace = 0.03,
  sankey_alpha = 0.5,
  sankey_remove_axes = NULL,
  zoom = FALSE,
  sep = " / ",
  print = FALSE,
  text_factor = getOption("plot2.text_factor", 1),
  font = getOption("plot2.font"),
  theme = getOption("plot2.theme", "theme_minimal2"),
  background = getOption("plot2.colour_background", "white"),
  markdown = TRUE,
  data = NULL,
  ...
)

Arguments

.data

Data to plot. A single character value that is the name of a data frame in the calling environment (such as plot2("df"), as used in tool calling) plots that data frame; only the calling environment is searched, not the search path.

x

Plotting 'direction' for the X-axis. This can be:

  • A single variable from .data, such as x = column1

  • A function to calculate over one or more variables from .data, such as x = format(column1, "%Y"), or x = ifelse(column1 == "A", "Group A", "Other")

  • Multiple variables from .data, such as x = c(column1, column2, column2), or using selection helpers such as x = where(is.character) or x = starts_with("var_") (only allowed and required for Sankey plots using type = "sankey")

y

Values to use for plotting along the Y-axis. This can be:

  • A single variable from .data, such as y = column1

  • Multiple variables from .data, such as y = c(column1, column2) or y = c(name1 = column1, "name 2" = column2), or using selection helpers such as y = where(is.double) or y = starts_with("var_") (multiple variables only allowed if category is not set)

  • A function to calculate over .data returning a single value, such as y = n() for the row count, or based on other variables such as y = n_distinct(person_id), y = max(column1), or y = median(column2) / column3

  • A function to calculate over .data returning multiple values, such as y = quantile(column1, c(0.25, 0.75)) or y = range(age) (multiple values only allowed if category is not set)

category, facet

Plotting 'direction' (category is called 'fill' and 'colour' in ggplot2). This can be:

  • A single variable from .data, such as category = column1

  • A function to calculate over one or more variables from .data, such as category = median(column2) / column3, or facet = ifelse(column1 == "A", "Group A", "Other")

  • Multiple variables from .data, such as facet = c(column1, column2) (use sep to control the separator character)

  • One or more variables from .data using selection helpers, such as category = where(is.double) or facet = starts_with("var_")

The category can also be a date or date/time (class Date or POSIXt).

type

Type of visualisation to use. This can be:

  • A ggplot2 geom name or their abbreviation such as "col" and "point". All geoms are supported (including geom_blank()).

    Full function names can be used (e.g., "geom_histogram"), but they can also be abbreviated (e.g., "h", "hist"). The following geoms can be abbreviated by their first character: area ("a"), boxplot ("b"), column ("c"), histogram ("h"), jitter ("j"), line ("l"), point ("p"), ribbon ("r"), and violin ("v"). Beeswarm plots ("beeswarm", short: "bs") require the ggbeeswarm package.

    Please note: in ggplot2, 'bars' and 'columns' are equal, while it is common to many people that 'bars' are oriented horizontally and 'columns' are oriented vertically since Microsoft Excel has been using these terms this way for many years. For this reason, type = "bar" will set type = "col" and horizontal = TRUE.

  • One of these additional types:

    • "barpercent" (short: "bp"), which is effectively a shortcut to set type = "col" and horizontal = TRUE and x.max_items = 10 and x.sort = "freq-desc" and datalabels.format = "%n (%p)".

    • "dumbbell" (short: "d" or "db"), which sets type = "point" and horizontal = TRUE, and adds a line between the points (using geom_segment()). The line colour cannot be changed. This plot type is only possible when the category has two distinct values.

    • "linedot" or "line-point" (short: "ld" or "lp"), which sets type = "line" and adds two point geoms using add_point(); one with large white dots and one with smaller dots using the colours set in colour. This is essentially equal to base R plot(..., type = "b") but with closed shapes.

    • "back-to-back" (short: "b2b", or "butterfly", "tornado" or "population") creates a back-to-back plot, sometimes called a Tornado diagram, a butterfly plot, or a Population Pyramid. It uses facet to distinguish the left and right plots. Therefore, facet must be set to (a column containing) two unique values.

    • "upset" or "UpSet" (short: "u") creates an UpSet plot, which requires x to contain multiple variables from .data that contain 0/1 or FALSE/TRUE values. It is also possible to provide y, on which then summarise_function will be applied.

    • "sankey" (short: "s") creates a Sankey plot using category for the flows and requires x to contain multiple variables from .data. At default, it also sets x.expand = c(0.05, 0.05) and y.limits = c(NA, NA) and y.expand = c(0.01, 0.01). The so-called 'nodes' (the 'blocks' with text) are considered the datalabels, so you can set the text size and colour of the nodes using datalabels.size, datalabels.colour, and datalabels.colour_fill. The transparency of the flows can be set using sankey_alpha, and the width of the nodes can be set using sankey_node_width. Sankey plots can also be flipped using horizontal = TRUE, and the label angles can be set with datalabels.angle.

    • "spider" or "radar" (short: "sp") creates a Spider plot using our novel CoordSpider coordinate system. Facets are supported, always with the same scale in all facets.

  • Left blank. In this case, the type will be determined automatically: "boxplot" if there is no X-axis or if the length of unique values per X-axis item is at least 3, "point" if both the y and x axes are numeric, "line" if the X-axis contains dates with one value each (a time series), and the option "plot2.default_type" otherwise (which defaults to "col", and accepts any value of type, such as "line" or "l"). Use type = "blank" or type = "geom_blank" to not add a geom.

title, subtitle, caption, tag, x.title, y.title, category.title, legend.title, y_secondary.title

A title to use. This can be:

  • A character, which supports markdown by using md_to_expression() internally if markdown = TRUE (which is the default)

  • A function to calculate over .data, such as title = paste("Based on n =", n_distinct(person_id), "individuals") or subtitle = paste("Total rows:", n()), see Examples

  • An expression, e.g. using parse(text = "...")

The category.title defaults to TRUE if the legend items are numeric. category.title and legend.title are the same setting; use one of them.

title.linelength

Maximum number of characters per line in the title, before a linebreak occurs.

title.colour

Text colour of the title.

subtitle.linelength

Maximum number of characters per line in the subtitle, before a linebreak occurs.

subtitle.colour

Text colour of the subtitle.

na.replace

Character to put in place of NA values if na.rm = FALSE.

na.rm

Remove NA values from showing in the plot.

facet.position, facet.colour_fill, facet.bold, facet.italic, facet.size, facet.margin, facet.repeat_labels_x, facet.repeat_labels_y, facet.drop, facet.nrow, facet.relative

Additional settings for the plotting direction facet. facet.repeat_labels_x and facet.repeat_labels_y repeat the axis labels in every facet, which also makes the scales of that axis free (unless facet.fixed_x or facet.fixed_y is TRUE).

facet.fixed_y

A logical to indicate whether all y scales should have the same limits. If not set, this depends on the data: TRUE only if the coefficient of variation (standard deviation divided by mean) of the maximum y values per facet, after y.transform, is less than 25%, otherwise every facet gets its own y scale. Both outcomes are reported in a message. Since this can change when the data change (e.g., next month's data), set facet.fixed_y = TRUE when panels must be compared.

facet.fixed_x

A logical to indicate whether all x scales should have the same breaks. This acts like the inverse of x.drop. If not set and x is numeric, the same rule as for facet.fixed_y applies to the maximum x values per facet, compared after x.transform (so as plotted, e.g. on a log scale).

x.date_breaks

Breaks to use when the X-axis contains dates, will be determined automatically if left blank. This accepts values such as "1 day" and "2 years".

x.date_labels

Labels to use when the X-axis contains dates, will be determined automatically if left blank. This accepts 'Excel' date-language such as "d mmmm yyyy": d/dd (day), ddd/dddd (weekday name), mm (month number), mmm/mmmm (month name), yy/yyyy (year), q/qq (quarter: 1 or Q1), w/ww (ISO week), h/hh (hour), MM (minutes), ss (seconds). Other words are kept as they are (e.g. "Week ww"), and text in single quotes is always kept literally (e.g. "'d' d"). A format containing ⁠%⁠ is used as a strftime() format. Month and weekday names follow the option plot2.language if set, and the system locale otherwise.

x.date_remove_years

A logical to indicate whether the years of all x values must be unified. This will set the years of all x values to 1970 if the data does not contain a leap year, and to 1972 otherwise. This allows to plot years on the category while maintaining a date range on x. The default is FALSE, unless category contains all years present in x.

category.focus

A value of category that should be highlighted, meaning that all other values in category will be greyed out. This can also be a numeric value between 1 and the length of unique values of category, e.g. category.focus = 2 to focus on the second legend item.

colour

Colour(s) to set, will be evaluated with get_colour() if set. This can also be one of the viridis colours with automatic implementation for any plot: "viridis", "magma", "inferno", "plasma", "cividis", "rocket", "mako" or "turbo". Also, this can be a named vector to match values of category, see Examples. Using a named vector can be used to manually sort the values of category.

colour_fill

Colour(s) to be used for filling, will be determined automatically if left blank and will be evaluated with get_colour().

colour_transparency

Amount of transparency for colour/colour_fill (0 = solid, 1 = fully transparent).

x.label_angle

Angle to use for the X-axis in a counter-clockwise direction (i.e., a value of 90 will orient the axis labels from bottom to top, a value of 270 will orient the axis labels from top to bottom).

x.label_align

Alignment for the X-axis between 0 (left aligned) and 1 (right aligned). If not set, rotated labels (see x.label_angle) are anchored at their ticks with guide_axis(angle = ), for every angle and also when horizontal = TRUE.

x.label_italic

logical to indicate whether the x labels should be in italics.

x.remove, y.remove

A logical to indicate whether the axis labels and title should be removed.

x.position, y.position

Position of the axis.

x.max_items, category.max_items, facet.max_items

Maximum number of items to show, including the item that holds the rest: x.max_items = 5 shows four values and the rest, see x.max_txt. Defaults to infinite. Left NULL (default for x.max_items), this is infinite, except for type = "barpercent" and back-to-back plots (10). The remaining values are grouped into one item and summarised using the summarise_function function. Please note: the sorting will be applied first, so that e.g. x.sort = "freq-desc" with x.max_items = 5 shows the four most frequent values of the X-axis and the rest.

x.max_txt, category.max_txt, facet.max_txt

The text of the item that holds the values beyond ⁠*.max_items⁠. The placeholder ⁠%n⁠ is replaced with the number of values in that item, and ⁠%p⁠ with their share of the total of y (or of the rows, when y is not numeric). For example, the default "(rest, x%n)" gives "(rest, x4)" for four values.

x.breaks, y.breaks

A breaks function or numeric vector to use for the axis.

x.n_breaks, y.n_breaks

Number of breaks, only useful if x.breaks or y.breaks respectively is NULL.

x.transform, y.transform, category.transform

A transformation function to use, e.g. "log2". This can be: "asinh", "asn", "atanh", "boxcox", "compose", "date", "exp", "hms", "identity", "log", "log10", "log1p", "log2", "logit", "modulus", "probability", "probit", "pseudo_log", "reciprocal", "reverse", "sqrt", "time", "timespan", "yj".

x.expand, y.expand

expansion to use for the axis, can be length 1 or 2. Left NULL (default), they are determined automatically: x.expand adds half a category on both sides of a discrete axis and a proportion of the range on a continuous axis, y.expand adds 25% above the data; both are 0 for sf objects or when the limits are set. An explicit value is used as given.

x.limits, y.limits

Limits to use for the axis, must be length 2. Use NA for the highest or lowest value in the data, e.g. y.limits = c(0, NA) to have the y scale start at zero. For a discrete x axis, x.limits are the items to show, in this order.

x.labels, y.labels, y_secondary.labels

A labels function or character vector to use for the axis.

x.character

A logical to indicate whether the values of the X-axis should be forced to character. If not set, whole numbers that look like years (1900 to 25 years after the current year) or months (exactly 1 to 12) become character when type is not set or is a discrete type such as "col" or "boxplot", with a message; years only so with at most one value per year (per category and facet), so that e.g. many measurements per year form a numeric axis; for continuous types such as "point", "line" and "area" they stay numeric, and years are then labelled without a thousands separator. Numeric values also become character for other discrete types, and always for "boxplot", "violin" and "dumbbell". Use x.character = FALSE to keep numeric values.

x.drop

logical to indicate whether factor levels should be dropped.

x.zoom, y.zoom

A logical to indicate if the axis should be zoomed on the data, i.e., cover the range of the data instead of starting at 0. Left NULL (default for x.zoom), the x axis is zoomed for plot types with a continuous x axis (such as histograms), and for years that stay numeric (such as in a line plot) only. This sets x.limits = c(NA, NA) (or y.limits) and, unless x.expand (or y.expand) is set, a 5% expansion on both sides, like ggplot2 does. It has no effect if x.limits (or y.limits) is set.

y.24h

A logical to indicate whether the y labels and breaks should be formatted as 24-hour sequences.

y.age

A logical to indicate whether the y labels and breaks should be formatted as ages in years.

y.scientific, y_secondary.scientific

A logical to indicate whether the y labels should be formatted in scientific notation. If not set, scientific notation is used only for labels of one billion (1e9) or more, or for non-zero labels below 0.0001; other labels use big.mark, e.g. ⁠2 000 000⁠.

y.percent, y_secondary.percent

A logical to indicate whether the y labels should be formatted as percentages. Left NULL (default for y.percent), percentages are used for density plots only.

y.percent_break

A value on which the Y-axis should have breaks if y.percent = TRUE. Left NULL (default), this is 0.1 (10%), widened to keep about 10 labels and narrowed if that would give three or fewer labels. An explicit value is used as given.

y_secondary

Values to use for plotting along the secondary Y-axis. This functionality is poorly supported by ggplot2 and might give unexpected results. Setting the secondary Y-axis will set the colour to the axis titles.

y_secondary.type

Type of the secondary series, see type. The default (NULL) is a line with points if the primary type is a column or bar plot, so that the secondary series does not cover the bars, and the primary type otherwise.

y_secondary.colour, y_secondary.colour_fill

Colours to set for the secondary Y-axis, will be evaluated with get_colour(). Left NULL (default), the second colour of the plot2.colour option is used.

category.type

Type of the category, one or more of: "colour" (default), "shape", "size", "linetype", "linewidth", "alpha". There is no need to set "fill", as plot2 handles colour-setting internally and determines automatically whether the colour or fill aesthetic must be used.

category.labels, category.percent, category.breaks, category.expand, category.midpoint

Settings for the plotting direction category.

category.limits

Limits to use for a numeric category, must be length 2. Use NA for the highest or lowest value in the data, e.g. category.limits = c(0, NA) to have the scale start at zero. If not set, the limits are the range of the data, rounded outwards to pretty values with pretty() (e.g., values from 12 to 87 give limits 0 to 100). With three colours and category.midpoint set, the limits are made symmetric around the midpoint.

category.date_breaks

Breaks to use when the category contains dates, will be determined automatically if left blank. This will be passed on to seq.Date(by = ...) and thus can be: a number, taken to be in days, or a character string containing one of "day", "week", "month", "quarter" or "year" (optionally preceded by an integer and a space, and/or followed by "s").

category.date_labels

Labels to use when the category contains dates, will be determined automatically if left blank. This accepts 'Excel' date-language such as "d mmmm yyyy".

category.character

A logical to indicate whether the values of the category should be forced to character. If not set, whole numbers that look like years (1900 to 25 years after the current year) or months (exactly 1 to 12) become character, with a message. Use category.character = FALSE to keep numeric values.

x.sort, category.sort, facet.sort

Sorting of the plotting direction. category.sort and facet.sort default to TRUE; x.sort defaults to NULL, which sorts text and factors as TRUE and leaves continuous values (such as dates and numbers) unsorted. Applying one of the sorting methods will transform the values to an ordered factor, which ggplot2 uses to orient the data. Valid values are:

  • A manual vector of values

  • TRUE: sort factors on their levels, otherwise sort ascending on alphabet, while maintaining numbers in the text (numeric sort)

  • FALSE: sort according to the order in the data

  • NULL: sort automatically, as described above

  • "asc", "alpha" or "alpha-asc": sort as TRUE

  • "desc" or "alpha-desc": sort factors on their reversed levels, otherwise sort descending on alphabet, while maintaining numbers in the text (numeric sort)

  • "order" or "inorder": sort as FALSE

  • "freq" or "freq-desc": sort descending according to the frequencies of y computed by summarise_function (highest value first)

  • "freq-asc": sort ascending according to the frequencies of y computed by summarise_function (lowest value first)

x.complete, category.complete, facet.complete

A value to complete the data. This makes use of tidyr::full_seq() and tidyr::complete(). For example, using x.complete = 0 will apply data |> complete(x = full_seq(x, ...), fill = list(y = 0)), crossed with the values of category and facet if set. Numeric values and dates are completed with tidyr::full_seq() at their observed resolution, date-times at their observed interval, and character values and factors with their unique values or levels. Using value TRUE (e.g., x.complete = TRUE) is identical to using value 0.

datalabels

Values to show as datalabels, see also datalabels.format. This can be:

  • NULL (default): automatic. This shows the values of y in column-type plots, or when plotting spatial 'sf' data, the values of the first column, with a maximum of 25 labels and none for continuous plot types such as lines and points.

  • TRUE to always show the values of y, without the maximum of 25 labels, or FALSE to remove datalabels

  • A function to calculate over .data, such as datalabels = paste(round(column1), "\n", column2)

datalabels.round

Number of digits to round the datalabels, applies to both "%n" and "%p" for replacement (see datalabels.format).

datalabels.format

Format to use for datalabels. This can be a function (such as euros()) or a text. For the text, "%n" will be replaced by the count number, and "%p" will be replaced by the percentage (see datalabels.percent_by). Use datalabels.format = NULL to not transform the datalabels.

datalabels.colour, datalabels.colour_fill, datalabels.size, datalabels.angle, datalabels.lineheight

Settings for the datalabels. Rotated datalabels (datalabels.angle) start or end at their bar with a small fixed gap; if y.expand and y.limits are not set, the value axis gets extra room for long rotated labels, estimated for a figure of about 6 by 4 inches.

datalabels.percent_by

Group within which the "%p" percentages of datalabels.format sum to 100%. This can be:

  • "x" (default): within each x value and facet, so that the stacked or dodged bars of one x value sum to 100%. Without a category, each x value has a single bar, so this is the same as "facet".

  • "category": within each category and facet

  • "facet": within each facet

  • "total": over all data in the plot

decimal.mark

Decimal mark, defaults to dec_mark().

big.mark

Thousands separator, defaults to big_mark().

summarise_function

A function to use if the data has to be summarised, see Examples. Left NULL (default), this is sum(), except when y contains several columns (then the values are not summarised). Use FALSE to not summarise the data at all.

stacked

A logical to indicate that values must be stacked, or "fill" to stack them to 100% (the same as stacked_fill = TRUE).

stacked_fill

A logical to indicate that values must be filled (i.e., stacked to 100%). If TRUE, this takes precedence over stacked.

horizontal

A logical to turn the plot 90 degrees using coord_flip(). This option also updates some theme options, so that e.g., x.label_italic will still apply to the original X-axis.

reverse

A logical to reverse the values of category. Use legend.reverse to reverse the legend of category.

smooth

A logical to add a smooth. In histograms, this will add the density count as an overlaying line (default: TRUE). In all other cases, a smooth will be added using geom_smooth() (default: FALSE).

smooth.method, smooth.formula, smooth.se, smooth.level, smooth.alpha, smooth.linewidth, smooth.linetype, smooth.colour

Settings for smooth. If not set, smooth.method and smooth.formula are chosen as in ggplot2: "loess" with y ~ x if the largest group (per category and facet) has fewer than 1000 values, and "gam" with y ~ s(x, bs = "cs") otherwise. The lines of the smooth are not affected by colour_transparency.

size

Size of the geom. Defaults to 2 for geoms point, jitter, and beeswarm; 4 for UpSet plots (using type = "upset"); 5 for dumbbell plots (using type = "dumbbell"); 0.75 otherwise.

linetype

Linetype of the geom, only suitable for geoms that draw lines. Possible options are:

  1. "solid" (default)

  2. "dashed"

  3. "dotted"

  4. "dotdash"

  5. "longdash"

  6. "twodash"

Both numbers and text are supported, e.g., linetype = 2 and linetype = "dashed" yield the same results.

linewidth

Linewidth of the geom, only suitable for geoms that draw lines. Defaults to:

  • 0.10 for sf

  • 0.25 for geoms that are continuous and have fills (such as area), except for geoms boxplot and violin

  • 1.0 for dumbbell plots (using type = "dumbbell") and UpSet plots (using type = "upset")

  • 0.5 otherwise (such as geoms line, boxplot, violin, and histogram)

binwidth

Width of bins (only useful for type = "histogram"), can be specified as a numeric value or as a function that calculates width from x, see geom_histogram(). It defaults to approx. diff(range(x)) divided by 12 to 22 based on the data.

width

Width of the geom. Defaults to 0.66 for geoms boxplot, violin and jitter, and to 0.5 otherwise.

jitter_seed

Seed (randomisation factor) to be set when using type = "jitter".

violin_scale

Scale to be set when using type = "violin", can also be set to "area".

legend

A logical to show (TRUE) or hide (FALSE) the legend, i.e. the box explaining the values of category. The default NULL shows it when the plot has a category.

legend.position

Position of the legend. This can be:

  • "top", "right", "bottom" or "left", can be abbreviated

  • "inside", to place the legend inside the plot area at ggplot2's default position

  • Two numbers between 0 and 1, to place the legend inside the plot area at these relative coordinates, e.g. c(0.95, 0.95) for the top right

  • "none", FALSE or NA to remove the legend

The default NULL sets it automatically: "right" for numeric category values and 'sf' plots, and "top" otherwise.

legend.reverse, legend.barheight, legend.barwidth, legend.nbin, legend.italic, legend.nrow

Other settings for the legend.

sankey_node_width

Width of the vertical nodes in a Sankey plot.

sankey_node_whitespace

Whitespace between the nodes in a Sankey plot.

sankey_alpha

Alpha of the flows in a Sankey plot.

sankey_remove_axes

Logical to indicate whether all axes must be removed in a Sankey plot.

zoom

A logical to indicate if the plot should be scaled to the data, i.e., not having the x and y axes to start at 0. This is identical to setting x.zoom = TRUE and y.zoom = TRUE.

sep

Separator character to use if multiple columns are given to either of the three directions: x, category and facet, e.g. facet = c(column1, column2).

print

A logical to indicate if the result should be printed instead of just returned.

text_factor

Text factor to use, which will apply to all texts shown in the plot.

font

Font (family) to use, can be set with options(plot2.font = "..."). Can be any installed system font or any of the > 1400 font names from Google Fonts. Custom fonts require the showtext, showtextdb and sysfonts packages. A Google Font that is not installed is downloaded once into the user cache folder of plot2 (tools::R_user_dir("plot2", "cache")); fonts that have not been used for 90 days are removed from it automatically. The font is applied only while the plot is drawn, so other plots in the session are not affected. When using custom fonts in R Markdown, be sure to set the chunk option fig.showtext = TRUE, otherwise an informative error will be generated.

theme

A valid ggplot2 theme to apply, or NULL to use the default theme_grey(). This argument accepts themes (e.g., theme_bw()), functions (e.g., theme_bw) and characters themes (e.g., "theme_bw"). A partial theme, such as theme(panel.background = element_blank()), is added on top of theme_minimal2(), and its elements take precedence over plot2's own settings. The default is theme_minimal2(), but can be set with options(plot2.theme = "...").

background

The background colour of the entire plot, can also be NA to remove it. Will be evaluated with get_colour(). Only applies when theme is not NULL.

markdown

A logical to turn all labels and titles into plotmath expressions, by converting common markdown language using the md_to_expression() function (defaults to TRUE).

data

Data for formula notation only, e.g. plot2(mpg ~ hp, data = mtcars), which is the same as mtcars |> plot2(mpg ~ hp). A formula takes the form y ~ x + category + facet or y ~ x + category | facet; terms can be expressions, such as log(mpg) ~ hp. For other input, data gives an error: pass the data as the first argument instead.

...

Any argument to give to the geom. This will override automatically-set settings for the geom.

Details

Plotting directions

A plot has up to four directions: x, y, category (the colours, called 'colour' and 'fill' in ggplot2) and facet (separate panels). Each can be a column or a calculation on the data. Groups of x, category and facet that contain several values are summarised with summarise_function, and each direction has its own settings, such as x.sort and category.sort for the order of the values, and x.max_items and category.max_items to show only the first values and combine the rest into one. Directions that are not given are chosen from the data, see Automatic choices below.

Plot types

type accepts every ggplot2 geom and adds the types "barpercent", "linedot", "dumbbell", "back-to-back", "sankey", "spider" and "upset". Without type, the type follows from the data. See vignette("supported_types", package = "plot2") for every type with its data requirements.

The result

The result is an ordinary ggplot object: it can be extended with + and any ggplot2 function, with the add_*() functions, which add layers with unquoted variables, and its layers can be reordered with move_layer(). The default theme is theme_minimal2(), and the colours are set with colour and colour_fill, which accept any value of get_colour().

Text and numbers

Titles and labels support markdown (such as "**bold**" and "*italic*") and calculations on the data, such as title = paste("Patients in", min(format(date, "%Y"))). The font can be any installed system font or a Google Font (font). Numbers use the decimal and big marks of dec_mark() and big_mark(), and the language of generated text follows the plot2.language option; see plot2-options for all options.

Further reading

vignette("plot2", package = "plot2") introduces the package step by step. The package website has articles on colours and themes, maps, fonts, and plot2() for ggplot2 users. create_interactively() builds a plot in a Shiny app and shows the code that creates it.

The generic plot2() currently has 153 arguments, all with a default value except .data and ....

Value

A ggplot object.

Automatic choices

Like base R's plot(), plot2() decides what is not given. Every decision follows a fixed rule, is announced in a message (in interactive sessions, see the plot2.silent option in plot2-options), and is overridden by setting the argument concerned. The rules are:

What to plot

  • y: a column named n, otherwise the first numeric column (the second one if x is also chosen automatically); y = n() to count rows if the data have no numeric column, or for type = "barpercent" and Sankey plots.

  • x: the first numeric column if there is no x and the data have several numeric columns, otherwise the first column not used elsewhere.

  • category: the first character or factor column if neither x nor category is given and the data have more than two columns; for 'sf' data, the first numeric column.

  • type: a boxplot if there is no x, or if every group of x, category and facet has at least three values; points if x and y are both numeric; a line if x contains dates with one value each (per category and facet), as in a time series; a histogram if x is the only numeric column; otherwise the plot2.default_type option (columns). A matrix with identical row and column names becomes a heatmap ("tile").

  • summarise_function: sum() if groups contain several values (see summarise_function).

Axes and scales

  • x.character and category.character: TRUE if the values are whole years from 1900 to 25 years after the current year, or exactly the months 1 to 12 (for x only in discrete plot types, and for years only with at most one value per year per category and facet); x.character also if x is numeric in a discrete plot type (including boxplots, violins and dumbbells), or if x.sort is set.

  • x.date_remove_years: TRUE if category contains the years of a date x.

  • x.date_breaks, x.date_labels, category.date_breaks and category.date_labels: based on the range of the dates.

  • facet.fixed_x and facet.fixed_y: the same scale in all facets if the maxima per facet differ by less than 25% (coefficient of variation, after the axis transformation), free scales otherwise; facet.repeat_labels_y = FALSE with a fixed y scale.

  • x.expand and y.expand: 0 if the limits are set.

  • y.percent: TRUE for density plots; y.percent_break: about 10 labels.

  • y.scientific: TRUE if a non-zero label would be 1e9 or larger, or smaller than 1e-4.

  • category.midpoint: the centre of the category scale, for three colours.

  • binwidth: based on the data for histograms, which also get smooth = TRUE.

Labels and layout

  • datalabels: the values of y in column-type plots, at most 25 and none for continuous plot types such as points and lines; for 'sf' data, the first character column, centred on the areas (datalabels.centroid = TRUE).

  • legend.position: "right" for numeric categories and 'sf' data, "top" otherwise; numeric categories also get a legend title.

  • sankey_remove_axes: TRUE for Sankey plots.

Argument names

The arguments follow one naming rule: ⁠<argument>.<setting>⁠, where the part before the dot is itself an argument of plot2() (x, y, category, facet, y_secondary, title, subtitle, datalabels, smooth or legend) and the setting is written in snake case, e.g. x.label_angle or facet.repeat_labels_x. All other arguments are plain snake case, e.g. colour_fill, sankey_node_width or jitter_seed. The exceptions are names known from base R: na.rm, na.replace, decimal.mark and big.mark.

A default of NULL means that plot2() determines the value automatically, often announced in a message. An explicit value is always used as given.

See Also

vignette("plot2", package = "plot2") and vignette("supported_types", package = "plot2"); plot2-methods for the methods per object class; add_type() and move_layer() to extend a plot; get_colour() and theme_minimal2() for colours and the theme.

Examples

# without variables, plot2() determines them: two numeric columns give points
iris |>
  plot2()

# the arguments are in this order: x, y, category, facet
iris |>
  plot2(Sepal.Length, Sepal.Width, Petal.Length, Species,
        colour = "viridis")

# y can be several columns, also with selection helpers
iris |>
  plot2(x = Species, y = where(is.double))

# y can be any calculation; datalabels are added for columns
ggplot2::mpg |>
  plot2(class, n(), drv)

# sorting and stacking are single arguments
ggplot2::mpg |>
  plot2(class, n(), drv,
        x.sort = "freq-asc",
        stacked = TRUE)

# set the plot type explicitly
ggplot2::mpg |>
  plot2(manufacturer, median(hwy), year, type = "dumbbell")

# titles support calculations too
ggplot2::mpg |>
  plot2(hwy, type = "hist",
        title = paste("Based on n =", n_distinct(model), "car models"))

# a correlation matrix becomes a heatmap
mtcars |>
  cor() |>
  plot2()

# many more examples, including Sankey, spider and geographic plots,
# are in the vignettes:
# vignette("plot2", package = "plot2")
# vignette("supported_types", package = "plot2")

Methods for plot2()

Description

These are the implemented methods for different S3 classes to be used in plot2(). Since they have an extensive list of arguments, they are placed here on a separate manual page.

Usage

## Default S3 method:
plot2(
  .data,
  x = NULL,
  y = NULL,
  category = NULL,
  facet = NULL,
  type = NULL,
  x.title = TRUE,
  y.title = TRUE,
  category.title = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  tag = NULL,
  title.linelength = 60,
  title.colour = getOption("plot2.colour_font_primary", "black"),
  subtitle.linelength = 60,
  subtitle.colour = getOption("plot2.colour_font_secondary", "grey35"),
  na.replace = "",
  na.rm = FALSE,
  facet.position = "top",
  facet.colour_fill = NULL,
  facet.bold = TRUE,
  facet.italic = FALSE,
  facet.size = 10,
  facet.margin = 8,
  facet.repeat_labels_x = TRUE,
  facet.repeat_labels_y = NULL,
  facet.fixed_y = NULL,
  facet.fixed_x = NULL,
  facet.drop = FALSE,
  facet.nrow = NULL,
  facet.relative = FALSE,
  x.date_breaks = NULL,
  x.date_labels = NULL,
  x.date_remove_years = NULL,
  category.focus = NULL,
  colour = getOption("plot2.colour", "ggplot2"),
  colour_fill = NULL,
  colour_transparency = 0,
  x.label_angle = 0,
  x.label_align = NULL,
  x.label_italic = FALSE,
  x.remove = FALSE,
  x.position = "bottom",
  x.max_items = NULL,
  x.max_txt = "(rest, x%n)",
  category.max_items = Inf,
  category.max_txt = "(rest, x%n)",
  facet.max_items = Inf,
  facet.max_txt = "(rest, x%n)",
  x.breaks = NULL,
  x.n_breaks = NULL,
  x.transform = "identity",
  x.expand = NULL,
  x.limits = NULL,
  x.labels = NULL,
  x.character = NULL,
  x.drop = FALSE,
  x.zoom = NULL,
  y.remove = FALSE,
  y.24h = FALSE,
  y.age = FALSE,
  y.scientific = NULL,
  y.percent = NULL,
  y.percent_break = NULL,
  y.breaks = NULL,
  y.n_breaks = NULL,
  y.limits = NULL,
  y.labels = NULL,
  y.expand = NULL,
  y.transform = "identity",
  y.position = "left",
  y.zoom = FALSE,
  y_secondary = NULL,
  y_secondary.type = NULL,
  y_secondary.title = TRUE,
  y_secondary.colour = NULL,
  y_secondary.colour_fill = NULL,
  y_secondary.scientific = NULL,
  y_secondary.percent = FALSE,
  y_secondary.labels = NULL,
  category.type = "colour",
  category.labels = NULL,
  category.percent = FALSE,
  category.breaks = NULL,
  category.limits = NULL,
  category.expand = 0,
  category.midpoint = NULL,
  category.transform = "identity",
  category.date_breaks = NULL,
  category.date_labels = NULL,
  category.character = NULL,
  x.sort = NULL,
  category.sort = TRUE,
  facet.sort = TRUE,
  x.complete = NULL,
  category.complete = NULL,
  facet.complete = NULL,
  datalabels = NULL,
  datalabels.round = ifelse(isTRUE(y.percent), 2, 1),
  datalabels.format = "%n",
  datalabels.colour = "grey25",
  datalabels.colour_fill = NULL,
  datalabels.size = (3 * text_factor),
  datalabels.angle = 0,
  datalabels.lineheight = 1,
  datalabels.percent_by = "x",
  decimal.mark = dec_mark(),
  big.mark = big_mark(),
  summarise_function = NULL,
  stacked = FALSE,
  stacked_fill = FALSE,
  horizontal = FALSE,
  reverse = horizontal,
  smooth = NULL,
  smooth.method = NULL,
  smooth.formula = NULL,
  smooth.se = TRUE,
  smooth.level = 0.95,
  smooth.alpha = NULL,
  smooth.linewidth = NULL,
  smooth.linetype = NULL,
  smooth.colour = NULL,
  size = NULL,
  linetype = 1,
  linewidth = NULL,
  binwidth = NULL,
  width = NULL,
  jitter_seed = NA,
  violin_scale = "count",
  legend = NULL,
  legend.position = NULL,
  legend.title = NULL,
  legend.reverse = FALSE,
  legend.nrow = NULL,
  legend.barheight = 6,
  legend.barwidth = 1.5,
  legend.nbin = 300,
  legend.italic = FALSE,
  sankey_node_width = 0.15,
  sankey_node_whitespace = 0.03,
  sankey_alpha = 0.5,
  sankey_remove_axes = NULL,
  zoom = FALSE,
  sep = " / ",
  print = FALSE,
  text_factor = getOption("plot2.text_factor", 1),
  font = getOption("plot2.font"),
  theme = getOption("plot2.theme", "theme_minimal2"),
  background = getOption("plot2.colour_background", "white"),
  markdown = TRUE,
  ...
)

## S3 method for class 'formula'
plot2(
  .data = NULL,
  x = NULL,
  y = NULL,
  category = NULL,
  facet = NULL,
  type = NULL,
  x.title = TRUE,
  y.title = TRUE,
  category.title = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  tag = NULL,
  title.linelength = 60,
  title.colour = getOption("plot2.colour_font_primary", "black"),
  subtitle.linelength = 60,
  subtitle.colour = getOption("plot2.colour_font_secondary", "grey35"),
  na.replace = "",
  na.rm = FALSE,
  facet.position = "top",
  facet.colour_fill = NULL,
  facet.bold = TRUE,
  facet.italic = FALSE,
  facet.size = 10,
  facet.margin = 8,
  facet.repeat_labels_x = TRUE,
  facet.repeat_labels_y = NULL,
  facet.fixed_y = NULL,
  facet.fixed_x = NULL,
  facet.drop = FALSE,
  facet.nrow = NULL,
  facet.relative = FALSE,
  x.date_breaks = NULL,
  x.date_labels = NULL,
  x.date_remove_years = NULL,
  category.focus = NULL,
  colour = getOption("plot2.colour", "ggplot2"),
  colour_fill = NULL,
  colour_transparency = 0,
  x.label_angle = 0,
  x.label_align = NULL,
  x.label_italic = FALSE,
  x.remove = FALSE,
  x.position = "bottom",
  x.max_items = NULL,
  x.max_txt = "(rest, x%n)",
  category.max_items = Inf,
  category.max_txt = "(rest, x%n)",
  facet.max_items = Inf,
  facet.max_txt = "(rest, x%n)",
  x.breaks = NULL,
  x.n_breaks = NULL,
  x.transform = "identity",
  x.expand = NULL,
  x.limits = NULL,
  x.labels = NULL,
  x.character = NULL,
  x.drop = FALSE,
  x.zoom = NULL,
  y.remove = FALSE,
  y.24h = FALSE,
  y.age = FALSE,
  y.scientific = NULL,
  y.percent = NULL,
  y.percent_break = NULL,
  y.breaks = NULL,
  y.n_breaks = NULL,
  y.limits = NULL,
  y.labels = NULL,
  y.expand = NULL,
  y.transform = "identity",
  y.position = "left",
  y.zoom = FALSE,
  y_secondary = NULL,
  y_secondary.type = NULL,
  y_secondary.title = TRUE,
  y_secondary.colour = NULL,
  y_secondary.colour_fill = NULL,
  y_secondary.scientific = NULL,
  y_secondary.percent = FALSE,
  y_secondary.labels = NULL,
  category.type = "colour",
  category.labels = NULL,
  category.percent = FALSE,
  category.breaks = NULL,
  category.limits = NULL,
  category.expand = 0,
  category.midpoint = NULL,
  category.transform = "identity",
  category.date_breaks = NULL,
  category.date_labels = NULL,
  category.character = NULL,
  x.sort = NULL,
  category.sort = TRUE,
  facet.sort = TRUE,
  x.complete = NULL,
  category.complete = NULL,
  facet.complete = NULL,
  datalabels = NULL,
  datalabels.round = ifelse(isTRUE(y.percent), 2, 1),
  datalabels.format = "%n",
  datalabels.colour = "grey25",
  datalabels.colour_fill = NULL,
  datalabels.size = (3 * text_factor),
  datalabels.angle = 0,
  datalabels.lineheight = 1,
  datalabels.percent_by = "x",
  decimal.mark = dec_mark(),
  big.mark = big_mark(),
  summarise_function = NULL,
  stacked = FALSE,
  stacked_fill = FALSE,
  horizontal = FALSE,
  reverse = horizontal,
  smooth = NULL,
  smooth.method = NULL,
  smooth.formula = NULL,
  smooth.se = TRUE,
  smooth.level = 0.95,
  smooth.alpha = NULL,
  smooth.linewidth = NULL,
  smooth.linetype = NULL,
  smooth.colour = NULL,
  size = NULL,
  linetype = 1,
  linewidth = NULL,
  binwidth = NULL,
  width = NULL,
  jitter_seed = NA,
  violin_scale = "count",
  legend = NULL,
  legend.position = NULL,
  legend.title = NULL,
  legend.reverse = FALSE,
  legend.nrow = NULL,
  legend.barheight = 6,
  legend.barwidth = 1.5,
  legend.nbin = 300,
  legend.italic = FALSE,
  sankey_node_width = 0.15,
  sankey_node_whitespace = 0.03,
  sankey_alpha = 0.5,
  sankey_remove_axes = NULL,
  zoom = FALSE,
  sep = " / ",
  print = FALSE,
  text_factor = getOption("plot2.text_factor", 1),
  font = getOption("plot2.font"),
  theme = getOption("plot2.theme", "theme_minimal2"),
  background = getOption("plot2.colour_background", "white"),
  markdown = TRUE,
  data = NULL,
  ...
)

## S3 method for class 'freq'
plot2(
  .data,
  x = .data$item,
  y = .data$count,
  category = NULL,
  facet = NULL,
  type = NULL,
  x.title = "Item",
  y.title = "Count",
  category.title = TRUE,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  tag = NULL,
  title.linelength = 60,
  title.colour = getOption("plot2.colour_font_primary", "black"),
  subtitle.linelength = 60,
  subtitle.colour = getOption("plot2.colour_font_secondary", "grey35"),
  na.replace = "",
  na.rm = FALSE,
  facet.position = "top",
  facet.colour_fill = NULL,
  facet.bold = TRUE,
  facet.italic = FALSE,
  facet.size = 10,
  facet.margin = 8,
  facet.repeat_labels_x = TRUE,
  facet.repeat_labels_y = NULL,
  facet.fixed_y = NULL,
  facet.fixed_x = NULL,
  facet.drop = FALSE,
  facet.nrow = NULL,
  facet.relative = FALSE,
  x.date_breaks = NULL,
  x.date_labels = NULL,
  x.date_remove_years = NULL,
  category.focus = NULL,
  colour = getOption("plot2.colour", "ggplot2"),
  colour_fill = NULL,
  colour_transparency = 0,
  x.label_angle = 0,
  x.label_align = NULL,
  x.label_italic = FALSE,
  x.remove = FALSE,
  x.position = "bottom",
  x.max_items = NULL,
  x.max_txt = "(rest, x%n)",
  category.max_items = Inf,
  category.max_txt = "(rest, x%n)",
  facet.max_items = Inf,
  facet.max_txt = "(rest, x%n)",
  x.breaks = NULL,
  x.n_breaks = NULL,
  x.transform = "identity",
  x.expand = NULL,
  x.limits = NULL,
  x.labels = NULL,
  x.character = NULL,
  x.drop = FALSE,
  x.zoom = NULL,
  y.remove = FALSE,
  y.24h = FALSE,
  y.age = FALSE,
  y.scientific = NULL,
  y.percent = NULL,
  y.percent_break = NULL,
  y.breaks = NULL,
  y.n_breaks = NULL,
  y.limits = NULL,
  y.labels = NULL,
  y.expand = NULL,
  y.transform = "identity",
  y.position = "left",
  y.zoom = FALSE,
  y_secondary = NULL,
  y_secondary.type = NULL,
  y_secondary.title = TRUE,
  y_secondary.colour = NULL,
  y_secondary.colour_fill = NULL,
  y_secondary.scientific = NULL,
  y_secondary.percent = FALSE,
  y_secondary.labels = NULL,
  category.type = "colour",
  category.labels = NULL,
  category.percent = FALSE,
  category.breaks = NULL,
  category.limits = NULL,
  category.expand = 0,
  category.midpoint = NULL,
  category.transform = "identity",
  category.date_breaks = NULL,
  category.date_labels = NULL,
  category.character = NULL,
  x.sort = "freq-desc",
  category.sort = TRUE,
  facet.sort = TRUE,
  x.complete = NULL,
  category.complete = NULL,
  facet.complete = NULL,
  datalabels = NULL,
  datalabels.round = ifelse(isTRUE(y.percent), 2, 1),
  datalabels.format = "%n",
  datalabels.colour = "grey25",
  datalabels.colour_fill = NULL,
  datalabels.size = (3 * text_factor),
  datalabels.angle = 0,
  datalabels.lineheight = 1,
  datalabels.percent_by = "x",
  decimal.mark = dec_mark(),
  big.mark = big_mark(),
  summarise_function = NULL,
  stacked = FALSE,
  stacked_fill = FALSE,
  horizontal = FALSE,
  reverse = horizontal,
  smooth = NULL,
  smooth.method = NULL,
  smooth.formula = NULL,
  smooth.se = TRUE,
  smooth.level = 0.95,
  smooth.alpha = NULL,
  smooth.linewidth = NULL,
  smooth.linetype = NULL,
  smooth.colour = NULL,
  size = NULL,
  linetype = 1,
  linewidth = NULL,
  binwidth = NULL,
  width = NULL,
  jitter_seed = NA,
  violin_scale = "count",
  legend = NULL,
  legend.position = NULL,
  legend.title = NULL,
  legend.reverse = FALSE,
  legend.nrow = NULL,
  legend.barheight = 6,
  legend.barwidth = 1.5,
  legend.nbin = 300,
  legend.italic = FALSE,
  sankey_node_width = 0.15,
  sankey_node_whitespace = 0.03,
  sankey_alpha = 0.5,
  sankey_remove_axes = NULL,
  zoom = FALSE,
  sep = " / ",
  print = FALSE,
  text_factor = getOption("plot2.text_factor", 1),
  font = getOption("plot2.font"),
  theme = getOption("plot2.theme", "theme_minimal2"),
  background = getOption("plot2.colour_background", "white"),
  markdown = TRUE,
  ...
)

## S3 method for class 'sf'
plot2(
  .data,
  x = NULL,
  y = NULL,
  category = NULL,
  facet = NULL,
  type = NULL,
  x.title = FALSE,
  y.title = FALSE,
  category.title = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  tag = NULL,
  title.linelength = 60,
  title.colour = getOption("plot2.colour_font_primary", "black"),
  subtitle.linelength = 60,
  subtitle.colour = getOption("plot2.colour_font_secondary", "grey35"),
  na.replace = "",
  na.rm = FALSE,
  facet.position = "top",
  facet.colour_fill = NULL,
  facet.bold = TRUE,
  facet.italic = FALSE,
  facet.size = 10,
  facet.margin = 8,
  facet.repeat_labels_x = TRUE,
  facet.repeat_labels_y = NULL,
  facet.fixed_y = NULL,
  facet.fixed_x = NULL,
  facet.drop = FALSE,
  facet.nrow = NULL,
  facet.relative = FALSE,
  x.date_breaks = NULL,
  x.date_labels = NULL,
  x.date_remove_years = NULL,
  category.focus = NULL,
  colour = getOption("plot2.colour_sf", "grey50"),
  colour_fill = getOption("plot2.colour_sf_fill", getOption("plot2.colour", "ggplot2")),
  colour_transparency = 0,
  x.label_angle = 0,
  x.label_align = NULL,
  x.label_italic = FALSE,
  x.remove = FALSE,
  x.position = "bottom",
  x.max_items = NULL,
  x.max_txt = "(rest, x%n)",
  category.max_items = Inf,
  category.max_txt = "(rest, x%n)",
  facet.max_items = Inf,
  facet.max_txt = "(rest, x%n)",
  x.breaks = NULL,
  x.n_breaks = NULL,
  x.transform = "identity",
  x.expand = 0,
  x.limits = NULL,
  x.labels = NULL,
  x.character = NULL,
  x.drop = FALSE,
  x.zoom = NULL,
  y.remove = FALSE,
  y.24h = FALSE,
  y.age = FALSE,
  y.scientific = NULL,
  y.percent = NULL,
  y.percent_break = NULL,
  y.breaks = NULL,
  y.n_breaks = NULL,
  y.limits = NULL,
  y.labels = NULL,
  y.expand = 0,
  y.transform = "identity",
  y.position = "left",
  y.zoom = FALSE,
  y_secondary = NULL,
  y_secondary.type = NULL,
  y_secondary.title = TRUE,
  y_secondary.colour = NULL,
  y_secondary.colour_fill = NULL,
  y_secondary.scientific = NULL,
  y_secondary.percent = FALSE,
  y_secondary.labels = NULL,
  category.type = "colour",
  category.labels = NULL,
  category.percent = FALSE,
  category.breaks = NULL,
  category.limits = NULL,
  category.expand = 0,
  category.midpoint = NULL,
  category.transform = "identity",
  category.date_breaks = NULL,
  category.date_labels = NULL,
  category.character = NULL,
  x.sort = NULL,
  category.sort = TRUE,
  facet.sort = TRUE,
  x.complete = NULL,
  category.complete = NULL,
  facet.complete = NULL,
  datalabels = NULL,
  datalabels.round = ifelse(isTRUE(y.percent), 2, 1),
  datalabels.format = NULL,
  datalabels.colour = "black",
  datalabels.colour_fill = NULL,
  datalabels.size = (3 * text_factor),
  datalabels.angle = 0,
  datalabels.lineheight = 1,
  datalabels.percent_by = "x",
  decimal.mark = dec_mark(),
  big.mark = big_mark(),
  summarise_function = NULL,
  stacked = FALSE,
  stacked_fill = FALSE,
  horizontal = FALSE,
  reverse = horizontal,
  smooth = NULL,
  smooth.method = NULL,
  smooth.formula = NULL,
  smooth.se = TRUE,
  smooth.level = 0.95,
  smooth.alpha = NULL,
  smooth.linewidth = NULL,
  smooth.linetype = NULL,
  smooth.colour = NULL,
  size = NULL,
  linetype = 1,
  linewidth = NULL,
  binwidth = NULL,
  width = NULL,
  jitter_seed = NA,
  violin_scale = "count",
  legend = NULL,
  legend.position = "right",
  legend.title = NULL,
  legend.reverse = FALSE,
  legend.nrow = NULL,
  legend.barheight = 6,
  legend.barwidth = 1.5,
  legend.nbin = 300,
  legend.italic = FALSE,
  sankey_node_width = 0.15,
  sankey_node_whitespace = 0.03,
  sankey_alpha = 0.5,
  sankey_remove_axes = NULL,
  zoom = FALSE,
  sep = " / ",
  print = FALSE,
  text_factor = getOption("plot2.text_factor", 1),
  font = getOption("plot2.font"),
  theme = theme_minimal2(panel.grid.major = element_blank(), panel.grid.minor =
    element_blank(), panel.border = element_blank(), plot.margin = unit(c(5, 5, 0, 0),
    units = "pt"), axis.title = element_blank(), axis.text = element_blank(), axis.line =
    element_blank(), axis.ticks = element_blank()),
  background = getOption("plot2.colour_background", "white"),
  markdown = TRUE,
  ...,
  crs = NULL,
  datalabels.centroid = NULL
)

## S3 method for class 'data.frame'
plot2(
  .data,
  x = NULL,
  y = NULL,
  category = NULL,
  facet = NULL,
  type = NULL,
  x.title = TRUE,
  y.title = TRUE,
  category.title = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  tag = NULL,
  title.linelength = 60,
  title.colour = getOption("plot2.colour_font_primary", "black"),
  subtitle.linelength = 60,
  subtitle.colour = getOption("plot2.colour_font_secondary", "grey35"),
  na.replace = "",
  na.rm = FALSE,
  facet.position = "top",
  facet.colour_fill = NULL,
  facet.bold = TRUE,
  facet.italic = FALSE,
  facet.size = 10,
  facet.margin = 8,
  facet.repeat_labels_x = TRUE,
  facet.repeat_labels_y = NULL,
  facet.fixed_y = NULL,
  facet.fixed_x = NULL,
  facet.drop = FALSE,
  facet.nrow = NULL,
  facet.relative = FALSE,
  x.date_breaks = NULL,
  x.date_labels = NULL,
  x.date_remove_years = NULL,
  category.focus = NULL,
  colour = getOption("plot2.colour", "ggplot2"),
  colour_fill = NULL,
  colour_transparency = 0,
  x.label_angle = 0,
  x.label_align = NULL,
  x.label_italic = FALSE,
  x.remove = FALSE,
  x.position = "bottom",
  x.max_items = NULL,
  x.max_txt = "(rest, x%n)",
  category.max_items = Inf,
  category.max_txt = "(rest, x%n)",
  facet.max_items = Inf,
  facet.max_txt = "(rest, x%n)",
  x.breaks = NULL,
  x.n_breaks = NULL,
  x.transform = "identity",
  x.expand = NULL,
  x.limits = NULL,
  x.labels = NULL,
  x.character = NULL,
  x.drop = FALSE,
  x.zoom = NULL,
  y.remove = FALSE,
  y.24h = FALSE,
  y.age = FALSE,
  y.scientific = NULL,
  y.percent = NULL,
  y.percent_break = NULL,
  y.breaks = NULL,
  y.n_breaks = NULL,
  y.limits = NULL,
  y.labels = NULL,
  y.expand = NULL,
  y.transform = "identity",
  y.position = "left",
  y.zoom = FALSE,
  y_secondary = NULL,
  y_secondary.type = NULL,
  y_secondary.title = TRUE,
  y_secondary.colour = NULL,
  y_secondary.colour_fill = NULL,
  y_secondary.scientific = NULL,
  y_secondary.percent = FALSE,
  y_secondary.labels = NULL,
  category.type = "colour",
  category.labels = NULL,
  category.percent = FALSE,
  category.breaks = NULL,
  category.limits = NULL,
  category.expand = 0,
  category.midpoint = NULL,
  category.transform = "identity",
  category.date_breaks = NULL,
  category.date_labels = NULL,
  category.character = NULL,
  x.sort = NULL,
  category.sort = TRUE,
  facet.sort = TRUE,
  x.complete = NULL,
  category.complete = NULL,
  facet.complete = NULL,
  datalabels = NULL,
  datalabels.round = ifelse(isTRUE(y.percent), 2, 1),
  datalabels.format = "%n",
  datalabels.colour = "grey25",
  datalabels.colour_fill = NULL,
  datalabels.size = (3 * text_factor),
  datalabels.angle = 0,
  datalabels.lineheight = 1,
  datalabels.percent_by = "x",
  decimal.mark = dec_mark(),
  big.mark = big_mark(),
  summarise_function = NULL,
  stacked = FALSE,
  stacked_fill = FALSE,
  horizontal = FALSE,
  reverse = horizontal,
  smooth = NULL,
  smooth.method = NULL,
  smooth.formula = NULL,
  smooth.se = TRUE,
  smooth.level = 0.95,
  smooth.alpha = NULL,
  smooth.linewidth = NULL,
  smooth.linetype = NULL,
  smooth.colour = NULL,
  size = NULL,
  linetype = 1,
  linewidth = NULL,
  binwidth = NULL,
  width = NULL,
  jitter_seed = NA,
  violin_scale = "count",
  legend = NULL,
  legend.position = NULL,
  legend.title = NULL,
  legend.reverse = FALSE,
  legend.nrow = NULL,
  legend.barheight = 6,
  legend.barwidth = 1.5,
  legend.nbin = 300,
  legend.italic = FALSE,
  sankey_node_width = 0.15,
  sankey_node_whitespace = 0.03,
  sankey_alpha = 0.5,
  sankey_remove_axes = NULL,
  zoom = FALSE,
  sep = " / ",
  print = FALSE,
  text_factor = getOption("plot2.text_factor", 1),
  font = getOption("plot2.font"),
  theme = getOption("plot2.theme", "theme_minimal2"),
  background = getOption("plot2.colour_background", "white"),
  markdown = TRUE,
  ...
)

## S3 method for class 'matrix'
plot2(
  .data,
  x = NULL,
  y = NULL,
  category = NULL,
  facet = NULL,
  type = NULL,
  x.title = FALSE,
  y.title = FALSE,
  category.title = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  tag = NULL,
  title.linelength = 60,
  title.colour = getOption("plot2.colour_font_primary", "black"),
  subtitle.linelength = 60,
  subtitle.colour = getOption("plot2.colour_font_secondary", "grey35"),
  na.replace = "",
  na.rm = FALSE,
  facet.position = "top",
  facet.colour_fill = NULL,
  facet.bold = TRUE,
  facet.italic = FALSE,
  facet.size = 10,
  facet.margin = 8,
  facet.repeat_labels_x = TRUE,
  facet.repeat_labels_y = NULL,
  facet.fixed_y = NULL,
  facet.fixed_x = NULL,
  facet.drop = FALSE,
  facet.nrow = NULL,
  facet.relative = FALSE,
  x.date_breaks = NULL,
  x.date_labels = NULL,
  x.date_remove_years = NULL,
  category.focus = NULL,
  colour = getOption("plot2.colour", "ggplot2"),
  colour_fill = NULL,
  colour_transparency = 0,
  x.label_angle = 0,
  x.label_align = NULL,
  x.label_italic = FALSE,
  x.remove = FALSE,
  x.position = "bottom",
  x.max_items = NULL,
  x.max_txt = "(rest, x%n)",
  category.max_items = Inf,
  category.max_txt = "(rest, x%n)",
  facet.max_items = Inf,
  facet.max_txt = "(rest, x%n)",
  x.breaks = NULL,
  x.n_breaks = NULL,
  x.transform = "identity",
  x.expand = NULL,
  x.limits = NULL,
  x.labels = NULL,
  x.character = NULL,
  x.drop = FALSE,
  x.zoom = NULL,
  y.remove = FALSE,
  y.24h = FALSE,
  y.age = FALSE,
  y.scientific = NULL,
  y.percent = NULL,
  y.percent_break = NULL,
  y.breaks = NULL,
  y.n_breaks = NULL,
  y.limits = NULL,
  y.labels = NULL,
  y.expand = NULL,
  y.transform = "identity",
  y.position = "left",
  y.zoom = FALSE,
  y_secondary = NULL,
  y_secondary.type = NULL,
  y_secondary.title = TRUE,
  y_secondary.colour = NULL,
  y_secondary.colour_fill = NULL,
  y_secondary.scientific = NULL,
  y_secondary.percent = FALSE,
  y_secondary.labels = NULL,
  category.type = "colour",
  category.labels = NULL,
  category.percent = FALSE,
  category.breaks = NULL,
  category.limits = NULL,
  category.expand = 0,
  category.midpoint = NULL,
  category.transform = "identity",
  category.date_breaks = NULL,
  category.date_labels = NULL,
  category.character = NULL,
  x.sort = NULL,
  category.sort = TRUE,
  facet.sort = TRUE,
  x.complete = NULL,
  category.complete = NULL,
  facet.complete = NULL,
  datalabels = NULL,
  datalabels.round = ifelse(isTRUE(y.percent), 2, 1),
  datalabels.format = "%n",
  datalabels.colour = "grey25",
  datalabels.colour_fill = NULL,
  datalabels.size = (3 * text_factor),
  datalabels.angle = 0,
  datalabels.lineheight = 1,
  datalabels.percent_by = "x",
  decimal.mark = dec_mark(),
  big.mark = big_mark(),
  summarise_function = NULL,
  stacked = FALSE,
  stacked_fill = FALSE,
  horizontal = FALSE,
  reverse = horizontal,
  smooth = NULL,
  smooth.method = NULL,
  smooth.formula = NULL,
  smooth.se = TRUE,
  smooth.level = 0.95,
  smooth.alpha = NULL,
  smooth.linewidth = NULL,
  smooth.linetype = NULL,
  smooth.colour = NULL,
  size = NULL,
  linetype = 1,
  linewidth = NULL,
  binwidth = NULL,
  width = NULL,
  jitter_seed = NA,
  violin_scale = "count",
  legend = NULL,
  legend.position = NULL,
  legend.title = NULL,
  legend.reverse = FALSE,
  legend.nrow = NULL,
  legend.barheight = 6,
  legend.barwidth = 1.5,
  legend.nbin = 300,
  legend.italic = FALSE,
  sankey_node_width = 0.15,
  sankey_node_whitespace = 0.03,
  sankey_alpha = 0.5,
  sankey_remove_axes = NULL,
  zoom = FALSE,
  sep = " / ",
  print = FALSE,
  text_factor = getOption("plot2.text_factor", 1),
  font = getOption("plot2.font"),
  theme = getOption("plot2.theme", "theme_minimal2"),
  background = getOption("plot2.colour_background", "white"),
  markdown = TRUE,
  ...
)

Arguments

.data, data

Data to plot. A single character value that is the name of a data frame in the calling environment (such as plot2("df"), as used in tool calling) plots that data frame; only the calling environment is searched, not the search path.

x

Plotting 'direction' for the X-axis. This can be:

  • A single variable from .data, such as x = column1

  • A function to calculate over one or more variables from .data, such as x = format(column1, "%Y"), or x = ifelse(column1 == "A", "Group A", "Other")

  • Multiple variables from .data, such as x = c(column1, column2, column2), or using selection helpers such as x = where(is.character) or x = starts_with("var_") (only allowed and required for Sankey plots using type = "sankey")

y

Values to use for plotting along the Y-axis. This can be:

  • A single variable from .data, such as y = column1

  • Multiple variables from .data, such as y = c(column1, column2) or y = c(name1 = column1, "name 2" = column2), or using selection helpers such as y = where(is.double) or y = starts_with("var_") (multiple variables only allowed if category is not set)

  • A function to calculate over .data returning a single value, such as y = n() for the row count, or based on other variables such as y = n_distinct(person_id), y = max(column1), or y = median(column2) / column3

  • A function to calculate over .data returning multiple values, such as y = quantile(column1, c(0.25, 0.75)) or y = range(age) (multiple values only allowed if category is not set)

category, facet

Plotting 'direction' (category is called 'fill' and 'colour' in ggplot2). This can be:

  • A single variable from .data, such as category = column1

  • A function to calculate over one or more variables from .data, such as category = median(column2) / column3, or facet = ifelse(column1 == "A", "Group A", "Other")

  • Multiple variables from .data, such as facet = c(column1, column2) (use sep to control the separator character)

  • One or more variables from .data using selection helpers, such as category = where(is.double) or facet = starts_with("var_")

The category can also be a date or date/time (class Date or POSIXt).

type

Type of visualisation to use. This can be:

  • A ggplot2 geom name or their abbreviation such as "col" and "point". All geoms are supported (including geom_blank()).

    Full function names can be used (e.g., "geom_histogram"), but they can also be abbreviated (e.g., "h", "hist"). The following geoms can be abbreviated by their first character: area ("a"), boxplot ("b"), column ("c"), histogram ("h"), jitter ("j"), line ("l"), point ("p"), ribbon ("r"), and violin ("v"). Beeswarm plots ("beeswarm", short: "bs") require the ggbeeswarm package.

    Please note: in ggplot2, 'bars' and 'columns' are equal, while it is common to many people that 'bars' are oriented horizontally and 'columns' are oriented vertically since Microsoft Excel has been using these terms this way for many years. For this reason, type = "bar" will set type = "col" and horizontal = TRUE.

  • One of these additional types:

    • "barpercent" (short: "bp"), which is effectively a shortcut to set type = "col" and horizontal = TRUE and x.max_items = 10 and x.sort = "freq-desc" and datalabels.format = "%n (%p)".

    • "dumbbell" (short: "d" or "db"), which sets type = "point" and horizontal = TRUE, and adds a line between the points (using geom_segment()). The line colour cannot be changed. This plot type is only possible when the category has two distinct values.

    • "linedot" or "line-point" (short: "ld" or "lp"), which sets type = "line" and adds two point geoms using add_point(); one with large white dots and one with smaller dots using the colours set in colour. This is essentially equal to base R plot(..., type = "b") but with closed shapes.

    • "back-to-back" (short: "b2b", or "butterfly", "tornado" or "population") creates a back-to-back plot, sometimes called a Tornado diagram, a butterfly plot, or a Population Pyramid. It uses facet to distinguish the left and right plots. Therefore, facet must be set to (a column containing) two unique values.

    • "upset" or "UpSet" (short: "u") creates an UpSet plot, which requires x to contain multiple variables from .data that contain 0/1 or FALSE/TRUE values. It is also possible to provide y, on which then summarise_function will be applied.

    • "sankey" (short: "s") creates a Sankey plot using category for the flows and requires x to contain multiple variables from .data. At default, it also sets x.expand = c(0.05, 0.05) and y.limits = c(NA, NA) and y.expand = c(0.01, 0.01). The so-called 'nodes' (the 'blocks' with text) are considered the datalabels, so you can set the text size and colour of the nodes using datalabels.size, datalabels.colour, and datalabels.colour_fill. The transparency of the flows can be set using sankey_alpha, and the width of the nodes can be set using sankey_node_width. Sankey plots can also be flipped using horizontal = TRUE, and the label angles can be set with datalabels.angle.

    • "spider" or "radar" (short: "sp") creates a Spider plot using our novel CoordSpider coordinate system. Facets are supported, always with the same scale in all facets.

  • Left blank. In this case, the type will be determined automatically: "boxplot" if there is no X-axis or if the length of unique values per X-axis item is at least 3, "point" if both the y and x axes are numeric, "line" if the X-axis contains dates with one value each (a time series), and the option "plot2.default_type" otherwise (which defaults to "col", and accepts any value of type, such as "line" or "l"). Use type = "blank" or type = "geom_blank" to not add a geom.

title, subtitle, caption, tag, x.title, y.title, category.title, legend.title, y_secondary.title

A title to use. This can be:

  • A character, which supports markdown by using md_to_expression() internally if markdown = TRUE (which is the default)

  • A function to calculate over .data, such as title = paste("Based on n =", n_distinct(person_id), "individuals") or subtitle = paste("Total rows:", n()), see Examples

  • An expression, e.g. using parse(text = "...")

The category.title defaults to TRUE if the legend items are numeric. category.title and legend.title are the same setting; use one of them.

title.linelength

Maximum number of characters per line in the title, before a linebreak occurs.

title.colour

Text colour of the title.

subtitle.linelength

Maximum number of characters per line in the subtitle, before a linebreak occurs.

subtitle.colour

Text colour of the subtitle.

na.replace

Character to put in place of NA values if na.rm = FALSE.

na.rm

Remove NA values from showing in the plot.

facet.position, facet.colour_fill, facet.bold, facet.italic, facet.size, facet.margin, facet.repeat_labels_x, facet.repeat_labels_y, facet.drop, facet.nrow, facet.relative

Additional settings for the plotting direction facet. facet.repeat_labels_x and facet.repeat_labels_y repeat the axis labels in every facet, which also makes the scales of that axis free (unless facet.fixed_x or facet.fixed_y is TRUE).

facet.fixed_y

A logical to indicate whether all y scales should have the same limits. If not set, this depends on the data: TRUE only if the coefficient of variation (standard deviation divided by mean) of the maximum y values per facet, after y.transform, is less than 25%, otherwise every facet gets its own y scale. Both outcomes are reported in a message. Since this can change when the data change (e.g., next month's data), set facet.fixed_y = TRUE when panels must be compared.

facet.fixed_x

A logical to indicate whether all x scales should have the same breaks. This acts like the inverse of x.drop. If not set and x is numeric, the same rule as for facet.fixed_y applies to the maximum x values per facet, compared after x.transform (so as plotted, e.g. on a log scale).

x.date_breaks

Breaks to use when the X-axis contains dates, will be determined automatically if left blank. This accepts values such as "1 day" and "2 years".

x.date_labels

Labels to use when the X-axis contains dates, will be determined automatically if left blank. This accepts 'Excel' date-language such as "d mmmm yyyy": d/dd (day), ddd/dddd (weekday name), mm (month number), mmm/mmmm (month name), yy/yyyy (year), q/qq (quarter: 1 or Q1), w/ww (ISO week), h/hh (hour), MM (minutes), ss (seconds). Other words are kept as they are (e.g. "Week ww"), and text in single quotes is always kept literally (e.g. "'d' d"). A format containing ⁠%⁠ is used as a strftime() format. Month and weekday names follow the option plot2.language if set, and the system locale otherwise.

x.date_remove_years

A logical to indicate whether the years of all x values must be unified. This will set the years of all x values to 1970 if the data does not contain a leap year, and to 1972 otherwise. This allows to plot years on the category while maintaining a date range on x. The default is FALSE, unless category contains all years present in x.

category.focus

A value of category that should be highlighted, meaning that all other values in category will be greyed out. This can also be a numeric value between 1 and the length of unique values of category, e.g. category.focus = 2 to focus on the second legend item.

colour

Colour(s) to set, will be evaluated with get_colour() if set. This can also be one of the viridis colours with automatic implementation for any plot: "viridis", "magma", "inferno", "plasma", "cividis", "rocket", "mako" or "turbo". Also, this can be a named vector to match values of category, see Examples. Using a named vector can be used to manually sort the values of category.

colour_fill

Colour(s) to be used for filling, will be determined automatically if left blank and will be evaluated with get_colour().

colour_transparency

Amount of transparency for colour/colour_fill (0 = solid, 1 = fully transparent).

x.label_angle

Angle to use for the X-axis in a counter-clockwise direction (i.e., a value of 90 will orient the axis labels from bottom to top, a value of 270 will orient the axis labels from top to bottom).

x.label_align

Alignment for the X-axis between 0 (left aligned) and 1 (right aligned). If not set, rotated labels (see x.label_angle) are anchored at their ticks with guide_axis(angle = ), for every angle and also when horizontal = TRUE.

x.label_italic

logical to indicate whether the x labels should be in italics.

x.remove, y.remove

A logical to indicate whether the axis labels and title should be removed.

x.position, y.position

Position of the axis.

x.max_items, category.max_items, facet.max_items

Maximum number of items to show, including the item that holds the rest: x.max_items = 5 shows four values and the rest, see x.max_txt. Defaults to infinite. Left NULL (default for x.max_items), this is infinite, except for type = "barpercent" and back-to-back plots (10). The remaining values are grouped into one item and summarised using the summarise_function function. Please note: the sorting will be applied first, so that e.g. x.sort = "freq-desc" with x.max_items = 5 shows the four most frequent values of the X-axis and the rest.

x.max_txt, category.max_txt, facet.max_txt

The text of the item that holds the values beyond ⁠*.max_items⁠. The placeholder ⁠%n⁠ is replaced with the number of values in that item, and ⁠%p⁠ with their share of the total of y (or of the rows, when y is not numeric). For example, the default "(rest, x%n)" gives "(rest, x4)" for four values.

x.breaks, y.breaks

A breaks function or numeric vector to use for the axis.

x.n_breaks, y.n_breaks

Number of breaks, only useful if x.breaks or y.breaks respectively is NULL.

x.transform, y.transform, category.transform

A transformation function to use, e.g. "log2". This can be: "asinh", "asn", "atanh", "boxcox", "compose", "date", "exp", "hms", "identity", "log", "log10", "log1p", "log2", "logit", "modulus", "probability", "probit", "pseudo_log", "reciprocal", "reverse", "sqrt", "time", "timespan", "yj".

x.expand, y.expand

expansion to use for the axis, can be length 1 or 2. Left NULL (default), they are determined automatically: x.expand adds half a category on both sides of a discrete axis and a proportion of the range on a continuous axis, y.expand adds 25% above the data; both are 0 for sf objects or when the limits are set. An explicit value is used as given.

x.limits, y.limits

Limits to use for the axis, must be length 2. Use NA for the highest or lowest value in the data, e.g. y.limits = c(0, NA) to have the y scale start at zero. For a discrete x axis, x.limits are the items to show, in this order.

x.labels, y.labels, y_secondary.labels

A labels function or character vector to use for the axis.

x.character

A logical to indicate whether the values of the X-axis should be forced to character. If not set, whole numbers that look like years (1900 to 25 years after the current year) or months (exactly 1 to 12) become character when type is not set or is a discrete type such as "col" or "boxplot", with a message; years only so with at most one value per year (per category and facet), so that e.g. many measurements per year form a numeric axis; for continuous types such as "point", "line" and "area" they stay numeric, and years are then labelled without a thousands separator. Numeric values also become character for other discrete types, and always for "boxplot", "violin" and "dumbbell". Use x.character = FALSE to keep numeric values.

x.drop

logical to indicate whether factor levels should be dropped.

x.zoom, y.zoom

A logical to indicate if the axis should be zoomed on the data, i.e., cover the range of the data instead of starting at 0. Left NULL (default for x.zoom), the x axis is zoomed for plot types with a continuous x axis (such as histograms), and for years that stay numeric (such as in a line plot) only. This sets x.limits = c(NA, NA) (or y.limits) and, unless x.expand (or y.expand) is set, a 5% expansion on both sides, like ggplot2 does. It has no effect if x.limits (or y.limits) is set.

y.24h

A logical to indicate whether the y labels and breaks should be formatted as 24-hour sequences.

y.age

A logical to indicate whether the y labels and breaks should be formatted as ages in years.

y.scientific, y_secondary.scientific

A logical to indicate whether the y labels should be formatted in scientific notation. If not set, scientific notation is used only for labels of one billion (1e9) or more, or for non-zero labels below 0.0001; other labels use big.mark, e.g. ⁠2 000 000⁠.

y.percent, y_secondary.percent

A logical to indicate whether the y labels should be formatted as percentages. Left NULL (default for y.percent), percentages are used for density plots only.

y.percent_break

A value on which the Y-axis should have breaks if y.percent = TRUE. Left NULL (default), this is 0.1 (10%), widened to keep about 10 labels and narrowed if that would give three or fewer labels. An explicit value is used as given.

y_secondary

Values to use for plotting along the secondary Y-axis. This functionality is poorly supported by ggplot2 and might give unexpected results. Setting the secondary Y-axis will set the colour to the axis titles.

y_secondary.type

Type of the secondary series, see type. The default (NULL) is a line with points if the primary type is a column or bar plot, so that the secondary series does not cover the bars, and the primary type otherwise.

y_secondary.colour, y_secondary.colour_fill

Colours to set for the secondary Y-axis, will be evaluated with get_colour(). Left NULL (default), the second colour of the plot2.colour option is used.

category.type

Type of the category, one or more of: "colour" (default), "shape", "size", "linetype", "linewidth", "alpha". There is no need to set "fill", as plot2 handles colour-setting internally and determines automatically whether the colour or fill aesthetic must be used.

category.labels, category.percent, category.breaks, category.expand, category.midpoint

Settings for the plotting direction category.

category.limits

Limits to use for a numeric category, must be length 2. Use NA for the highest or lowest value in the data, e.g. category.limits = c(0, NA) to have the scale start at zero. If not set, the limits are the range of the data, rounded outwards to pretty values with pretty() (e.g., values from 12 to 87 give limits 0 to 100). With three colours and category.midpoint set, the limits are made symmetric around the midpoint.

category.date_breaks

Breaks to use when the category contains dates, will be determined automatically if left blank. This will be passed on to seq.Date(by = ...) and thus can be: a number, taken to be in days, or a character string containing one of "day", "week", "month", "quarter" or "year" (optionally preceded by an integer and a space, and/or followed by "s").

category.date_labels

Labels to use when the category contains dates, will be determined automatically if left blank. This accepts 'Excel' date-language such as "d mmmm yyyy".

category.character

A logical to indicate whether the values of the category should be forced to character. If not set, whole numbers that look like years (1900 to 25 years after the current year) or months (exactly 1 to 12) become character, with a message. Use category.character = FALSE to keep numeric values.

x.sort, category.sort, facet.sort

Sorting of the plotting direction. category.sort and facet.sort default to TRUE; x.sort defaults to NULL, which sorts text and factors as TRUE and leaves continuous values (such as dates and numbers) unsorted. Applying one of the sorting methods will transform the values to an ordered factor, which ggplot2 uses to orient the data. Valid values are:

  • A manual vector of values

  • TRUE: sort factors on their levels, otherwise sort ascending on alphabet, while maintaining numbers in the text (numeric sort)

  • FALSE: sort according to the order in the data

  • NULL: sort automatically, as described above

  • "asc", "alpha" or "alpha-asc": sort as TRUE

  • "desc" or "alpha-desc": sort factors on their reversed levels, otherwise sort descending on alphabet, while maintaining numbers in the text (numeric sort)

  • "order" or "inorder": sort as FALSE

  • "freq" or "freq-desc": sort descending according to the frequencies of y computed by summarise_function (highest value first)

  • "freq-asc": sort ascending according to the frequencies of y computed by summarise_function (lowest value first)

x.complete, category.complete, facet.complete

A value to complete the data. This makes use of tidyr::full_seq() and tidyr::complete(). For example, using x.complete = 0 will apply data |> complete(x = full_seq(x, ...), fill = list(y = 0)), crossed with the values of category and facet if set. Numeric values and dates are completed with tidyr::full_seq() at their observed resolution, date-times at their observed interval, and character values and factors with their unique values or levels. Using value TRUE (e.g., x.complete = TRUE) is identical to using value 0.

datalabels

Values to show as datalabels, see also datalabels.format. This can be:

  • NULL (default): automatic. This shows the values of y in column-type plots, or when plotting spatial 'sf' data, the values of the first column, with a maximum of 25 labels and none for continuous plot types such as lines and points.

  • TRUE to always show the values of y, without the maximum of 25 labels, or FALSE to remove datalabels

  • A function to calculate over .data, such as datalabels = paste(round(column1), "\n", column2)

datalabels.round

Number of digits to round the datalabels, applies to both "%n" and "%p" for replacement (see datalabels.format).

datalabels.format

Format to use for datalabels. This can be a function (such as euros()) or a text. For the text, "%n" will be replaced by the count number, and "%p" will be replaced by the percentage (see datalabels.percent_by). Use datalabels.format = NULL to not transform the datalabels.

datalabels.colour, datalabels.colour_fill, datalabels.size, datalabels.angle, datalabels.lineheight

Settings for the datalabels. Rotated datalabels (datalabels.angle) start or end at their bar with a small fixed gap; if y.expand and y.limits are not set, the value axis gets extra room for long rotated labels, estimated for a figure of about 6 by 4 inches.

datalabels.percent_by

Group within which the "%p" percentages of datalabels.format sum to 100%. This can be:

  • "x" (default): within each x value and facet, so that the stacked or dodged bars of one x value sum to 100%. Without a category, each x value has a single bar, so this is the same as "facet".

  • "category": within each category and facet

  • "facet": within each facet

  • "total": over all data in the plot

decimal.mark

Decimal mark, defaults to dec_mark().

big.mark

Thousands separator, defaults to big_mark().

summarise_function

A function to use if the data has to be summarised, see Examples. Left NULL (default), this is sum(), except when y contains several columns (then the values are not summarised). Use FALSE to not summarise the data at all.

stacked

A logical to indicate that values must be stacked, or "fill" to stack them to 100% (the same as stacked_fill = TRUE).

stacked_fill

A logical to indicate that values must be filled (i.e., stacked to 100%). If TRUE, this takes precedence over stacked.

horizontal

A logical to turn the plot 90 degrees using coord_flip(). This option also updates some theme options, so that e.g., x.label_italic will still apply to the original X-axis.

reverse

A logical to reverse the values of category. Use legend.reverse to reverse the legend of category.

smooth

A logical to add a smooth. In histograms, this will add the density count as an overlaying line (default: TRUE). In all other cases, a smooth will be added using geom_smooth() (default: FALSE).

smooth.method, smooth.formula, smooth.se, smooth.level, smooth.alpha, smooth.linewidth, smooth.linetype, smooth.colour

Settings for smooth. If not set, smooth.method and smooth.formula are chosen as in ggplot2: "loess" with y ~ x if the largest group (per category and facet) has fewer than 1000 values, and "gam" with y ~ s(x, bs = "cs") otherwise. The lines of the smooth are not affected by colour_transparency.

size

Size of the geom. Defaults to 2 for geoms point, jitter, and beeswarm; 4 for UpSet plots (using type = "upset"); 5 for dumbbell plots (using type = "dumbbell"); 0.75 otherwise.

linetype

Linetype of the geom, only suitable for geoms that draw lines. Possible options are:

  1. "solid" (default)

  2. "dashed"

  3. "dotted"

  4. "dotdash"

  5. "longdash"

  6. "twodash"

Both numbers and text are supported, e.g., linetype = 2 and linetype = "dashed" yield the same results.

linewidth

Linewidth of the geom, only suitable for geoms that draw lines. Defaults to:

  • 0.10 for sf

  • 0.25 for geoms that are continuous and have fills (such as area), except for geoms boxplot and violin

  • 1.0 for dumbbell plots (using type = "dumbbell") and UpSet plots (using type = "upset")

  • 0.5 otherwise (such as geoms line, boxplot, violin, and histogram)

binwidth

Width of bins (only useful for type = "histogram"), can be specified as a numeric value or as a function that calculates width from x, see geom_histogram(). It defaults to approx. diff(range(x)) divided by 12 to 22 based on the data.

width

Width of the geom. Defaults to 0.66 for geoms boxplot, violin and jitter, and to 0.5 otherwise.

jitter_seed

Seed (randomisation factor) to be set when using type = "jitter".

violin_scale

Scale to be set when using type = "violin", can also be set to "area".

legend

A logical to show (TRUE) or hide (FALSE) the legend, i.e. the box explaining the values of category. The default NULL shows it when the plot has a category.

legend.position

Position of the legend. This can be:

  • "top", "right", "bottom" or "left", can be abbreviated

  • "inside", to place the legend inside the plot area at ggplot2's default position

  • Two numbers between 0 and 1, to place the legend inside the plot area at these relative coordinates, e.g. c(0.95, 0.95) for the top right

  • "none", FALSE or NA to remove the legend

The default NULL sets it automatically: "right" for numeric category values and 'sf' plots, and "top" otherwise.

legend.reverse, legend.barheight, legend.barwidth, legend.nbin, legend.italic, legend.nrow

Other settings for the legend.

sankey_node_width

Width of the vertical nodes in a Sankey plot.

sankey_node_whitespace

Whitespace between the nodes in a Sankey plot.

sankey_alpha

Alpha of the flows in a Sankey plot.

sankey_remove_axes

Logical to indicate whether all axes must be removed in a Sankey plot.

zoom

A logical to indicate if the plot should be scaled to the data, i.e., not having the x and y axes to start at 0. This is identical to setting x.zoom = TRUE and y.zoom = TRUE.

sep

Separator character to use if multiple columns are given to either of the three directions: x, category and facet, e.g. facet = c(column1, column2).

print

A logical to indicate if the result should be printed instead of just returned.

text_factor

Text factor to use, which will apply to all texts shown in the plot.

font

Font (family) to use, can be set with options(plot2.font = "..."). Can be any installed system font or any of the > 1400 font names from Google Fonts. Custom fonts require the showtext, showtextdb and sysfonts packages. A Google Font that is not installed is downloaded once into the user cache folder of plot2 (tools::R_user_dir("plot2", "cache")); fonts that have not been used for 90 days are removed from it automatically. The font is applied only while the plot is drawn, so other plots in the session are not affected. When using custom fonts in R Markdown, be sure to set the chunk option fig.showtext = TRUE, otherwise an informative error will be generated.

theme

A valid ggplot2 theme to apply, or NULL to use the default theme_grey(). This argument accepts themes (e.g., theme_bw()), functions (e.g., theme_bw) and characters themes (e.g., "theme_bw"). A partial theme, such as theme(panel.background = element_blank()), is added on top of theme_minimal2(), and its elements take precedence over plot2's own settings. The default is theme_minimal2(), but can be set with options(plot2.theme = "...").

background

The background colour of the entire plot, can also be NA to remove it. Will be evaluated with get_colour(). Only applies when theme is not NULL.

markdown

A logical to turn all labels and titles into plotmath expressions, by converting common markdown language using the md_to_expression() function (defaults to TRUE).

...

Any argument to give to the geom. This will override automatically-set settings for the geom.

crs

The coordinate reference system (CRS) to use. If this is not left blank, sf::st_transform() will be used to transform the geometric data to the new CRS.

datalabels.centroid

A logical to indicate whether datalabels must be centred on the polygon (using sf::st_centroid(), the default), or be placed on the 'best' spot on the surface (using sf::st_point_on_surface()).

Details

The methods differ from the data frame method as follows:

  • Vectors and other objects (plot2.default()): the input is converted to a data frame first. Character and factor values are counted. A single character value that is the name of a data frame is replaced by that data frame.

  • Formulas (plot2.formula()): y ~ x takes the variables from data, e.g. plot2(Sepal.Length ~ Species, data = iris).

  • Frequency tables (plot2.freq(), from cleaner::freq()): x and y default to the items and their counts, the axis titles to "Item" and "Count", and x.sort to "freq-desc".

  • Spatial data (plot2.sf(), from the sf package): plots a map, without axis titles, axis expansion, grid or axes; the borders use the plot2.colour_sf option (default "grey50"), the fill uses plot2.colour_sf_fill, and the legend is on the right. The extra arguments crs and datalabels.centroid apply only here.

  • Matrices (plot2.matrix()): the row names (or row numbers) become x and every column becomes a category. A matrix with identical row and column names, such as the outcome of cor(), is plotted as a heatmap (type = "tile"). The axis titles are left out, unless the dimensions are named (e.g. dimnames = list(region = ..., year = ...)); these names are then used as titles of x and of the category.

For geographic information system (GIS) analysis, use the sf package with a data set containing geometries. The result can be used as input for plot2().

Value

A ggplot object.

Examples

# vectors: character values are counted
plot2(c("a", "b", "b", "c", "c", "c"))

# formulas
plot2(Sepal.Length ~ Species, data = iris)

# frequency tables
if (requireNamespace("cleaner", quietly = TRUE)) {
  plot2(cleaner::freq(iris$Species))
}

# correlation matrices become a heatmap
plot2(cor(mtcars[, 1:5]))

# spatial data
if (requireNamespace("sf", quietly = TRUE)) {
  plot2(netherlands)
}

plot2() Options

Description

These are the package options for usage in plot2(). These can all be set using options(), and their values can be retrieved using getOption().

Package Options

  • plot2.big.mark
    Default character for a thousands separator: ",", ".", " " or "". Defaults to "." if the decimal mark is a comma, and " " otherwise

  • plot2.colour
    Default colour to use in plots, defaults to "ggplot2" (the colours of ggplot2 itself)

  • plot2.colour_background
    Default background colour to use in plots, defaults to "white"

  • plot2.colour_font_axis
    Default colour of the axis text (axis.title.x and axis.title.y), defaults to "grey25"

  • plot2.colour_font_primary
    Default colour of the plot title and plot tag, defaults to "black"

  • plot2.colour_font_secondary
    Default colour of the plot subtitle and caption, defaults to "grey35"

  • plot2.colour_sf
    Default colour of the borders in sf plots, defaults to "grey50"

  • plot2.colour_sf_fill
    Default colour of the area fills in sf plots, defaults to the option plot2.colour

  • plot2.decimal.mark
    Default character for a decimal separator: "," or ".". Defaults to the option OutDec, which is "." in a standard R session

  • plot2.default_type
    Default plot type when type is left blank and cannot be determined from the data, defaults to "col". Any value of type can be used, such as "line" or "l"

  • plot2.font
    Default plot font family, defaults to the font of the graphics device. See the font argument of plot2()

  • plot2.language
    Language of the words that plot2 generates (such as automatic titles and the labels of y.24h and y.age) and of month and weekday names in date labels: "en" (default) or "nl" (Dutch). If not set, date labels follow the system locale.

  • plot2.silent
    A logical to hide the console messages when plotting (TRUE), default is FALSE. Messages are printed only in interactive sessions (and pkgdown builds), at the end of the plot2() call. Unless this option is TRUE, they are signalled as R conditions of class plot2_message (and plot2_caution for cautions), so they can also be caught with withCallingHandlers() or hidden with suppressMessages(). With TRUE, no message conditions are signalled at all, so R Markdown, Quarto and pkgdown output contain no messages either. Warnings are R warnings of class plot2_warning and are not hidden by this option.

  • plot2.text_factor
    Default factor to multiply all text sizes with, defaults to 1

  • plot2.theme
    Default plot theme, defaults to "theme_minimal2" (theme_minimal2())


An Even More Minimal Theme

Description

This ggplot2 theme provides even more white area and less clutter than theme_minimal().

Usage

theme_minimal2(
  ...,
  colour_font_primary = getOption("plot2.colour_font_primary", "black"),
  colour_font_secondary = getOption("plot2.colour_font_secondary", "grey35"),
  colour_font_axis = getOption("plot2.colour_font_axis", "grey25"),
  colour_background = getOption("plot2.colour_background", "white")
)

Arguments

...

Arguments passed on to ggplot2::theme().

colour_font_primary

Colour to set for the plot title and tag.

colour_font_secondary

Colour to set for the plot subtitle and caption.

colour_font_axis

Colour to set for the axis titles on both x and y.

colour_background

Colour to set for the background.

Examples

library(ggplot2)
ggplot(mtcars, aes(hp, mpg)) +
  geom_point()
  
ggplot(mtcars, aes(hp, mpg)) +
  geom_point() +
  theme_minimal2()
  
# in plot2(), the 'theme' argument defaults to theme_minimal2():
mtcars |>
  plot2(hp, mpg)
  
# set to NULL to use the ggplot2 default:
mtcars |>
  plot2(hp, mpg, theme = NULL)