peel_hulls: Bivariate data peelings

In gggda: A 'ggplot2' Extension for Geometric Data Analysis

Bivariate data peelings

Description

Use convex hulls (and eventually other peelings) to order bivariate data.

Usage

peel_hulls(
  x,
  y = NULL,
  num = NULL,
  by = 1L,
  breaks = c(0.5),
  cut = c("above", "below")
)

Arguments

x, y	coordinate vectors of points. This can be specified as two vectors x and y, a 2-column matrix x, a list x with two components, etc, see xy.coords.
num	A positive integer; the number of hulls to peel. Pass Inf for all hulls.
by	A positive integer; with what frequency to include consecutive hulls, pairs with num.
breaks	A numeric vector of fractions (between 0 and 1) of the data to contain in each hull; overridden by num.
cut	Character; one of "above" and "below", indicating whether each hull should contain at least or at most breaks of the data, respectively.

Details

Methods for peeling bivariate data into concentric tiers generalize the univariate concept of rank to separate core versus peripheral cases (Green, 1981).

The code for peeling convex hulls was adapted from plothulls() in the aplpack package. Other peeling options should be implemented soon.

Value

A matrix with some or all of the following columns:

x,y

original coordinates

i

position in input matrix or vectors

hull

index of hull, starting from outermost

frac

value of breaks used to determine hull

prop

proportion of data within hull

References

Green PJ (1981) "Peeling Bivariate Data". Interpreting Multivariate Data Chapter 1, 3–19. John Wiley & Sons, Ltd, ISBN 978-0-471-28039-2.

Examples

x <- mtcars$disp; y <- mtcars$mpg

# all hulls
peel_hulls(x, y, num = Inf)

# every third hull
peel_hulls(x, y, num = Inf, by = 3)

# tertile hulls, cut below
peel_hulls(x, y, breaks = seq(0, 1, length.out = 4))

# tertile hulls, cut above
peel_hulls(x, y, breaks = seq(0, 1, length.out = 4), cut = "below")

gggda documentation built on July 18, 2026, 5:07 p.m.