Home

Awesome

r5r: Rapid Realistic Routing with R5 in R <img align="right" src="r-package/man/figures/r5r_blue.png" alt="logo" width="180">

CRAN/METACRAN Version CRAN/METACRAN Total downloads R build status Codecov test coverage Lifecycle: maturing Publication

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<sup>5</sup>, 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<sup>5</sup> 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<sup>5</sup>.

This repository contains the R code (r-package folder) and the Java code (java-api folder) that provides the interface to R<sup>5</sup>.

Installation

You can install r5r:

# from CRAN
install.packages("r5r")

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

Please bear in mind that you need to have Java Development Kit (JDK) 21 installed on your computer to use r5r. No worries, you don't have to pay for it. There are numerous open-source JDK implementations, any of which should work with r5r. If you don't already have a preferred JDK, we recommend Adoptium/Eclipse Temurin. Other open-source JDK implementations include Amazon Corretto, and Oracle OpenJDK. You only need to install one JDK.

The easiest way to install JDK is using the new {rJavaEnv} package in R:

# install.packages('rJavaEnv')

# check version of Java currently installed (if any) 
rJavaEnv::java_check_version_rjava()

# install Java 21
rJavaEnv::java_quick_install(version = 21)

Usage

The package has seven fundamental functions:

  1. setup_r5()

    • Downloads and stores locally an R5 Jar file (the Jar file is downloaded only once per installation)
    • Builds a multimodal transport network given (1) a OpenStreetMap 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).

  2. 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.

  3. travel_time_matrix()

    • Fast function that returns a simple data.table with travel time estimates between one or multiple origin destination pairs.

  4. expanded_travel_time_matrix()

    • Calculates travel time matrices between origin destination pairs with additional information such as routes used and total time disaggregated by access, waiting, in-vehicle and transfer times.

  5. 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 segment.

  6. pareto_frontier()

    • Returns a data.table with the travel time and monetary cost of multiple route alternatives for specified origin-destination pairs.

  7. isochrone()

    • Returns a A ⁠POLYGON "sf" "data.frame" showing the area that can be reached from an origin point at a given travel time limit.

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

The package also includes a few support functions.

  1. street_network_to_sf()

    • Extract OpenStreetMap network in sf format from a network.dat file.

  2. transit_network_to_sf()

    • Extract transit network in sf format from a network.dat file.

  3. find_snap()

    • Find snapped locations of input points on street network.

  4. r5r_sitrep()

    • Generate a situation report to help debug eventual errors.

Data requirements:

To use r5r, you will need:

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

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 **before** loading the {r5r} library
options(java.parameters = "-Xmx2G")

library(r5r)

# 1) build transport network, pointing to the path where OSM and GTFS data are stored
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 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.

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<sup>5</sup>, one of the fastest and most robust routing engines available.

For Python users, you might want to check our sister package: r5py!

Acknowledgement

The R<sup>5</sup> routing engine is developed at Conveyal with contributions from several people.

Citation <img align="right" src="r-package/man/figures/ipea_logo.png" alt="ipea" width="300">

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:

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},
	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}
}

Please also cite the relevant publications relating to the R⁵ engine on which r5r builds up: