Package {ggplotplus}

Title:	Universal Design-Oriented Enhancements for 'ggplot2'
Version:	0.5.5
BugReports:	https://github.com/MAISRC/ggplotplus/issues
Description:	A collection of enhancements to 'ggplot2', with a focus on creating Universally Designed, accessible graphs easily and quickly.
Depends:	R (≥ 4.1.0)
License:	MIT + file LICENSE
Encoding:	UTF-8
URL:	https://github.com/MAISRC/ggplotplus
RoxygenNote:	7.3.3
Language:	en-US
Imports:	ggplot2 (≥ 4.0.1), rlang, S7, grid, gtable, scales, viridisLite, polyclip, ggrepel (≥ 0.9.0), dplyr, stats
Suggests:	testthat (≥ 3.0.0), ragg (≥ 1.5.2), patchwork, cowplot
Config/testthat/edition:	3
LazyData:	true
NeedsCompilation:	no
Packaged:	2026-06-09 19:53:30 UTC; Bajcz
Author:	Alex Bajcz [aut, cre]
Maintainer:	Alex Bajcz <bajcz003@umn.edu>
Repository:	CRAN
Date/Publication:	2026-06-17 13:40:08 UTC

ggplotplus: Universal Design-Oriented Enhancements for 'ggplot2'

Description

A collection of enhancements to 'ggplot2', with a focus on creating Universally Designed, accessible graphs easily and quickly.

Author(s)

Maintainer: Alex Bajcz bajcz003@umn.edu (ORCID)

See Also

Useful links:

• https://github.com/MAISRC/ggplotplus

• Report bugs at https://github.com/MAISRC/ggplotplus/issues

Check whether an aesthetic is mapped to a continuous (numeric) variable

Description

Internal helper that determines whether a given aesthetic is mapped to a continuous variable. Used to guard legend override operations that are appropriate only for discrete legends (not colorbars), because applying a guide_legend() to a continuous scale would suppress the colorbar.

Usage

.aes_mapped_var_is_continuous(plot, aes_name)

Arguments

Details

The helper first checks for an explicit continuous scale on the plot. If none is found, it inspects the mapped expression and looks up the variable in the plot and layer data to determine whether it's numeric.

Value

A logical scalar. Returns TRUE if the aesthetic appears to be mapped to a continuous variable; otherwise returns FALSE.

Apply replacement labels for direct labels

Description

.apply_key_labels_plus() is an internal helper used by direct_labels_plus() to replace default group labels with user-supplied labels.

Usage

.apply_key_labels_plus(label_data, key_labels)

Arguments

Details

Named key_labels are treated as an explicit lookup table. Every unique value in label_data must appear among the names of key_labels; otherwise, the helper fails with an informative error.

Unnamed key_labels are assigned to unique labels in alphanumeric order. This behavior may be surprising, so the helper emits a message recommending named labels when users want more control.

Value

A character vector of labels with the same length as label_data.

Choose direct-label anchor points for grouped line data

Description

directlabel_lines() is an internal helper used by direct_labels_plus() when geometry = "line". It chooses one endpoint or extreme point per group, or per group-by-facet combination, to use as the anchor location for a direct label. How the label is then drawn with respect to that chosen point is determined by ggrepel::geom_label_repel().

Usage

.directlabel_lines(data, x, y, group, placement, adj_fact, facet_vars)

Arguments

Details

For "right" placement, the helper selects the row with the largest x-value in each group. For "left", it selects the smallest x-value. For "top", it selects the largest y-value. For "bottom", it selects the smallest y-value. After this anchor row is selected, adj_fact can shift the final label anchor outward or inward along the relevant axis.

This helper is intended for ordinary Cartesian line-like geometries where endpoint or extreme-value labeling is meaningful. It does not account for data generated by ggplot2 statistics, transformed scales, or coordinate transformations. For fitted lines or smooths, callers should pass the pre-computed fitted data.

Value

A tibble with one row per group or group-by-facet combination. The returned data include standardized x and y columns, .label_plus, and any grouping or faceting variables needed by ggplot2 to assign labels to panels correctly.

Choose direct-label anchor points for grouped point data

Description

directlabel_points() is an internal helper used by direct_labels_plus() when geometry = "point". It chooses one observed point per group, or per group-by-facet combination, to use as the anchor location for a direct label. How the label is then drawn with respect to that chosen point is determined by ggrepel::geom_label_repel().

