Package 'ggforce'

Description

This extension to ggplot2::facet_grid() will allow you to split a facetted plot over multiple pages. You define a number of rows and columns per page as well as the page number to plot, and the function will automatically only plot the correct panels. Usually this will be put in a loop to render all pages one by one.

Usage

facet_grid_paginate(
  facets,
  margins = FALSE,
  scales = "fixed",
  space = "fixed",
  shrink = TRUE,
  labeller = "label_value",
  as.table = TRUE,
  switch = NULL,
  drop = TRUE,
  ncol = NULL,
  nrow = NULL,
  page = 1,
  byrow = TRUE
)

Arguments

Note

If either ncol or nrow is NULL this function will fall back to the standard facet_grid functionality.

See Also

n_pages() to compute the total number of pages in a paginated faceted plot

Other ggforce facets: facet_stereo(), facet_wrap_paginate(), facet_zoom()

Examples

# Draw a small section of the grid
ggplot(diamonds) +
  geom_point(aes(carat, price), alpha = 0.1) +
  facet_grid_paginate(color ~ cut:clarity, ncol = 3, nrow = 3, page = 4)

Description

The facet_matrix() facet allows you to put different data columns into different rows and columns in a grid of panels. If the same data columns are present in both the rows and the columns of the grid, and used together with ggplot2::geom_point() it is also known as a scatterplot matrix, and if other geoms are used it is sometimes referred to as a pairs plot. facet_matrix is so flexible that these types are simply a subset of its capabilities, as any combination of data columns can be plotted against each other using any type of geom. Layers should use the .panel_x and .panel_y placeholders to map aesthetics to, in order to access the row and column data.

Usage

facet_matrix(
  rows,
  cols = rows,
  shrink = TRUE,
  switch = NULL,
  labeller = "label_value",
  flip.rows = FALSE,
  alternate.axes = FALSE,
  layer.lower = NULL,
  layer.diag = NULL,
  layer.upper = NULL,
  layer.continuous = NULL,
  layer.discrete = NULL,
  layer.mixed = NULL,
  grid.y.diag = TRUE
)

Arguments

Note

Due to the special nature of this faceting it slightly breaks the ggplot2 API, in that any positional scale settings are ignored. This is because each row and column in the grid will potentially have very different scale types and it is not currently possible to have multiple different scale specifications in the same plot object.

See Also

geom_autopoint, geom_autohistogram, geom_autodensity, and position_auto for geoms and positions that adapts to different positional scale types

Examples

# Standard use:
ggplot(mpg) +
  geom_point(aes(x = .panel_x, y = .panel_y)) +
  facet_matrix(vars(displ, cty, hwy))

# Switch the diagonal, alternate the axes and style strips as axis labels
ggplot(mpg) +
  geom_point(aes(x = .panel_x, y = .panel_y)) +
  facet_matrix(vars(displ, cty, hwy), flip.rows = TRUE,
               alternate.axes = TRUE, switch = 'both') +
  theme(strip.background = element_blank(),
        strip.placement = 'outside',
        strip.text = element_text(size = 12))

# Mix discrete and continuous columns. Use geom_autopoint for scale-based jitter
ggplot(mpg) +
  geom_autopoint() +
  facet_matrix(vars(drv:fl))

# Have a special diagonal layer
ggplot(mpg) +
  geom_autopoint() +
  geom_autodensity() +
  facet_matrix(vars(drv:fl), layer.diag = 2)


# Show continuous panels in upper triangle as contours and rest as binned
ggplot(mpg) +
  geom_autopoint() +
  geom_autodensity() +
  geom_density2d(aes(x = .panel_x, y = .panel_y)) +
  geom_bin2d(aes(x = .panel_x, y = .panel_y)) +
  facet_matrix(vars(drv:fl), layer.lower = 1, layer.diag = 2,
               layer.continuous = -4, layer.discrete = -3, layer.mixed = -3)


# Make asymmetric grid
ggplot(mpg) +
  geom_boxplot(aes(x = .panel_x, y = .panel_y, group = .panel_x)) +
  facet_matrix(rows = vars(cty, hwy), cols = vars(drv, fl))

Description

These facets are one-dimensional versions of ggplot2::facet_wrap(), arranging the panels in either a single row or a single column. This restriction makes it possible to support a space argument as seen in ggplot2::facet_grid() which, if set to "free" will allow the panels to be sized based on the relative range of their scales. Another way of thinking about them are one-dimensional versions of ggplot2::facet_grid() (ie. . ~ {var} or {var} ~ .), but with the ability to position the strip at either side of the panel. However you look at it it is the best of both world if you just need one dimension.

Usage

facet_row(
  facets,
  scales = "fixed",
  space = "fixed",
  shrink = TRUE,
  labeller = "label_value",
  drop = TRUE,
  strip.position = "top"
)

facet_col(
  facets,
  scales = "fixed",
  space = "fixed",
  shrink = TRUE,
  labeller = "label_value",
  drop = TRUE,
  strip.position = "top"
)

Arguments

Examples

# Standard use
ggplot(mtcars) +
  geom_point(aes(disp, mpg)) +
  facet_col(~gear)
# It retains the ability to have unique scales for each panel
ggplot(mtcars) +
  geom_point(aes(disp, mpg)) +
  facet_col(~gear, scales = 'free')

# But can have free sizing along the stacking dimension
ggplot(mtcars) +
  geom_point(aes(disp, mpg)) +
  facet_col(~gear, scales = 'free', space = 'free')

# And you can position the strip where-ever you like
ggplot(mtcars) +
  geom_point(aes(disp, mpg)) +
  facet_col(~gear, scales = 'free', space = 'free', strip.position = 'bottom')

Description

This, arguably pretty useless function, lets you create plots with a sense of depth by creating two slightly different versions of the plot that corresponds to how the eyes would see it if the plot was 3 dimensional. To experience the effect look at the plots through 3D hardware such as Google Cardboard or by relaxing the eyes and focusing into the distance. The depth of a point is calculated for layers having a depth aesthetic supplied. The scaling of the depth can be controlled with scale_depth() as you would control any aesthetic. Negative values will result in features placed behind the paper plane, while positive values will result in features hovering in front of the paper. While features within each layer is sorted so those closest to you are plotted on top of those more distant, this cannot be done between layers. Thus, layers are always plotted on top of each others, even if the features in one layer lies behind features in a layer behind it. The depth experience is inaccurate and should not be used for conveying important data. Regard this more as a party-trick...

Usage

facet_stereo(IPD = 63.5, panel.size = 200, shrink = TRUE)

Arguments

See Also

