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%",
  warning = NA
)
```

# traveltime

<!-- badges: start -->
[![traveltime status badge](https://idem-lab.r-universe.dev/badges/traveltime)](https://idem-lab.r-universe.dev/traveltime)
[![R-CMD-check](https://github.com/idem-lab/traveltime/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/idem-lab/traveltime/actions/workflows/R-CMD-check.yaml)
![GitHub License](https://img.shields.io/github/license/geryan/traveltime)
[![Lifecycle:](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
![GitHub commit activity](https://img.shields.io/github/commit-activity/w/geryan/traveltime)
![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/geryan/traveltime/total)
![GitHub last commit](https://img.shields.io/github/last-commit/geryan/traveltime)
![GitHub commits since latest release](https://img.shields.io/github/commits-since/geryan/traveltime/latest)
[![Codecov test coverage](https://codecov.io/gh/idem-lab/traveltime/graph/badge.svg)](https://app.codecov.io/gh/idem-lab/traveltime)
<!-- badges: end -->

Implements methods from Weiss et al. 2018, 2020 to calculate travel time from
given locations over a friction surface.

Citations:

*D. J. Weiss, A. Nelson, C. A. Vargas-Ruiz, K. Gligoric, S., Bavadekar, E.
Gabrilovich, A. Bertozzi-Villa, J. Rozier, H. S. Gibson, T., Shekel, C. Kamath,
A. Lieber, K. Schulman, Y. Shao, V. Qarkaxhija, A. K. Nandi, S. H. Keddie, S.
Rumisha, P. Amratia, R. Arambepola, E. G. Chestnutt, J. J. Millar, T. L. Symons,
E. Cameron, K. E. Battle, S. Bhatt, and P. W. Gething.* **Global maps of travel
time to healthcare facilities.** (2020) Nature Medicine.
<https://doi.org/10.1038/s41591-020-1059-1>

*D. J. Weiss, A. Nelson, H.S. Gibson, W. Temperley, S. Peedell, A. Lieber, M.
Hancher, E. Poyart, S. Belchior, N. Fullman, B. Mappin, U. Dalrymple, J. Rozier,
T.C.D. Lucas, R.E. Howes, L.S. Tusting, S.Y. Kang, E. Cameron, D. Bisanzio, K.E.
Battle, S. Bhatt, and P.W. Gething.* **A global map of travel time to cities to
assess inequalities in accessibility in 2015.** (2018). Nature.
<https://doi.org/10.1038/nature25181>

## Installation

You can install `traveltime` with:

``` r
install.packages("traveltime", repos = c("https://idem-lab.r-universe.dev"))
```

## Let's calculate some travel times

First download a friction surface --— here we are using the motorised travel
time from Weiss *et al.* 2020. We use the function
`traveltime::get_friction_surface`, specify the surface (type) as `"motor2020"`,
 and provide the spatial extent of interest:
```{r }
library(traveltime)
library(terra)

friction_surface <- get_friction_surface(
    surface = "motor2020",
    extent = c(111,112,0,1)
  )
friction_surface
```

Let's have a look at that `SpatRaster`:
```{r}
plot(friction_surface)
```

Now, prepare points that we would like to calculate travel time from:
```{r}
from_here <- tibble::tibble(
  x = c(111.2, 111.9),
  y = c(0.2, 0.35)
)
from_here
```

And calculate the travel time from our points `from_here` over the friction 
surface `friction_surface` using the function
`traveltime::calculate_travel_time`:
```{r}
travel_time <- calculate_travel_time(
  friction_surface = friction_surface,
  points = from_here
)
travel_time
```

Et voila! Here is the motorised travel time in minutes for each cell, with our
points in pink.
```{r}
plot(travel_time)
points(from_here, pch = 19, col = "hotpink")
```

## A more tangible example: Walking in Singapore

Let's create a map of the walking time across the island of Singapore from the 
nearest
[MRT or LRT](https://en.wikipedia.org/wiki/Transport_in_Singapore#Rail_transport)
station.

To do this, we need:

- a map of Singapore
- locations of the stations

Here's our basemap via `geodata`:

```{r}
#install.packages("geodata")
library(geodata)
sin <- gadm(
  country = "Singapore",
  level = 0,
  path = tempdir(),
  resolution = 2
)
plot(sin)
```

We're going to see how long it takes to walk home from a station, so we'll
download the walking-only friction surface this time by specifying 
`surface = "walk2020`. 

We can also pass in our basemap `sin`, a `SpatVector`, directly as the `extent`,
instead of specifying by hand as above. We're also only interested in walking 
*on land* so we mask out areas outside of `sin`, that are within the extent of 
the raster:

```{r }
library(traveltime)
library(terra)

friction_singapore <- get_friction_surface(
    surface = "walk2020",
    extent = sin
  )|> 
  mask(sin)

friction_singapore
```

The the `stations` data set in this package contains the longitude and latitude
of all LRT and MRT station exits in Singapore[^1].

```{r}
head(stations)
```

Let's look at our data now.

Below we plot the friction surface raster `friction_singapore`, with the vector
boundary of `sin` as a dashed grey line, and `stations` as grey points:

```{r}
library(tidyterra)
library(ggplot2)

ggplot() +
  geom_spatraster(
    data = friction_singapore
  ) +
  geom_spatvector(
    data = sin,
    fill = "transparent",
    col = "grey50",
    lty = 2
  ) +
  geom_point(
    data = stations,
    aes(
      x = x,
      y = y
    ),
    col = "grey60",
    size = 0.5
  ) +
  scale_fill_viridis_c(
    option = "A",
    na.value = "transparent",
    direction = -1
  ) +
  labs(
    fill = "Friction"
  )


```

OK, now we want to calculate the walking travel time in minutes across the 
friction surface from the nearest station exit:

```{r}
travel_time_sin <- calculate_travel_time(
  friction_surface = friction_singapore,
  points = stations
)
travel_time_sin
```

Et voi*lah* --- a raster of walking time from the nearest station.
```{r}
contour(
  x = travel_time_sin,
  filled = TRUE,
  nlevels = 20,
  col = viridis::magma(19, direction = -1)
)
```

[^1]: Land Transport Authority. (2019). LTA MRT Station Exit (GEOJSON) (2024)
[Dataset]. data.gov.sg. Retrieved December 10, 2024 from
https://data.gov.sg/datasets/d_b39d3a0871985372d7e1637193335da5/view