In RussellPolitzky/quake: Earthquake Data Visualizations

Introduction

quake provides functions to clean and visualize NOAA data.

quake supports two kinds of visualizations based on ggplot2; timelines and maps. Timelines show when earthquakes happened, while maps show where they happened.

Timelines make use a number of aesthetics to show:

the time at which each quake happened (x position on the timeline) and
indicate the magnitude of each quake by the size of the marker used and
indicate the number of associated deaths by the colour of the marker and
indicate the country or region in which the quake occurred by grouping these together on the y axis and,
indicate the city/town where a quake occurred using labels pointing to the associated marker and,
use transparency to indicate the degree of clustering in time, of earthquakes.

quake provides two custom ggplot2 geometries to render timelines.

Maps show the positions of earthquakes. They also:

indicate quake magnitude by marker size and
show the location, magnitude and total, associated deaths by way of click-able pop-ups.

quake wraps functionality from the leaflet package to achieve this.

The examples below show typical usage of all the functions exported by quake. Additional detail on each function is available in the API documentation.

Cleaning NOAA Data

The code below reads a sample file using data.table's fread function and cleans it using eq_clean_data. The sample shows the first three rows and columns 1-5, and 48-49 of the cleaned output.

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

data_file_name <- system.file("extdata", "earthquakes.tsv", package = "quake")
clean_data     <- fread(data_file_name) %>% eq_clean_data

Rows 1-3 and columns 1-5 and 48-49 of the cleaned data is given below.

clean_data[1:3, c(1:5, 48:49)]  # show 1st three rows and cols 1-5 and 48-49

eq_clean_data uses function eq_location_clean, which is also exposed by quake, to clean NOAA location information. The example below shows how to use eq_location_clean to produce a vector of clean, location strings.

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

data_file_name  <- system.file("extdata", "earthquakes.tsv", package = "quake")
clean_locations <- fread(data_file_name)[, LOCATION_NAME] %>% eq_location_clean

The first few cleaned locations are shown below.

head(clean_locations)  # show 1st three rows and cols 1-5 and 48-49

Plotting an Earthquake Timeline

quake has two custom, ggplot2 geometries to plot earthquake data. geom_timeline plots timelines while geom_timeline_label adds labels to timelines.

The example code below generates sample data and plots a timeline showing the dates, magnitudes and countries of each quake.

Generate sample data

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

n        <- 20 # no samples
# get a list of countries and cities.
cty_file <- system.file("extdata", "countries_cities.csv", package = "quake")
ctry_cty <- (fread(cty_file))[sample(1:.N, size = n, replace = TRUE), ]

# Sample data
dt <- data.table(
  date      = as.Date('2017-01-01') + seq(1, 365, 365/n),
  country   = factor(ctry_cty$Country),
  location  = factor(ctry_cty$City   ),
  intensity = runif(n)*10,
  deaths    = runif(n)*12
)

The sample data head's shown below.

head(dt)

Plot the sample data

date on the x axis, \beta^{2\ }+\sin\left(x\right)- country on the y axis,
quake magnitude shown using marker size,
the number of associated deaths indicated by colour

dt %>%
  ggplot() +
  geom_timeline(
    aes(
      x    = date, 
      y    = country, 
      size = intensity, 
      col  = deaths
    ), 
    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

Notice theme_timeline_with_y_axis_text theme add-on, which is one of two themes provided by the quake package, the other being theme_timeline, which turns off all y-axis graphics including the text.

Also notice that by adding y = country, timelines, grouped by country, are produced. Without this optional aesthetic, all quakes will be plotted on a single timeline.

Plot sample data without y axis

This is the same plot, as above, with all quakes shown on a single timeline, and without any y-axis decorations.

dt %>%
  ggplot() +
  geom_timeline(
    aes(
      x    = date, 
      size = intensity, 
      col  = deaths
    ), 
    alpha = 0.8
  ) +
  labs(x = "DATE")                                     +
  scale_size_continuous (name = "Richter scale value") +
  scale_color_continuous(name = "# deaths"           ) +
  theme_classic()                                      +
  theme_timeline # no y axis

Note that in this example, no y aesthetic was used and that as such, geom_timeline plots a single timeline showing all events.

Adding Labels to An Earthquake Timeline

The example above shows a timeline without labels. That is, the timeline doesn't indicate the actual locations at which the quakes happened. The geom_timeline_label addresses this problem.

The example below shows a timeline, plotting the same data, but with labels added using geom_timeline_label.

dt %>%
  ggplot() +
  geom_timeline(       # plot the timeline
    aes(
      x    = date, 
      y    = country, 
      size = intensity, 
      col  = deaths
    ), 
    alpha = 0.8
  ) + 
  geom_timeline_label( # add labels.
    aes(
      label = location , # label text
      x     = date     , # x location
      y     = country  , # level to add label at 
      size  = intensity  #
    ),
    n_max = 5 # only label 5 most intense quakes
  ) +
  labs(x = "DATE")                                     +
  scale_size_continuous (name = "Richter scale value") +
  scale_color_continuous(name = "# deaths"           ) +
  theme_classic()                                      +
  theme_timeline_with_y_axis_text

Locating Quakes on a Map

quake also maps NOAA data making it easy to identify fault lines, for example.

library(readr)
library(dplyr)
library(lubridate)
library(quake)

data_file_name <- system.file("extdata", "earthquakes.tsv.gz", package = "quake")

read_delim(data_file_name, delim = "\t")           %>% # read tsv, NOAA data
  eq_clean_data()                                  %>% # clean data
  filter(COUNTRY == "MEXICO" & year(date) >= 2000) %>% # filter to show Mexico
  mutate(popup_text = eq_create_label(.))          %>% # add col with HTML popups
  eq_map(annot_col = "popup_text")                     # render map with popup