Other ggforce facets: facet_grid_paginate(), facet_wrap_paginate(), facet_zoom()

Examples

# You'll have to accept a warning about depth being an unknown aesthetic
ggplot(mtcars) +
  geom_point(aes(mpg, disp, depth = cyl)) +
  facet_stereo()

Description

This extension to ggplot2::facet_wrap() will allow you to split a facetted plot over multiple pages. You define a number of rows and columns per page as well as the page number to plot, and the function will automatically only plot the correct panels. Usually this will be put in a loop to render all pages one by one.

Usage

facet_wrap_paginate(
  facets,
  nrow = NULL,
  ncol = NULL,
  scales = "fixed",
  shrink = TRUE,
  labeller = "label_value",
  as.table = TRUE,
  switch = deprecated(),
  drop = TRUE,
  dir = "h",
  strip.position = "top",
  page = 1
)

Arguments

Note

If either ncol or nrow is NULL this function will fall back to the standard facet_wrap functionality.

See Also

n_pages() to compute the total number of pages in a paginated faceted plot

Other ggforce facets: facet_grid_paginate(), facet_stereo(), facet_zoom()

Examples

ggplot(diamonds) +
    geom_point(aes(carat, price), alpha = 0.1) +
    facet_wrap_paginate(~ cut:clarity, ncol = 3, nrow = 3, page = 4)

Description

This facetting provides the means to zoom in on a subset of the data, while keeping the view of the full dataset as a separate panel. The zoomed-in area will be indicated on the full dataset panel for reference. It is possible to zoom in on both the x and y axis at the same time. If this is done it is possible to both get each zoom separately and combined or just combined.

Usage

facet_zoom(
  x,
  y,
  xy,
  zoom.data,
  xlim = NULL,
  ylim = NULL,
  split = FALSE,
  horizontal = TRUE,
  zoom.size = 2,
  show.area = TRUE,
  shrink = TRUE
)

Arguments

See Also

Other ggforce facets: facet_grid_paginate(), facet_stereo(), facet_wrap_paginate()

Examples

# Zoom in on the versicolor species on the x-axis
ggplot(iris, aes(Petal.Length, Petal.Width, colour = Species)) +
  geom_point() +
  facet_zoom(x = Species == 'versicolor')

# Zoom in on versicolor on both axes
ggplot(iris, aes(Petal.Length, Petal.Width, colour = Species)) +
  geom_point() +
  facet_zoom(xy = Species == 'versicolor')

# Use different zoom criteria on each axis
ggplot(iris, aes(Petal.Length, Petal.Width, colour = Species)) +
  geom_point() +
  facet_zoom(x = Species != 'setosa', y = Species == 'versicolor')

# Get each axis zoom separately as well
ggplot(iris, aes(Petal.Length, Petal.Width, colour = Species)) +
  geom_point() +
  facet_zoom(xy = Species == 'versicolor', split = TRUE)

# Define the zoom area directly
ggplot(iris, aes(Petal.Length, Petal.Width, colour = Species)) +
  geom_point() +
  facet_zoom(xlim = c(2, 4))

# Selectively show data in the zoom panel
ggplot(iris, aes(Petal.Length, Petal.Width, colour = Species)) +
  geom_point() +
  facet_zoom(x = Species == 'versicolor', zoom.data = Species == 'versicolor')

Description

This helper function makes it easy to change tidy data into a tidy(er) format that can be used by geom_parallel_sets.

Usage

gather_set_data(data, x, id_name = "id")

Arguments

Value

A data.frame

Examples

data <- reshape2::melt(Titanic)
head(gather_set_data(data, 1:4))
head(gather_set_data(data, c("Class","Sex","Age","Survived")))

Description

This set of stats and geoms makes it possible to draw circle segments based on a center point, a radius and a start and end angle (in radians). These functions are intended for cartesian coordinate systems and makes it possible to create circular plot types without using the ggplot2::coord_polar() coordinate system.

Usage

stat_arc(
  mapping = NULL,
  data = NULL,
  geom = "arc",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  n = 360,
  inherit.aes = TRUE,
  ...
)

