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%"
)
```
# I Know How You Drive (ikhyd)

<!-- badges: start -->
[![Build Status](https://travis-ci.com/issactoast/ikhyd.svg?branch=master)](https://travis-ci.com/issactoast/ikhyd)
<!-- badges: end -->

R package `ikhyd` is designed to make the driving behavior analysis using telematics data easier.

# Prerequisite

## Package installation and loading

To reproduce the research result, the \textbf{R package}  `ikhyd` should be installed from github page, \url{www.github.com/issactoast}, using the following \textbf{R} code:

```{r eval=FALSE}
# packages loading
devtools::install_github("issactoast/ikhyd")
```

After the installation, load package as follows:

```{r}
library(ikhyd)
```

## Google API

To use the visualization functions, the google map aip key should be fed into the function as an argument. Google API can be obtained [the Google Maps Platform](https://cloud.google.com/maps-platform) by following the registration [instruction](https://developers.google.com/maps/documentation/geocoding/get-api-key). The google map API service will charge $2 per 1000 requests however, [\$200 deposite will be added to the account per month](https://cloud.google.com/maps-platform/pricing).  Thus, the personal usage is technically free but **you need to register the credit card to use the service**.

```{r echo=FALSE}
your_google_api <- keyring::key_get("GOOGLEMAP_API")
```

For example, `track_vis()` has the following structure:

```{r eval=FALSE}
track_vis(sample_trip$gps_data,
          api = your_google_api,
          zoom = 1)
```


## How to access to data set

`ikhyd` package contains seven telematics files;

1. Sample route telematics: sample_trip.csv
1. Test route with OBD information:
    - trip_with_obd.csv
    - trip_with_obd.txt
1. Driving telematics files:
    - driver1.csv
    - driver2.csv
    - driver3.csv
    - driver4.csv
    
Note that `trip_with_obd.txt` contains the OBD speed information which combines with telematics data generated by smartphone, `trip_with_obd.csv`.

To get the path of the each files, users can use `system.file()` in **R**. For example, the follow code will give you the path of `sample_trip.csv`;

```{r}
system.file("extdata", "sample_trip.csv", package = "ikhyd")
```

## See help and actual code

You can check out the actual code in this instruction by typing the name of the **R** console. For example, examination the code of `load_telematic_data()` will be as follows:

```{r}
load_telematic_data
```
Also, the help page of each function is available via `?function_name()`.

```{r eval=FALSE}
?load_telematic_data()
```

## Load trip data

When you have a path of telematics data, you can load the data using `get_trip()` with `data_option` arguments as follows:

```{r}
# telematics file path
sample_trip_path <- system.file("extdata", "sample_trip.csv", package = "ikhyd")

# load data
sample_trip <- load_telematic_data(sample_trip_path, all_in_one = TRUE)
summary(sample_trip)
```

# Visualization

## GPS data

The snippet of `gps_data` for the sample trip looks as follows:

```{r}
head(sample_trip$gps_data)
```

The GPS coordinates of the sample trip can be visualized with `track_vis()` in `ikhyd` package as in the following Figure:

```{r trackvis, message=FALSE, fig.cap = "Visulization of the GPS data of the sample trip by `track_vis()`"}
track_vis(sample_trip$gps_data,
          api = your_google_api,
          zoom = 1)
```

The following figure shows the  Speed information from GPS sensor stored in `speed_data`, which can be visualized with `plot_speed()` as follows:

```{r gpsspeed, fig.cap="The result of `plot_speed()` code. It also supports many base plot arguments such as `xlim` in **R**"}
plot_speed(sample_trip$speed_data, tripname = "the sample trip")
```

## Accelerometer data

For accelerometer information, you can plot it by using `plot_acc()` function with an option of smoothing parameter `rate`. Also note that some base plot options such as `xlim` can be used.

The figure below is generated by the following code.

```{r plotacc, fig.cap="The result of `plot_acc()` code. `rate` is the smoothing parameter of low pass filter whose range between 0 to 1."}
plot_acc(sample_trip$acc_data,
         rate = 0.2, 
         tripname = "the sample trip")
```

# Calibration

Kalman filtering and smoothing operation of the sample trip can be reproduced by the following functions: `kalmanfilter_telematics()` and `kalmansmooth_telematics()`.

The visualization of the Kalman filtered and smoothed telematics data can be done by the `plot_telematics()` function in the package.

```{r}
# telematics file for longer trips
obdtrip_path <- system.file("extdata", "trip_with_obd.csv", package = "ikhyd")
obdtrip_path_obd <- system.file("extdata", "trip_with_obd.txt", package = "ikhyd")
```

## Kalman filter

```{r}
kalmanfilter_result <- kalmanfilter_telematics(obdtrip_path)
head(kalmanfilter_result)
```


```{r fig.cap="Visualization of the Kalman filtering based calibration"}
plot_telematics(kalmanfilter_result)
```

## Kalman smoothing

```{r}
kalmansmooth_result <- kalmansmooth_telematics(obdtrip_path)
head(kalmansmooth_result)
```


```{r fig.cap="Visualization of the Kalman smoothing based calibration"}
plot_telematics(kalmansmooth_result)
```

# Comparison with OBD data

```{r warning=FALSE, message=FALSE}
# load OBD trip data for the comparison 
obd_trip <- load_telematic_data(obdtrip_path, 
                                all_in_one = TRUE)

