Package {ggrefine}

Title:	Publication-Quality 'ggplot2' Themes
Version:	1.0.0
Description:	Complete themes and functions for publication-quality 'ggplot2' visualisation.
License:	MIT + file LICENSE
URL:	https://github.com/davidhodge931/ggrefine, https://davidhodge931.github.io/ggrefine/
BugReports:	https://github.com/davidhodge931/ggrefine/issues
Depends:	R (≥ 4.1.0)
Imports:	blends, farver, ggplot2 (≥ 4.0.0), grid, jumble, rlang, scales, viridis
Suggests:	dplyr, flexoki, knitr, patchwork, rmarkdown, spelling, tidyr
Encoding:	UTF-8
Language:	en-GB
Config/roxygen2/version:	8.1.0
NeedsCompilation:	no
Packaged:	2026-10-29 19:12:09 UTC; david
Author:	David Hodge [aut, cre, cph]
Maintainer:	David Hodge <davidhodge931@gmail.com>
Repository:	CRAN
Date/Publication:	2026-10-29 20:50:02 UTC

Blend fill into a derived colour mapping

Description

Note: this sets colour, not fill — fill is the value it reads from, colour is what it derives. Maps colour to a blended version of fill, evaluated after scale training via ggplot2::after_scale(). Attaches no scale itself — use scale_colour_blend_discrete() (or ⁠_continuous⁠/⁠_binned⁠) for a ready-to-plot version that also scales fill. Requires the ggrefine function to be used instead of ggplot2::ggplot to work where no fill aesthetic is mapped.

Usage

aes_colour_blend(blend = NULL)

Arguments

Value

A ggplot2 mapping object (as returned by ggplot2::aes()).

Derive a legible colour by contrasting against fill

Description

Note: this sets colour, not fill — fill is the value it reads from, colour is what it derives. Maps colour to a dark or light shade chosen for contrast against the layer's fill aesthetic, evaluated after scale training via ggplot2::after_scale(). Attaches no scale itself — sits downstream of whatever fill scale you've already applied.

Usage

aes_colour_contrast(dark = NULL, light = NULL, ...)

Arguments

Value

A ggplot2 mapping object (as returned by ggplot2::aes()).

Derive a legible colour by contrasting against the panel background

Description

Maps colour to a dark or light shade chosen for contrast against the active theme's panel (or plot) background fill, evaluated after scale training via ggplot2::after_scale(). Attaches no scale itself.

Usage

aes_colour_panel(dark = NULL, light = NULL, ...)

Arguments

Value

A ggplot2 mapping object (as returned by ggplot2::aes()).

Blend colour into a derived fill mapping

Description

Note: this sets fill, not colour — colour is the value it reads from, fill is what it derives. Maps fill to a blended version of colour, evaluated after scale training via ggplot2::after_scale(). Attaches no scale itself — use scale_fill_blend_discrete() (or ⁠_continuous⁠/⁠_binned⁠) for a ready-to-plot version that also scales colour.

Usage

aes_fill_blend(blend = NULL)

Arguments

Value

A ggplot2 mapping object (as returned by ggplot2::aes()).

Initialize a plot object with theme-aware default aesthetics

Description

ggrefine() initializes a plot object using a specified plotting function (defaults to ggplot2::ggplot()) and pre-populates default identity fill and colour aesthetic mappings derived from the active theme's geom defaults (falling back to "grey35" and "black" respectively).

These default aesthetics act as lightweight fallbacks and are cleanly overridden when explicit mappings are added in subsequent layers via ggplot2::aes().

Usage

ggrefine(data = NULL, initialise = ggplot2::ggplot)

Arguments

Value

A plot object initialized with default aesthetic mappings.

Examples

library(ggplot2)
library(dplyr)

set_theme(ggrefine::theme_lights())

mpg |>
  count(class) |>
  ggrefine() +
  aes(x = class, y = n, fill = class) +
  geom_col() +
  scale_colour_blend_discrete()

Refine plot axes and panel grid

Description

A single entry point over the axis_mode x grid_mode combinations previously exposed as sixteen separate ⁠refine_*_*()⁠ functions. Those functions still exist internally (e.g. .refine_modern_drift()) and do the actual work; this function just dispatches to the right one.

