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 R5, a really fast and open source Java-based routing engine developed separately by Conveyal. R5 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.
You can install {r5r}
from CRAN, or the development
version from github.
# from CRAN
install.packages('r5r')
# dev version with latest features
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:
The easiest way to install JDK is using the new {rJavaEnv} package in R:
# install {rJavaEnv} from CRAN
install.packages("rJavaEnv")
# check version of Java currently installed (if any)
rJavaEnv::java_check_version_rjava()
## if this is the first time you use {rJavaEnv}, you might need to run this code
## below to consent the installation of Java.
# rJavaEnv::rje_consent(provided = TRUE)
# install Java 21
rJavaEnv::java_quick_install(version = 21)
# check if Java was successfully installed
rJavaEnv::java_check_version_rjava()
First, we need to increase the memory available to Java. This has to
be done before loading the {r5r}
library
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")
# By default, {r5r} uses all CPU cores available. If you want to limit the
# number of CPUs to 4, for example, you can run:
options(java.parameters = c("-Xmx2G", "-XX:ActiveProcessorCount=4"))
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:
The {r5r}
package has seven fundamental
functions:
setup_r5()
to initialize an instance of
{r5r}
, that also builds a routable transport
network;
accessibility()
for fast computation of access to
opportunities considering a selected decay function;
travel_time_matrix()
for fast computation of travel
time estimates between origin/destination pairs;
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.
detailed_itineraries()
to get detailed information
on one or multiple alternative routes between origin/destination
pairs.
pareto_frontier()
for analyzing the trade-off
between the travel time and monetary costs of multiple route
alternatives between origin/destination pairs.
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.
street_network_to_sf()
to extract OpenStreetMap
network in sf format from a network.dat
file.
transit_network_to_sf()
to extract transit network
in sf format from a network.dat
file.
find_snap()
to find snapped locations of input
points on street network.
r5r_sitrep()
to generate a situation report to help
debug eventual errors.
To use {r5r}
, you will need:
.pbf
format (mandatory)GTFS.zip
format
(optional).tif
format (optional)Here are a few places from where you can download these data sets:
Let’s have a quick look at how {r5r}
works using a
sample data set.
To illustrate the functionalities of {r5r}
, the package
includes a small sample data for the city of Porto Alegre (Brazil). It
includes seven files:
poa_osm.pbf
poa_eptc.zip
and
poa_trensurb.zip
poa_elevation.tif
poa_hexgrid.csv
file with spatial coordinates of a
regular hexagonal grid covering the sample area, which can be used as
origin/destination pairs in a travel time matrix calculation.poa_points_of_interest.csv
file containing the names
and spatial coordinates of 15 places within Porto Alegrefares_poa.zip
file with the fare rules of the city’s
public transport system.The points of interest data can be seen below. In this example, we will be looking at transport alternatives between some of those places.
The data with origin destination pairs is shown below. In this example, we will be using 200 points randomly selected from this data set.
setup_r5()
The first step is to build the multimodal transport network used for
routing in R5. This is done with the setup_r5
function. This function does two things: (1) downloads/updates a
compiled JAR file of R5 and stores it locally in the
{r5r}
package directory for future use; and (2) combines
the osm.pbf and gtfs.zip data sets to build a routable network
object.
The fastest way to calculate accessibility estimates is using the
accessibility()
function. In this example, we calculate the
number of schools and health care facilities accessible in less than 60
minutes by public transport and walking. More details in this vignette
on Calculating
and visualizing Accessibility.
# 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)
For fast routing analysis, r5r currently has three
core functions: travel_time_matrix()
,
expanded_travel_time_matrix()
and
detailed_itineraries()
.
The travel_time_matrix()
function is a really simple and
fast function to compute travel time estimates between one or multiple
origin/destination pairs. The origin/destination input can be either a
spatial sf POINT
object, or a data.frame
containing the columns id, lon, lat
. The function also
receives as inputs the max walking distance, in meters, and the
max trip duration, in minutes. Resulting travel times are also
output in minutes.
This function also allows users to very efficiently capture the travel time uncertainties inside a given time window considering multiple departure times. More info on this vignette.
# 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)
For those interested in more detailed outputs, the
expanded_travel_time_matrix()
works very similarly with
travel_time_matrix()
but it brings much more information.
It estimates for each origin destination pair the routes used and total
time disaggregated by access, waiting, in-vehicle and transfer times.
Please note this function can be very memory intensive for large data
sets.
Most routing packages only return the fastest route. A key advantage
of the detailed_itineraries()
function is that is allows
for fast routing analysis while providing multiple alternative routes
between origin destination pairs. The output also brings detailed
information for each route alternative at the trip segment level,
including the transport mode, waiting times, travel time and distance of
each trip segment.
In this example below, we want to know some alternative routes between one origin/destination pair only.
# 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)
The output is a data.frame sf
object, so we can easily
visualize the results.
Static visualization with ggplot2
package: To provide a geographic context for the visualization of the
results in ggplot2
, you can also use the
street_network_to_sf()
function to extract the OSM street
network used in the routing.
{r5r}
objects are still allocated to any amount of
memory previously set after they are done with their calculations. In
order to remove an existing {r5r}
object and reallocate the
memory it had been using, we use the stop_r5
function
followed by a call to Java’s garbage collector, as follows:
If you have any suggestions or want to report an error, please visit the package GitHub page.