README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

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

# ndsbr <img src="man/figures/README-ndsbr.png" align="right" width="160" />

<!-- badges: start -->
[![R-CMD-check](https://github.com/pabsantos/ndsbr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/pabsantos/ndsbr/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->

The goal of ndsbr is to help you **load**, **manipulate** and **analyze** the data sample of the [Brazilian Naturalistic Driving Study (NDS-BR)](http://www.tecnologia.ufpr.br/portal/ceppur/estudo-naturalistico-de-direcao-brasileiro/).

## Overview

This package provides four main categories of functions: `nds_create`,  `nds_calc`, `nds_join`, and `nds_download`. `nds_create` functions are used to create spatial objects in sf format, using the naturalistic data as input:

- `nds_create_points`
- `nds_create_lines`

`nds_calc` functions can be used to extract basic information of the naturalistic sample (traveled time or traveled distance) and safety-related variables, such as speeding:

- `nds_calc_dist`
- `nds_calc_time`
- `nds_calc_speeding`

`nds_join` functions performs spatial join operations between ndsbr data and other spatial data, like road axis (`nds_join_axis`), neighborhood data (`nds_join_neigh`), and speed limit data (`nds_join_spdlimit`).

`nds_load_data` is used to load naturalistic data and `nds_download` functions ( `nds_download_sf`, `nds_download_cwb_osm`) can be used to download spatial data and import into the project environment. 

A brief presentation (in portuguese) about `ndsbr` can be [accessed here](https://rpubs.com/pabsantos/stpr_ndsbr).

## Installation

You can install the current version of ndsbr like so:

``` {r install, results = 'hide', eval = FALSE}
# install.packages("devtools")
devtools::install_github("pabsantos/ndsbr")
```

## Example

This is a basic example which shows you how to load NDS-BR data and calculate traveled distances. First, `nds_load_data` loads the sample from all NDS-BR files inside a specific folder, defined by the user. 

```{r load, warning=FALSE, message=FALSE}
library(ndsbr)
path <- system.file("extdata", package = "ndsbr") ## Example files location
nds_data <- nds_load_data("driver", path)

head(nds_data, n = 5)
```

Creating a sf object with linestring geometry using `nds_create_lines`

```{r lines}
nds_lines <- nds_create_lines(nds_data, x = LONG, y = LAT)

plot(nds_lines["DRIVER"])
```

Finally, `nds_calc_dist` extracts traveled distance, grouped by a variable defined by the user.

```{r dist}
nds_dist <- nds_calc_dist(nds_lines, geom = wkt_lines, by = DRIVER)
nds_dist
```