Usage

refine_axis_grid(
  discrete = "none",
  orientation = NULL,
  ...,
  axis_mode = "modern",
  grid_mode = "flow"
)

Arguments

Details

axis_mode controls what happens to axis lines, ticks, text, and titles:

classic

Removes ticks on discrete axes only.

modern

Like classic, plus removes the axis line and ticks on the non-orientation axis.

minimal

Removes all axis lines and ticks, regardless of orientation or discreteness.

void

Like minimal, plus removes all axis text and titles.

grid_mode controls what happens to panel gridlines:

keep

Leaves panel gridlines unchanged.

drift

Removes gridlines on the orientation axis, but only when at least one axis is discrete.

flow

Removes gridlines on the orientation axis unconditionally.

drop

Removes all panel gridlines.

Value

A ggplot2 theme object.

refine_darks (internal, not exported)

Description

Builds the colour-only, incomplete theme() elements used by update_darks(). Not exported (no ⁠@export⁠ tag); documented with ⁠@keywords internal⁠ so that ⁠@inheritParams refine_lights⁠ resolves on the public ⁠update_*()⁠ functions.

Usage

refine_darks(
  ...,
  text_colour = "#CECDC3",
  title_colour = NULL,
  subtitle_colour = NULL,
  caption_colour = NULL,
  axis_line_colour = NULL,
  axis_ticks_colour = NULL,
  legend_axis_line_colour = NULL,
  legend_background_fill = NULL,
  legend_key_fill = NULL,
  legend_ticks_colour = NULL,
  panel_background_fill = "#282726",
  panel_grid_colour = "#100F0F",
  plot_background_fill = "#100F0F"
)

Arguments

Value

An incomplete ggplot theme, intended to be added to an existing theme.

refine_greys (internal, not exported)

Description

Builds the colour-only, incomplete theme() elements used by update_greys(). Not exported (no ⁠@export⁠ tag); documented with ⁠@keywords internal⁠ so that ⁠@inheritParams refine_lights⁠ resolves on the public ⁠update_*()⁠ functions.

Usage

refine_greys(
  ...,
  text_colour = "#100F0F",
  title_colour = NULL,
  subtitle_colour = NULL,
  caption_colour = NULL,
  axis_line_colour = NULL,
  axis_ticks_colour = NULL,
  legend_axis_line_colour = NULL,
  legend_background_fill = NULL,
  legend_key_fill = NULL,
  legend_ticks_colour = NULL,
  panel_background_fill = "#F2F0E5FF",
  panel_grid_colour = "white",
  plot_background_fill = "white"
)

Arguments

Value

An incomplete ggplot theme, intended to be added to an existing theme.

Move Legend

Description

Helper shortcut to set legend position, location, and margins.

Usage

refine_legend(position = "right", ...)

Arguments

Value

A ggplot2 theme object.

refine_lights (internal, not exported)

Description

Builds the colour-only, incomplete theme() elements used by update_lights(). Not exported (no ⁠@export⁠ tag); documented with ⁠@keywords internal⁠ so that ⁠@inheritParams refine_lights⁠ resolves on the public ⁠update_*()⁠ functions.

Usage

refine_lights(
  ...,
  text_colour = "#100F0F",
  title_colour = NULL,
  subtitle_colour = NULL,
  caption_colour = NULL,
  axis_line_colour = NULL,
  axis_ticks_colour = NULL,
  legend_axis_line_colour = NULL,
  legend_background_fill = NULL,
  legend_key_fill = NULL,
  legend_ticks_colour = NULL,
  panel_background_fill = "white",
  panel_grid_colour = "#F2F0E5",
  plot_background_fill = "white"
)

Arguments

Value

An incomplete ggplot theme, intended to be added to an existing theme.

Scale fill, and derive colour by blending (binned)

Description

Scales fill with a binned colour scale, and additionally maps colour to a blended version of the resulting fill, via aes_colour_blend(). The colour legend is suppressed since fill already communicates the mapping.

Usage

scale_colour_blend_binned(blend = NULL, ...)

Arguments