Usage

.directlabel_points(data, x, y, group, placement, adj_fact, facet_vars)

Arguments

Details

The helper works by calculating a target location for each group and then selecting the observed point closest to that target. For "top" and "bottom" placements, the target is centered at the group's median x-value and then shifted toward the group's maximum or minimum y-value. For "left" and "right" placements, the same logic is applied with x and y reversed.

This helper assumes that label locations should be tied to observed points. It therefore never invents a new x/y coordinate for point labels. Empty or all-missing groups should be screened before this helper is called.

Value

A tibble with one row per group or group-by-facet combination. The returned data include standardized x and y columns, .label_plus, and any grouping or faceting variables needed by ggplot2 to assign labels to panels correctly.

Retrieve the pre-build label for an aesthetic

Description

Internal helper that attempts to determine the eventual user-facing label associated with a mapped aesthetic before the plot has been formally built.

Usage

.get_prebuild_aes_label(plot, aes_name)

Arguments

Details

The helper first checks for explicit labels supplied through ggplot2::labs() or related mechanisms. If no explicit label is found, it falls back to the mapped expression itself using rlang::as_label().

Both plot-level and layer-level mappings are searched.

ggplotplus uses this helper during pre-build guide processing to identify aesthetics that are likely to collapse into a shared legend, such as when both fill and shape are mapped to the same variable.

Value

A character string representing the best available pre-build label for the requested aesthetic.

Check whether ggplotplus coaching messages are enabled

Description

Internal helper that checks the session-level ggplotplus coaching option.

Usage

.ggplotplus_coaching_enabled()

Details

ggplotplus uses this helper to determine whether advisory or educational messages ("coaching") should be displayed during plot construction. Coaching messages can be globally enabled or disabled for the current R session using:

options(ggplotplus.enable_coaching = TRUE)
options(ggplotplus.enable_coaching = FALSE)

User-facing ggplotplus functions additionally expose local enable_coaching arguments; both the local setting and the global option must evaluate to TRUE for coaching messages to appear.

Value

A logical scalar. Returns TRUE if coaching messages are globally enabled for the current R session; otherwise returns FALSE.

Check whether a guide is suppressed for an aesthetic

Description

Internal helper that checks both scale-level and plot-level guide declarations to determine whether the guide for a given aesthetic has been explicitly suppressed.

Usage

.guide_is_none_for_aes(plot, aes_name)

Arguments

Details

This is used before adding ggplotplus legend-key overrides so that suppressed legends are not accidentally restored.

Value

A logical scalar. Returns TRUE if the guide is suppressed either through a scale or through guides().

Check whether a scale suppresses a guide

Description

Internal helper that checks whether a plot contains a scale for a given aesthetic with guide = "none".

Usage

.has_guide_none_for_aes(plot, aes_name)

Arguments

Details

This is used to preserve user intent when ggplotplus applies automatic legend key overrides. If a user has explicitly suppressed a guide through a scale, ggplotplus should not reintroduce that guide.

Value

A logical scalar. Returns TRUE if a matching scale has guide = "none"; otherwise returns FALSE.

Check whether plot-level guides suppress an aesthetic

Description

Internal helper that checks whether a plot-level guide specification suppresses the guide for a given aesthetic, such as through guides(fill = "none").

Usage

.has_plot_guide_none_for_aes(plot, aes_name)

Arguments

Details

This complements the scale-level guide checker above, because guide suppression can be declared either on a scale or through guides().

Value

A logical scalar. Returns TRUE if the plot-level guide for the aesthetic is "none" or a GuideNone object.

Merge ggplotplus legend-key overrides with an existing guide

Description

Internal helper that merges ggplotplus legend-key defaults with any user-specified override.aes values for a guide.

Usage

.merge_legend_override(plot, aes_name, override_list)

Arguments

Details

ggplotplus uses this helper to improve legend readability by overriding non-semantic, hard-to-read, constant alpha and size values in legend keys. Existing user overrides are preserved and take precedence over ggplotplus defaults for positive UX.

Value

A guide object. If no guide exists for aes_name, returns a new ggplot2::guide_legend() using override_list. If a guide exists, returns a copy with merged override.aes values, where existing user values win over ggplotplus defaults.

geom_point_plus() shape registry

Description

Package-private environment used to store built-in and user-registered point shapes for geom_point_plus().

Usage

.onLoad(libname, pkgname)

