Help for package ggincerta

Title:

Extend 'ggplot2' with Layers and Scales for Spatial Uncertainty Visualization

Version:

0.2.0

Description:

Provide specialized 'ggplot2' layers and scales for spatial uncertainty visualization, including bivariate choropleth maps, pixel maps, glyph maps, and exceedance probability maps.

Imports:

cli, colorspace, dplyr, grDevices, grid, gtable, purrr, rlang, scales, sf, withr

License:

MIT + file LICENSE

Encoding:

UTF-8

RoxygenNote:

7.3.3

Suggests:

ggChernoff, testthat (≥ 3.0.0), vdiffr

Config/testthat/edition:

Depends:

ggplot2 (≥ 3.5.0), R (≥ 4.1.0)

LazyData:

true

URL:

https://github.com/maggiexma/ggincerta

BugReports:

https://github.com/maggiexma/ggincerta/issues

NeedsCompilation:

Packaged:

2026-05-25 04:21:27 UTC; maxueqi

Author:

Xueqi Ma [aut, cre, cph], Emi Tanaka

[aut, ths], Weihao Li

[ths], Quan Vu [ths], Francis Hui

[ths]

Maintainer:

Xueqi Ma <maggiexma07@gmail.com>

Repository:

CRAN

Date/Publication:

2026-05-25 04:30:02 UTC

ggincerta: Extend 'ggplot2' with Layers and Scales for Spatial Uncertainty Visualization

Description

Provide specialized 'ggplot2' layers and scales for spatial uncertainty visualization, including bivariate choropleth maps, pixel maps, glyph maps, and exceedance probability maps.

Author(s)

Maintainer: Xueqi Ma maggiexma07@gmail.com [copyright holder]

Authors:

Emi Tanaka dr.emi.tanaka@gmail.com (ORCID) [thesis advisor]

Other contributors:

Weihao Li llreczx@gmail.com (ORCID) [thesis advisor]
Quan Vu [thesis advisor]
Francis Hui fhui28@gmail.com (ORCID) [thesis advisor]

Bivariate colour guide

Description

The bivariate colour guide is displayed as a grid, where each cell represents the mapping between a colour and the corresponding bin intervals of the two variables along the guide axes.

Usage

GuideBivariate

guide_bivariate(
  theme = NULL,
  title = NULL,
  order = 0,
  position = NULL,
  rotated = FALSE,
  angle = 45
)

Arguments

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.*⁠.

title

A character string or expression indicating a title of guide. If NULL, the title is not shown. By default (waiver()), the name of the scale object or the name specified in labs() is used for the title.

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.

position

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

rotated

Logical indicating whether the guide should be displayed in a rotated orientation.

angle

A numeric value specifying the rotation angle of the guide.

Format

An object of class GuideBivariate (inherits from GuideLegend, Guide, ggproto, gg) of length 26.

Drop glyph guide

Description

Guide for drop glyph consists of two axes and a sequence of example drop grobs illustrating the mapping between uncertainty and glyph rotation angles.

Usage

GuideGlyph

guide_glyph(
  theme = NULL,
  title = waiver(),
  order = 99,
  position = NULL,
  direction = "vertical"
)

Arguments

theme

title

order

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".

Format

An object of class GuideGlyph (inherits from Guide, ggproto, gg) of length 4.

Details

Rotation angles range from \pi to -\pi, corresponding to the minimum and maximum uncertainty values respectively.

VSUP guide

Description

This guide is displayed as a fan-shaped legend. Uncertainty levels are arranged along the radial axis, while value groups are arranged along the arc axis. As uncertainty increases towards the centre of the guide, the number of value groups progressively decreases until only a single group remains.

Usage

GuideVSUP

guide_vsup(theme = NULL, title = waiver(), order = 0, position = NULL)

Arguments

theme

title

order

position

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

Format

An object of class GuideVSUP (inherits from GuideLegend, Guide, ggproto, gg) of length 18.

Bivariate colour scale constructor

Description

bivariate_scale() maps binned combinations of two variables to colour dimensions and their combinations in perceptual colour space, supporting the construction of bivariate choropleth maps.

Usage

ScaleBivariate

bivariate_scale(
  aesthetics,
  ...,
  name = waiver(),
  breaks = list(waiver(), waiver()),
  labels = list(waiver(), waiver()),
  limits = list(NULL, NULL),
  transform = list("identity", "identity"),
  na.value = NA,
  na.translate = TRUE,
  drop = FALSE,
  guide = waiver(),
  colours = c("gold", "red4"),
  palette_fun = NULL,
  palette_params = list(),
  n_breaks = c(4, 4),
  bin_method = c("equal", "equal"),
  var1_name = NULL,
  var2_name = NULL,
  super = ScaleBivariate
)

scale_fill_bivariate(
  ...,
  name = waiver(),
  var1_name = NULL,
  var2_name = NULL,
  colours = c("gold", "red4"),
  palette_fun = NULL,
  palette_params = list(),
  n_breaks = c(4, 4),
  breaks = list(waiver(), waiver()),
  labels = list(waiver(), waiver()),
  limits = list(NULL, NULL),
  transform = list("identity", "identity"),
  bin_method = c("equal", "equal"),
  na.value = NA,
  aesthetics = "fill",
  guide = guide_bivariate()
)

scale_color_bivariate(
  ...,
  name = waiver(),
  var1_name = NULL,
  var2_name = NULL,
  colours = c("gold", "red4"),
  palette_fun = NULL,
  palette_params = list(),
  n_breaks = c(4, 4),
  breaks = list(waiver(), waiver()),
  labels = list(waiver(), waiver()),
  limits = list(NULL, NULL),
  transform = list("identity", "identity"),
  bin_method = c("equal", "equal"),
  na.value = NA,
  aesthetics = "colour",
  guide = guide_bivariate()
)

scale_colour_bivariate(
  ...,
  name = waiver(),
  var1_name = NULL,
  var2_name = NULL,
  colours = c("gold", "red4"),
  palette_fun = NULL,
  palette_params = list(),
  n_breaks = c(4, 4),
  breaks = list(waiver(), waiver()),
  labels = list(waiver(), waiver()),
  limits = list(NULL, NULL),
  transform = list("identity", "identity"),
  bin_method = c("equal", "equal"),
  na.value = NA,
  aesthetics = "colour",
  guide = guide_bivariate()
)

Arguments

aesthetics

The names of the aesthetics that this scale works with.

...

Other arguments passed to ggplot2::discrete_scale().

name

The name of the scale. Used as the axis or legend title. If waiver(), the default, the name of the scale is taken from the first mapping used for that aesthetic. If NULL, the legend title will be omitted.

breaks

A list of two numeric vectors specifying bin boundaries for each variable. If waiver(), breaks are computed from the data according to n_breaks and bin_method.

labels

A list of two character vectors or labelling functions used to label the bin boundaries for each variable. If waiver(), default numeric labels are used.

limits

A list of two numeric vectors specifying the range of values to include for each variable.

transform

A list of two transformations applied to the variables before binning. Each element can be a transformation name or a transformer object accepted by scales::as.transform().

na.value

If na.translate = TRUE, what aesthetic value should the missing values be displayed as? Does not apply to position scales where NA is always placed at the far right.

na.translate

Unlike continuous scales, discrete scales can easily show missing values, and do so by default. If you want to remove missing values from a discrete scale, specify na.translate = FALSE.

drop

Should unused factor levels be omitted from the scale? The default, TRUE, uses the levels that appear in the data; FALSE includes the levels in the factor. Please note that to display every level in a legend, the layer should use show.legend = TRUE.

guide

A function used to create a guide or its name. See guides() for more information.

colours

A character vector of colours used as key points in the colour ramp that variables are mapped to. For details on how supplied colours are used to construct the resulting palette, see bivar_palette() and bivar_fade_palette().

palette_fun

A palette function that, when called with colours and n_breaks, returns a character vector of colours for all binned combinations. If NULL, the default, bivar_palette() is used.

palette_params

A list of additional arguments passed to palette. For details of arguments, see bivar_palette() and bivar_fade_palette().

n_breaks

An integer or a length-two vector specifying the number of bins for each variable. The default is 4 for both variables, and unequal numbers of bins are supported.

bin_method

A character string or a length-two vector specifying the method used to bin each variable: "equal" (the default) or "quantile".

var1_name, var2_name

Optional names for v1 and v2. Used as axis titles in the legend. If NULL, the default, the names are taken from the mapping.

super