Value

A list of ggplot2 components (a mapping, a binned colour/fill scale, and a guide) that can be added to a ggplot object.

Scale fill, and derive colour by blending (continuous)

Description

Scales fill with a continuous colour scale, and additionally maps colour to a blended version of the resulting fill, via aes_colour_blend(). The colour legend is suppressed since fill already communicates the mapping.

Usage

scale_colour_blend_continuous(blend = NULL, ...)

Arguments

Value

A list of ggplot2 components (a mapping, a continuous colour/fill scale, and a guide) that can be added to a ggplot object.

Scale fill, and derive colour by blending (discrete)

Description

Scales fill with a discrete colour scale, and additionally maps colour to a blended version of the resulting fill, via aes_colour_blend(). The colour legend is suppressed since fill already communicates the mapping.

Usage

scale_colour_blend_discrete(blend = NULL, ...)

Arguments

Value

A list of ggplot2 components (a mapping, a discrete colour/fill scale, and a guide) that can be added to a ggplot object.

Scale colour, and derive fill by blending (binned)

Description

Scales colour with a binned colour scale, and additionally maps fill to a blended version of the resulting colour, via aes_fill_blend(). The fill legend is suppressed since colour already communicates the mapping.

Usage

scale_fill_blend_binned(blend = NULL, ...)

Arguments

Value

A list of ggplot2 components (a mapping, a binned colour/fill scale, and a guide) that can be added to a ggplot object.

Scale colour, and derive fill by blending (continuous)

Description

Scales colour with a continuous colour scale, and additionally maps fill to a blended version of the resulting colour, via aes_fill_blend(). The fill legend is suppressed since colour already communicates the mapping.

Usage

scale_fill_blend_continuous(blend = NULL, ...)

Arguments

Value

A list of ggplot2 components (a mapping, a continuous colour/fill scale, and a guide) that can be added to a ggplot object.

Scale colour, and derive fill by blending (discrete)

Description

Scales colour with a discrete colour scale, and additionally maps fill to a blended version of the resulting colour, via aes_fill_blend(). The fill legend is suppressed since colour already communicates the mapping.

Usage

scale_fill_blend_discrete(blend = NULL, ...)

Arguments

Value

A list of ggplot2 components (a mapping, a discrete colour/fill scale, and a guide) that can be added to a ggplot object.

Set continuous x-axis minimum flush to zero

Description

A convenience wrapper around ggplot2::scale_x_continuous() that sets the lower limit of the x-axis strictly to zero with no padding by default, while allowing full customization of scale parameters.

Usage

scale_x_zero(expand = ggplot2::expansion(c(0, 0.05)), limits = c(0, NA), ...)

Arguments

Value

A ScaleContinuousPosition object.

Set continuous y-axis minimum flush to zero

Description

A convenience wrapper around ggplot2::scale_y_continuous() that sets the lower limit of the y-axis strictly to zero with no padding by default, while allowing full customization of scale parameters.

Usage

scale_y_zero(expand = ggplot2::expansion(c(0, 0.05)), limits = c(0, NA), ...)

Arguments

Value

A ScaleContinuousPosition object.

set_darks——————————————————————–

Description

Builds theme_darks() and registers it as the session-wide default theme with ggplot2::set_theme(). All arguments are forwarded to theme_darks().

Usage

set_darks(
  ...,
  text_size = 10,
  text_family = "",
  text_colour = "#CECDC3",
  title_size = NULL,
  title_family = NULL,
  title_colour = NULL,
  subtitle_size = NULL,
  subtitle_family = NULL,
  subtitle_colour = NULL,
  caption_size = NULL,
  caption_family = NULL,
  caption_colour = NULL,
  caption_hjust = 0,
  legend_position = "right",
  legend_axis_line_colour = NULL,
  legend_axis_line_linewidth = NULL,
  legend_background_fill = NULL,
  legend_key_fill = NULL,
  legend_ticks_colour = NULL,
  legend_ticks_linewidth = NULL,
  legend_ticks_linetype = 1,
  legend_ticks_length = grid::unit(c(2.75, 0), "pt"),
  axis_line_colour = NULL,
  axis_line_linewidth = 0.15,
  axis_ticks_colour = NULL,
  axis_ticks_linewidth = NULL,
  axis_ticks_length = grid::unit(3.66, "pt"),
  panel_background_fill = "#282726",
  panel_grid_colour = "#100F0F",
  panel_grid_linetype = 1,
  panel_grid_linewidth = 1,
  panel_grid_minor_linetype = 1,
  panel_grid_minor_linewidth = ggplot2::rel(0.5),
  plot_background_fill = "#100F0F"
)