Collect column names from plot- and layer-level data

Description

Internal helper that gathers column names from all data frames associated with a ggplot object, including both plot-level data and any layer-specific data.

Usage

.plot_data_names(plot)

Arguments

Details

ggplotplus uses this helper when evaluating whether scale titles appear to still use raw column names, which may indicate that user-facing labels have not yet been customized with ggplot2::labs().

Value

A character vector of unique column names found across the plot-level and layer-level data frames associated with the plot.

Check whether a plot maps one or more aesthetics

Description

Internal helper that checks whether any layer in a ggplot object maps one or more requested aesthetics, either directly in the layer mapping or through inherited plot-level mappings.

Usage

.plot_has_mapped_aes(plot, aes_name)

Arguments

Details

This is used before plot building to determine whether an aesthetic such as alpha or size is being mapped explicitly, in which case ggplotplus should avoid overriding that aesthetic in legend keys.

Value

A logical scalar. Returns TRUE if any requested aesthetic is mapped in any layer, including through inherited global mappings.

Get registered geom_point_plus() shapes

Description

Internal helper that returns the current ggplotplus point-shape registry, including both built-in package shapes and any shapes added during the current R session with add_shape_plus().

Usage

.pointplus_shapes()

Value

A named list of point-shape data frames.

Safely check whether an S7 property is TRUE

Description

Internal helper that safely checks whether an object:

1. exists and is not NULL,

2. is an S7 object,

3. contains a specified property, and

4. has that property set to TRUE.

Usage

.s7_prop_is_true(object, prop)

Arguments

Details

This helper is primarily used to avoid errors when optional ggplotplus S7 components may not (yet) exist on a plot object.

Value

A logical scalar. Returns TRUE only if the object is a valid S7 object, the property exists, and the property value is exactly TRUE. Otherwise returns FALSE.

Standardize ggplotplus shape names

Description

Internal helper to normalize shape identifiers used by geom_point_plus(). Converts numeric shape codes corresponding to base R's fillable point shapes (21–25) into their ggplotplus string equivalents.

Usage

.standardize_pointplus_shape_names(shape)

Arguments

Details

This ensures consistent downstream handling regardless of whether users supply shapes as numbers (e.g., 21) or names (e.g., "circle").

Value

A character vector of standardized shape names.

Validate a geom_point_plus() shape definition

Description

Internal helper used by add_shape_plus() to check that a custom point shape has the structure needed by the ggplotplus shape-drawing machinery.

Usage

.validate_pointplus_shape(shape, name = NULL)

Arguments

Value

A cleaned shape data frame containing only x, y, and piece. The piece column is converted to sequential integers if it wasn't already formatted like that.

An alternative version of ggplot2's geomPoint proto that incorporates new, distinctive shapes.

Description

This ggplot proto object is called internally by geom_point2() and inherits most, but not all, of its methods and properties from ggplot2's standard geomPoint proto. However, it has different default aesthetics, a different shapes palette, and can draw these new shapes in a legend. This subclass is not meant to be encountered by the user and is instead fodder for geom_point_plus().

Usage

GeomPointPlus

Format

An object of class PointPlus (inherits from GeomPoint, Geom, ggproto, gg) of length 3.

Value

A ggplot2 ggproto subclass object.

Add a custom shape for geom_point_plus()

Description

Registers a custom point shape for use with geom_point_plus(). Custom shapes are defined by a data frame of connected polygon coordinates and, once validated, are stored in a session-level shape registry.

Usage

add_shape_plus(name = NULL, shape = NULL, overwrite = FALSE, ...)

Arguments

Details

A shape must be supplied as a data frame with columns x, y, and piece. The x and y columns define the vertices of the shape, centered around 0, 0. Coordinates should generally be scaled to about +/-0.4 to match the scaling of built-in point shapes. The piece column identifies separate polygon pieces within the same shape to generate "holes," as appropriate.

For inspiration and to model inputs, see ggplotplus_shapes_list for the structure of the built-in point shapes.

Value

Invisibly returns the registered shape name.

Examples

test_star = data.frame(
  x = c(0.000,  0.118,  0.380,  0.190,  0.235,
        0.000, -0.235, -0.190, -0.380, -0.118),
  y = c(0.400,  0.124,  0.124, -0.047, -0.324,
       -0.153, -0.324, -0.047,  0.124,  0.124),
  piece = 1
)

add_shape_plus("test_star", test_star)