# load obd information and calculate acceleration
speed_data_obd <- get_obd_trip(obdtrip_path_obd)
speed_data_obd <- acc_from_obd(speed_data_obd)
```

Root Mean Square Error (RMSE) of accelerometer (y-axis), Kalman filtered accelerations, and Kalman smoothed accelerations for the given trip are calculated as follows:

```{r result = 'asis'}
rmse <- function(x, y){
    sqrt(sum((x - y)^2))
}

RMSEresult <- data.frame(
    Methods = "RMSE",
    Accelerometer = rmse(obd_trip$acc_data$y, speed_data_obd$dv_dt),
    KalmanFilter = rmse(kalmanfilter_result$a_lon, speed_data_obd$dv_dt),
    KalmanSmooth = rmse(kalmansmooth_result$a_lon, speed_data_obd$dv_dt)
)
knitr::kable(RMSEresult)
```


## OBD based speed and accelaration


### Speed comparison: OBD vs. GPS

```{r fig.cap="Comparion of Speed: GPS(red) vs. OBD(black)"}
obd_trip$speed_data$obd_speed <- speed_data_obd$speed
plot_speed(obd_trip$speed_data, col = "red",
           tripname = "OBD trip")
```

### Acceleration comparison: Accelerometer vs. OBD

```{r fig.cap="Comparion of Acceleration: Accelerometer(red) vs. OBD(black)"}
plot_data <- data.frame(time = obd_trip$acc_data$time,
                        acc1 = obd_trip$acc_data$y,
                        acc2 = speed_data_obd$dv_dt)
plot_acc_compare(plot_data, 
                 sensor_name = c("Y-axis accelerometer(red)", "OBD(black)"),
                 xlim = c(0, 400))
```

### Acceleration comparison: Kalman filtering vs. OBD

```{r fig.cap="Comparion of Acceleration: Kalman filter base(red) vs. OBD(black)"}
plot_data$acc1 <- kalmanfilter_result$a_lon
plot_acc_compare(plot_data, 
                 sensor_name = c("Kalman filtering(red)", "OBD(black)"),
                 xlim = c(0, 400))
```

### Acceleration comparison: Kalman smoothing vs. OBD

```{r fig.cap="Comparion of Acceleration: Kalman smooth base(red) vs. OBD(black)"}
plot_data$acc1 <- kalmansmooth_result$a_lon
plot_acc_compare(plot_data, 
                 sensor_name = c("Kalman smooth(red)", "OBD(black)"),
                 xlim = c(0, 400))

```


# Heatmap visualization

Here is some example of visualization of telematics data; v-a heatmap suggested by Wuthrich (2017) and [Lee and Shyamal (2019)](https://www.researchgate.net/publication/334749450_I_KNOW_HOW_YOU_DRIVE_DRIVING_STYLE_PROFILE_VIA_SMARTPHONE) the Lon-Lat plot suggested by The following code generates the v-a heatmap of the telematics data 

```{r}
# telematics file for driver 1 and 2
driver1_path <- system.file("extdata", "driver1.csv", package = "ikhyd")
driver2_path <- system.file("extdata", "driver2.csv", package = "ikhyd")

telematics_driver1 <- kalmansmooth_telematics(driver1_path)
telematics_driver2 <- kalmansmooth_telematics(driver2_path)
```


## Heatmap (V-A)

```{r message=FALSE, fig.show="hold", out.width="50%", fig.cap="Reproduce V-A heatmap result for 2 drivers", fig.subcap=c("Driver 1", "Driver 2")}
draw_vaHeatmap(telematics_driver1)
draw_vaHeatmap(telematics_driver2)
```

## Heatmap (Lon-Lat)

```{r fig.show="hold", out.width="50%", fig.cap="Reproduce Lon-Lat plot result for drivers; 1 and 2", fig.subcap=c("Driver 1", "Driver 2")}
par(mar = c(4, 4, .1, .1))
drawHeatmap(telematics_driver1)
drawHeatmap(telematics_driver2)
```

## License

Provided under the terms of the [MIT License](https://github.com/posquit0/hugo-awesome-identity/blob/master/LICENSE).

Copyright © 2019-2020, Issac Lee.