R/fars_function.R

In mykoCheng/farsManipulate: Manipulates FARS data

#' @title Read CSV Files
#' @description This function reads in a csv file and returns as 'tbl_df' format. Stops and throws an error if inputed file name does not exist in the working directory.
#' @param filename Takes csv file's name desired to be read
#' @examples
#' \dontrun{fars_read("accident_2013.csv.bz2")}
#' @return  A tibble of the FARS data
#' @importFrom readr read_csv
#' @importFrom  dplyr tbl_df
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)
}

#' @title Making File Name for FARS CSV File
#' @description A function that generates a file name for the desired year of FARS data
#' @param year Year of the FARS data ranging from 2013 to 2015
#' @examples
#' \dontrun{make_filename(2015)}
#' @return a character vector of file name for the desired name of FARS data
make_filename <- function(year) {
  year <- as.integer(year)
  sprintf("accident_%d.csv.bz2", year)
}

#' @title Reading Specified Years of FARS Datasets
#' @description Returns a list of dataframes each with two variables: the MONTH and year of which accidents occured. It will return an error if the entered year is invalid, or the workspace location does not contain the file.
#' @param years Years of the FARS data ranging from 2013 to 2015
#' @examples
#' \dontrun{fars_read_years(c(2013,2014,2015))}
#' @return  a list of tibbles of the years inputed
#' @importFrom dplyr mutate select
#' @importFrom magrittr %>%
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)
    })
  })
}

#' @title Summarizing the Each Year's Monthly Fatalities
#' @description Returns each year's monthly fatalities.
#' @param years Years of the FARS data ranging from 2013 to 2015
#' @examples
#' \dontrun{fars_summarize_years(c(2013:2015))}
#' @return A tibble of monthly fatalities of each year.
#' @importFrom dplyr bind_rows group_by summarize
#' @importFrom tidyr spread
#' @importFrom magrittr %>%
#' @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)
}

#' @title Graphing Accident Distribution of a State
#' @description Graphs a distribution of the number of accidents in a designated state and year by dots on the state's map. Throws an error if the given state number is invalid, and does not graph (returns NULL) if there is no accident in the data to plot.
#' @param state.num The state number given by FARS guide.
#' @param year The year the user desires to aquire
#' @examples
#' \dontrun{fars_map_state(1,2013)}
#' @return A map of the state with dots on it representing the number of accidents given the year.
#' @importFrom dplyr filter
#' @importFrom maps map
#' @importFrom graphics points
#' @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)
  })
}