geom_timeline_label: Add text labels to timelines produced with geom_timeline
In RussellPolitzky/quake: Earthquake Data Visualizations

Description Usage Arguments Value Examples

View source: R/geom_timeline_label.R

geom_timeline_label adds annotations to earthquake data timelines produced with geom_timeline. This geom adds a vertical line to each data point with a text annotation (e.g. the location of an earthquake) attached atop each line. geom_timeline_label provides an option to subset to n_max number of earthquakes, where n_max selects the largest (by magnitude) earthquakes. This geometry supports the following aesthetics:

x is the date of the earthquake and
label is the column name from which annotations will be obtained

geom_timeline_label(mapping = NULL, data = NULL, stat = "identity",
  position = "identity", na.rm = FALSE, show.legend = NA,
  inherit.aes = TRUE, pointerheight = 0.05, angle = 45,
  labelcolour = "black", n_max = .Machine$integer.max, fill = "black",
  xmin = .Machine$double.xmin, xmax = .Machine$double.xmax, ...)

`mapping`	Set of aesthetic mappings created by `aes` or `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.
`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.
`na.rm`	a `boolean` indicating whether or not to remove NAs. `na.rm = FALSE` by default.
`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.
`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. `borders`.
`pointerheight`	is a `numeric` indicating the height of lable, pointer lines This height is specified as a faction of the viewport height, and will usually not require adjustment. The default value for this parameter is 0.05.
`angle`	is a `numeric` indicating the text label angle. Text is printed at an angle to allow good readability and to reduce label collisions for dense time lines. This angle won't usually require adjustment and is set at 45 degrees by default.
`labelcolour`	is a `string` giving the label colour. This is set to 'black' by default.
`n_max`	is a `numeric` giving the maximum number of labels to display. This reduces the number of label collisions in dense, timelime plots. The labels to show are chosen based on the `size` aestheic. Setting `n_max` will result in a maximum of `n_max` labels, ordered by the aesthetic `size`, being rendered.
`fill`	a `string` indicating the label, fill colour. `fill = 'black'` by default.
`xmin`	is a `numeric` specifiying the minimum `x` value to consider. `xmin = .Machine$double.xmin` by default.
`xmax`	is a `numeric` specifiying the maximum `x` value to consider. `xmax = .Machine$double.xmax` by default.
`...`	a `...` indicates a list of additional parameters used for a geom. `geom_timeline_label` doesn't make use of these.

a ggplot2 object representing timeline labels. This is intended to be used with geom_timeline.

library(quake     )
library(magrittr  )
library(data.table)
library(ggplot2   )

# Create dummy data

n         <- 100 # start with 100 data samples
countries <- c("USA", "China", "India", "South Africa")

dt <- data.table(
  date      = as.Date('2017-01-01') + seq(1, 365, 365/n),
  country   = factor(sample(countries, replace = TRUE, size = n)),
  intensity = runif(n)*10, # mag is somewhere beteen 0 and 10
  deaths    = runif(n)*12
)

head(dt) # show dummy data

start_date       <- as.Date('2017-07-01') # only show quakes from July 2017
end_date         <- as.Date('2017-07-30') # only show quakes from July 2017
no_labels_toshow <- 3 # show only three labels from highest intensity quakes

dt %>%
  ggplot() +
  geom_timeline_label(
    aes(
      label = as.character(country),
      x     = date     ,
      y     = country  ,
      size  = intensity
    ),
    n_max = no_labels_toshow,
    xmin  = start_date,
    xmax  = end_date
  ) +
  geom_timeline(
    aes(
      x    = date     ,
      y    = country  ,
      size = intensity,
      col  = deaths
    ),
    xmin  = start_date,
    xmax  = end_date,
    alpha = 0.8
  ) +
  labs(x = "DATE")                                     +
  scale_size_continuous (name = "Richter scale value") +
  scale_color_continuous(name = "# deaths"           ) +
  theme_classic()                                      +
  theme_timeline_with_y_axis_text