Package 'ggtintshade'

Title: Tinting and Shading Aesthetics for 'ggplot2'
Description: Adds a 'tintshade' aesthetic to 'ggplot2' that varies the lightness of a mapped 'colour' or 'fill' within each hue group, keeping the plotted layer and its legend in sync. Supports both nested designs (each item belongs to one hue) and crossed designs (each lightness level appears across hues).
Authors: William Kumler [aut, cre]
Maintainer: William Kumler <[email protected]>
License: MIT + file LICENSE
Version: 0.1.2
Built: 2026-07-23 15:51:29 UTC
Source: https://github.com/cran/ggtintshade

Help Index

Geoms with a tintshade aesthetic

Description

Drop-in tintshade variants of common ggplot2 geoms. Map colour or fill to a hue and tintshade to a within-hue lightness; whichever of colour/fill carries the hue is tinted automatically (or both, if both are mapped). The plotted layer and its legend stay in sync.

Usage

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

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

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

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

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

geom_area_tintshade(
  mapping = NULL,
  data = NULL,
  stat = "align",
  position = "stack",
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

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

geom_bar_tintshade(
  mapping = NULL,
  data = NULL,
  stat = "count",
  position = "stack",
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

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

geom_histogram_tintshade(
  mapping = NULL,
  data = NULL,
  stat = "bin",
  position = "stack",
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_boxplot_tintshade(
  mapping = NULL,
  data = NULL,
  stat = "boxplot",
  position = "dodge2",
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_violin_tintshade(
  mapping = NULL,
  data = NULL,
  stat = "ydensity",
  position = "dodge",
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

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

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

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

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

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

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

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

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

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

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

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

Arguments

mapping, data, stat, position, na.rm, show.legend, inherit.aes, ...

Standard ggplot2::layer() arguments, with the same defaults as the corresponding plain ggplot2 geom.

Value

A ggplot2 layer.

See Also

scale_tintshade_discrete(), guide_tintshade()

Examples

library(ggplot2)
df <- data.frame(
  g = rep(c("a", "b", "c"), each = 3),
  item = rep(c("lo", "mid", "hi"), 3),
  x = rep(1:3, each = 3), y = runif(9)
)
ggplot(df, aes(x, y, colour = g, tintshade = item)) +
  geom_point_tintshade(size = 4)

ggplot(diamonds) +
  geom_bar_tintshade(aes(x=cut, fill = cut, tintshade = clarity), color="black")

mpgsub <- head(mpg, 60)
mpgsub$model <- factor(mpgsub$model, levels=unique(mpgsub$model))
ggplot(mpgsub, aes(displ, hwy, colour = manufacturer, tintshade = model)) +
  geom_point_tintshade(size = 3)

ggplot(penguins[!is.na(penguins$bill_len),]) +
  geom_point_tintshade(aes(x=bill_len, y=bill_dep, fill=species, tintshade=sex),
                       pch=21, color="black", size=3)

Legend guide for the tintshade aesthetic

Description

A ggplot2::guide_legend() whose keys are recoloured to match the tinted layer. The tintshade scale uses this guide by default.

Usage

guide_tintshade(
  title = ggplot2::waiver(),
  type = c("auto", "unique", "crossed"),
  theme = NULL,
  position = NULL,
  direction = NULL,
  override.aes = list(),
  nrow = NULL,
  ncol = NULL,
  reverse = FALSE,
  order = 0,
  ...
)

Arguments

title

Legend title. Defaults to the mapped variable name.
type

How to colour the legend keys:

  • "auto" (default): a key is drawn in its hue when its tintshade level maps to a single hue (a nested design) and in neutral grey when it co-occurs with several (a crossed design, where lightness is hue-independent).

  • "unique": always use the hue.

  • "crossed": always use neutral grey.

theme

A theme object to style the guide individually or differently from the plot's theme settings. The theme argument in the guide partially overrides, and is combined with, the plot's theme. Arguments that apply to a single legend are respected, most of which have the legend-prefix. Arguments that apply to combined legends (the legend box) are ignored, including legend.position, ⁠legend.justification.*⁠, legend.location and ⁠legend.box.*⁠.
position

A character string indicating where the legend should be placed relative to the plot panels. One of "top", "right", "bottom", "left", or "inside".
direction

A character string indicating the direction of the guide. One of "horizontal" or "vertical".
override.aes

A list specifying aesthetic parameters of legend key. See details and examples.
nrow, ncol

The desired number of rows and column of legends respectively.
reverse

logical. If TRUE the order of legends is reversed.
order

positive integer less than 99 that specifies the order of this guide among multiple guides. This controls the order in which multiple guides are displayed, not the contents of the guide itself. If 0 (default), the order is determined by a secret algorithm.
...

Additional arguments passed on to ggplot2::new_guide().

Value

A guide object.

See Also

scale_tintshade_discrete()

Examples

library(ggplot2)
df <- expand.grid(hue = c("good", "bad"), level = c("lo", "hi"))
df$y <- 1
ggplot(df, aes(hue, y, fill = hue, tintshade = level)) +
  geom_col_tintshade(position = "dodge") +
  guides(tintshade = guide_tintshade(type = "crossed"))

Lightness (tintshade) scales

Description

Map a variable to a lightness tint. The mapped value runs from 0 (black) through 0.5 (the base hue) to 1 (white); the geom rescales these within each hue group so the ramp restarts per group.

Usage

scale_tintshade_discrete(
  ...,
  range = c(0.2, 0.8),
  aesthetics = "tintshade",
  guide = guide_tintshade()
)

scale_tintshade_continuous(
  ...,
  range = c(0.2, 0.8),
  aesthetics = "tintshade",
  guide = guide_tintshade()
)

Arguments

...

Passed to ggplot2::discrete_scale() or ggplot2::continuous_scale().
range

Numeric length-2 output range within ⁠[0, 1]⁠. Defaults to c(0.2, 0.8) (dark to pale, base hue in the middle).
aesthetics

Aesthetic this scale applies to. Defaults to "tintshade".
guide

The legend guide. Defaults to guide_tintshade(); pass a configured guide_tintshade(...) to customise the legend.

Value

A ggplot2 scale object.

See Also

guide_tintshade()

Examples

library(ggplot2)
df <- data.frame(x = 1:3, y = 1:3, g = "a", item = c("lo", "mid", "hi"))
ggplot(df, aes(x, y, colour = g, tintshade = item)) +
  geom_point_tintshade(size = 4) +
  scale_tintshade_discrete(range = c(0.1, 0.9))