R/fars_functions.R

In olb1605/FARS_Package_Coursera: Analyse FARS accidents data

#' @title FARS functions
#'
#' These functions provided are using data from the US National Highway Traffic
#' Safety Administration's Fatality Analysis Reporting System (FARS), which is
#' a nationwide census providing the American public yearly data regarding
#' fatal injuries suffered in motor vehicle traffic crashes.
#'
#'
#' Function "fars_read" - Open CSV file
#'
#' @description This function reads CSV file and opens it in a data frame form.
#'
#' @details This function opens CSV file from FARS. If the file with the specified name
#' does not exist the function gives an error message"file....does not exist".
#' Function suppress any warning messages that can be generated by read_csv function
#' used to open CSV file. It contributes to the function fars_read_years.
#'
#'
#' @importFrom readr read_csv
#' @importFrom dplyr tbl_df
#'
#' @param filename A character string giving the file name with its location.
#' This parameter generated by fars_map_state.
#'
#'
#' @return This function returns a data frame that containes data from CSV file.
#' If file does not exist it returns an error message.
#'
#' @examples
#' \dontrun{
#' library(dplyr)
#' library(readr)
#' library(magrittr)
#' library(tidyr)
#' library(dplyr)
#' library(maps)
#' library(graphics)
#'
#' fars_read("accident_2015.csv.bz2")}
#'
#'
#' @export
fars_read <- function(filename) {
  if(!file.exists(filename))
    stop("file '", filename, "' does not exist")
  data <- suppressMessages({
    readr::read_csv(filename, progress = FALSE)
  })
  dplyr::tbl_df(data)
}

#' Function "make_filename" - creates a file name in a specified format
#'
#' @description Function creates a string to be used as a name of CSV file
#' using a given year and a string "accident_" ... ".csv.bz2".
#'
#' @details This function contributes to the functions fars_read_years,
#' fars_map_state
#'
#' @param year A string or an integer
#'
#' @return This function returns a string with the CSV file name for a given
#'  year
#'
#' @note The returned string of this function used in the function fars_read
#' and as an input in the function fars_map_state to make an input parameter
#' filename
#'
#' @examples
#' \dontrun{
#' make_filename(2015)}
#'
#'
#' @export
make_filename <- function(year) {
  year <- as.integer(year)
  sprintf("accident_%d.csv.bz2", year)
}

#' Function fars_read_years - read data by years from the FARS files
#'
#' @description . This function reads data from FARS files. It opens specified CSV file
#' which name generated by fars_readmake_filename finction and it use
#' fars_read function to open the file. It returns the data frames by specified
#'  years. if any year specified is not walid it shows error messege "invalid year: "
#'
#' @param years a vector with the list of years
#'
#' @importFrom dplyr mutate select %>%
#'
#'
#' @return This function returns data frames or NULL if the year is not valid
#'
#'
#' @examples
#' \dontrun{
#' fars_read_years(2013:2014)}
#'
#' @export

fars_read_years <- function(years) {
  lapply(years, function(year) {
    file <- make_filename(year)
    tryCatch({
      dat <- fars_read(file)
      dplyr::mutate(dat, year = year) %>%
        dplyr::select(MONTH, year)
    }, error = function(e) {
      warning("invalid year: ", year)
      return(NULL)
    })
  })
}


#' Function "fars_summarize_years" - Summarize data from FARS
#'
#' @description . This function summarizes yearly accidents data, by month. it uses the
#' data frames created by the function fars_read_years. It merges data frames,
#' groups data by year and month and spread data by columns
#'
#' @param years a vector with the list of years
#'
#' @return This function returns a data frame with number of accidents by years
#' summarized by month
#'
#' @importFrom dplyr bind_rows group_by summarize %>%
#' @importFrom tidyr spread
#'
#'
#'
#' @examples
#' \dontrun{
#' fars_summarize_years(2013:2015)}
#'
#' @export


fars_summarize_years <- function(years) {
  dat_list <- fars_read_years(years)
  dplyr::bind_rows(dat_list) %>%
    dplyr::group_by(year, MONTH) %>%
    dplyr::summarize(n = n()) %>%
    tidyr::spread(year, n)
}



#' Function "fars_map_state" - Display accidents map by state and year
#'
#' @description This function displays a plot with a state map including the accidents
#' location by year. The functions make_filename and fars_read contribute to this
#' function. If the state number is invalid the function shows an error message
#' "invalid STATE number: ". If there are no accidents in the speicific
#' state in the specified year the function shows warning message "no accidents to plot".
#'
#' @param state.num an integer with the State Code
#' @param year a string or an integer
#'
#'
#' @importFrom dplyr filter
#' @importFrom maps map
#' @importFrom graphics points

#' @return This function returns a map with the accidents in the speicified state at
#' the specified year. It returns NULL and warning message if no accidents recorded
#' and returns warning message if the state number is invalid.
#'
#'
#' @examples
#' \dontrun{
#' fars_map_state(42, 2013)
#' }
#' @export


fars_map_state <- function(state.num, year) {
  filename <- make_filename(year)
  data <- fars_read(filename)
  state.num <- as.integer(state.num)

  if(!(state.num %in% unique(data$STATE)))
    stop("invalid STATE number: ", state.num)
  data.sub <- dplyr::filter_(data, ~STATE == state.num)
  if(nrow(data.sub) == 0L) {
    message("no accidents to plot")
    return(invisible(NULL))
  }
  is.na(data.sub$LONGITUD) <- data.sub$LONGITUD > 900
  is.na(data.sub$LATITUDE) <- data.sub$LATITUDE > 90
  with(data.sub, {
    maps::map("state", ylim = range(LATITUDE, na.rm = TRUE),
              xlim = range(LONGITUD, na.rm = TRUE))
    graphics::points(LONGITUD, LATITUDE, pch = 46)
  })
}