r5r: Rapid Realistic Routing with R5 in R

r5r is an R package for rapid realistic routing on multimodal transport networks (walk, bike, public transport and car). It provides a simple and friendly interface to R⁵, the Rapid Realistic Routing on Real-world and Reimagined networks, the routing engine developed independently by Conveyal.

r5r is a simple way to run R⁵ locally, allowing R users to generate detailed routing analysis or calculate travel time matrices and accessibility using seamless parallel computing. See a detailed demonstration of r5r in the intro Vignette. More details about r5r can be found on the package webpage or on this paper. Over time, r5r might be expanded to incorporate other functionality from R⁵

This repository contains the R code (r-package folder) and the Java code (java-api folder) that provides the interface to R⁵.

Installation

You can install r5r:

# From CRAN
  install.packages("r5r")
  library(r5r)

# or use the development version with latest features
  utils::remove.packages('r5r')
  devtools::install_github("ipeaGIT/r5r", subdir = "r-package")
  library(r5r)

Please bear in mind that you need to have Java SE Development Kit 11 installed on your computer to use r5r. No worries, you don't have to pay for it. The jdk 11 is freely available from the options below:

If you don't know what version of Java you have installed on your computer, you can check it by running this on R console.

rJava::.jinit()
rJava::.jcall("java.lang.System", "S", "getProperty", "java.version")

Usage

The package has five fundamental functions.

setup_r5()
- Downloads and stores locally an R5 Jar file (Jar file is downloaded only once per installation)
- Builds a multimodal transport network given (1) a street network in .pbf format (mandatory), (2) one or more public transport networks in GTFS.zip format (optional), and (3) elevation data in raster.tif (optional).
accessibility()
- Fast computation of access to opportunities. The function returns a data.table with accessibility estimates for all origin points by transport mode given a selected decay function. Multiple decay functions are available, including step (cumulative opportunities), logistic, fixed exponential and linear.
travel_time_matrix()
- Fast function that returns a simple data.table with travel time estimates between one or multiple origin destination pairs.
expanded_travel_time_matrix()
- Calculates travel time matrices between origin destination pairs with additional information such routes used and total time disaggregated by access, waiting, in-vehicle and transfer times
detailed_itineraries()
- Returns a data.frame sf LINESTRINGs with one or multiple alternative routes between one or multiple origin destination pairs. The data output brings detailed information on transport mode, travel time, walk distance etc for each trip section

obs. Most of these functions also allow users to account for monetary travel costs when generating travel time matrices and accessibility estimates. More info about how to consider monetary costs can be found in this vignette.

Data requirements:

To use r5r, you will need:

A road network data set from OpenStreetMap in .pbf format (mandatory)
A public transport feed in GTFS.zip format (optional)
A raster file of Digital Elevation Model data in .tif format (optional)

Here are a few places from where you can download these data sets:

OpenStreetMap
- osmextract R package
- geofabrik website
- hot export tool website
- BBBike.org website
GTFS
- tidytransit R package
- transitland website
Elevation
- elevatr R package
- Nasa's SRTMGL1 website

Demonstration on sample data

See a detailed demonstration of r5r in this intro Vignette. To illustrate functionality, the package includes a small sample data set of the public transport and Open Street Map networks of Porto Alegre (Brazil). Three steps are required to use r5r, as follows.

# allocate RAM memory to Java
options(java.parameters = "-Xmx2G")

# 1) build transport network, pointing to the path where OSM and GTFS data are stored
library(r5r)
path <- system.file("extdata/poa", package = "r5r")
r5r_core <- setup_r5(data_path = path, verbose = FALSE)

# 2) load origin/destination points and set arguments
points <- read.csv(system.file("extdata/poa/poa_hexgrid.csv", package = "r5r"))
mode <- c("WALK", "TRANSIT")
max_walk_time <- 30   # minutes
max_trip_duration <- 60 # minutes
departure_datetime <- as.POSIXct("13-05-2019 14:00:00",
                                 format = "%d-%m-%Y %H:%M:%S")

# 3.1) calculate a travel time matrix
ttm <- travel_time_matrix(r5r_core = r5r_core,
                          origins = points,
                          destinations = points,
                          mode = mode,
                          departure_datetime = departure_datetime,
                          max_walk_time = max_walk_time,
                          max_trip_duration = max_trip_duration)

# 3.2) or get detailed info on multiple alternative routes
det <- detailed_itineraries(r5r_core = r5r_core,
                            origins = points[370, ],
                            destinations = points[200, ],
                            mode = mode,
                            departure_datetime = departure_datetime,
                            max_walk_time = max_walk_time,
                            max_trip_duration = max_trip_duration,
                            shortest_path = FALSE,
                            drop_geometry = FALSE)

# 4) Calculate number of schools accessible within 20 minutes 
access <- accessibility(r5r_core = r5r_core,
                        origins = points,
                        destinations = points,
                        opportunities_colname = "schools",
                        decay_function = "step",
                        cutoffs = 21,
                        mode =  c("WALK", "TRANSIT"),
                        verbose = FALSE)

Related R packages

There is a growing number of R packages with functionalities for transport routing, analysis and planning more broadly. Here are few of theses packages.

dodgr: Distances on Directed Graphs in R
gtfsrouter: R package for routing with GTFS data
hereR: an R interface to the HERE REST APIs
opentripplanner: OpenTripPlanner for R
stplanr: sustainable transport planning with R

The r5r package is particularly focused on fast multimodal transport routing and accessibility. A key advantage of r5r is that is provides a simple and friendly R interface to R⁵, one of the fastest and most robust routing engines available.

Acknowledgement

The R⁵ routing engine is developed at Conveyal with contributions from several people.

Citation

The R package r5r is developed by a team at the Institute for Applied Economic Research (Ipea), Brazil. If you use this package in research publications, we please cite it as:

Pereira, R. H. M., Saraiva, M., Herszenhut, D., Braga, C. K. V., & Conway, M. W. (2021). r5r: Rapid Realistic Routing on Multimodal Transport Networks with R5 in R. Findings, 21262. https://doi.org/10.32866/001c.21262

BibTeX:

@article{pereira_r5r_2021,
	title = {r5r: Rapid Realistic Routing on Multimodal Transport Networks with {R}$^{\textrm{5}}$ in R},
	shorttitle = {r5r},
	url = {https://findingspress.org/article/21262-r5r-rapid-realistic-routing-on-multimodal-transport-networks-with-r-5-in-r},
	doi = {10.32866/001c.21262},
	abstract = {Routing is a key step in transport planning and research. Nonetheless, researchers and practitioners often face challenges when performing this task due to long computation times and the cost of licensed software. R{\textasciicircum}5{\textasciicircum} is a multimodal transport network router that offers multiple routing features, such as calculating travel times over a time window and returning multiple itineraries for origin/destination pairs. This paper describes r5r, an open-source R package that leverages R{\textasciicircum}5{\textasciicircum} to efficiently compute travel time matrices and generate detailed itineraries between sets of origins and destinations at no expense using seamless parallel computing.},
	language = {en},
	urldate = {2021-03-04},
	journal = {Findings},
	author = {Pereira, Rafael H. M. and Saraiva, Marcus and Herszenhut, Daniel and Braga, Carlos Kaue Vieira and Conway, Matthew Wigginton},
	month = mar,
	year = {2021},
	note = {Publisher: Network Design Lab}
}

JeremyGelb/r5r