The super class to use for the constructed scale

Format

An object of class ScaleBivariate (inherits from ScaleDiscrete, Scale, ggproto, gg) of length 17.

Details

It can be automatically dispatched in aes() using duo() and works with any ggplot2 geom.

Value

A ScaleBivariate ggproto object.

Examples

# Basic bivariate map
ggplot(nc) +
  geom_sf(aes(fill = duo(value, sd)))

# Use an alternative bivariate palette
ggplot(nc) +
  geom_sf(aes(fill = duo(value, sd))) +
  scale_fill_bivariate(
    palette_fun = bivar_fade_palette,
    colours = c("#F6E8C3", "orange", "red")
  )

# Customize the number of bins
ggplot(nc) +
  geom_sf(aes(fill = duo(value, sd))) +
  scale_fill_bivariate(n_breaks = c(3, 4))

Value-Suppressing Uncertainty Palette (VSUP) scale

Description

This scale implements Value-Suppressing Uncertainty Palettes (VSUPs), proposed by Correll et al. (2018). The main idea is to suppress colour variation in regions with higher uncertainty, thereby directing visual attention towards more reliable value differences.

Usage

ScaleVSUP

scale_fill_vsup(
  name = waiver(),
  colours = c("gold", "red4"),
  layers = 4,
  branch = 2L,
  breaks = list(NULL, NULL),
  limits = list(NULL, NULL),
  transform = list("identity", "identity"),
  title_value = "Value",
  title_uncertainty = "Uncertainty",
  na.value = NA,
  na.translate = TRUE,
  aesthetics = "fill",
  max_light = 0.7,
  max_desat = 0.9,
  pow_light = 1,
  pow_desat = 1,
  space = "Lab",
  guide = guide_vsup(),
  ...
)

scale_colour_vsup(
  name = waiver(),
  colours = c("gold", "red4"),
  layers = 4,
  branch = 2L,
  breaks = list(NULL, NULL),
  limits = list(NULL, NULL),
  transform = list("identity", "identity"),
  title_value = "Value",
  title_uncertainty = "Uncertainty",
  na.value = NA,
  na.translate = TRUE,
  aesthetics = "colour",
  max_light = 0.7,
  max_desat = 0.9,
  pow_light = 1,
  pow_desat = 1,
  space = "Lab",
  guide = guide_vsup(),
  ...
)

Arguments

name

colours

A character vector of colours used as key points in the value colour scale. See vsup_palette() for details.

layers

An integer specifying the number of uncertainty levels.

branch

An integer specifying the branching factor used to allocate value bins across uncertainty levels. The maximum number of value bins is branch^(layers - 1), and higher uncertainty levels are assigned fewer value bins.

breaks

One of:

NULL for no breaks
waiver() for the default breaks (the scale limits)
A character vector of breaks
A function that takes the limits as input and returns breaks as output. Also accepts rlang lambda function notation.

limits

One of:

NULL to use the default scale values
A character vector that defines possible values of the scale and their order
A function that accepts the existing (automatic) values and returns new ones. Also accepts rlang lambda function notation.

transform

A list of two transformations applied to the variables before binning. Each element can be a transformation name or a transformer object accepted by scales::as.transform().

title_value, title_uncertainty

Optional titles for the value and uncertainty dimensions in the guide.

na.value

If na.translate = TRUE, what aesthetic value should the missing values be displayed as? Does not apply to position scales where NA is always placed at the far right.

na.translate

Unlike continuous scales, discrete scales can easily show missing values, and do so by default. If you want to remove missing values from a discrete scale, specify na.translate = FALSE.

aesthetics

The names of the aesthetics that this scale works with.

max_light

A numeric value specifying the maximum amount of lightening applied across uncertainty levels.

max_desat

A numeric value specifying the maximum amount of desaturation applied across uncertainty levels.

pow_light, pow_desat

Numeric values controlling the rate of lightening and desaturation across uncertainty levels.

space

A character string specifying the colour space used for colour interpolation.

guide

A function used to create a guide or its name. See guides() for more information.

...

Other arguments passed to ggplot2::discrete_scale().

Format

An object of class ScaleVSUP (inherits from ScaleDiscrete, Scale, ggproto, gg) of length 8.

Pixel map

Description

