Package 'ggscribe'

Title: Publication-Quality 'ggplot2' Annotation
Description: Annotation helper functions for publication-quality 'ggplot2' visualisation. These functions make it easier to annotate plots in a way that stays consistent with the set theme.
Authors: David Hodge [aut, cre, cph] (ORCID: <https://orcid.org/0000-0002-3868-7501>)
Maintainer: David Hodge <[email protected]>
License: MIT + file LICENSE
Version: 0.2.0
Built: 2026-07-07 04:49:46 UTC
Source: https://github.com/davidhodge931/ggscribe

Help Index

A mapped aesthetic for text colour on fill

Description

Modifies a mapped colour (or fill) aesthetic for contrast against the fill (or colour) aesthetic.

Function can be spliced into ggplot2::aes with rlang::!!!.

Usage

aes_contrast(..., dark = NULL, light = NULL, aesthetic = "colour")

Arguments

...

Unused. Included to support a trailing comma.
dark

A dark colour. If NULL, derived from theme text or panel background.
light

A light colour. If NULL, derived from theme text or panel background.
aesthetic

The aesthetic to be modified for contrast. Either "colour" (default) or "fill".

Value

A ggplot2 mapping object suitable for use in ggplot2::aes() or as a ⁠mapping =⁠ argument in a layer.

Annotate an axis bracket

Description

Draws one or more brackets along a floating axis line. Each bracket spans min(breaks) to max(breaks) with caps at every break value. Requires coord_cartesian(clip = "off").

Usage

axis_bracket(
  xintercept = NULL,
  yintercept = NULL,
  breaks,
  length = ggplot2::rel(1),
  colour = NULL,
  linewidth = NULL,
  linetype = NULL,
  layout = NULL
)

Arguments

xintercept

One or more x positions for vertical axis lines, in data coordinates or wrapped in I() for normalised panel coordinates (npc). May be a vector; each value produces a separate axis.
yintercept

One or more y positions for horizontal axis lines, in data coordinates or wrapped in I() for normalised panel coordinates (npc). May be a vector; each value produces a separate axis.
breaks

A numeric vector of length >= 2 in data coordinates, or wrapped in I() for npc. The bar spans min(breaks) to max(breaks); caps are drawn at every break value. Pass a list the same length as the total number of axes to use different breaks per axis.
length

Length of the bracket caps. Supports rel(). Negative values flip the cap direction. Defaults to rel(1). May be a vector the same length as the number of axes.
colour

Inherits from axis.ticks in the set theme (falling back through axis.line and line). May be a vector the same length as the number of axes.
linewidth

Inherits from axis.ticks in the set theme. Supports rel(). May be a vector the same length as the number of axes.
linetype

Inherits from axis.ticks in the set theme. May be a vector the same length as the number of axes.
layout

Controls which panels the annotation appears in. NULL (default) repeats in all panels. An integer targets a specific panel. "fixed" repeats in all panels ignoring faceting variables. See ggplot2::layer() for full details.

Details

Caps always point in the positive direction by default (right for xintercept, up for yintercept). Use a negative length to flip them (e.g. length = -rel(1)).

Value

A list of ggplot2 annotation layers.

Annotate an axis line

Description

Draws a full line at one or more floating positions, with style defaults taken from the axis.line element of the set theme. Requires coord_cartesian(clip = "off").

Usage

axis_line(
  xintercept = NULL,
  yintercept = NULL,
  colour = NULL,
  linewidth = NULL,
  linetype = NULL,
  arrow = NULL,
  layout = NULL
)

Arguments

xintercept

One or more x positions for vertical axis lines, in data coordinates or wrapped in I() for normalised panel coordinates (npc). May be a vector; each value produces a separate line.
yintercept

One or more y positions for horizontal axis lines, in data coordinates or wrapped in I() for normalised panel coordinates (npc). May be a vector; each value produces a separate line.
colour

Inherits from axis.line in the set theme. May be a vector the same length as the total number of lines.
linewidth

Inherits from axis.line in the set theme. Supports rel(). May be a vector the same length as the total number of lines.
linetype

Inherits from axis.line in the set theme. May be a vector the same length as the total number of lines.
arrow

A grid::arrow() specification, or a list the same length as the total number of lines. Must use list() not c() when supplying multiple values. E.g. grid::arrow(angle = 15, length = unit(1.5, "mm"), type = "closed").
layout

Controls which panels the annotation appears in. NULL (default) repeats in all panels. An integer targets a specific panel. "fixed" repeats in all panels ignoring faceting variables. See ggplot2::layer() for full details.

Details

The arrow (if any) points in the positive direction by default — rightward for xintercept lines, upward for yintercept lines.

Value

A list of ggplot2 annotation layers.

Annotate axis text

Description

Draws text labels at specified break positions along a floating axis line, with style defaults taken from the axis.text element of the set theme. Requires coord_cartesian(clip = "off").

Usage

axis_text(
  xintercept = NULL,
  yintercept = NULL,
  breaks,
  labels = NULL,
  length = ggplot2::rel(1),
  angle = 0,
  hjust = NULL,
  vjust = NULL,
  colour = NULL,
  size = NULL,
  family = NULL,
  layout = NULL
)

Arguments

xintercept

One or more x positions for vertical axis lines, in data coordinates or wrapped in I() for normalised panel coordinates (npc). May be a vector; each value produces a separate axis.
yintercept

One or more y positions for horizontal axis lines, in data coordinates or wrapped in I() for normalised panel coordinates (npc). May be a vector; each value produces a separate axis.
breaks

A numeric vector of break positions in data coordinates, or wrapped in I() for npc. Pass a list the same length as the total number of axes to use different breaks per axis.
labels

One of:

  • NULL (default) to use break values as labels

  • A character vector recycled across all breaks in order

  • A function taking break values and returning labels

  • A list the same length as the number of axes, each element being one of the above

length

Offset from the axis line including tick length and margin. Supports rel(). Negative values place text on the opposite side. Defaults to rel(1). May be a vector recycled across all breaks in order.
angle

Text rotation angle. Defaults to 0. May be a vector recycled across all breaks in order.
hjust, vjust

Justification. Auto-calculated from axis direction and angle if NULL. May be a vector recycled across all breaks in order.
colour

Inherits from axis.text in the set theme. May be a vector recycled across all breaks in order.
size

Inherits from axis.text in the set theme. May be a vector recycled across all breaks in order.
family

Inherits from axis.text in the set theme. May be a vector recycled across all breaks in order.
layout

Controls which panels the annotation appears in. NULL (default) repeats in all panels. An integer targets a specific panel. "fixed" repeats in all panels ignoring faceting variables. See ggplot2::layer() for full details.

Details

Text always sits on the positive side of the axis by default (right of xintercept lines, above yintercept lines). Use a negative length to place text on the opposite side (e.g. length = -rel(1)).

Value

A list of ggplot2 annotation layers.

Annotate axis ticks

Description

Draws axis ticks at specified break positions along a floating axis line. Requires coord_cartesian(clip = "off").

Usage

axis_ticks(
  xintercept = NULL,
  yintercept = NULL,
  breaks,
  length = ggplot2::rel(1),
  colour = NULL,
  linewidth = NULL,
  linetype = NULL,
  arrow = NULL,
  layout = NULL
)

Arguments

xintercept

One or more x positions for vertical axis lines, in data coordinates or wrapped in I() for normalised panel coordinates (npc). May be a vector; each value produces a separate axis.
yintercept

One or more y positions for horizontal axis lines, in data coordinates or wrapped in I() for normalised panel coordinates (npc). May be a vector; each value produces a separate axis.
breaks

A numeric vector of break positions in data coordinates, or wrapped in I() for npc. Pass a list the same length as the total number of axes to use different breaks per axis.
length

Total tick length. Supports rel(). Negative values flip the tick direction. Defaults to rel(1). May be a vector recycled across all breaks in order.
colour

Inherits from axis.ticks in the set theme. May be a vector recycled across all breaks in order.
linewidth

Inherits from axis.ticks in the set theme. Supports rel(). May be a vector recycled across all breaks in order.
linetype

Inherits from axis.ticks in the set theme. May be a vector recycled across all breaks in order.
arrow

A grid::arrow() specification, or a list recycled across all breaks. The arrowhead points toward the axis line. Must use list() not c() when supplying multiple values. E.g. grid::arrow(angle = 15, length = unit(1.5, "mm"), type = "closed").
layout

Controls which panels the annotation appears in. NULL (default) repeats in all panels. An integer targets a specific panel. "fixed" repeats in all panels ignoring faceting variables. See ggplot2::layer() for full details.

Details

Ticks always point in the positive direction by default (right for xintercept, up for yintercept). Use a negative length to flip them (e.g. length = -rel(1)).

Value

A list of ggplot2 annotation layers.

Guide optimised for secondary axis text annotations

Description

A wrapper around ggplot2::guide_axis() that defaults to making transparent ticks and lines while preserving text, making it ideal for annotation labels.

Usage

guide_sec_axis_text(..., theme = NULL)

Arguments

...

Additional arguments passed to ggplot2::guide_axis(), such as title, check.overlap, or angle.
theme

A theme object to style the secondary axis.

Value

A guide object to be used in a scale's guide argument or within sec_axis_text().

Annotate a panel background region

Description

Draws filled rectangles over the panel. Defaults to the panel.background fill from the set theme at full opacity, making it useful for layering a solid background over existing content. Should be placed before geom layers.

Usage

panel_background(
  xmin = -Inf,
  xmax = Inf,
  ymin = -Inf,
  ymax = Inf,
  fill = NULL,
  alpha = 1,
  colour = NULL,
  linewidth = NULL,
  linetype = 0,
  layout = NULL
)

Arguments

xmin, xmax

Left and right edges of the rectangle in data coordinates. Defaults to -Inf and Inf. Use I() for normalised coordinates (0-1). May be a vector for multiple rectangles. Bounds may be mixed freely, e.g. ⁠xmin = I(0.5), xmax = Inf⁠ fills from 50% to the right panel edge.
ymin, ymax

Bottom and top edges of the rectangle in data coordinates. Defaults to -Inf and Inf. Use I() for normalised coordinates (0-1). May be a vector for multiple rectangles.
fill

Fill colour. Defaults to the panel.background fill from the set theme, falling back to "white". May be a vector the same length as the bounds to style each rectangle individually.
alpha

Opacity. Defaults to 1 (fully opaque). May be a vector.
colour

Border colour. Defaults to the resolved fill value, giving a seamless border. May be a vector.
linewidth

Inherits from panel.border in the set theme. Supports rel(). May be a vector.
linetype

Border linetype. Defaults to 0 (none). May be a vector.
layout

Controls which panels the annotation appears in. NULL (default) repeats in all panels. An integer targets a specific panel. "fixed" repeats in all panels ignoring faceting variables. See ggplot2::layer() for full details.

Value

A list containing annotation layers.

Annotate panel gridlines

Description

Draws gridlines at specified positions, with style defaults taken from the panel.grid.major element of the set theme. Crop bounds (xmin, xmax, ymin, ymax) both filter which lines are drawn and control how far they run across the panel.

Usage

panel_grid(
  xintercept = NULL,
  yintercept = NULL,
  xmin = -Inf,
  xmax = Inf,
  ymin = -Inf,
  ymax = Inf,
  colour = NULL,
  linewidth = NULL,
  linetype = NULL,
  layout = NULL
)

Arguments

xintercept

One or more x positions for vertical gridlines, in data coordinates or wrapped in I() for normalised panel coordinates (npc). May be a vector.
yintercept

One or more y positions for horizontal gridlines, in data coordinates or wrapped in I() for normalised panel coordinates (npc). May be a vector.
xmin, xmax

Left and right crop bounds. Vertical gridlines outside ⁠[xmin, xmax]⁠ are not drawn; horizontal gridlines run only from xmin to xmax. Defaults to -Inf and Inf (full panel). Use I() for normalised coordinates (npc). Note: filtering (removing lines outside the range) only works when both the crop bound and the intercept are in data coordinates. npc bounds affect extent only.
ymin, ymax

Bottom and top crop bounds. Horizontal gridlines outside ⁠[ymin, ymax]⁠ are not drawn; vertical gridlines run only from ymin to ymax. Defaults to -Inf and Inf (full panel). Use I() for normalised coordinates (npc). Note: filtering only works when both the crop bound and the intercept are in data coordinates. npc bounds affect extent only.
colour

Inherits from panel.grid.major in the set theme. May be a vector the same length as the total number of lines.
linewidth

Inherits from panel.grid.major in the set theme. Supports rel(). May be a vector the same length as the total number of lines.
linetype

Inherits from panel.grid.major in the set theme. May be a vector the same length as the total number of lines.
layout

Controls which panels the annotation appears in. NULL (default) repeats in all panels. An integer targets a specific panel. "fixed" repeats in all panels ignoring faceting variables. See ggplot2::layer() for full details.

Value

A list of ggplot2 annotation layers.

Annotate a shaded panel region

Description

A convenience wrapper around panel_background() with a smart shade default which blends the panel background fill with jumble::slate at 25% opacity with no border. Should be placed before geom layers.

Usage

panel_shade(
  xmin = -Inf,
  xmax = Inf,
  ymin = -Inf,
  ymax = Inf,
  fill = NULL,
  alpha = 0.2,
  colour = "transparent",
  linewidth = NULL,
  linetype = 1,
  layout = NULL
)

Arguments

xmin, xmax

Left and right edges of the rectangle in data coordinates. Defaults to -Inf and Inf. Use I() for normalised coordinates (0-1). May be a vector for multiple rectangles. Bounds may be mixed freely, e.g. ⁠xmin = I(0.5), xmax = Inf⁠ fills from 50% to the right panel edge.
ymin, ymax

Bottom and top edges of the rectangle in data coordinates. Defaults to -Inf and Inf. Use I() for normalised coordinates (0-1). May be a vector for multiple rectangles.
fill

Fill colour.
alpha

Opacity. Defaults to 0.2. May be a vector.
colour

Border colour. Defaults to "transparent". May be a vector.
linewidth

Inherits from panel.border in the set theme. Supports rel(). May be a vector.
linetype

Border linetype. Defaults to 1. May be a vector.
layout

Controls which panels the annotation appears in. NULL (default) repeats in all panels. An integer targets a specific panel. "fixed" repeats in all panels ignoring faceting variables. See ggplot2::layer() for full details.

Value

A list containing annotation layers.

Annotate a reference line

Description

Draws one or more reference lines within the panel, with style defaults taken from the axis.line element of the set theme.

Usage

reference_line(
  xintercept = NULL,
  yintercept = NULL,
  colour = NULL,
  linewidth = NULL,
  linetype = "dashed",
  arrow = NULL,
  layout = NULL
)

Arguments

xintercept

One or more x positions for vertical reference lines, in data coordinates or wrapped in I() for normalised panel coordinates (npc). May be a vector; each value produces a separate line.
yintercept

One or more y positions for horizontal reference lines, in data coordinates or wrapped in I() for normalised panel coordinates (npc). May be a vector; each value produces a separate line.
colour

Inherits from axis.line in the set theme. May be a vector the same length as the total number of lines.
linewidth

Inherits from axis.line in the set theme. Supports rel(). May be a vector the same length as the total number of lines.
linetype

Defaults to "dashed". May be a vector the same length as the total number of lines.
arrow

A grid::arrow() specification, or a list the same length as the total number of lines. Must use list() not c() when supplying multiple values. E.g. grid::arrow(angle = 15, length = unit(1.5, "mm"), type = "closed").
layout

Controls which panels the annotation appears in. NULL (default) repeats in all panels. An integer targets a specific panel. "fixed" repeats in all panels ignoring faceting variables. See ggplot2::layer() for full details.

Details

The arrow (if any) points in the positive direction by default — rightward for xintercept lines, upward for yintercept lines.

Value

A list of ggplot2 annotation layers.

Secondary axis for text annotations

Description

Secondary axis for text annotations

Usage

sec_axis_text(
  breaks = function(x) mean(x),
  labels = ggplot2::waiver(),
  name = NULL,
  guide = guide_sec_axis_text(),
  ...
)

Arguments

breaks

A function or numeric vector giving the break position(s) used to anchor the text. Defaults to ⁠\(x) mean(x)⁠, which places a single label at the midpoint of the scale limits for continuous scales.
labels

One of:

  • A character vector of labels, the same length as breaks

  • A function that takes break positions as input and returns labels If left as ggplot2::waiver(), labels are derived from the break positions and may be numeric.

name

The name of the secondary axis. Use ggplot2::waiver() to derive the name from the primary axis, or NULL (default) for no name.
guide

A guide object used to render the axis. Defaults to guide_sec_axis_text(), which makes transparent ticks and lines.
...

Additional arguments passed to ggplot2::dup_axis().

Value

A AxisSecondary object for use in the sec.axis argument of scale_x_continuous() or scale_y_continuous().