Connected points

Source: R/geom-pointline.r

Geoms are soft-deprecated, and will not be supported in the future. Please use the ggh4x-package. geom_pointpath combines geom_point and geom_path, such that a) when jittering is used, both lines and points stay connected, and b) provides a visual effect by adding a small gap between the point and the end of line. geom_pointline combines geom_point and geom_path.

geom_pointpath(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  distance = unit(3, "pt"),
  shorten = 0.5,
  threshold = 0.1,
  lineend = "butt",
  linejoin = "round",
  linemitre = 1,
  linesize = 0.5,
  linecolour = waiver(),
  linecolor = waiver(),
  arrow = NULL,
  ...
)

geom_pointline(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  distance = unit(3, "pt"),
  shorten = 0.5,
  threshold = 0.1,
  lineend = "butt",
  linejoin = "round",
  linemitre = 1,
  linesize = 0.5,
  linecolour = waiver(),
  linecolor = waiver(),
  arrow = NULL,
  ...
)

geom_pointrangeline(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  distance = unit(3, "pt"),
  lineend = "butt",
  linejoin = "round",
  linemitre = 1,
  linesize = 0.5,
  linecolour = waiver(),
  linecolor = waiver(),
  arrow = NULL,
  ...
)

Arguments

mapping

Set of aesthetic mappings created by aes or aes_.

data

The data to be displayed in this layer.

stat

The statistical transformation to use on the data for this layer, as a string.

position

Position adjustment, either as a string, or the result of a call to a position adjustment function (e.g. position_jitter). Both lines and points gets the same adjustment (this is where the function excels over geom_point() + geom_line()).

na.rm

If FALSE (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 (default), includes if any aesthetics are mapped. FALSE never includes, and TRUE always includes.

inherit.aes

If FALSE, overrides the default aesthetic, 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.

distance

Gap size between point and end of lines; use unit. Is converted to 'pt' if given as simple numeric. When NULL or NA, gapping and shorten/treshold is disabled. To keep the latter, set to 0.

shorten, threshold

When points are closer than threshold, shorten the line by the proportion in shorten instead of adding a gap by distance.

lineend

Line end style (round, butt, square).

linejoin

Line join style (round, mintre, bevel).

linemitre

Line mitre limit (number greater than 1).

linesize

Width of of line.

linecolour, linecolor

When not waiver(), the line is drawn with this colour instead of that set by aesthetic colour.

arrow

Arrow specification, as created by arrow.

...

other arguments passed on to layer.

Details

geom_pointpath connects the observations in the same order in which they appear in the data. geom_pointline connects them in order of the variable on the x-axis.

Both geom_pointpath and geom_pointline will only connect observations within the same group! However, if linecolour is not waiver(), connections will be made between groups, but possible in an incorrect order.

Aesthetics

geom_pointline and geom_pointpath understands the following aesthetics (required aesthetics are in bold):

  • x

  • y

  • alpha

  • colour – sets colour of point. Only affects line if linecolour=waiver().

  • stroke

  • shape

  • stroke

  • group

  • linetype

  • size – only affects point size. Width of line is set with linesize and cannot be linked to an aesthetic.

Examples

# geom_point examples
library(ggplot2)

p <- ggplot(mtcars, aes(wt, mpg))
p + geom_point() + geom_line()

p + geom_pointline()
#> Warning: `geom_pointpath` and `geom_pointline` have been soft-deprecated. A replacement can be found in ggh4x::geom_pointpath.


p + geom_pointline(linecolour='brown')
#> Warning: `geom_pointpath` and `geom_pointline` have been soft-deprecated. A replacement can be found in ggh4x::geom_pointpath.


p + geom_pointpath()
#> Warning: `geom_pointpath` and `geom_pointline` have been soft-deprecated. A replacement can be found in ggh4x::geom_pointpath.


# Add aesthetic mappings
p + geom_pointline(aes(colour = factor(cyl)))
#> Warning: `geom_pointpath` and `geom_pointline` have been soft-deprecated. A replacement can be found in ggh4x::geom_pointpath.

# Using linecolour preserved groups.
p + geom_pointline(aes(colour = factor(cyl)), linecolour='brown') 
#> Warning: `geom_pointpath` and `geom_pointline` have been soft-deprecated. A replacement can be found in ggh4x::geom_pointpath.


## If you want to combine the pretty lines of pointline that do *not* respect
## grouping (or order), combine several layers with geom_point on top:
p + geom_pointline() + geom_point(aes(colour=factor(cyl)))
#> Warning: `geom_pointpath` and `geom_pointline` have been soft-deprecated. A replacement can be found in ggh4x::geom_pointpath.


# Change scales
p + geom_pointline(aes(colour = cyl)) + scale_colour_gradient(low = "blue")
#> Warning: `geom_pointpath` and `geom_pointline` have been soft-deprecated. A replacement can be found in ggh4x::geom_pointpath.

p + geom_pointline(aes(colour = cyl), linecolour='black') + scale_colour_gradient(low = "blue")
#> Warning: `geom_pointpath` and `geom_pointline` have been soft-deprecated. A replacement can be found in ggh4x::geom_pointpath.

p + geom_pointline(aes(shape = factor(cyl))) + scale_shape(solid = FALSE)
#> Warning: `geom_pointpath` and `geom_pointline` have been soft-deprecated. A replacement can be found in ggh4x::geom_pointpath.


# For shapes that have a border (like 21), you can colour the inside and
# outside separately. Use the stroke aesthetic to modify the width of the
# border
ggplot(mtcars, aes(wt, mpg)) +
  geom_pointline(shape = 21, colour = "black", fill = "white", 
                 size = 5, stroke = 5, distance = unit(10, 'pt'))
#> Warning: `geom_pointpath` and `geom_pointline` have been soft-deprecated. A replacement can be found in ggh4x::geom_pointpath.


## Another example
df <- data.frame(x=rep(c('orange','apple','pear'), each=3), 
                 b=rep(c('red','green','purple'), times=3), y=runif(9))
ggplot(df, aes(x=x, y=y, colour=b, group=b)) + 
  geom_pointline(linesize=1, size=2, distance=6) + theme_bw()
#> Warning: `geom_pointpath` and `geom_pointline` have been soft-deprecated. A replacement can be found in ggh4x::geom_pointpath.


# geom_pointline() is suitable for time series
ggplot(economics, aes(date, unemploy)) + geom_pointline()
#> Warning: `geom_pointpath` and `geom_pointline` have been soft-deprecated. A replacement can be found in ggh4x::geom_pointpath.

ggplot(economics_long, aes(date, value01, colour = variable)) +
  geom_pointline()
#> Warning: `geom_pointpath` and `geom_pointline` have been soft-deprecated. A replacement can be found in ggh4x::geom_pointpath.