rfars

Download raw data from the Fatality Analysis Reporting System and prepare it for research.

https://github.com/s87jackson/rfars

Keywords

Repository

Download raw data from the Fatality Analysis Reporting System and prepare it for research.

README.Rmd

---
output: github_document
editor_options: 
  markdown: 
    wrap: 80
---



```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "80%", fig.align = "center",
  dpi = 500
)
```

# rfars 



[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version/rfars)](https://cran.r-project.org/package=rfars)
[![R CMD
Check](https://github.com/s87jackson/rfars/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/s87jackson/rfars/actions/workflows/R-CMD-check.yaml)
[![](https://cranlogs.r-pkg.org/badges/grand-total/rfars)](https://CRAN.R-project.org/package=rfars)



The goal of `rfars` is to facilitate transportation safety analysis by
simplifying the process of extracting data from official crash databases. The
[National Highway Traffic Safety Administration](https://www.nhtsa.gov/)
collects and publishes a census of fatal crashes in the [Fatality Analysis
Reporting
System](https://www.nhtsa.gov/research-data/fatality-analysis-reporting-system-fars)
and a sample of fatal and non-fatal crashes in the [Crash Report Sampling
System](https://www.nhtsa.gov/crash-data-systems/crash-report-sampling-system)
(an evolution of the [General Estimates
System](https://www.nhtsa.gov/national-automotive-sampling-system/nass-general-estimates-system)).
The [Fatality and Injury Reporting System Tool](https://cdan.dot.gov/query)
allows users to query these databases, and can produce simple tables and graphs.
This suffices for simple analysis, but often leaves researchers wanting more.
Digging any deeper, however, involves a time-consuming process of downloading
annual ZIP files and attempting to stitch them together - after first combing
through immense data dictionaries to determine the required variables and table
names.

`rfars` allows users to download the last 10 years of FARS and GES/CRSS data
with just one line of code. The result is a full, rich dataset ready for
mapping, modeling, and other downstream analysis. Codebooks with variable
definitions and value labels support an informed analysis of the data (see
`vignette("Searchable Codebooks", package = "rfars")` for more information).
Helper functions are also provided to produce common counts and comparisons.

## Installation

You can install the latest version of `rfars` from [GitHub](https://github.com/)
with:

``` r
# install.packages("devtools")
devtools::install_github("s87jackson/rfars")
```

or the CRAN stable release with:

``` r
install.packages("rfars")
```

Then load rfars and some helpful packages:

```{r, echo=TRUE, warning=FALSE, message=FALSE}
library(rfars)
library(dplyr)
```

## Getting and Using Data

The `get_fars()` and `get_gescrss()` are the primary functions of the `rfars`
package. These functions download and process data files directly from [NHTSA's
FTP Site](https://www.nhtsa.gov/file-downloads?p=nhtsa/downloads/), or pull the
prepared data stored on your local machine. They take the parameters `years` and
`states` (FARS) or `regions` (GES/CRSS). As the source data files follow an
annual structure, `years` determines how many file sets are downloaded or
loaded, and `states`/`regions` filters the resulting dataset. Downloading and
processing these files can take several minutes. Before downloading, `rfars`
will inform you that it's about to download files and asks your permission to do
so. To skip this dialog, set `proceed = TRUE`. You can use the `dir` and `cache`
parameters to save an RDS file to your local machine. The `dir` parameter
specifies the directory, and `cache` names the file (be sure to include the .rds
file extension).

Below we get one year of FARS data:

```{r}
myFARS <- get_fars(years = 2023, proceed = TRUE)
```

We could have saved that file locally with:

```{r, eval=F}
myFARS <- get_fars(years=2023, proceed = TRUE, dir = getwd(), cache = "myFARS.rds")
```

Note that you can assign and save this data with one function call.

We could similarly get one year of CRSS data:

```{r, eval=F}
myCRSS <- get_gescrss(years = 2023, proceed = TRUE)
```

`get_fars()` and `get_gescrss()` return a list with six tibbles: `flat`,
`multi_acc`, `multi_veh`, `multi_per`, `events`, and `codebook`.

Each row in the `flat` tibble corresponds to a person involved in a crash. As
there may be multiple people and/or vehicles involved in one crash, some
variable-values are repeated within a crash or vehicle. Each crash is uniquely
identified with `id`, which is a combination of `year` and `st_case`. Note that
`st_case` is not unique across years, for example, `st_case` 510001 will appear
in each year. The `id` variable attempts to avoid this issue.

```{r}
glimpse(myFARS$flat, width = 100)
```

The `multi_` tibbles contain those variables for which there may be a varying
number of values for any entity (e.g., driver impairments, vehicle events,
weather conditions at time of crash). Each tibble has the requisite data
elements corresponding to the entity: `multi_acc` includes `st_case` and `year`,
`multi_veh` adds `veh_no` (vehicle number), and `multi_per` adds `per_no`
(person number).

The top name-value pairs of each tibble are shown below.

```{r, results='asis'}
myFARS$multi_acc %>% 
  filter(!is.na(value)) %>% 
  group_by(name, value) %>% 
  summarize(n=n(), .groups = "drop") %>% 
  arrange(desc(n)) %>% slice(1:10) %>% 
  select(name, value, n) %>% 
  knitr::kable(format = "html", caption = "Top Name-Value Pairs for the multi_acc Object")
```

```{r, results='asis'}
myFARS$multi_veh %>% 
  filter(!is.na(value)) %>% 
  group_by(name, value) %>% 
  summarize(n=n(), .groups = "drop") %>% 
  arrange(desc(n)) %>% slice(1:10) %>% 
  select(name, value, n) %>% 
  knitr::kable(format = "html", caption = "Top Name-Value Pairs for the multi_veh Object")
```

```{r, results='asis'}
myFARS$multi_per %>% 
  filter(!is.na(value)) %>% 
  group_by(name, value) %>% 
  summarize(n=n(), .groups = "drop") %>% 
  arrange(desc(n)) %>% slice(1:10) %>% 
  select(name, value, n) %>% 
  knitr::kable(format = "html", caption = "Top Name-Value Pairs for the multi_per Object")
```

The `events` tibble provides a sequence of numbered events for each vehicle in
each crash. See the vignette("Crash Sequence of Events", package = "rfars") for
more information.

```{r, results='asis'}
head(myFARS$events, 10) %>% 
  knitr::kable(format="html", caption = "Preview of events Object")
```

The `codebook` tibble provides a searchable codebook for the data, useful if you
know what concept you're looking for but not the variable that describes it.
`rfars` also includes pre-loaded codebooks for FARS and GESCRSS
(`rfars::fars_codebook` and `rfars::gescrss_codebook`). These tables span
2014-2023 whereas the `codebook` object returned from `get_fars()` and
`get_gescrss()` only include the specified `years`. See
`vignette('Searchable Codebooks', package = 'rfars')` for more information.

## Counts

See `vignette("Counts", package = "rfars")` for information on the pre-loaded
`annual_counts` dataframe and the `counts()` function. Also see
`vignette("Alcohol Counts", package = "rfars")` for details on how BAC values
are imputed and reported in *Traffic Safety Facts*.

## Helpful Links

-   [National Highway Traffic Safety Administration
    (NHTSA)](https://www.nhtsa.gov/)
-   [Fatality Analysis Reporting System
    (FARS)](https://www.nhtsa.gov/research-data/fatality-analysis-reporting-system-fars)
-   [Fatality and Injury Reporting System Tool
    (FIRST)](https://cdan.dot.gov/query)
-   [FARS Analytical User's
    Manual](https://crashstats.nhtsa.dot.gov/Api/Public/ViewPublication/813706)
-   [General Estimates System
    (GES)](https://www.nhtsa.gov/national-automotive-sampling-system/nass-general-estimates-system)
-   [Crash Report Sampling System
    (CRSS)](https://www.nhtsa.gov/crash-data-systems/crash-report-sampling-system)
-   [CRSS Analytical User's
    Manual](https://crashstats.nhtsa.dot.gov/Api/Public/ViewPublication/813707)
-   [NCSA and Other Data
    Sources](https://cdan.dot.gov/Homepage/MotorVehicleCrashDataOverview.htm)
-   [NHTSA FTP Site](https://www.nhtsa.gov/file-downloads?p=nhtsa/downloads/)

```{r, include=FALSE}
unlink(paste0(getwd(),"/FARS data"), recursive = TRUE)
```

Owner

GitHub Events

Committers

Last synced: over 2 years ago

Issues and Pull Requests

Last synced: 11 months ago

Packages