In johnxz/farsr: Summarize and Visulize FARS Data in R

library(farsr)
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
knitr::opts_knit$set(
  root.dir = system.file("extdata", "fars_data", package = "farsr")
)

farsr: Overview

This R package was created as an assignment for the Coursera course "Building R Packages".

It provides R functions that can be used to import, summarize and visualize 'yearly data regarding fatal injuries suffered in motor vehicle traffic crashes' that has been annually published by and publicly available for download from the Fatality Analysis Reporting System (FARS), which is a nationwide census of US National Highway Traffic Safety Administration (NHTSA). For more information about FARS data, visit the FARS|NHTSA website.

Two main functions provided in the package are fars_summarize_years() and fars_map_state(), both of which can directly read in raw fatal traffic crash data from the annual FARS data file(s), by calling the helper functions fars_read() and make_filename() that are also provided in the package. The fars_summarize_years() function lets you read in yearly data of multiple years by calling the helper function fars_read_years(), and produces national-level aggregated counts of monthly total fatal crashes as a descriptive statistic of the data on a yearly basis. The fars_map_state() function plots annual geographic distribution of FARS fatal crash locations, but only on individual state-level.

library(farsr)
ls("package:farsr")

# load dependencies
library(dplyr)
library(readr)
library(tidyr)
library(maps)

Count FARS Traffic Accidents by Month and Year

To produce the aggregated counts of fatalities by month and year, call fars_summarize_years() function and supply a numeric vector of four digit numbers that represents years as the argument. This will produce a pivot table of monthly totals, with rows by month and columns by year:

years <- c(2013:2015)  # or a single number, as a vector of length 1
fars_summarize_years(years = years)

The FARS data file to be read into R must be put in the current working directory. It should also be noted that the range of years within which FARS data are available to public is from 1975 to present. An invalid value (year) specified in the input, corresponding to either a non-existent data or a file name that does not exist in the given path, will cause a NULL value generated while reading data from file(s), missing value (column) for the invalid year in the output, and a warning message "invalid year: ...". Completely invalid input will cause a "Must group by variables found in .data" error in addition to warning messages of "invalid year: ...":

fars_summarize_years(c(1960, 2013, 2014))
tryCatch( fars_summarize_years(c(1960, 2020)), error = function(e) {
  message("An error occurred:\n", e)
})

Geographic Mapping of Fatal Crash Locations by State

The raw FARS data includes the geographical coordinates of its fatal traffic accident entries. Geographically mapping the FARS location data and visualize the spatial relationships among them can help you gain insight into data that might be missed in its tabular format.

The fars_map_state() function takes two arguments: a FIPS state numeric code and a four-digit year. It plots geographic distribution of locations where FARS fatal crashes occurred in the particular state and year specified in the arguments. The function calls \code{\link[maps]{map}} to draw the map of the state, an outlined polygon selected from the geographical database of USA state, then calls \code{\link[graphics]{points}} function to add the points of geographic mapping to all non NA latitude and longitude coordinates of the read in FARS entries to the state map:

pdf(file="2015_STATE06.pdf")
fars_map_state(state.num=06, year=2015)  # California
dev.off()

fars_map_state(state.num=36, year=2015)  #New York

Make sure that correct inputs are supplied. Invalid year will result in a "file ... does not exist" error. Invalid \code{state.num}, which has no match in STATE column of FARS data, will cause function to stop execution and result in "invalid STATE number: ..." error. Missing data for the state and year as specified in the arguments will result in a message "no accidents to plot" and a (temporarily) invisible NULL object to be returned:

```r
tryCatch( fars_map_state(state.num=36, year=2021), error = function(e) {
  message("An error occurred:\n", e)
})  
tryCatch( fars_map_state(state.num=90, year=2015), error = function(e) {
  message("An error occurred:\n", e)
})   

johnxz/farsr documentation built on Dec. 21, 2021, 2:14 a.m.