geom_arc(
  mapping = NULL,
  data = NULL,
  stat = "arc",
  position = "identity",
  n = 360,
  arrow = NULL,
  lineend = "butt",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

stat_arc2(
  mapping = NULL,
  data = NULL,
  geom = "path_interpolate",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  n = 360,
  inherit.aes = TRUE,
  ...
)

geom_arc2(
  mapping = NULL,
  data = NULL,
  stat = "arc2",
  position = "identity",
  n = 360,
  arrow = NULL,
  lineend = "butt",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

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

geom_arc0(
  mapping = NULL,
  data = NULL,
  stat = "arc0",
  position = "identity",
  ncp = 5,
  arrow = NULL,
  lineend = "butt",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

Arguments

Details

An arc is a segment of a line describing a circle. It is the fundamental visual element in donut charts where the length of the segment (and conversely the angular span of the segment) describes the proportion of an entety.

Aesthetics

geom_arc understand the following aesthetics (required aesthetics are in bold):

• x0

• y0

• r

• start

• end

• color

• linewidth

• linetype

• alpha

• lineend

Computed variables

x, y

The start coordinates for the segment

xend, yend

The end coordinates for the segment

curvature

The curvature of the curveGrob to match a circle

See Also

geom_arc_bar() for drawing arcs with fill

Examples

# Lets make some data
arcs <- data.frame(
  start = seq(0, 2 * pi, length.out = 11)[-11],
  end = seq(0, 2 * pi, length.out = 11)[-1],
  r = rep(1:2, 5)
)

# Behold the arcs
ggplot(arcs) +
  geom_arc(aes(x0 = 0, y0 = 0, r = r, start = start, end = end,
               linetype = factor(r)))

# Use the calculated index to map values to position on the arc
ggplot(arcs) +
  geom_arc(aes(x0 = 0, y0 = 0, r = r, start = start, end = end,
               size = after_stat(index)), lineend = 'round')

# The 0 version maps directly to curveGrob instead of calculating the points
# itself
ggplot(arcs) +
  geom_arc0(aes(x0 = 0, y0 = 0, r = r, start = start, end = end,
                linetype = factor(r)))

# The 2 version allows interpolation of aesthetics between the start and end
# points
arcs2 <- data.frame(
  angle = c(arcs$start, arcs$end),
  r = rep(arcs$r, 2),
  group = rep(1:10, 2),
  colour = sample(letters[1:5], 20, TRUE)
)

ggplot(arcs2) +
  geom_arc2(aes(x0 = 0, y0 = 0, r = r, end = angle, group = group,
                colour = colour), size = 2)

Description

This set of stats and geoms makes it possible to draw arcs and wedges as known from pie and donut charts as well as more specialized plottypes such as sunburst plots.

Usage

stat_arc_bar(
  mapping = NULL,
  data = NULL,
  geom = "arc_bar",
  position = "identity",
  n = 360,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

stat_pie(
  mapping = NULL,
  data = NULL,
  geom = "arc_bar",
  position = "identity",
  n = 360,
  sep = 0,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

geom_arc_bar(
  mapping = NULL,
  data = NULL,
  stat = "arc_bar",
  position = "identity",
  n = 360,
  expand = 0,
  radius = 0,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

Arguments

Details

An arc bar is the thick version of an arc; that is, a circle segment drawn as a polygon in the same way as a rectangle is a thick version of a line. A wedge is a special case of an arc where the inner radius is 0. As opposed to applying coord_polar to a stacked bar chart, these layers are drawn in cartesian space, which allows for transformations not possible with the native ggplot2 approach. Most notable of these are the option to explode arcs and wedgets away from their center point, thus detaching it from the main pie/donut.

Aesthetics

geom_arc_bar understand the following aesthetics (required aesthetics are in bold):

• x0

• y0

• r0

• r

• start - when using stat_arc_bar

• end - when using stat_arc_bar

• amount - when using stat_pie

• explode

• color

• fill

• linewidth

• linetype

• alpha

Computed variables

x, y

x and y coordinates for the polygon

x, y

The start coordinates for the segment

See Also

geom_arc() for drawing arcs as lines

Examples

# If you know the angle spans to plot it is easy
arcs <- data.frame(
  start = seq(0, 2 * pi, length.out = 11)[-11],
  end = seq(0, 2 * pi, length.out = 11)[-1],
  r = rep(1:2, 5)
)

# Behold the arcs
ggplot(arcs) +
  geom_arc_bar(aes(x0 = 0, y0 = 0, r0 = r - 1, r = r, start = start,
                   end = end, fill = r))

# geom_arc_bar uses geom_shape to draw the arcs, so you have all the
# possibilities of that as well, e.g. rounding of corners
ggplot(arcs) +
  geom_arc_bar(aes(x0 = 0, y0 = 0, r0 = r - 1, r = r, start = start,
                   end = end, fill = r), radius = unit(4, 'mm'))

# If you got values for a pie chart, use stat_pie
states <- c(
  'eaten', "eaten but said you didn\'t", 'cat took it', 'for tonight',
  'will decompose slowly'
)
pie <- data.frame(
  state = factor(rep(states, 2), levels = states),
  type = rep(c('Pie', 'Donut'), each = 5),
  r0 = rep(c(0, 0.8), each = 5),
  focus = rep(c(0.2, 0, 0, 0, 0), 2),
  amount = c(4, 3, 1, 1.5, 6, 6, 1, 2, 3, 2)
)

# Look at the cakes
ggplot() + geom_arc_bar(aes(
  x0 = 0, y0 = 0, r0 = r0, r = 1, amount = amount,
  fill = state, explode = focus
),
data = pie, stat = 'pie'
) +
  facet_wrap(~type, ncol = 1) +
  coord_fixed() +
  theme_no_axes() +
  scale_fill_brewer('', type = 'qual')

Description

These versions of the histogram and density geoms have been designed specifically for diagonal plotting with facet_matrix(). They differ from ggplot2::geom_histogram() and ggplot2::geom_density() in that they defaults to mapping x and y to .panel_x and .panel_y respectively, they ignore the y scale of the panel and fills it out, and they work for both continuous and discrete x scales.

Usage

geom_autodensity(
  mapping = NULL,
  data = NULL,
  stat = "autodensity",
  position = "floatstack",
  ...,
  bw = "nrd0",
  adjust = 1,
  kernel = "gaussian",
  n = 512,
  trim = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  outline.type = "upper"
)

geom_autohistogram(
  mapping = NULL,
  data = NULL,
  stat = "autobin",
  position = "floatstack",
  ...,
  bins = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

See Also

facet_matrix for creating matrix grids

Examples

# A matrix plot with a mix of discrete and continuous variables
p <- ggplot(mpg) +
  geom_autopoint() +
  facet_matrix(vars(drv:fl), layer.diag = 2, grid.y.diag = FALSE)
p

# Diagonal histograms
p + geom_autohistogram()

# Diagonal density distributions
p + geom_autodensity()

# You can use them like regular layers with groupings etc
p + geom_autodensity(aes(colour = drv, fill = drv),
                     alpha = 0.4)

Description

This geom is a specialisation of ggplot2::geom_point() with two changes. It defaults to mapping x and y to .panel_x and .panel_y respectively, and it defaults to using position_auto() to jitter the points based on the combination of position scale types.

Usage

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

Arguments

See Also

facet_matrix for how to lay out scatterplot matrices and position_auto for information about the position adjustments

Examples

# Continuous vs continuous: No jitter
ggplot(mpg) + geom_autopoint(aes(cty, hwy))

# Continuous vs discrete: sina jitter
ggplot(mpg) + geom_autopoint(aes(cty, drv))

# Discrete vs discrete: disc-jitter
ggplot(mpg) + geom_autopoint(aes(fl, drv))

# Used with facet_matrix (x and y are automatically mapped)
ggplot(mpg) +
  geom_autopoint() +
  facet_matrix(vars(drv:fl))

Description

This set of geoms makes it possible to connect points creating either quadratic or cubic beziers. bezier and bezier2 both work by calculating points along the bezier and connecting these to draw the curve. bezier0 directly draws the bezier using bezierGrob. In line with the geom_link() and geom_link2() differences geom_bezier creates the points, assign an index to each interpolated point and repeat the aesthetics for the start point, while geom_bezier2 interpolates the aesthetics between the start and end points.

Usage

stat_bezier(
  mapping = NULL,
  data = NULL,
  geom = "path",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  n = 100,
  inherit.aes = TRUE,
  ...
)

geom_bezier(
  mapping = NULL,
  data = NULL,
  stat = "bezier",
  position = "identity",
  arrow = NULL,
  lineend = "butt",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  n = 100,
  ...
)

stat_bezier2(
  mapping = NULL,
  data = NULL,
  geom = "path_interpolate",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  n = 100,
  inherit.aes = TRUE,
  ...
)

geom_bezier2(
  mapping = NULL,
  data = NULL,
  stat = "bezier2",
  position = "identity",
  arrow = NULL,
  lineend = "butt",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  n = 100,
  ...
)

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

geom_bezier0(
  mapping = NULL,
  data = NULL,
  stat = "bezier0",
  position = "identity",
  arrow = NULL,
  lineend = "butt",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

Arguments

Details

Input data is understood as a sequence of data points the first being the start point, then followed by one or two control points and then the end point. More than 4 and less than 3 points per group will throw an error. grid::bezierGrob() only takes cubic beziers so if three points are supplied the middle one as duplicated. This, along with the fact that grid::bezierGrob() estimates the curve using an x-spline means that the curves produced by geom_bezier and geom_bezier2 deviates from those produced by geom_bezier0. If you want true bezier paths use geom_bezier or geom_bezier2.

Aesthetics

geom_bezier, geom_bezier2 and geom_bezier0 understand the following aesthetics (required aesthetics are in bold):

• x

• y

• color

• linewidth

• linetype

• alpha

• lineend

Computed variables

x, y

The interpolated point coordinates

index

The progression along the interpolation mapped between 0 and 1

Examples

beziers <- data.frame(
  x = c(1, 2, 3, 4, 4, 6, 6),
  y = c(0, 2, 0, 0, 2, 2, 0),
  type = rep(c('cubic', 'quadratic'), c(3, 4)),
  point = c('end', 'control', 'end', 'end', 'control', 'control', 'end'),
  colour = letters[1:7]
)
help_lines <- data.frame(
  x = c(1, 3, 4, 6),
  xend = c(2, 2, 4, 6),
  y = 0,
  yend = 2
)

# See how control points affect the bezier
ggplot() +
  geom_segment(aes(x = x, xend = xend, y = y, yend = yend),
               data = help_lines,
               arrow = arrow(length = unit(c(0, 0, 0.5, 0.5), 'cm')),
               colour = 'grey') +
  geom_bezier(aes(x = x, y = y, group = type, linetype = type),
              data = beziers) +
  geom_point(aes(x = x, y = y, colour = point),
             data = beziers)

# geom_bezier0 is less exact
ggplot() +
  geom_segment(aes(x = x, xend = xend, y = y, yend = yend),
               data = help_lines,
               arrow = arrow(length = unit(c(0, 0, 0.5, 0.5), 'cm')),
               colour = 'grey') +
  geom_bezier0(aes(x = x, y = y, group = type, linetype = type),
               data = beziers) +
  geom_point(aes(x = x, y = y, colour = point),
             data = beziers)

# Use geom_bezier2 to interpolate between endpoint aesthetics
ggplot(beziers) +
  geom_bezier2(aes(x = x, y = y, group = type, colour = colour))

Description

This set of stats and geoms makes it possible to draw b-splines based on a set of control points. As with geom_bezier() there exists several versions each having there own strengths. The base version calculates the b-spline as a number of points along the spline and connects these with a path. The *2 version does the same but in addition interpolates aesthetics between each control point. This makes the *2 version considerably slower so it shouldn't be used unless needed. The *0 version uses grid::xsplineGrob() with shape = 1 to approximate a b-spline.

Usage

stat_bspline(
  mapping = NULL,
  data = NULL,
  geom = "path",
  position = "identity",
  na.rm = FALSE,
  n = 100,
  type = "clamped",
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

geom_bspline(
  mapping = NULL,
  data = NULL,
  stat = "bspline",
  position = "identity",
  arrow = NULL,
  n = 100,
  type = "clamped",
  lineend = "butt",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

stat_bspline2(
  mapping = NULL,
  data = NULL,
  geom = "path_interpolate",
  position = "identity",
  na.rm = FALSE,
  n = 100,
  type = "clamped",
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

geom_bspline2(
  mapping = NULL,
  data = NULL,
  stat = "bspline2",
  position = "identity",
  arrow = NULL,
  n = 100,
  type = "clamped",
  lineend = "butt",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

stat_bspline0(
  mapping = NULL,
  data = NULL,
  geom = "bspline0",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  type = "clamped",
  ...
)

geom_bspline0(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  arrow = NULL,
  lineend = "butt",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  type = "clamped",
  ...
)

Arguments

Aesthetics

geom_bspline understand the following aesthetics (required aesthetics are in bold):

• x

• y

• color

• linewidth

• linetype

• alpha

• lineend

Computed variables

x, y

The coordinates for the path describing the spline

index

The progression along the interpolation mapped between 0 and 1

Author(s)

Thomas Lin Pedersen. The C++ code for De Boor's algorithm has been adapted from Jason Yu-Tseh Chi implementation

Examples

# Define some control points
cp <- data.frame(
  x = c(
    0, -5, -5, 5, 5, 2.5, 5, 7.5, 5, 2.5, 5, 7.5, 5, -2.5, -5, -7.5, -5,
    -2.5, -5, -7.5, -5
  ),
  y = c(
    0, -5, 5, -5, 5, 5, 7.5, 5, 2.5, -5, -7.5, -5, -2.5, 5, 7.5, 5, 2.5,
    -5, -7.5, -5, -2.5
  ),
  class = sample(letters[1:3], 21, replace = TRUE)
)

# Now create some paths between them
paths <- data.frame(
  ind = c(
    7, 5, 8, 8, 5, 9, 9, 5, 6, 6, 5, 7, 7, 5, 1, 3, 15, 8, 5, 1, 3, 17, 9, 5,
    1, 2, 19, 6, 5, 1, 4, 12, 7, 5, 1, 4, 10, 6, 5, 1, 2, 20
  ),
  group = c(
    1, 1, 1, 2, 2, 2, 3, 3, 3, 4, 4, 4, 5, 5, 5, 5, 5, 6, 6, 6, 6, 6, 7, 7,
    7, 7, 7, 8, 8, 8, 8, 8, 9, 9, 9, 9, 9, 10, 10, 10, 10, 10
  )
)
paths$x <- cp$x[paths$ind]
paths$y <- cp$y[paths$ind]
paths$class <- cp$class[paths$ind]

ggplot(paths) +
  geom_bspline(aes(x = x, y = y, group = group, colour = after_stat(index))) +
  geom_point(aes(x = x, y = y), data = cp, color = 'steelblue')

ggplot(paths) +
  geom_bspline2(aes(x = x, y = y, group = group, colour = class)) +
  geom_point(aes(x = x, y = y), data = cp, color = 'steelblue')

ggplot(paths) +
  geom_bspline0(aes(x = x, y = y, group = group)) +
  geom_point(aes(x = x, y = y), data = cp, color = 'steelblue')

Description

This geom creates closed b-spline curves and draws them as shapes. The closed b-spline is achieved by wrapping the control points rather than the knots. The *0 version uses the grid::xsplineGrob() function with open = FALSE and can thus not be manipulated as a shape geom in the same way as the base version (expand, contract, etc).

Usage

stat_bspline_closed(
  mapping = NULL,
  data = NULL,
  geom = "shape",
  position = "identity",
  na.rm = FALSE,
  n = 100,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

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

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

Arguments

Aesthetics

geom_bspline_closed understand the following aesthetics (required aesthetics are in bold):

• x

• y

• color

• fill

• linewidth

• linetype

• alpha

Computed variables

x, y

The coordinates for the path describing the spline

index

The progression along the interpolation mapped between 0 and 1

Author(s)

Thomas Lin Pedersen. The C++ code for De Boor's algorithm has been adapted from Jason Yu-Tseh Chi implementation

Examples

# Create 6 random control points
controls <- data.frame(
  x = runif(6),
  y = runif(6)
)

ggplot(controls, aes(x, y)) +
  geom_polygon(fill = NA, colour = 'grey') +
  geom_point(colour = 'red') +
  geom_bspline_closed(alpha = 0.5)

# The 0 version approximates the correct shape
ggplot(controls, aes(x, y)) +
  geom_polygon(fill = NA, colour = 'grey') +
  geom_point(colour = 'red') +
  geom_bspline_closed0(alpha = 0.5)

# But only the standard version supports geom_shape operations
# Be aware of self-intersections though
ggplot(controls, aes(x, y)) +
  geom_polygon(fill = NA, colour = 'grey') +
  geom_point(colour = 'red') +
  geom_bspline_closed(alpha = 0.5, expand = unit(2, 'cm'))

Description

This set of stats and geoms makes it possible to draw circles based on a center point and a radius. In contrast to using ggplot2::geom_point(), the size of the circles are related to the coordinate system and not to a separate scale. These functions are intended for cartesian coordinate systems and will only produce a true circle if ggplot2::coord_fixed() is used.

Usage

stat_circle(
  mapping = NULL,
  data = NULL,
  geom = "circle",
  position = "identity",
  n = 360,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

geom_circle(
  mapping = NULL,
  data = NULL,
  stat = "circle",
  position = "identity",
  n = 360,
  expand = 0,
  radius = 0,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

Arguments

Aesthetics

geom_circle understand the following aesthetics (required aesthetics are in bold):

• x0

• y0

• r

• color

• fill

• linewidth

• linetype

• alpha

• lineend

Computed variables

x, y

The start coordinates for the segment

Note

If the intend is to draw a bubble chart then use ggplot2::geom_point() and map a variable to the size scale

See Also

geom_arc_bar() for drawing arcs with fill

Examples

# Lets make some data
circles <- data.frame(
  x0 = rep(1:3, 3),
  y0 = rep(1:3, each = 3),
  r = seq(0.1, 1, length.out = 9)
)

# Behold some circles
ggplot() +
  geom_circle(aes(x0 = x0, y0 = y0, r = r, fill = r), data = circles)

# Use coord_fixed to ensure true circularity
ggplot() +
  geom_circle(aes(x0 = x0, y0 = y0, r = r, fill = r), data = circles) +
  coord_fixed()

Description

A diagonal is a bezier curve where the control points are moved perpendicularly towards the center in either the x or y direction a fixed amount. The versions provided here calculates horizontal diagonals meaning that the x coordinate is moved to achieve the control point. The geom_diagonal() and stat_diagonal() functions are simply helpers that takes care of calculating the position of the control points and then forwards the actual bezier calculations to geom_bezier().

Usage

stat_diagonal(
  mapping = NULL,
  data = NULL,
  geom = "path",
  position = "identity",
  n = 100,
  strength = 0.5,
  na.rm = FALSE,
  orientation = NA,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

geom_diagonal(
  mapping = NULL,
  data = NULL,
  stat = "diagonal",
  position = "identity",
  n = 100,
  na.rm = FALSE,
  orientation = NA,
  strength = 0.5,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

stat_diagonal2(
  mapping = NULL,
  data = NULL,
  geom = "path_interpolate",
  position = "identity",
  na.rm = FALSE,
  orientation = NA,
  show.legend = NA,
  n = 100,
  strength = 0.5,
  inherit.aes = TRUE,
  ...
)

geom_diagonal2(
  mapping = NULL,
  data = NULL,
  stat = "diagonal2",
  position = "identity",
  arrow = NULL,
  lineend = "butt",
  na.rm = FALSE,
  orientation = NA,
  show.legend = NA,
  inherit.aes = TRUE,
  n = 100,
  strength = 0.5,
  ...
)

stat_diagonal0(
  mapping = NULL,
  data = NULL,
  geom = "bezier0",
  position = "identity",
  na.rm = FALSE,
  orientation = NA,
  show.legend = NA,
  inherit.aes = TRUE,
  strength = 0.5,
  ...
)

geom_diagonal0(
  mapping = NULL,
  data = NULL,
  stat = "diagonal0",
  position = "identity",
  arrow = NULL,
  lineend = "butt",
  na.rm = FALSE,
  orientation = NA,
  show.legend = NA,
  inherit.aes = TRUE,
  strength = 0.5,
  ...
)

Arguments

Aesthetics

geom_diagonal and geom_diagonal0 understand the following aesthetics (required aesthetics are in bold):

• x

• y

• xend

• yend

• color

• linewidth

• linetype

• alpha

• lineend

geom_diagonal2 understand the following aesthetics (required aesthetics are in bold):

• x

• y

• group

• color

• linewidth

• linetype

• alpha

• lineend

Computed variables

x, y

The interpolated point coordinates

index

The progression along the interpolation mapped between 0 and 1

Orientation

This geom treats each axis differently and, thus, can thus have two orientations. Often the orientation is easy to deduce from a combination of the given mappings and the types of positional scales in use. Thus, ggplot2 will by default try to guess which orientation the layer should have. Under rare circumstances, the orientation is ambiguous and guessing may fail. In that case the orientation can be specified directly using the orientation parameter, which can be either "x" or "y". The value gives the axis that the geom should run along, "x" being the default orientation you would expect for the geom.

Examples

data <- data.frame(
  x = rep(0, 10),
  y = 1:10,
  xend = 1:10,
  yend = 2:11
)

ggplot(data) +
  geom_diagonal(aes(x, y, xend = xend, yend = yend))

# The standard version provides an index to create gradients
ggplot(data) +
  geom_diagonal(aes(x, y, xend = xend, yend = yend, alpha = after_stat(index)))

# The 0 version uses bezierGrob under the hood for an approximation
ggplot(data) +
  geom_diagonal0(aes(x, y, xend = xend, yend = yend))

# The 2 version allows you to interpolate between endpoint aesthetics
data2 <- data.frame(
  x = c(data$x, data$xend),
  y = c(data$y, data$yend),
  group = rep(1:10, 2),
  colour = sample(letters[1:5], 20, TRUE)
)
ggplot(data2) +
  geom_diagonal2(aes(x, y, group = group, colour = colour))

# Use strength to control the steepness of the central region
ggplot(data, aes(x, y, xend = xend, yend = yend)) +
  geom_diagonal(strength = 0.75, colour = 'red') +
  geom_diagonal(strength = 0.25, colour = 'blue')

Description

The geom_diagonal_wide() function draws a thick diagonal, that is, a polygon confined between a lower and upper diagonal. This geom is bidirectional and the direction can be controlled with the orientation argument.

Usage

stat_diagonal_wide(
  mapping = NULL,
  data = NULL,
  geom = "shape",
  position = "identity",
  n = 100,
  strength = 0.5,
  na.rm = FALSE,
  orientation = NA,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

geom_diagonal_wide(
  mapping = NULL,
  data = NULL,
  stat = "diagonal_wide",
  position = "identity",
  n = 100,
  na.rm = FALSE,
  orientation = NA,
  strength = 0.5,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

Arguments

Aesthetics

geom_diagonal_wide understand the following aesthetics (required aesthetics are in bold):

• x

• y

• group

• color

• linewidth

• linetype

• alpha

• lineend

Orientation

This geom treats each axis differently and, thus, can thus have two orientations. Often the orientation is easy to deduce from a combination of the given mappings and the types of positional scales in use. Thus, ggplot2 will by default try to guess which orientation the layer should have. Under rare circumstances, the orientation is ambiguous and guessing may fail. In that case the orientation can be specified directly using the orientation parameter, which can be either "x" or "y". The value gives the axis that the geom should run along, "x" being the default orientation you would expect for the geom.

Examples

data <- data.frame(
  x = c(1, 2, 2, 1, 2, 3, 3, 2),
  y = c(1, 2, 3, 2, 3, 1, 2, 5),
  group = c(1, 1, 1, 1, 2, 2, 2, 2)
)

ggplot(data) +
  geom_diagonal_wide(aes(x, y, group = group))

# The strength control the steepness
ggplot(data, aes(x, y, group = group)) +
  geom_diagonal_wide(strength = 0.75, alpha = 0.5, fill = 'red') +
  geom_diagonal_wide(strength = 0.25, alpha = 0.5, fill = 'blue')

# The diagonal_wide geom uses geom_shape under the hood, so corner rounding
# etc are all there
ggplot(data) +
  geom_diagonal_wide(aes(x, y, group = group), radius = unit(5, 'mm'))

Description

This is a generalisation of geom_circle() that allows you to draw ellipses at a specified angle and center relative to the coordinate system. Apart from letting you draw regular ellipsis, the stat is using the generalised formula for superellipses which can be utilised by setting the m1 and m2 aesthetics. If you only set the m1 the m2 value will follow that to ensure a symmetric appearance.

Usage

stat_ellip(
  mapping = NULL,
  data = NULL,
  geom = "circle",
  position = "identity",
  n = 360,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

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

Arguments

Aesthetics

geom_arc understand the following aesthetics (required aesthetics are in bold):

• x0

• y0

• a

• b

• angle

• m1

• m2

• color

• fill

• linewidth

• linetype

• alpha

• lineend

Computed variables

x, y

The coordinates for the points along the ellipse

Examples

# Basic usage
ggplot() +
  geom_ellipse(aes(x0 = 0, y0 = 0, a = 10, b = 3, angle = 0)) +
  coord_fixed()

# Rotation
# Note that it expects radians and rotates the ellipse counter-clockwise
ggplot() +
  geom_ellipse(aes(x0 = 0, y0 = 0, a = 10, b = 3, angle = pi / 4)) +
  coord_fixed()

# Draw a super ellipse
ggplot() +
  geom_ellipse(aes(x0 = 0, y0 = 0, a = 6, b = 3, angle = -pi / 3, m1 = 3)) +
  coord_fixed()

Description

This set of geoms makes it possible to connect points using straight lines. Before you think ggplot2::geom_segment() and ggplot2::geom_path(), these functions have some additional tricks up their sleeves. geom_link connects two points in the same way as ggplot2::geom_segment() but does so by interpolating multiple points between the two. An additional column called index is added to the data with a sequential progression of the interpolated points. This can be used to map color or size to the direction of the link. geom_link2 uses the same syntax as ggplot2::geom_path() but interpolates between the aesthetics given by each row in the data.

Usage

stat_link(
  mapping = NULL,
  data = NULL,
  geom = "path",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  n = 100,
  inherit.aes = TRUE,
  ...
)

stat_link2(
  mapping = NULL,
  data = NULL,
  geom = "path_interpolate",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  n = 100,
  inherit.aes = TRUE,
  ...
)

geom_link(
  mapping = NULL,
  data = NULL,
  stat = "link",
  position = "identity",
  arrow = NULL,
  lineend = "butt",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  n = 100,
  ...
)

geom_link2(
  mapping = NULL,
  data = NULL,
  stat = "link2",
  position = "identity",
  arrow = NULL,
  lineend = "butt",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  n = 100,
  ...
)

geom_link0(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  arrow = NULL,
  arrow.fill = NULL,
  lineend = "butt",
  linejoin = "round",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Aesthetics

geom_link understand the following aesthetics (required aesthetics are in bold):

• x

• y

• xend

• yend

• color

• size

• linetype

• alpha

• lineend

geom_link2 understand the following aesthetics (required aesthetics are in bold):

• x

• y

• color

• size

• linetype

• alpha

• lineend

Computed variables

x, y

The interpolated point coordinates

index

The progression along the interpolation mapped between 0 and 1

Examples

# Lets make some data
lines <- data.frame(
  x = c(5, 12, 15, 9, 6),
  y = c(17, 20, 4, 15, 5),
  xend = c(19, 17, 2, 9, 5),
  yend = c(10, 18, 7, 12, 1),
  width = c(1, 10, 6, 2, 3),
  colour = letters[1:5]
)

ggplot(lines) +
  geom_link(aes(x = x, y = y, xend = xend, yend = yend, colour = colour,
                alpha = stat(index), size = after_stat(index)))

ggplot(lines) +
  geom_link2(aes(x = x, y = y, colour = colour, size = width, group = 1),
             lineend = 'round', n = 500)

# geom_link0 is simply an alias for geom_segment to put the link geoms in
# line with the other line geoms with multiple versions. `index` is not
# available here
ggplot(lines) +
  geom_link0(aes(x = x, y = y, xend = xend, yend = yend, colour = colour))

Description

This geom lets you annotate sets of points via circles. The enclosing circles are calculated at draw time and the most optimal enclosure at the given aspect ratio is thus guaranteed. As with the other ⁠geom_mark_*⁠ geoms the enclosure inherits from geom_shape() and defaults to be expanded slightly to better enclose the points.

Usage

geom_mark_circle(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  expand = unit(5, "mm"),
  radius = expand,
  n = 100,
  label.margin = margin(2, 2, 2, 2, "mm"),
  label.width = NULL,
  label.minwidth = unit(50, "mm"),
  label.hjust = 0,
  label.fontsize = 12,
  label.family = "",
  label.lineheight = 1,
  label.fontface = c("bold", "plain"),
  label.fill = "white",
  label.colour = "black",
  label.buffer = unit(10, "mm"),
  con.colour = "black",
  con.size = 0.5,
  con.type = "elbow",
  con.linetype = 1,
  con.border = "one",
  con.cap = unit(3, "mm"),
  con.arrow = NULL,
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Annotation

All ⁠geom_mark_*⁠ allow you to put descriptive textboxes connected to the mark on the plot, using the label and description aesthetics. The textboxes are automatically placed close to the mark, but without obscuring any of the datapoints in the layer. The placement is dynamic so if you resize the plot you'll see that the annotation might move around as areas become big enough or too small to fit the annotation. If there's not enough space for the annotation without overlapping data it will not get drawn. In these cases try resizing the plot, change the size of the annotation, or decrease the buffer region around the marks.

Filtering

Often marks are used to draw attention to, or annotate specific features of the plot and it is thus not desirable to have marks around everything. While it is possible to simply pre-filter the data used for the mark layer, the ⁠geom_mark_*⁠ geoms also comes with a dedicated filter aesthetic that, if set, will remove all rows where it evalutates to FALSE. There are multiple benefits of using this instead of prefiltering. First, you don't have to change your data source, making your code more adaptable for exploration. Second, the data removed by the filter aesthetic is remembered by the geom, and any annotation will take care not to overlap with the removed data.

Aesthetics

geom_mark_circle understand the following aesthetics (required aesthetics are in bold):

• x

• y

• x0 (used to anchor the label)

• y0 (used to anchor the label)

• filter

• label

• description

• color

• fill

• group

• size

• linetype

• alpha

See Also

Other mark geoms: geom_mark_ellipse(), geom_mark_hull(), geom_mark_rect()

Examples

ggplot(iris, aes(Petal.Length, Petal.Width)) +
  geom_mark_circle(aes(fill = Species, filter = Species != 'versicolor')) +
  geom_point()

# Add annotation
ggplot(iris, aes(Petal.Length, Petal.Width)) +
  geom_mark_circle(aes(fill = Species, label = Species)) +
  geom_point()

# Long descriptions are automatically wrapped to fit into the width
iris$desc <- c(
  'A super Iris - and it knows it',
  'Pretty mediocre Iris, but give it a couple of years and it might surprise you',
  "You'll never guess what this Iris does every Sunday"
)[iris$Species]

ggplot(iris, aes(Petal.Length, Petal.Width)) +
  geom_mark_circle(aes(fill = Species, label = Species, description = desc,
                       filter = Species == 'setosa')) +
  geom_point()

# Change the buffer size to move labels farther away (or closer) from the
# marks
ggplot(iris, aes(Petal.Length, Petal.Width)) +
  geom_mark_circle(aes(fill = Species, label = Species),
                   label.buffer = unit(30, 'mm')) +
  geom_point()

# The connector is capped a bit before it reaches the mark, but this can be
# controlled
ggplot(iris, aes(Petal.Length, Petal.Width)) +
  geom_mark_circle(aes(fill = Species, label = Species),
                   con.cap = 0) +
  geom_point()

# If you want to use the scaled colours for the labels or connectors you can
# use the "inherit" keyword instead
ggplot(iris, aes(Petal.Length, Petal.Width)) +
  geom_mark_circle(aes(fill = Species, label = Species),
                   label.fill = "inherit") +
  geom_point()

Description

This geom lets you annotate sets of points via ellipses. The enclosing ellipses are estimated using the Khachiyan algorithm which guarantees an optimal solution within the given tolerance level. As this geom is often expanded it is of lesser concern that some points are slightly outside the ellipsis. The Khachiyan algorithm has polynomial complexity and can thus suffer from scaling issues. Still, it is only calculated on the convex hull of the groups, so performance issues should be rare (it can easily handle a hull consisting of 1000 points).

Usage

geom_mark_ellipse(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  expand = unit(5, "mm"),
  radius = expand,
  n = 100,
  tol = 0.01,
  label.margin = margin(2, 2, 2, 2, "mm"),
  label.width = NULL,
  label.minwidth = unit(50, "mm"),
  label.hjust = 0,
  label.fontsize = 12,
  label.family = "",
  label.lineheight = 1,
  label.fontface = c("bold", "plain"),
  label.fill = "white",
  label.colour = "black",
  label.buffer = unit(10, "mm"),
  con.colour = "black",
  con.size = 0.5,
  con.type = "elbow",
  con.linetype = 1,
  con.border = "one",
  con.cap = unit(3, "mm"),
  con.arrow = NULL,
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Aesthetics

geom_mark_ellipse understands the following aesthetics (required aesthetics are in bold):

• x

• y

• x0 (used to anchor the label)

• y0 (used to anchor the label)

• filter

• label

• description

• color

• fill

• group

• size

• linetype

• alpha

Annotation

All ⁠geom_mark_*⁠ allow you to put descriptive textboxes connected to the mark on the plot, using the label and description aesthetics. The textboxes are automatically placed close to the mark, but without obscuring any of the datapoints in the layer. The placement is dynamic so if you resize the plot you'll see that the annotation might move around as areas become big enough or too small to fit the annotation. If there's not enough space for the annotation without overlapping data it will not get drawn. In these cases try resizing the plot, change the size of the annotation, or decrease the buffer region around the marks.

Filtering

Often marks are used to draw attention to, or annotate specific features of the plot and it is thus not desirable to have marks around everything. While it is possible to simply pre-filter the data used for the mark layer, the ⁠geom_mark_*⁠ geoms also comes with a dedicated filter aesthetic that, if set, will remove all rows where it evalutates to FALSE. There are multiple benefits of using this instead of prefiltering. First, you don't have to change your data source, making your code more adaptable for exploration. Second, the data removed by the filter aesthetic is remembered by the geom, and any annotation will take care not to overlap with the removed data.

See Also

Other mark geoms: geom_mark_circle(), geom_mark_hull(), geom_mark_rect()

Examples

ggplot(iris, aes(Petal.Length, Petal.Width)) +
  geom_mark_ellipse(aes(fill = Species, filter = Species != 'versicolor')) +
  geom_point()

# Add annotation
ggplot(iris, aes(Petal.Length, Petal.Width)) +
  geom_mark_ellipse(aes(fill = Species, label = Species)) +
  geom_point()

# Long descriptions are automatically wrapped to fit into the width
iris$desc <- c(
  'A super Iris - and it knows it',
  'Pretty mediocre Iris, but give it a couple of years and it might surprise you',
  "You'll never guess what this Iris does every Sunday"
)[iris$Species]

ggplot(iris, aes(Petal.Length, Petal.Width)) +
  geom_mark_ellipse(aes(fill = Species, label = Species, description = desc,
                        filter = Species == 'setosa')) +
  geom_point()

# Change the buffer size to move labels farther away (or closer) from the
# marks
ggplot(iris, aes(Petal.Length, Petal.Width)) +
  geom_mark_ellipse(aes(fill = Species, label = Species),
                    label.buffer = unit(40, 'mm')) +
  geom_point()

# The connector is capped a bit before it reaches the mark, but this can be
# controlled
ggplot(iris, aes(Petal.Length, Petal.Width)) +
  geom_mark_ellipse(aes(fill = Species, label = Species),
                    con.cap = 0) +
  geom_point()

# If you want to use the scaled colours for the labels or connectors you can
# use the "inherit" keyword instead
ggplot(iris, aes(Petal.Length, Petal.Width)) +
  geom_mark_ellipse(aes(fill = Species, label = Species),
                    label.fill = "inherit") +
  geom_point()

Description

This geom lets you annotate sets of points via hulls. While convex hulls are most common due to their clear definition, they can lead to large areas covered that does not contain points. Due to this geom_mark_hull uses concaveman which lets you adjust concavity of the resulting hull. The hull is calculated at draw time, and can thus change as you resize the plot. In order to clearly contain all points, and for aesthetic purpose the resulting hull is expanded 5mm and rounded on the corners. This can be adjusted with the expand and radius parameters.

Usage

geom_mark_hull(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  expand = unit(5, "mm"),
  radius = unit(2.5, "mm"),
  concavity = 2,
  label.margin = margin(2, 2, 2, 2, "mm"),
  label.width = NULL,
  label.minwidth = unit(50, "mm"),
  label.hjust = 0,
  label.fontsize = 12,
  label.family = "",
  label.lineheight = 1,
  label.fontface = c("bold", "plain"),
  label.fill = "white",
  label.colour = "black",
  label.buffer = unit(10, "mm"),
  con.colour = "black",
  con.size = 0.5,
  con.type = "elbow",
  con.linetype = 1,
  con.border = "one",
  con.cap = unit(3, "mm"),
  con.arrow = NULL,
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Aesthetics

geom_mark_hull understand the following aesthetics (required aesthetics are in bold):

• x

• y

• x0 (used to anchor the label)

• y0 (used to anchor the label)

• filter

• label

• description

• color

• fill

• group

• size

• linetype

• alpha

Annotation

All ⁠geom_mark_*⁠ allow you to put descriptive textboxes connected to the mark on the plot, using the label and description aesthetics. The textboxes are automatically placed close to the mark, but without obscuring any of the datapoints in the layer. The placement is dynamic so if you resize the plot you'll see that the annotation might move around as areas become big enough or too small to fit the annotation. If there's not enough space for the annotation without overlapping data it will not get drawn. In these cases try resizing the plot, change the size of the annotation, or decrease the buffer region around the marks.

Filtering

Often marks are used to draw attention to, or annotate specific features of the plot and it is thus not desirable to have marks around everything. While it is possible to simply pre-filter the data used for the mark layer, the ⁠geom_mark_*⁠ geoms also comes with a dedicated filter aesthetic that, if set, will remove all rows where it evalutates to FALSE. There are multiple benefits of using this instead of prefiltering. First, you don't have to change your data source, making your code more adaptable for exploration. Second, the data removed by the filter aesthetic is remembered by the geom, and any annotation will take care not to overlap with the removed data.

See Also

Other mark geoms: geom_mark_circle(), geom_mark_ellipse(), geom_mark_rect()

Examples

ggplot(iris, aes(Petal.Length, Petal.Width)) +
  geom_mark_hull(aes(fill = Species, filter = Species != 'versicolor')) +
  geom_point()

# Adjusting the concavity lets you change the shape of the hull
ggplot(iris, aes(Petal.Length, Petal.Width)) +
  geom_mark_hull(aes(fill = Species, filter = Species != 'versicolor'),
    concavity = 1
  ) +
  geom_point()

ggplot(iris, aes(Petal.Length, Petal.Width)) +
  geom_mark_hull(aes(fill = Species, filter = Species != 'versicolor'),
    concavity = 10
  ) +
  geom_point()

# Add annotation
ggplot(iris, aes(Petal.Length, Petal.Width)) +
  geom_mark_hull(aes(fill = Species, label = Species)) +
  geom_point()

# Long descriptions are automatically wrapped to fit into the width
iris$desc <- c(
  'A super Iris - and it knows it',
  'Pretty mediocre Iris, but give it a couple of years and it might surprise you',
  "You'll never guess what this Iris does every Sunday"
)[iris$Species]

ggplot(iris, aes(Petal.Length, Petal.Width)) +
  geom_mark_hull(aes(fill = Species, label = Species, description = desc,
                     filter = Species == 'setosa')) +
  geom_point()

# Change the buffer size to move labels farther away (or closer) from the
# marks
ggplot(iris, aes(Petal.Length, Petal.Width)) +
  geom_mark_hull(aes(fill = Species, label = Species),
                 label.buffer = unit(40, 'mm')) +
  geom_point()

# The connector is capped a bit before it reaches the mark, but this can be
# controlled
ggplot(iris, aes(Petal.Length, Petal.Width)) +
  geom_mark_hull(aes(fill = Species, label = Species),
                 con.cap = 0) +
  geom_point()

# If you want to use the scaled colours for the labels or connectors you can
# use the "inherit" keyword instead
ggplot(iris, aes(Petal.Length, Petal.Width)) +
  geom_mark_hull(aes(fill = Species, label = Species),
                 label.fill = "inherit") +
  geom_point()