Add direct labels to grouped point or line plots

Description

direct_labels_plus() adds procedurally placed text labels to grouped point or line plots as an alternative to using a legend, which might be space-inefficient, off to one side away from where readers will see it, or force readers to jump their focus long distances to align groups with labels. The function is intended as a friendlier alternative to manually placing group labels via ggplot2::annotate(). Labels are drawn using ggrepel::geom_label_repel(), so they'll repel one another as well as the plotted data they're labeling (within reason).

Usage

direct_labels_plus(
  data,
  x,
  y,
  group,
  placement = "top",
  geometry = "point",
  adj_fact = 0,
  key_labels = NULL,
  facet_vars = NULL,
  ...
)

Arguments

Details

This function is experimental. It currently works best for ordinary scatterplots and grouped line/path plots where each group has a visually meaningful position in two-dimensional (x/y) space. It will not work for every ggplot2 geometry, statistic, coordinate system, or faceting arrangement.

For point geometries, direct_labels_plus() calculates one label location per group by finding the observed point closest to a group-specific target positioned towards one of the "edges" of a group's cluster of points. For "top" and "bottom" placement, the target is horizontally centered on the group's median x-value and vertically placed near the group's maximum or minimum y-value. For "left" and "right" placement, the same logic is applied with x and y reversed.

For line geometries, labels are placed at the group-specific endpoint or extreme value implied by placement: the largest x-value for "right", the smallest x-value for "left", the largest y-value for "top", and the smallest y-value for "bottom". The final label anchor may then be adjusted by adj_fact.

To help labels repel from plotted points or lines, the function silently adds empty-label rows at the original data coordinates. ggrepel does not draw these empty labels, but still uses their positions when placing visible labels. This helps to ensure, in general, that labels neither cover each other nor the underlying data they're labelling.

Currently, the function sets defaults for the following parameters of ggrepel::geom_label_repel(): size (5), box.padding (0.5), max.overlaps (Inf), segment.size (1), and min.segment.length (0). However, these are overridable, if the user provides named arguments that at least partially match.

Known limitations:

• Label locations are calculated in the raw data space supplied to the function. Transformed scales, reversed axes, and non-Cartesian coordinate systems may give unexpected results. Pre-transform data rather than entering raw data and transforming later.

• coord_flip(), coord_polar(), map projections, and other coordinate transformations are not currently supported.

• The function places labels according to the data values supplied in data, not those subsequently generated by ggplot2 stat functions. For example, to label fitted smooth lines like those from ggplot2::geom_smooth(), feed this function fitted values outputted from such a function instead of the raw data.

• Very dense plots or plots with many groups will likely still have overlapping or poorly placed labels. ggrepel helps, but it cannot make a crowded plot uncrowded. Alas.

• Polygon, ribbon, area, segment, curve, and spatial geometries are not currently supported but might be in the future.

Value

A ggplot2 layer produced by ggrepel::geom_label_repel().

Examples

ggplot2::ggplot(iris, ggplot2::aes(Sepal.Length, Sepal.Width, color = Species)) +
ggplot2::geom_point() +
direct_labels_plus(
data = iris,
x = Sepal.Length,
y = Sepal.Width,
group = Species,
placement = "right",
geometry = "point"
) +
ggplot2::guides(color = "none")

line_data = ChickWeight |>
dplyr::group_by(Diet, Time) |>
dplyr::summarize(weight = mean(weight), .groups = "drop")

ggplot2::ggplot(line_data, ggplot2::aes(Time, weight, color = Diet)) +
ggplot2::geom_line(ggplot2::aes(group = Diet)) +
direct_labels_plus(
data = line_data,
x = Time,
y = weight,
group = Diet,
placement = "right",
geometry = "line",
adj_fact = 0.05
) +
ggplot2::guides(color = "none")

Jittered points with ggplotplus point shapes

Description

geom_jitter_plus() is a convenience wrapper around geom_point_plus() that applies jittering to reduce overplotting. It supports the same custom shape palette and fillable point rendering as geom_point_plus() while exposing the familiar width, height, and seed arguments used by ggplot2::position_jitter().

Usage