Arguments

Details

Set the darks theme as the active ggplot2 theme

Value

Invisibly returns the previously active theme, so it can be restored with ggplot2::set_theme().

set_greys——————————————————————–

Description

Builds theme_greys() and registers it as the session-wide default theme with ggplot2::set_theme(). All arguments are forwarded to theme_greys().

Usage

set_greys(
  ...,
  text_size = 10,
  text_family = "",
  text_colour = "#100F0F",
  title_size = NULL,
  title_family = NULL,
  title_colour = NULL,
  subtitle_size = NULL,
  subtitle_family = NULL,
  subtitle_colour = NULL,
  caption_size = NULL,
  caption_family = NULL,
  caption_colour = NULL,
  caption_hjust = 0,
  legend_position = "right",
  legend_axis_line_colour = NULL,
  legend_axis_line_linewidth = NULL,
  legend_background_fill = NULL,
  legend_key_fill = NULL,
  legend_ticks_colour = NULL,
  legend_ticks_linewidth = NULL,
  legend_ticks_linetype = 1,
  legend_ticks_length = grid::unit(c(2.75, 0), "pt"),
  axis_line_colour = NULL,
  axis_line_linewidth = 0.15,
  axis_ticks_colour = NULL,
  axis_ticks_linewidth = NULL,
  axis_ticks_length = grid::unit(3.66, "pt"),
  panel_background_fill = "#F2F0E5FF",
  panel_grid_colour = "white",
  panel_grid_linetype = 1,
  panel_grid_linewidth = 1,
  panel_grid_minor_linetype = 1,
  panel_grid_minor_linewidth = ggplot2::rel(0.5),
  plot_background_fill = "white"
)

Arguments

Details

Set the greys theme as the active ggplot2 theme

Value

Invisibly returns the previously active theme, so it can be restored with ggplot2::set_theme().

set_lights——————————————————————–

Description

Builds theme_lights() and registers it as the session-wide default theme with ggplot2::set_theme(). All arguments are forwarded to theme_lights().

Usage

set_lights(
  ...,
  text_size = 10,
  text_family = "",
  text_colour = "#100F0F",
  title_size = NULL,
  title_family = NULL,
  title_colour = NULL,
  subtitle_size = NULL,
  subtitle_family = NULL,
  subtitle_colour = NULL,
  caption_size = NULL,
  caption_family = NULL,
  caption_colour = NULL,
  caption_hjust = 0,
  legend_position = "right",
  legend_axis_line_colour = NULL,
  legend_axis_line_linewidth = NULL,
  legend_background_fill = NULL,
  legend_key_fill = NULL,
  legend_ticks_colour = NULL,
  legend_ticks_linewidth = NULL,
  legend_ticks_linetype = 1,
  legend_ticks_length = grid::unit(c(2.75, 0), "pt"),
  axis_line_colour = NULL,
  axis_line_linewidth = 0.15,
  axis_ticks_colour = NULL,
  axis_ticks_linewidth = NULL,
  axis_ticks_length = grid::unit(3.66, "pt"),
  panel_background_fill = "white",
  panel_grid_colour = "#F2F0E5",
  panel_grid_linetype = 1,
  panel_grid_linewidth = 1,
  panel_grid_minor_linetype = 1,
  panel_grid_minor_linewidth = ggplot2::rel(0.5),
  plot_background_fill = "white"
)

Arguments

Details

Set the lights theme as the active ggplot2 theme

Value

Invisibly returns the previously active theme, so it can be restored with ggplot2::set_theme().

theme_darks——————————————————————

Description

A complete theme with a dark plot and panel background. Uses flexoki inspired colours.

