ggpointless: Additional Geometries and Stats for 'ggplot2'

Description

An (aspirational) collection of additional geometries and statistics for 'ggplot2'.

Author(s)

Maintainer: Markus Döring m4rkus.doering@gmail.com [copyright holder]

See Also

Useful links:

• https://flrd.github.io/ggpointless/

• https://github.com/flrd/ggpointless

• Report bugs at https://github.com/flrd/ggpointless/issues

Monthly CO2 records taken at Mauna Loa, since March 1958

Description

Atmospheric Carbon Dioxide Dry Air Mole Fractions from the NOAA GML Carbon Cycle Cooperative Global Air Sampling Network. Monthly time series constructed from daily mean values, from March 1958 to January 2022.

Usage

co2_ml

Format

A data frame with 766 rows and 5 variables

date

date of measurement

year

year of measurement

month

month of measurement

co2_ppm

CO2 concentration, in parts per million

decade

decade of the measurement

Source

Dr. Pieter Tans, NOAA/GML (gml.noaa.gov/ccgg/trends/) and Dr. Ralph Keeling, Scripps Institution of Oceanography (scrippsco2.ucsd.edu/).

https://gml.noaa.gov/ccgg/trends/data.html

Rates of COVID-19 Cases and Deaths by Vaccination Status

Description

Data on overall weekly rates of COVID-19 cases and deaths among fully vaccinated and unvaccinated people aged 12 years and older, according to COVID-19 positive specimen collection date. Data covers the periods from April 4, to December 25, 2021.

Usage

covid_vac

Format

A data frame with 146 rows and 4 variables

date

Week of data collection

incidence

COVID-19 cases and deaths, standardized by age

status

vaccination status

outcome

COVID-19 cases and deaths

Source

Centers for Disease Control and Prevention, Rates of COVID-19 Cases and Deaths by Vaccination Status

https://covid.cdc.gov/covid-data-tracker/#rates-by-vaccine-status

Key glyphs for legends

Description

Each geom has an associated function that draws the key when the geom needs to be displayed in a legend. These functions are called draw_key_*(), where * stands for the name of the respective key glyph. The key glyphs of the geom_lexis() function draws a short line of 45° with a point at the end, see examples below.

Usage

draw_key_pointless(data, params, size)

draw_key_sabline(data, params, linewidth, size)

draw_key_lexis(data, params, linewidth, size)

Arguments

Value

A grid grob.

Examples

df1 <- data.frame(x = c(0, 1), xend = c(2, 3), grp = c("A", "B"))
ggplot(df1, aes(x, xend = xend, color = grp)) +
  geom_lexis()

# the glyph can be changed using the `key_glyph` argument
ggplot(mtcars, aes(wt, mpg, color = "red")) +
  geom_point(key_glyph = "lexis")

Female leaders of independent states.

Description

Data from Wikipedia on women who have been elected or appointed head of state or government of their respective countries since the interwar period (1918–1939).

Usage

female_leaders

Format

A data frame with 131 rows and 5 variables

name

Person

startdate

Start of tenure

enddate

End of tenure

country

Country

power

Executive or non-executive

Details

This list includes women who were appointed by a governing committee or parliament where heads of state or government are not directly elected by citizens. The list does not include women chosen by a hereditary monarch.

Source

wikipedia.org

https://en.wikipedia.org/w/index.php?title=List_of_elected_and_appointed_female_heads_of_state_and_government&oldid=1078024588

Draw a catenary curve

Description

geom_catenary() draws a catenary curve which has a U-like shape, similar in appearance to a parabola, which it is not.

Usage

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

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

Arguments

Details

If a flexible chain or rope is loosely hung between two fixed points, it is a curve called a catenary. Catenary, from Latin word catēna, means "chain".

Aesthetics

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

• x

• y

• alpha

• color

• group

• linetype

• linewidth

Examples

dat <- data.frame(
  x = c(0, 1, 2),
  y = c(1, 2, -3)
)

p <- ggplot(dat, aes(x, y))
p + geom_catenary() +
  ylim(-4, NA)

# use chainLength argument to change default behaviour
# if you pick a chain length that is too short, a straight line is
# drawn and a message about minimum chain length is shown
p + geom_catenary(chainLength = 10) +
  ylim(-4, NA)

Apply Chaikin's corner cutting algorithm to smooth a path

Description

Chaikin's corner-cutting algorithm can be used to smooth sharp corners of a path.

Usage