geom_jitter_plus(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "jitter",
  ...,
  width = NULL,
  height = NULL,
  seed = NA,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2 layer.

Examples

ggplot2::ggplot(iris, ggplot2::aes(Species, Sepal.Length)) +
  geom_jitter_plus(
    ggplot2::aes(shape = Species, fill = Petal.Length),
    width = 0.15,
    seed = 1,
    colour = "black"
  )

ggplot2::ggplot(iris, ggplot2::aes(Species, Sepal.Length)) +
  geom_jitter_plus(
    ggplot2::aes(shape = Species),
    chosen_shapes = c("plus", "flower", "lotus"),
    seed = 123
  )

A backend version of geom_point() that can access distinctive shapes.

Description

This function behaves much like ggplot2's geom_point() function except that it allows access to a palette of nine new shapes that vary in their openness, spikiness, and intersectionality, making them more easily distinguished. This function is not meant to be called directly–instead, geom_point_plus() calls and modifies this function and is the intended function for users.

Usage

geom_point2(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  shapes = NULL,
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2 layer object.

Create and add a scatterplot layer to your ggplot2 graph with new, distinctive shapes.

Description

This function behaves similarly to ggplot2::geom_point() except that it takes several new inputs: shapes, n_shapes, shape_values, legend_title, key_size, and show_shape_scale. These are explained below.

Usage

geom_point_plus(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  avail_shapes = NULL,
  n_shapes = length(avail_shapes),
  chosen_shapes = NULL,
  legend_title = NULL,
  legend_labels = NULL,
  include_shape_legend = TRUE,
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  show_shape_scale = TRUE
)

Arguments

Details

Collectively, these inputs allow geom_point_plus() to access and draw several new and distinctive shapes that are designed to be more readily distinguishable from one another when shape communicates difference.

To see the special shapes available via this function run geom_point_plus_shapes().

Note: As of Version 0.5.2, shapes 21-25 in R's default shapes palette are now also available via geom_point_plus_shapes(); these are called "circle", "square", "diamond", "triangle_up", and "triangle_down", respectively, though they can also be referred to by number.

Value

A ggplot2 layer object.

Examples

ggplot2::ggplot(mtcars, ggplot2::aes(wt, mpg, fill = drat)) +
geom_point_plus(ggplot2::aes(shape = factor(gear)), size = 5)
ggplot2::ggplot(mtcars, ggplot2::aes(wt, mpg, fill = factor(cyl))) +
geom_point_plus(ggplot2::aes(shape = factor(carb)),
shape_values = c("squircle", "lotus", "sunburst", "octagon", "cross", "oval"),
size = 5, stroke = 0.4)
ggplot2::ggplot(iris, ggplot2::aes(Petal.Width, Petal.Length, fill = Species)) +
geom_point_plus(ggplot2::aes(shape = Species), size = 5, alpha = 0.7)

Demo plot showing geom_point_plus() shapes

Description

A prebuilt ggplot object displaying the nine custom point shapes designed specifically for use in geom_point_plus(). As of Version 0.5.2, other shapes are also available, but those are not shown via this function. See the documentation for geom_point_plus() for details.

Usage

geom_point_plus_shapes()

Format

A ggplot object.

Value

Returns a ggplot2 graph showing the ggplotplus shapes palette.

Custom shape palette for geom_point_plus()

Description

A named list of custom point shapes used by geom_point_plus(). Each element contains x and y coordinates plus a piece identifier used when drawing filled shapes and holes.

Usage

ggplotplus_shapes_list

Format

A named list of data frames. Each data frame has columns:

x

X coordinates for the shape outline.

y

Y coordinates for the shape outline.

piece

Integer identifier for separate polygon pieces or holes.

Examples

names(ggplotplus_shapes_list)

Convert a ggplotplus plot into a grob

Description

Convenience helper for converting ggplotplus plot objects into grobs using ggplot2::ggplotGrob().

Usage

ggplotplus_to_cowplot(plot)

Arguments

Details

This is primarily intended for compatibility with packages such as cowplot that may not yet fully recognize custom S7 plot subclasses during internal dispatch.

Value

A grob object suitable for use with grid-based plotting utilities such as cowplot::plot_grid().

Examples

p = ggplot2::ggplot(iris, ggplot2::aes(Sepal.Length, Petal.Length, colour = Species)) +
  geom_point_plus()

if(requireNamespace("cowplot", quietly = TRUE)) {

cowplot::plot_grid(
  ggplotplus_to_cowplot(p),
  ggplotplus_to_cowplot(p)
)
}

Convert a ggplotplus plot into a patchwork-compatible element

Description

Convenience helper for converting ggplotplus plot objects into patchwork-compatible wrapped elements.

Usage

ggplotplus_to_patchwork(plot)

Arguments

Details

This helper is primarily intended for compatibility with patchwork, whose plot-composition operators may not yet fully recognize custom S7 plot subclasses under ggplot2 4.x.

Internally, the plot is first converted into a grob using ggplotplus_to_cowplot(), then wrapped using patchwork::wrap_elements().

This helper requires the patchwork package, but ggplotplus does not import patchwork. Users only need patchwork installed if they want to compose ggplotplus plots with patchwork.

Value

A patchwork-compatible wrapped plot element.

Examples

if(requireNamespace("patchwork", quietly = TRUE)) {

p1 = ggplot2::ggplot(iris, ggplot2::aes(Sepal.Length, Petal.Length, colour = Species)) +
  geom_point_plus()

p2 = ggplot2::ggplot(mtcars, ggplot2::aes(wt, mpg, shape = factor(cyl))) +
  geom_point_plus()

(ggplotplus_to_patchwork(p1) |
  ggplotplus_to_patchwork(p2)) +
  patchwork::plot_annotation(
    title = "ggplotplus + patchwork"
  )
}

Subtle, Minimal Gridlines For When and Where They Help

Description

Adds light and easily ignored major gridlines along only axes mapped to continuous variables. Minor gridlines are blanked. This enables the benefits of gridlines (in instances where there are some) but minimizes visual clutter and cognitive load.

Usage

gridlines_plus(
  color = "gray90",
  linewidth = 1.2,
  linetype = "solid",
  notx = FALSE,
  noty = FALSE,
  override_legend_alphasize = TRUE,
  enable_coaching = TRUE
)

Arguments

Details

gridlines_plus() ignores any theme instructions to blank major panel scales in either the x or y direction via, e.g., theme_plus(panel.grid.major.y = ggplot2::element_blank()). Instead, users can set, e.g., noty == TRUE to prevent gridlines from being drawn in a specific direction, even if that scale is continuous. Similarly, gridline color, linewidth, and linetypes should be set directly in gridlines_plus() instead of via theme(). Trying to do the latter will fail without error or warning!

Under the hood, gridlines_plus() checks layer and/or global mappings to see if x and/or y are continuous. It does this by inspecting the trained panel scales. It then turns on major gridlines for continuous directions and explicitly blanks gridlines for other axes (as well as all minor gridlines).

Value

An ggplot class object for adding to a plot with +.

Examples

library(ggplot2)

ggplot2::ggplot(iris, ggplot2::aes(Sepal.Length, Petal.Length)) +
  ggplot2::geom_point() +
  theme_plus() + #WE DON'T RECOMMEND USING gridlines_plus() WITHOUT ALSO USING theme_plus()
  gridlines_plus()

# Only y is continuous here (x is discrete) → y-only major gridlines
ggplot2::ggplot(mtcars, ggplot2::aes(factor(cyl), mpg)) +
  ggplot2::geom_boxplot() +
  gridlines_plus(color = "grey85", linewidth = 1, linetype = "dashed")

# Works with derived continuous axes (histogram)
ggplot2::ggplot(mtcars, aes(mpg)) +
  ggplot2::geom_histogram() +
  gridlines_plus()

Continuous Scales With Endpoint-Aware Breaks

Description

scale_continuous_plus() is an opinionated wrapper around ggplot2's continuous x, y, colour, and fill scales. It chooses "pretty" breaks while gently expanding the scale limits so breaks generally will appear near both ends of the data range.

Usage

scale_continuous_plus(
  scale = NA,
  ...,
  thin.labels = FALSE,
  pad.labels = "start",
  target.breaks = 5,
  buffer_frac = 0.05,
  split_name = FALSE
)

Arguments

Details

This is useful because ggplot2's default continuous scales frequently will leave the ends of an axis or colorbar visually unlabeled, making it look as if an endpoint break is missing.

scale_continuous_plus() routes to one of ggplot2::scale_x_continuous(), ggplot2::scale_y_continuous(), ggplot2::scale_colour_continuous(), or ggplot2::scale_fill_continuous() based on scale.

Unlike the ggplot2 defaults, this function intentionally controls breaks and limits. If either is supplied through ..., it's ignored with a warning. Transformed scales are also not currently supported; pre-transform the data or use ggplot2's scale functions directly when a transformed scale is needed.

User-supplied label vectors are supported, but endpoint-aware breaks can sometimes create hidden outer breaks. When possible, this function pads label vectors with blank labels to align them with the computed break vector in length. If alignment is ambiguous by one label, use pad.labels to choose which side of the input labels vector to pad.

Value

A ggplot2 continuous scale object.

Examples

library(ggplot2)

ggplot(iris, aes(Sepal.Width, Sepal.Length)) +
  geom_point() +
  scale_continuous_plus(scale = "x") +
  scale_continuous_plus(scale = "y")

ggplot(iris, aes(Sepal.Width, Sepal.Length, fill = Petal.Length)) +
  geom_point(shape = 21) +
  scale_continuous_plus(scale = "x") +
  scale_continuous_plus(scale = "y") +
  scale_continuous_plus(scale = "fill")

ggplot(iris, aes(Sepal.Width, Sepal.Length)) +
  geom_point() +
  scale_continuous_plus(
    scale = "y",
    name = "Sepal length",
    labels = LETTERS[1:5],
    pad.labels = "start"
  )

A Universal Design-Oriented Base Ggplot2 Theme With Scalable and Overridable Defaults

Description

theme_plus() returns a ggplot2 theme designed to make publication-quality, accessible graphs easier to produce. It keeps all of ggplot2’s normal behaviors (last theme wins; user overrides take precedence), but bakes in opinionated defaults with Universal Design in mind. A few knobs let you scale typography/lines, flip the legend layout, and switch the background color if desired.

Usage

theme_plus(
  ...,
  legend_pos = "top",
  base_font_size = 16,
  base_linewidth = 1.2,
  base_rectlinewidth = 1.2,
  line_color = "black",
  text_color = "black",
  background_color = "#FFFEFD",
  palette_discrete = "D",
  palette_continuous = "E",
  begin_discrete = 0,
  end_discrete = 0.72,
  begin_continuous = 0,
  end_continuous = 1,
  export_width = 7.25,
  export_height = 5.95,
  override_legend_alphasize = TRUE,
  enable_coaching = TRUE
)

Arguments

Details

Internally, text sizes are expressed with rel(), so they scale with base_font_size. Line/rect line thicknesses start from base_linewidth and base_rectlinewidth and scale similarly with rel().

The function builds a base theme, then adds any user overrides via theme(...), so the user's preferences always take precedence.

Value

A ggplot2 theme object to add with +.

See Also

ggplot2::theme(), ggplot2::theme_gray(), ggplot2::theme_get()

Examples

# Basic use
library(ggplot2)
ggplot(iris, aes(Sepal.Length, Petal.Length, colour = Species)) +
  geom_point() +
  theme_plus()

# Prefer the right-side legend and pure white background
ggplot(mtcars, aes(wt, mpg)) +
  geom_point() +
  theme_plus(legend_pos = "right", background_color = "white")

# Scale text up and make lines a bit lighter
ggplot(iris, aes(Sepal.Length, Petal.Length)) +
  geom_point() +
  theme_plus(base_font_size = 18, base_linewidth = 1.0)

# You can still override any element normally via theme()
ggplot(iris, aes(Sepal.Length, Petal.Length)) +
  geom_point() +
  theme_plus() +
  theme(axis.line = element_line(linewidth = 0.8))

# But you could just as easily do so via theme_plus()
ggplot(iris, aes(Sepal.Length, Petal.Length)) +
  geom_point() +
  theme_plus(axis.line = element_line(linewidth = 0.8))

Relocate a Y Axis Title to Above the Y Axis on a Ggplot and Turn it Horizontal.

Description

This function relocates the y axis title of a ggplot to the top, above the y axis line and left-justified to the left edge of the y axis labels, sort of like a plot subtitle. It also orients the text horizontally for space-efficiency and easy reading. This is otherwise difficult to do using ggplot2's default styling tools.

Usage

yaxis_title_plus(
  location = "top",
  nudgeTopLegendDown = FALSE,
  nudgeHowMuch = 20,
  override_legend_alphasize = TRUE,
  enable_coaching = TRUE
)

Arguments

Value

An ggplot class object for adding to a plot with +.

Examples

#WE DO NOT RECOMMEND USING yaxis_title_plus() WITHOUT theme_plus()
ggplot2::ggplot(iris, ggplot2::aes(x=Sepal.Length, y=Petal.Length)) +
ggplot2::geom_point() +
theme_plus() +
yaxis_title_plus()