Usage

theme_darks(
  ...,
  text_size = 10,
  text_family = "",
  text_colour = "#CECDC3",
  title_size = NULL,
  title_family = NULL,
  title_colour = NULL,
  subtitle_size = NULL,
  subtitle_family = NULL,
  subtitle_colour = NULL,
  caption_size = NULL,
  caption_family = NULL,
  caption_colour = NULL,
  caption_hjust = 0,
  legend_position = "right",
  legend_axis_line_colour = NULL,
  legend_axis_line_linewidth = NULL,
  legend_background_fill = NULL,
  legend_key_fill = NULL,
  legend_ticks_colour = NULL,
  legend_ticks_linewidth = NULL,
  legend_ticks_linetype = 1,
  legend_ticks_length = grid::unit(c(2.75, 0), "pt"),
  axis_line_colour = NULL,
  axis_line_linewidth = 0.15,
  axis_ticks_colour = NULL,
  axis_ticks_linewidth = NULL,
  axis_ticks_length = grid::unit(3.66, "pt"),
  panel_background_fill = "#282726",
  panel_grid_colour = "#100F0F",
  panel_grid_linetype = 1,
  panel_grid_linewidth = 1,
  panel_grid_minor_linetype = 1,
  panel_grid_minor_linewidth = ggplot2::rel(0.5),
  plot_background_fill = "#100F0F"
)

Arguments

Details

Dark theme

Value

A ggplot theme.

theme_greys——————————————————————

Description

A complete theme with a light grey panel background and white panel grid colour. Uses flexoki inspired colours.

Usage

theme_greys(
  ...,
  text_size = 10,
  text_family = "",
  text_colour = "#100F0F",
  title_size = NULL,
  title_family = NULL,
  title_colour = NULL,
  subtitle_size = NULL,
  subtitle_family = NULL,
  subtitle_colour = NULL,
  caption_size = NULL,
  caption_family = NULL,
  caption_colour = NULL,
  caption_hjust = 0,
  legend_position = "right",
  legend_axis_line_colour = NULL,
  legend_axis_line_linewidth = NULL,
  legend_background_fill = NULL,
  legend_key_fill = NULL,
  legend_ticks_colour = NULL,
  legend_ticks_linewidth = NULL,
  legend_ticks_linetype = 1,
  legend_ticks_length = grid::unit(c(2.75, 0), "pt"),
  axis_line_colour = NULL,
  axis_line_linewidth = 0.15,
  axis_ticks_colour = NULL,
  axis_ticks_linewidth = NULL,
  axis_ticks_length = grid::unit(3.66, "pt"),
  panel_background_fill = "#F2F0E5FF",
  panel_grid_colour = "white",
  panel_grid_linetype = 1,
  panel_grid_linewidth = 1,
  panel_grid_minor_linetype = 1,
  panel_grid_minor_linewidth = ggplot2::rel(0.5),
  plot_background_fill = "white"
)

Arguments

Details

Grey theme

Value

A ggplot theme.

theme_lights——————————————————————

Description

A complete theme with a white panel background and a light panel grid colour. Uses flexoki inspired colours.

Usage

theme_lights(
  ...,
  text_size = 10,
  text_family = "",
  text_colour = "#100F0F",
  title_size = NULL,
  title_family = NULL,
  title_colour = NULL,
  subtitle_size = NULL,
  subtitle_family = NULL,
  subtitle_colour = NULL,
  caption_size = NULL,
  caption_family = NULL,
  caption_colour = NULL,
  caption_hjust = 0,
  legend_position = "right",
  legend_axis_line_colour = NULL,
  legend_axis_line_linewidth = NULL,
  legend_background_fill = NULL,
  legend_key_fill = NULL,
  legend_ticks_colour = NULL,
  legend_ticks_linewidth = NULL,
  legend_ticks_linetype = 1,
  legend_ticks_length = grid::unit(c(2.75, 0), "pt"),
  axis_line_colour = NULL,
  axis_line_linewidth = 0.15,
  axis_ticks_colour = NULL,
  axis_ticks_linewidth = NULL,
  axis_ticks_length = grid::unit(3.66, "pt"),
  panel_background_fill = "white",
  panel_grid_colour = "#F2F0E5",
  panel_grid_linetype = 1,
  panel_grid_linewidth = 1,
  panel_grid_minor_linetype = 1,
  panel_grid_minor_linewidth = ggplot2::rel(0.5),
  plot_background_fill = "white"
)

