1. Introduction

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⁵, a really fast and open source Java-based routing engine developed separately by Conveyal. R⁵ stands for Rapid Realistic Routing on Real-world and Reimagined networks. More details about r5r can be found on the package webpage or on this paper.

2. Installation

You can install r5r from CRAN, or the development version from github.

# CRAN
install.packages('r5r')

# dev version on github
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, and you only need to install one JDK. Here are a few options:

• Adoptium/Eclipse Temurin (our preferred option)
• Amazon Corretto
• Oracle OpenJDK.

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")

3. Usage

Before we start, we need to increase the memory available to Java. This is necessary because, by default, R allocates only 512MB of memory for Java processes, which is not enough for large queries using r5r. To increase available memory to 2GB, for example, we need to set the java.parameters option at the beginning of the script, as follows:

options(java.parameters = "-Xmx2G")

Note: It’s very important to allocate enough memory before loading r5r or any other Java-based package, since rJava starts a Java Virtual Machine only once for each R session. It might be useful to restart your R session and execute the code above right after, if you notice that you haven’t succeeded in your previous attempts.

Then we can load the packages used in this vignette:

library(r5r)
library(sf)
library(data.table)
library(ggplot2)

The r5r package has seven fundamental functions:

1. setup_r5() to initialize an instance of r5r, that also builds a routable transport network;

2. accessibility() for fast computation of access to opportunities considering a selected decay function;

3. travel_time_matrix() for fast computation of travel time estimates between origin/destination pairs;

4. expanded_travel_time_matrix() for calculating travel 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() to get detailed information on one or multiple alternative routes between origin/destination pairs.

6. pareto_frontier() for analyzing the trade-off between the travel time and monetary costs of multiple route alternatives between origin/destination pairs.

7. isochrone() to estimate the polygons of the areas that can be reached from an origin point at different travel time limits.

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.

The package also includes a few support functions.

1. street_network_to_sf() to extract OpenStreetMap network in sf format from a network.dat file.

2. transit_network_to_sf() to extract transit network in sf format from a network.dat file.

3. find_snap() to find snapped locations of input points on street network.

4. r5r_sitrep() to generate a situation report to help debug eventual errors.

4. Demonstration on sample data

data_path <- system.file("extdata/poa", package = "r5r")
list.files(data_path)

poi <- fread(file.path(data_path, "poa_points_of_interest.csv"))
head(poi)

points <- fread(file.path(data_path, "poa_hexgrid.csv"))

# sample points
sampled_rows <-  sample(1:nrow(points), 200, replace=TRUE)
points <- points[ sampled_rows, ]
head(points)

# Indicate the path where OSM and GTFS data are stored
r5r_core <- setup_r5(data_path = data_path)

# set departure datetime input
departure_datetime <- as.POSIXct("13-05-2019 14:00:00",
                                 format = "%d-%m-%Y %H:%M:%S")

# calculate accessibility
access <- accessibility(r5r_core = r5r_core,
                        origins = points,
                        destinations = points,
                        opportunities_colnames = c("schools", "healthcare"),
                        mode = c("WALK", "TRANSIT"),
                        departure_datetime = departure_datetime,
                        decay_function = "step",
                        cutoffs = 60
                        )
head(access)

# set inputs
mode <- c("WALK", "TRANSIT")
max_walk_time <- 30 # minutes
max_trip_duration <- 120 # minutes
departure_datetime <- as.POSIXct("13-05-2019 14:00:00",
                                 format = "%d-%m-%Y %H:%M:%S")

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

head(ttm)

# calculate a travel time matrix
ettm <- expanded_travel_time_matrix(r5r_core = r5r_core,
                          origins = poi,
                          destinations = poi,
                          mode = mode,
                          departure_datetime = departure_datetime,
                          breakdown = TRUE,
                          max_walk_time = max_walk_time,
                          max_trip_duration = max_trip_duration)

head(ettm)

# set inputs
origins <- poi[10,]
destinations <- poi[12,]
mode <- c("WALK", "TRANSIT")
max_walk_time <- 60 # minutes
departure_datetime <- as.POSIXct("13-05-2019 14:00:00",
                                 format = "%d-%m-%Y %H:%M:%S")

# calculate detailed itineraries
det <- detailed_itineraries(r5r_core = r5r_core,
                            origins = origins,
                            destinations = destinations,
                            mode = mode,
                            departure_datetime = departure_datetime,
                            max_walk_time = max_walk_time,
                            shortest_path = FALSE)

head(det)

# extract OSM network
street_net <- street_network_to_sf(r5r_core)

# extract public transport network
transit_net <- r5r::transit_network_to_sf(r5r_core)

# plot
ggplot() +
  geom_sf(data = street_net$edges, color='gray85') +
  geom_sf(data = det, aes(color=mode)) +
  facet_wrap(.~option) + 
  theme_void()

r5r::stop_r5(r5r_core)
rJava::.jgc(R.gc = TRUE)