In davidbody/earthquakes-package: Earthquakes Package for Mastering Software Development in R Capstone

The earthquakes package consists of four components:

Data from NOAA Significant Earthquakes Database
Helper functions to clean the data
Geoms for plotting earthquake timelines
Functions for plotting interactive earthquake maps

Data

Data from the NOAA Significant Earthquakes Database is included with this package.

This is a dataset containing data on destructive earthquakes from 2150 B.C. to the present (mid April 2017). The variables are as follows:

I_D
FLAG_TSUNAMI
YEAR
MONTH
DAY
HOUR
MINUTE
SECOND
FOCAL_DEPTH
EQ_PRIMARY
EQ_MAG_MW
EQ_MAG_MS
EQ_MAG_MB
EQ_MAG_ML
EQ_MAG_MFA
EQ_MAG_UNK
INTENSITY
COUNTRY
STATE
LOCATION_NAME
LATITUDE
LONGITUDE
REGION_CODE
DEATHS
DEATHS_DESCRIPTION
MISSING
MISSING_DESCRIPTION
INJURIES
INJURIES_DESCRIPTION
DAMAGE_MILLIONS_DOLLARS
DAMAGE_DESCRIPTION
HOUSES_DESTROYED
HOUSES_DESTROYED_DESCRIPTION
HOUSES_DAMAGED
HOUSES_DAMAGED_DESCRIPTION
TOTAL_DEATHS
TOTAL_DEATHS_DESCRIPTION
TOTAL_MISSING
TOTAL_MISSING_DESCRIPTION
TOTAL_INJURIES
TOTAL_INJURIES_DESCRIPTION
TOTAL_DAMAGE_MILLIONS_DOLLARS
TOTAL_DAMAGE_DESCRIPTION
TOTAL_HOUSES_DESTROYED
TOTAL_HOUSES_DESTROYED_DESCRIPTION
TOTAL_HOUSES_DAMAGED
TOTAL_HOUSES_DAMAGED_DESCRIPTION

More information, including variable definitions, is available at https://www.ngdc.noaa.gov/nndc/struts/form?t=101650&s=1&d=1

To use the data

filename <- system.file("extdata", "earthquakes.tsv.gz", package = "earthquakes")
earthquakes <- readr::read_delim(filename, delim = "\t")

library(earthquakes)

Functions for cleaning the data

There are two functions for cleaning the earthquakes data.

eq_clean_data adds a DATE column based on YEAR, MONTH, DAY, converts several character fields to numeric, and cleans LOCATION_NAME by passing it to the eq_location_clean function.

eq_location_clean returns a title case character string with the location's country removed. For example,

eq_location_clean("ITALY: VERONA")

Create a clean_earthquakes data frame like this:

library(dplyr)

clean_earthquakes <- earthquakes %>%
    eq_clean_data()

Geoms for earthquake time lines

This package contains two ggplot2 geoms for plotting earthquake time lines.

geom_timeline

geom_timeline plots a time line of earthquakes with a point for each earthquake. The x aesthetic is a date and the y aesthetic is a factor indicating some stratification in which case multiple time lines will be plotted for each level of the factor (e.g. country). Optional aesthetics include color, size, and alpha.

Here is an example:

library(lubridate)
library(ggplot2)

recent_earthquakes <- clean_earthquakes %>%
    filter(COUNTRY == "CHINA", DATE >= ymd('2000-01-01'))#'

g <- ggplot(recent_earthquakes,
            aes(x = DATE, y = COUNTRY, size = EQ_PRIMARY, color = TOTAL_DEATHS))
g <- g + geom_timeline(alpha = 0.5)
g <- g + theme_classic()
g <- g + theme(legend.position = "bottom",
               axis.line.y = element_blank(),
               axis.ticks.y = element_blank(),
               axis.title.y = element_blank(),
               axis.text.y = element_blank())
g <- g + guides(color = guide_colorbar(title = "# deaths"),
                size = guide_legend("Richter scale value"))
g

geom_timeline_label

This geom is intended to be used in conjunction with the geom_timeline geom to add a vertical line with a text annotation (e.g. the location of the earthquake) for each data point on an earthquake timeline. The x aesthetic specifies the date of the earthquake and the label aesthetic specifies the label for the annotation. An optional n_max aesthetic can be used to subset to n_max earthquakes, meaning the n_max largest (by magnitude) will be labeled.

Here is an example:

recent_earthquakes <- clean_earthquakes %>%
    filter(COUNTRY == "CHINA" | COUNTRY == "USA", DATE >= ymd('2000-01-01'))

g <- ggplot(recent_earthquakes,
            aes(x = DATE, y = COUNTRY, size = EQ_PRIMARY, color = TOTAL_DEATHS))

g <- g + geom_timeline(alpha = 0.5)
g <- g + geom_timeline_label(aes(label = LOCATION_NAME, n_max = 5))
g <- g + theme_classic()
g <- g + theme(legend.position = "bottom",
               axis.line.y = element_blank(),
               axis.ticks.y = element_blank(),
               axis.title.y = element_blank())
g <- g + guides(color = guide_colorbar(title = "# deaths"),
                size = guide_legend("Richter scale value"))
g

Mapping functions

eq_map

The eq_map function #' produces a map of earthquake epicenters (LATITUDE/LONGITUDE) and annotates each point with a popup window containing annotation data stored in a column of the data frame. The radius of each circle is proportional to the earthquake's magnitude (EQ_PRIMARY).

For example:

clean_earthquakes %>%
    dplyr::filter(COUNTRY == "MEXICO" & lubridate::year(DATE) >= 2000) %>%
    eq_map(annot_col = "DATE")

Notice that the date is displayed when you click on an earthquake on the map.

eq_create_label

This function creates HTML labels with location, magnitude, and total deaths for each earthquake.

Example:

clean_earthquakes %>%
    filter(COUNTRY == "MEXICO" & lubridate::year(DATE) >= 2000) %>%
    dplyr::mutate(popup_text = eq_create_label(.)) %>%
    eq_map(annot_col = "popup_text")