Arguments

Details

Lights theme

Value

A ggplot theme.

update_darks

Description

Updates the currently active/set theme in place with the colours of theme_darks(), via ggplot2::theme_update(). Useful for recolouring every plot for the rest of the session without swapping out the full theme.

Usage

update_darks(
  ...,
  text_colour = "#CECDC3",
  title_colour = NULL,
  subtitle_colour = NULL,
  caption_colour = NULL,
  axis_line_colour = NULL,
  axis_ticks_colour = NULL,
  legend_axis_line_colour = NULL,
  legend_background_fill = NULL,
  legend_key_fill = NULL,
  legend_ticks_colour = NULL,
  panel_background_fill = "#282726",
  panel_grid_colour = "#100F0F",
  plot_background_fill = "#100F0F"
)

Arguments

Details

Update the set theme (Darks)

Value

The previous theme, invisibly (see ggplot2::theme_update()).

update_greys

Description

Updates the currently active/set theme in place with the colours of theme_greys(), via ggplot2::theme_update(). Useful for recolouring every plot for the rest of the session without swapping out the full theme.

Usage

update_greys(
  ...,
  text_colour = "#100F0F",
  title_colour = NULL,
  subtitle_colour = NULL,
  caption_colour = NULL,
  axis_line_colour = NULL,
  axis_ticks_colour = NULL,
  legend_axis_line_colour = NULL,
  legend_background_fill = NULL,
  legend_key_fill = NULL,
  legend_ticks_colour = NULL,
  panel_background_fill = "#F2F0E5FF",
  panel_grid_colour = "white",
  plot_background_fill = "white"
)

Arguments

Details

Update the set theme (greys)

Value

The previous theme, invisibly (see ggplot2::theme_update()).

update_lights

Description

Updates the currently active/set theme in place with the colours of theme_lights(), via ggplot2::theme_update(). Useful for recolouring every plot for the rest of the session without swapping out the full theme.

Usage

update_lights(
  ...,
  text_colour = "#100F0F",
  title_colour = NULL,
  subtitle_colour = NULL,
  caption_colour = NULL,
  axis_line_colour = NULL,
  axis_ticks_colour = NULL,
  legend_axis_line_colour = NULL,
  legend_background_fill = NULL,
  legend_key_fill = NULL,
  legend_ticks_colour = NULL,
  panel_background_fill = "white",
  panel_grid_colour = "#F2F0E5",
  plot_background_fill = "white"
)

Arguments

Details

Update the set theme (Lights)

Value

The previous theme, invisibly (see ggplot2::theme_update()).

Update colour/fill palettes or fixed geom colour/fill

Description

Modifies active theme settings for fixed, discrete, and continuous palettes only for parameters explicitly provided by the user.

Usage

update_palette(
  fixed = NULL,
  discrete = NULL,
  continuous = NULL,
  aesthetic = c("colour", "fill")
)

Arguments

Value

Invisibly returns the result of the theme_update() calls.

Examples

## Not run: 
# Update fixed geom colour and fill
update_palette(fixed = "steelblue")

# Update only the fill of fixed geoms
update_palette(fixed = "steelblue", aesthetic = "fill")

# Update discrete palette for colour only
update_palette(discrete = scales::pal_hue(), aesthetic = "colour")

# Update continuous palette for both colour and fill
update_palette(continuous = scales::pal_viridis())

## End(Not run)

Update panel dimensions in the current ggplot theme

Description

Modifies panel dimensions such as heights and widths by updating the global theme settings.

Usage

update_panel_size(heights = ggplot2::waiver(), widths = ggplot2::waiver())

Arguments

Value

Invisibly returns the updated theme object.

Examples

## Not run: 
update_panel_size(
  heights = grid::unit(6, "cm"),
  widths = grid::unit(8, "cm")
)

## End(Not run)