geom_chaikin(
  mapping = NULL,
  data = NULL,
  stat = "chaikin",
  position = "identity",
  ...,
  iterations = 5,
  ratio = 0.25,
  closed = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_chaikin(
  mapping = NULL,
  data = NULL,
  geom = "path",
  position = "identity",
  ...,
  iterations = 5,
  ratio = 0.25,
  closed = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Details

Chaikin's corner cutting algorithm iteratively turns a jagged path into a smooth path.

The recursion formula starts from two vertices A and B, which represent a single corner of your path. From this, the algorithm derives two new points: one at the specified ratio when going from point A to point B, and one when going from B to A in the opposite direction. By default, a ratio of 0.25 results in two points: the first at 25% of point A and the other at 75% of point A (or 25% of point B). Those new points form a smoother path. Then the algorithm applies the same rule to each pair of new points. The rule is applied iterations times. The maximum number of iterations is 10, default is 5.

The ratio parameter must be a number between 0 and 1. If ratio > 0.5, then it will be flipped to 1 - ratio, and a message is shown.

Aesthetics

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

• x

• y

• alpha

• color

• group

• linetype

• linewidth

References

Chaikin, G. An algorithm for high speed curve generation. Computer Graphics and Image Processing 3 (1974), 346–349

Examples

set.seed(42)
dat <- data.frame(
  x = seq.int(10),
  y = sample(15:30, 10)
)

p1 <- ggplot(dat, aes(x, y)) +
  geom_line(linetype = "12")

p1 +
  geom_chaikin()

p1 +
  geom_chaikin(iterations = 1)

triangle <- data.frame(x = c(0, 0, 1), y = c(0, 1, 1))
p2 <- ggplot(triangle, aes(x, y)) +
  geom_path(linetype = "12") +
  coord_equal()

# ratio let's you control
p2 + geom_chaikin(ratio = .1)
p2 + geom_chaikin(ratio = .5)

# closed parameter to generate a closed shape - or not
p2 + geom_chaikin(iterations = 5, ratio = 0.25, closed = FALSE) # default
p2 + geom_chaikin(closed = TRUE)

Display events of different cohorts in form of a lexis charts

Description

This geom can be used to plot 45° lifelines for a cohort. Lexis diagrams are named after Wilhelm Lexis and used by demographers for more than a century.

Usage

geom_lexis(
  mapping = NULL,
  data = NULL,
  ...,
  point_show = TRUE,
  point_colour = NULL,
  point_size = deprecated(),
  gap_filler = TRUE,
  lineend = "round",
  linejoin = "round",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_lexis(
  mapping = NULL,
  data = NULL,
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Details

This geom draws 45° lines from the start to the end of a 'lifetime'. It is a combination of a segment, and a point. Besides y and yend coordinates this geom creates one additional variable called type in the layer data. You might want to map to an aesthetic with ggplot2::after_stat(), see Examples section and vignette("ggpointless") for more details.

Rows in your data with either missing x or xend values will be removed (your segments must start and end somewhere).

Aesthetics

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

• x

• xend

• alpha

• color

• fill

• group

• shape

• size

• linetype

• linewidth

• stroke

Examples

df1 <- data.frame(
  key = c("A", "B", "B", "C", "D", "E"),
  start = c(0, 1, 6, 5, 6, 9),
  end = c(5, 4, 10, 9, 8, 11)
)
p <- ggplot(df1, aes(x = start, xend = end, color = key))
p +
  geom_lexis()
p +
  geom_lexis(gap_filler = FALSE)
p +
  geom_lexis(aes(linetype = after_stat(type)),
    point_show = FALSE
  )

# change point appearance
p + geom_lexis(
  point_colour = "black",
  size = 3,
  shape = 21,
  fill = "white",
  stroke = 1
)

# missing values will be removed
df2 <- data.frame(
  key = c("A", "B", "B", "C", "D"),
  start = c(0, 1, 7, 5, 6),
  end = c(5, 4, 13, 9, NA)
)
ggplot(df2, aes(x = start, xend = end, color = key)) +
  geom_lexis()

# Ideally, `x` values should be increasing, unlike
# in the next example
df3 <- data.frame(x = Sys.Date() - 0:2, xend = Sys.Date() + 1:3)
ggplot(df3, aes(x = x, xend = xend)) +
  geom_lexis()

# If `x` is of class Date, `xend` can't be of class `POSIXt` or
# `POSIXct`. The error is thrown by the `scales::date_trans` function.
## Not run: 
ggplot(
  data.frame(x = Sys.Date(), xend = Sys.time()),
  aes(x = x, xend = xend)
) +
  geom_lexis()

## End(Not run)

Emphasize some observations with points

Description

This is a wrapper around geom_point() with the one additional argument: location. It allows to emphasize some observations, namely the first, the last, the minima and/or maxima, see examples. This geom is not particularly useful on its own, hence its name, but hopefully in conjunction with geom_line() and friends.

Usage

geom_pointless(
  mapping = NULL,
  data = NULL,
  stat = "pointless",
  position = "identity",
  ...,
  location = "last",
  na.rm = FALSE,
  orientation = NA,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_pointless(
  mapping = NULL,
  data = NULL,
  geom = "point",
  position = "identity",
  ...,
  location = "last",
  na.rm = FALSE,
  orientation = NA,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Details

The location argument allows you to specify which observations should be highlighted. If location is "last", the default, a single point will be plotted at the last non-missing observation. The locations are determined in the order in which they appear in the data – like geom_path() does compared to geom_line(). See the vignette("ggpointless") for more details.

Overplotting

Points may be plotted on top of one another. If location is set to "all", then the order in which points are plotted from top to bottom is: "first" > "last" > "minimum" > "maximum". Otherwise, the order is determined as specified in the location argument, which also then applies to the order legend key labels, see examples.

Orientation

This geom treats each axis differently and, 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.

Aesthetics

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

• x

• y

• alpha

• color

• fill

• group

• shape

• size

• stroke

Computed variables

location

locations, returned as factor

Examples

x <- seq(-pi, pi, length.out = 100)
y <- outer(x, 1:5, FUN = function(x, y) sin(x * y))

df1 <- data.frame(
  var1 = x,
  var2 = rowSums(y)
)

# not terribly useful on its own ...
p <- ggplot(df1, aes(x = var1, y = var2))
p + geom_pointless()
p + geom_pointless(location = "all")

# ... but in conjunction with geom_line(), hopefully
p <- p + geom_line()
p + geom_pointless()
p + geom_pointless(location = c("first", "last"))
p + geom_pointless(location = c("minimum", "maximum"))
p + geom_pointless(location = c("all"))

# The layer computes one additional variable, 'location',
# that you can map e.g. to the color aesthetic
p + geom_pointless(
  aes(color = after_stat(location)),
  location = c("all"),
  size = 3
)

# Example with missing first and last observations
set.seed(42)
df1 <- data.frame(x = 1:10, y = c(NA, sample(1:8), NA))
ggplot(df1, aes(x, y)) +
  geom_line() +
  geom_pointless(location = c("first", "last"))

# Change the order in which points are drawn when they overlap
df1 <- data.frame(var1 = 1:2, var2 = 1:2)
cols <- c(
  "first" = "#f8766d",
  "last" = "#7cae00",
  "minimum" = "#00bfc4",
  "maximum" = "#c77cff"
)

p <- ggplot(df1, aes(x = var1, y = var2)) +
  geom_path() +
  coord_equal() +
  # makes comparision easier
  scale_color_manual(values = cols)

# same as location = 'all'
p + geom_pointless(aes(color = after_stat(location)),
  location = c("first", "last", "minimum", "maximum")
) +
  labs(subtitle = "same as location = 'all'")

# reversed custom order
p + geom_pointless(aes(color = after_stat(location)),
  location = c("maximum", "minimum", "last", "first")
) +
  labs(subtitle = "custom order")

# same as location = 'all' again
p + geom_pointless(aes(color = after_stat(location)),
  location = c("maximum", "minimum", "last", "first", "all")
) +
  labs(subtitle = "same as location = 'all' again")

# Use stat_pointless() with a geom other than "point"
set.seed(42)
df1 <- data.frame(x = 1:10, y = sample(1:10))
ggplot(df1, aes(x, y)) +
  geom_line() +
  stat_pointless(
    aes(yintercept = y, color = after_stat(location)),
    location = c("maximum", "minimum"),
    geom = "hline"
  )

# Example using facets
# https://stackoverflow.com/q/29375169
p <- ggplot(economics_long, aes(x = date, y = value)) +
  geom_line() +
  facet_wrap(~variable, ncol = 1, scales = "free_y")

p +
  geom_pointless(
    aes(color = after_stat(location)),
    location = c("minimum", "maximum"),
    size = 2
  )

Given a year, get the decade

Description

Given a year, get the decade

Usage

get_decades(years, anno_domini = FALSE)

Arguments

Value

A string of the same length as year

Given a start, and end get the 'age' of an event

Description

Given a start, and end get the 'age' of an event

Usage

get_lexis(x, xend)

Arguments

Value

A data.frame

Subset input data based on locations

Description

Given a data frame, this functions returns a subset. Returns a data frame with either "first" row, "last" row and/or the row(s) that contain minima or maxima

Usage

get_locations(
  data = NULL,
  location = c("first", "last", "minimum", "maximum", "all")
)

Arguments

Value

A data.frame

Base ggproto classes for ggpointless

Description

If you are creating a new geom, stat, position, or scale in another package, you'll need to extend from ggplot2::Geom, ggplot2::Stat, ggplot2::Position, or ggplot2::Scale.

Details

More info at ggplot2-book.org

See Also

ggproto

Given a number, get the corresponding point shape

Description

Given a number, get the corresponding point shape

Usage

translate_shape_string(shape_string)

Arguments

Value

A data.frame