geom_sf_pixel() generates a pixel map layer on areal sf data. Each region is tessellated into small pixels, with pixel colours mapped from values sampled from a specified distribution.

Usage

StatPixel

geom_sf_pixel(
  mapping = NULL,
  data = NULL,
  n = 60,
  distribution = "uniform",
  seed = NULL,
  pixel_shape = "hex",
  flat_topped = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

Arguments

mapping

Set of aesthetic mappings created by aes(). If specified and inherit.aes = TRUE (the default), it is combined with the default mapping at the top level of the plot. You must supply mapping if there is no plot mapping.

data

The data to be displayed in this layer. There are three options:

If NULL, the default, the data is inherited from the plot data as specified in the call to ggplot().

A data.frame, or other object, will override the plot data. All objects will be fortified to produce a data frame. See fortify() for which variables will be created.

A function will be called with a single argument, the plot data. The return value must be a data.frame, and will be used as the layer data. A function can be created from a formula (e.g. ~ head(.x, 10)).

n

integer of length 1 or 2, number of grid cells in x and y direction (columns, rows)

distribution

Distribution used to sample pixel values within each region. Currently supports "uniform" (the default) and "normal".

seed

Integer seed used for reproducible sampling.

pixel_shape

Shape of the generated pixels. One of "hex" (the default), "square", or "rect". "rect" is when dividing the x and y ranges into the same number of intervals, so cells may be rectangular.

flat_topped

logical; if TRUE generate flat topped hexagons, else generate pointy topped

show.legend

logical. Should this layer be included in the legends? NA, the default, includes if any aesthetics are mapped. FALSE never includes, and TRUE always includes.

You can also set this to one of "polygon", "line", and "point" to override the default legend.

inherit.aes

If FALSE, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. annotation_borders().

...

Other arguments passed on to layer()'s params argument. These arguments broadly fall into one of 4 categories below. Notably, further arguments to the position argument, or aesthetics that are required can not be passed through .... Unknown arguments that are not part of the 4 categories below are ignored.

Static aesthetics that are not mapped to a scale, but are at a fixed value and apply to the layer as a whole. For example, colour = "red" or linewidth = 3. The geom's documentation has an Aesthetics section that lists the available options. The 'required' aesthetics cannot be passed on to the params. Please note that while passing unmapped aesthetics as vectors is technically possible, the order and required length is not guaranteed to be parallel to the input data.
When constructing a layer using a ⁠stat_*()⁠ function, the ... argument can be used to pass on parameters to the geom part of the layer. An example of this is stat_density(geom = "area", outline.type = "both"). The geom's documentation lists which parameters it can accept.
Inversely, when constructing a layer using a ⁠geom_*()⁠ function, the ... argument can be used to pass on parameters to the stat part of the layer. An example of this is geom_area(stat = "density", adjust = 0.5). The stat's documentation lists which parameters it can accept.
The key_glyph argument of layer() may also be passed on through .... This can be one of the functions described as key glyphs, to change the display of the layer in the legend.

Format

An object of class StatPixel (inherits from StatSf, Stat, ggproto, gg) of length 3.

Details

Mappings in geom_sf_pixel() is also supplied with duo_pixel() inside aes(), which automatically dispatches an scale.

Since sf::st_intersection() is used internally, operating directly on geographic (s2) sf objects can be slow, especially when a large number of pixels are generated. Projecting data to a planar coordinate system in advance is recommended.

Value

A list of ggplot2 layer objects.

Examples

# Transform sf data into a planar crs for faster geometric intersection
nc_flat <- sf::st_transform(nc, sf::st_crs(3857))

# Basic pixel map
ggplot(nc_flat, aes(fill = duo_pixel(value, sd))) +
  geom_sf_pixel(n = 40)

# Control pixel shape and resolution
ggplot(nc_flat, aes(fill = duo_pixel(value, sd))) +
  geom_sf_pixel(n = 30, pixel_shape = "square")

Colour fading palette

Description

One or more supplied colours construct a value colour scale, then varies perceptual properties such as lightness, saturation, or transparency along the uncertainty dimension.

Usage

bivar_fade_palette(
  colours,
  n_breaks,
  fade = c("lighten", "alpha", "desaturate"),
  alpha_range = c(1, 0.3),
  max_light = 0.7,
  max_desat = 0.9,
  space = "Lab"
)

Arguments

colours

A character vector of colours used as key points in interpolation.

n_breaks

An integer or a length-two vector specifying the number of bins for each variable. The default is 4 for both variables, and unequal numbers of bins are supported.

fade

A character string specifying the fading method: "lighten", "desaturate", or "alpha".

alpha_range

A numeric vector of length two specifying the range of transparency values used when fade = "alpha".

max_light

A numeric value specifying the maximum amount of lightening applied across uncertainty levels.

max_desat

A numeric value specifying the maximum amount of desaturation applied across uncertainty levels.

space

A character string specifying the colour space used for interpolation.

Colour blending palette

Description

This palette function constructs two colour ramps from white to the supplied endpoint colours, then blends them by additive averaging in grDevices::rgb colour space. The resulting palette contains one colour for each combination of the two binned variables.

Usage

bivar_palette(
  colours = NULL,
  n_breaks = c(4, 4),
  flip = c("none", "vertical", "horizontal", "both")
)

Arguments

colours

A character vector of two colours used as the endpoints of the two colour ramps.

n_breaks

An integer or a length-two vector specifying the number of bins for each variable. The default is 4 for both variables, and unequal numbers of bins are supported.

flip

A character string specifying how to flip the palette: "none" (the default), "vertical", "horizontal", or "both".

Format input and assign the "map" class

Description

duo() and duo_pixel() create paired mapping objects that combine two variables, record their names, and assign the bivariate/pixel class as an attribute for use in aesthetic mappings.

Usage

duo(v1, v2)

duo_pixel(estimate, error)

Arguments

v1, v2

Input variables for duo().

estimate, error

Input variables for duo_pixel() representing the point estimate and its uncertainty.

Value

A list-like object containing pairs of values from the two variables, with attributes storing the variable names and the class.

Examples

value <- nc$value
sd <- nc$sd
res <- duo(value, sd)
res_pixel <- duo_pixel(value, sd)
class(res); class(res_pixel)
attr(res, "vars"); attr(res_pixel, "vars")

Dual map

Description

geom_sf_dualmap() generates a map where each region is represented by two visual components: the surrounding area is mapped using fill, and the central glyph is mapped using colour.

Usage

geom_sf_dualmap(
  mapping = NULL,
  data = NULL,
  ...,
  shape = "circle",
  max_angle = NULL,
  size = 1,
  point_fun = sf::st_point_on_surface,
  border_colour = NA,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  angle_guide = TRUE,
  angle_name = waiver(),
  angle_order = 2,
  fill_scale = NULL
)

Arguments

mapping

data

The data to be displayed in this layer. There are three options:

If NULL, the default, the data is inherited from the plot data as specified in the call to ggplot().

A data.frame, or other object, will override the plot data. All objects will be fortified to produce a data frame. See fortify() for which variables will be created.

...

Static aesthetics that are not mapped to a scale, but are at a fixed value and apply to the layer as a whole. For example, colour = "red" or linewidth = 3. The geom's documentation has an Aesthetics section that lists the available options. The 'required' aesthetics cannot be passed on to the params. Please note that while passing unmapped aesthetics as vectors is technically possible, the order and required length is not guaranteed to be parallel to the input data.
When constructing a layer using a ⁠stat_*()⁠ function, the ... argument can be used to pass on parameters to the geom part of the layer. An example of this is stat_density(geom = "area", outline.type = "both"). The geom's documentation lists which parameters it can accept.
Inversely, when constructing a layer using a ⁠geom_*()⁠ function, the ... argument can be used to pass on parameters to the stat part of the layer. An example of this is geom_area(stat = "density", adjust = 0.5). The stat's documentation lists which parameters it can accept.
The key_glyph argument of layer() may also be passed on through .... This can be one of the functions described as key glyphs, to change the display of the layer in the legend.

shape

Glyph shape. One of "circle" (the default), "square", "triangle", "hex", "drop", or "chernoff".

max_angle

Maximum value of the angle aesthetic used for rescaling glyph rotation.

size

A positive numeric scaling factor controlling glyph size.

point_fun

Function used to calculate the representative point for each region. The default is usually sf::st_point_on_surface().

border_colour

Colour used for glyph borders.

na.rm

If FALSE, the default, missing values are removed with a warning. If TRUE, missing values are silently removed.

show.legend

logical. Should this layer be included in the legends? NA, the default, includes if any aesthetics are mapped. FALSE never includes, and TRUE always includes.

You can also set this to one of "polygon", "line", and "point" to override the default legend.

inherit.aes

angle_guide

Logical indicating whether to display a guide for the angle aesthetic.

angle_name

Title used for the angle guide.

angle_order

Order of the angle guide relative to other guides.

fill_scale

Optional fill scale for the surrounding area. If NULL, a default grey gradient is added when the fill mapping is not created by duo().

Details

This allows two variables, such as value and uncertainty, to be shown within the same geographic region using separate scales.

Value

A list of layers generated by ggplot2::geom_sf() and geom_sf_glyph().

Examples

# Dual map with separate fill and colour mappings
ggplot(nc) +
  geom_sf_dualmap(aes(fill = sd, colour = value))

# Dual map using a bivariate colour scale for the central glyph
ggplot(nc) +
  geom_sf_dualmap(aes(fill = duo(value, sd), colour = sd_log2))

Glyph map

Description

geom_sf_glyph() generates a glyph map sf layer. A glyph map is a centroid-based map, where each region is represented by a chosen glyph.

Usage

geom_sf_glyph(
  mapping = NULL,
  data = NULL,
  ...,
  shape = "circle",
  max_angle = NULL,
  size = 1,
  point_fun = sf::st_point_on_surface,
  border_colour = NA,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  angle_guide = TRUE,
  angle_name = waiver(),
  angle_order = 99
)

Arguments

mapping

data

The data to be displayed in this layer. There are three options:

If NULL, the default, the data is inherited from the plot data as specified in the call to ggplot().

A data.frame, or other object, will override the plot data. All objects will be fortified to produce a data frame. See fortify() for which variables will be created.

...

Static aesthetics that are not mapped to a scale, but are at a fixed value and apply to the layer as a whole. For example, colour = "red" or linewidth = 3. The geom's documentation has an Aesthetics section that lists the available options. The 'required' aesthetics cannot be passed on to the params. Please note that while passing unmapped aesthetics as vectors is technically possible, the order and required length is not guaranteed to be parallel to the input data.
When constructing a layer using a ⁠stat_*()⁠ function, the ... argument can be used to pass on parameters to the geom part of the layer. An example of this is stat_density(geom = "area", outline.type = "both"). The geom's documentation lists which parameters it can accept.
Inversely, when constructing a layer using a ⁠geom_*()⁠ function, the ... argument can be used to pass on parameters to the stat part of the layer. An example of this is geom_area(stat = "density", adjust = 0.5). The stat's documentation lists which parameters it can accept.
The key_glyph argument of layer() may also be passed on through .... This can be one of the functions described as key glyphs, to change the display of the layer in the legend.

shape

Glyph shape. One of "circle" (the default), "square", "triangle", "hex", "drop", or "chernoff".

max_angle

Maximum value of the angle aesthetic used for rescaling glyph rotation.

size

A positive numeric scaling factor controlling glyph size.

point_fun

Function used to calculate the representative point for each region. The default is usually sf::st_point_on_surface().

border_colour

Colour used for glyph borders.

na.rm

If FALSE, the default, missing values are removed with a warning. If TRUE, missing values are silently removed.

show.legend

logical. Should this layer be included in the legends? NA, the default, includes if any aesthetics are mapped. FALSE never includes, and TRUE always includes.

You can also set this to one of "polygon", "line", and "point" to override the default legend.

inherit.aes

angle_guide

Logical indicating whether to display a guide for the angle aesthetic.

angle_name

Title used for the angle guide.

angle_order

Order of the angle guide relative to other guides.

Details

Regular shape glyphs can be treated as ordinary point-like symbols and used together with bivariate_scale(). Drop-shaped glyphs use rotation angle to represent uncertainty. Chernoff glyphs are adapted from the ggChernoff package and work with the smile aesthetic.

Value

A list of ggplot2 layer objects.

Examples

# Regular glyph map
ggplot(nc) +
  geom_sf_glyph(aes(colour = value), shape = "hex")

# Rotated drop glyph map
ggplot(nc) +
  geom_sf_glyph(
    aes(colour = value, angle = sd),
    shape = "drop"
  )

# Chernoff face glyph map
if (requireNamespace("ggChernoff", quietly = TRUE)) {
  ggplot(nc) +
    geom_sf_glyph(
      aes(colour = value, smile = sd),
      shape = "chernoff"
    )
}

Create your own bivariate colour scale

Description

These scales allow users to provide all colours used for the combinations of two variables in a bivariate colour scale.

Usage

manual_bivariate_scale(
  aesthetics,
  ...,
  values,
  name = waiver(),
  breaks = list(waiver(), waiver()),
  labels = list(waiver(), waiver()),
  limits = list(NULL, NULL),
  transform = list("identity", "identity"),
  na.value = NA,
  na.translate = TRUE,
  drop = FALSE,
  guide = guide_bivariate(),
  n_breaks = c(4, 4),
  bin_method = c("equal", "equal"),
  var1_name = NULL,
  var2_name = NULL,
  super = ScaleBivariate
)

scale_fill_bivariate_manual(
  ...,
  values,
  name = waiver(),
  var1_name = NULL,
  var2_name = NULL,
  n_breaks = c(4, 4),
  breaks = list(waiver(), waiver()),
  labels = list(waiver(), waiver()),
  limits = list(NULL, NULL),
  transform = list("identity", "identity"),
  bin_method = c("equal", "equal"),
  na.value = NA,
  na.translate = TRUE,
  aesthetics = "fill",
  guide = guide_bivariate()
)

scale_colour_bivariate_manual(
  ...,
  values,
  name = waiver(),
  var1_name = NULL,
  var2_name = NULL,
  n_breaks = c(4, 4),
  breaks = list(waiver(), waiver()),
  labels = list(waiver(), waiver()),
  limits = list(NULL, NULL),
  transform = list("identity", "identity"),
  bin_method = c("equal", "equal"),
  na.value = NA,
  na.translate = TRUE,
  aesthetics = "colour",
  guide = guide_bivariate()
)

scale_color_bivariate_manual(
  ...,
  values,
  name = waiver(),
  var1_name = NULL,
  var2_name = NULL,
  n_breaks = c(4, 4),
  breaks = list(waiver(), waiver()),
  labels = list(waiver(), waiver()),
  limits = list(NULL, NULL),
  transform = list("identity", "identity"),
  bin_method = c("equal", "equal"),
  na.value = NA,
  na.translate = TRUE,
  aesthetics = "colour",
  guide = guide_bivariate()
)

Arguments

aesthetics

The names of the aesthetics that this scale works with.

...

Other arguments passed to ggplot2::discrete_scale().

values

A character vector of colours. The length should be at least the product of n_breaks, giving one colour for each combination of the two binned variables.

name

breaks

A list of two numeric vectors specifying bin boundaries for each variable. If waiver(), breaks are computed from the data according to n_breaks and bin_method.

labels

A list of two character vectors or labelling functions used to label the bin boundaries for each variable. If waiver(), default numeric labels are used.

limits

A list of two numeric vectors specifying the range of values to include for each variable.

transform

A list of two transformations applied to the variables before binning. Each element can be a transformation name or a transformer object accepted by scales::as.transform().

na.value

If na.translate = TRUE, what aesthetic value should the missing values be displayed as? Does not apply to position scales where NA is always placed at the far right.

na.translate

Unlike continuous scales, discrete scales can easily show missing values, and do so by default. If you want to remove missing values from a discrete scale, specify na.translate = FALSE.

drop

guide

A function used to create a guide or its name. See guides() for more information.

n_breaks

An integer or a length-two vector specifying the number of bins for each variable. The default is 4 for both variables, and unequal numbers of bins are supported.

bin_method

A character string or a length-two vector specifying the method used to bin each variable: "equal" (the default) or "quantile".

var1_name, var2_name

Optional names for v1 and v2. Used as axis titles in the legend. If NULL, the default, the names are taken from the mapping.

super

The super class to use for the constructed scale

Examples

ggplot(nc, aes(fill = duo(value, sd))) +
  geom_sf() +
  scale_fill_bivariate_manual(
    values = c(
      "#F7F4F9", "#D4B9DA", "#C994C7", "#980043",
      "#E0ECF4", "#BFD3E6", "#9EBCDA", "#8856A7",
      "#D0D1E6", "#A6BDDB", "#74A9CF", "#2B8CBE",
      "#B8E186", "#7FBC41", "#4D9221", "#276419"
    )
  )

North Carolina SIDS data

Description

The dataset nc is derived from the North Carolina shapefile (nc.shp) included in the sf package. Two random variables, value and sd, have been added for demonstration purposes.

Further details about the original data can be found in the spdep package vignette.

Usage

nc

Format

A sf object.

Examples

head(nc)

plot(sf::st_geometry(nc))

Pixel fill scale

Description

Pixel fill scale

Usage

scale_fill_pixel(
  type = "seq",
  palette = "Oranges",
  direction = 1,
  name = waiver(),
  ...
)

Arguments

type

One of "seq" (sequential), "div" (diverging) or "qual" (qualitative)

palette

A palette function that when called with a numeric vector with values between 0 and 1 returns the corresponding output values (e.g., scales::pal_area()).

direction

Sets the order of colours in the scale. If 1, the default, colours are as output by RColorBrewer::brewer.pal(). If -1, the order of colours is reversed.

name

...

Additional arguments passed to ggplot2::continuous_scale().

Value-Suppressing Uncertainty Palettes

Description

vsup_palette() handles colour generation for VSUP scales. It modifies the supplied base colours by progressively desaturating and lightening them as uncertainty increases.

Usage

vsup_palette(
  leaf_info,
  colours,
  layers = 4,
  branch = 2,
  max_light = 0.7,
  max_desat = 0.9,
  pow_light = 1,
  pow_desat = 1,
  space = "Lab"
)

Arguments

leaf_info

A data frame describing the VSUP bin structure, produced by vsup_quantize(). It stores the leaf identifiers, uncertainty layers, and value positions used to assign colours.

colours

A character vector of colours used as key points for interpolating the value colour scale at the lowest uncertainty level.

layers

An integer specifying the number of uncertainty levels.

branch

max_light

A numeric value specifying the maximum amount of lightening applied across uncertainty levels.

max_desat

A numeric value specifying the maximum amount of desaturation applied across uncertainty levels.

pow_light, pow_desat

Numeric values controlling the rate of lightening and desaturation across uncertainty levels.

space

A character string specifying the colour space used for colour interpolation.

Tree quantization for VSUPs

Description

Quantize value and uncertainty variables into a hierarchical VSUP tree.

Usage

vsup_quantize(
  v,
  u,
  layers = 4,
  branch = 2L,
  breaks = list(NULL, NULL),
  limits = list(NULL, NULL),
  transform = list("identity", "identity")
)

Arguments

v

Numeric vector of value variable.

u

Numeric vector of uncertainty variable.

layers

An integer specifying the number of uncertainty levels.

branch

breaks

One of:

NULL for no breaks
waiver() for the default breaks (the scale limits)
A character vector of breaks
A function that takes the limits as input and returns breaks as output. Also accepts rlang lambda function notation.

limits

One of:

NULL to use the default scale values
A character vector that defines possible values of the scale and their order
A function that accepts the existing (automatic) values and returns new ones. Also accepts rlang lambda function notation.

transform

A list of two transformations applied to the variables before binning. Each element can be a transformation name or a transformer object accepted by scales::as.transform().

Value

A list containing quantized leaf ids and break information.

Package {ggincerta}

ggincerta: Extend 'ggplot2' with Layers and Scales for Spatial Uncertainty Visualization

Description

Author(s)

See Also

Bivariate colour guide

Description

Usage

Arguments

Format

Drop glyph guide

Description

Usage

Arguments

Format

Details

VSUP guide

Description

Usage

Arguments

Format

Bivariate colour scale constructor

Description

Usage

Arguments

Format

Details

Value

See Also

Examples

Value-Suppressing Uncertainty Palette (VSUP) scale

Description

Usage

Arguments

Format

See Also

Pixel map

Description

Usage

Arguments

Format

Details

Value

Examples

Colour fading palette

Description

Usage

Arguments

Colour blending palette

Description

Usage

Arguments

Format input and assign the "map" class

Description

Usage

Arguments

Value

Examples

Dual map

Description

Usage

Arguments

Details

Value

Examples

Glyph map

Description

Usage

Arguments

Details

Value

Examples

Create your own bivariate colour scale

Description

Usage

Arguments

Examples

North Carolina SIDS data

Description

Usage