Help for package r5r

Type:

Package

Title:

Rapid Realistic Routing with 'R5'

Version:

2.2.0

Description:

Rapid realistic routing on multimodal transport networks (walk, bike, public transport and car) using 'R5', the Rapid Realistic Routing on Real-world and Reimagined networks engine https://github.com/conveyal/r5. The package allows users to generate detailed routing analysis or calculate travel time and monetary cost matrices using seamless parallel computing on top of the R5 Java machine. While R5 is developed by Conveyal, the package r5r is independently developed by a team at the Institute for Applied Economic Research (Ipea) with contributions from collaborators. Apart from the documentation in this package, users will find additional information on R5 documentation at https://docs.conveyal.com/. Although we try to keep new releases of r5r in synchrony with R5, the development of R5 follows Conveyal's independent update process. Hence, users should confirm the R5 version implied by the Conveyal user manual (see https://docs.conveyal.com/changelog) corresponds with the R5 version that r5r depends on. This version of r5r depends on R5 v7.1.

License:

MIT + file LICENSE

URL:

https://github.com/ipeaGIT/r5r, https://ipeagit.github.io/r5r/

BugReports:

https://github.com/ipeaGIT/r5r/issues

Depends:

R (≥ 3.6)

Imports:

checkmate, cli, concaveman, data.table, jsonlite, rJava (≥ 0.9-10), rlang, sf (≥ 1.0-12), sfheaders, utils, zip

Suggests:

accessibility, covr, dplyr, ggplot2 (≥ 3.3.1), gtfstools, h3jsr (≥ 1.3.0), interp, knitr, parallel, patchwork, rJavaEnv, rmarkdown, testthat

VignetteBuilder:

knitr

Encoding:

UTF-8

RoxygenNote:

7.3.2

SystemRequirements:

Java JDK (>= 21.0)

NeedsCompilation:

Packaged:

2025-05-22 15:10:35 UTC; rafap

Author:

Marcus Saraiva

[aut], Rafael H. M. Pereira

[aut, cre], Daniel Herszenhut

[aut], Carlos Kaue Vieira Braga

[aut], Matthew Wigginton Bhagat-Conway

[aut], Luyu Liu

[ctb], Alex Magnus [ctb], Daniel Snow [ctb], Ipea - Institute for Applied Economic Research [cph, fnd], Department of Geography & Planning, University of Toronto [fnd]

Maintainer:

Rafael H. M. Pereira <rafa.pereira.br@gmail.com>

Repository:

CRAN

Date/Publication:

2025-05-22 15:50:02 UTC

r5r: Rapid Realistic Routing with 'R5'

Description

Rapid realistic routing on multimodal transport networks (walk, bike, public transport and car) using R5, the Rapid Realistic Routing on Real-world and Reimagined networks engine https://github.com/conveyal/r5. The package allows users to generate detailed routing analysis or calculate travel time matrices using seamless parallel computing on top of the R5 Java machine. While R5 is developed by Conveyal, the package r5r is independently developed by a team at the Institute for Applied Economic Research (Ipea) with contributions from collaborators. Apart from the documentation in this package, users will find additional information on R5 documentation at https://docs.conveyal.com/. Although we try to keep new releases of r5r in synchrony with R5, the development of R5 follows Conveyal's independent update process. Hence, users should confirm if the R5 version implied by the Conveyal user manual (see https://docs.conveyal.com/changelog) corresponds with the R5 version that r5r depends on.

Usage

Please check the vignettes on the website.

Author(s)

Maintainer: Rafael H. M. Pereira rafa.pereira.br@gmail.com (ORCID)

Authors:

Marcus Saraiva marcus.saraiva@gmail.com (ORCID)
Daniel Herszenhut dhersz@gmail.com (ORCID)
Carlos Kaue Vieira Braga kaue@kauebraga.dev (ORCID)
Matthew Wigginton Bhagat-Conway mwbc@unc.edu (ORCID)

Other contributors:

Luyu Liu luyuliu@ufl.edu (ORCID) [contributor]
Alex Magnus alex.magnus@mail.utoronto.ca [contributor]
Daniel Snow dan@sno.ws [contributor]
Ipea - Institute for Applied Economic Research [copyright holder, funder]
Department of Geography & Planning, University of Toronto [funder]

Calculate access to opportunities

Description

Fast computation of access to opportunities given a selected decay function.

Usage

accessibility(
  r5r_core,
  origins,
  destinations,
  opportunities_colnames = "opportunities",
  mode = "WALK",
  mode_egress = "WALK",
  departure_datetime = Sys.time(),
  time_window = 10L,
  percentiles = 50L,
  decay_function = "step",
  cutoffs = NULL,
  decay_value = NULL,
  fare_structure = NULL,
  max_fare = Inf,
  max_walk_time = Inf,
  max_bike_time = Inf,
  max_car_time = Inf,
  max_trip_duration = 120L,
  walk_speed = 3.6,
  bike_speed = 12,
  max_rides = 3,
  max_lts = 2,
  draws_per_minute = 5L,
  n_threads = Inf,
  verbose = FALSE,
  progress = FALSE,
  output_dir = NULL
)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

origins, destinations

Either a ⁠POINT sf⁠ object with WGS84 CRS, or a data.frame containing the columns id, lon and lat.

opportunities_colnames

A character vector. The names of the columns in the destinations input that tells the number of opportunities in each location. Several different column names can be passed, in which case the accessibility to each kind of opportunity will be calculated.

mode

A character vector. The transport modes allowed for access, transfer and vehicle legs of the trips. Defaults to WALK. Please see details for other options.

mode_egress

A character vector. The transport mode used after egress from the last public transport. It can be either WALK, BICYCLE or CAR. Defaults to WALK. Ignored when public transport is not used.

departure_datetime

A POSIXct object. Please note that the departure time only influences public transport legs. When working with public transport networks, please check the calendar.txt within your GTFS feeds for valid dates. Please see details for further information on how datetimes are parsed.

time_window

An integer. The time window in minutes for which r5r will calculate multiple travel time matrices departing each minute. Defaults to 10 minutes. By default, the function returns the result based on median travel times, but the user can set the percentiles parameter to extract more results. Please read the time window vignette for more details on its usage vignette("time_window", package = "r5r")

percentiles

An integer vector (max length of 5). Specifies the percentile to use when returning accessibility estimates within the given time window. Please note that this parameter is applied to the travel time estimates that generate the accessibility results, and not to the accessibility distribution itself (i.e. if the 25th percentile is specified, the accessibility is calculated from the 25th percentile travel time, which may or may not be equal to the 25th percentile of the accessibility distribution itself). Defaults to 50, returning the accessibility calculated from the median travel time. If a vector with length bigger than 1 is passed, the output contains an additional column that specifies the percentile of each accessibility estimate. Due to upstream restrictions, only 5 percentiles can be specified at a time. For more details, please see R5 documentation at https://docs.conveyal.com/analysis/methodology#accounting-for-variability.

decay_function

A string. Which decay function to use when calculating accessibility. One of step, exponential, fixed_exponential, linear or logistic. Defaults to step, which is equivalent to a cumulative opportunities measure. Please see the details to understand how each alternative works and how they relate to the cutoffs and decay_value parameters.

cutoffs

A numeric vector (maximum length of 12). This parameter has different effects for each decay function: it indicates the cutoff times in minutes when calculating cumulative opportunities accessibility with the step function, the median (or inflection point) of the decay curves in the logistic and linear functions, and the half-life in the exponential function. It has no effect when using the fixed_exponential function.

decay_value

A number. Extra parameter to be passed to the selected decay_function. Has no effects when decay_function is either step or exponential.

fare_structure

A fare structure object, following the convention set in setup_fare_structure(). This object describes how transit fares should be calculated. Please see the fare structure vignette to understand how this object is structured: vignette("fare_structure", package = "r5r").

max_fare

A number. The maximum value that trips can cost when calculating the fastest journey between each origin and destination pair.

max_walk_time

An integer. The maximum walking time (in minutes) to access and egress the transit network, to make transfers within the network or to complete walk-only trips. Defaults to no restrictions (numeric value of Inf), as long as max_trip_duration is respected. When routing transit trips, the max time is considered separately for each leg (e.g. if you set max_walk_time to 15, you could get trips with an up to 15 minutes walk leg to reach transit and another up to 15 minutes walk leg to reach the destination after leaving transit. In walk-only trips, whenever max_walk_time differs from max_trip_duration, the lowest value is considered.

max_bike_time

An integer. The maximum cycling time (in minutes) to access and egress the transit network, to make transfers within the network or to complete bicycle-only trips. Defaults to no restrictions (numeric value of Inf), as long as max_trip_duration is respected. When routing transit trips, the max time is considered separately for each leg (e.g. if you set max_bike_time to 15, you could get trips with an up to 15 minutes cycle leg to reach transit and another up to 15 minutes cycle leg to reach the destination after leaving transit. In bicycle-only trips, whenever max_bike_time differs from max_trip_duration, the lowest value is considered.

max_car_time

An integer. The maximum driving time (in minutes) to access and egress the transit network. Defaults to no restrictions, as long as max_trip_duration is respected. The max time is considered separately for each leg (e.g. if you set max_car_time to 15 minutes, you could potentially drive up to 15 minutes to reach transit, and up to another 15 minutes to reach the destination after leaving transit). Defaults to Inf, no limit.

max_trip_duration

An integer. The maximum trip duration in minutes. Defaults to 120 minutes (2 hours).

walk_speed

A numeric. Average walk speed in km/h. Defaults to 3.6 km/h.

bike_speed

A numeric. Average cycling speed in km/h. Defaults to 12 km/h.

max_rides

An integer. The maximum number of public transport rides allowed in the same trip. Defaults to 3.

max_lts

An integer between 1 and 4. The maximum level of traffic stress that cyclists will tolerate. A value of 1 means cyclists will only travel through the quietest streets, while a value of 4 indicates cyclists can travel through any road. Defaults to 2. Please see details for more information.

draws_per_minute

An integer. The number of Monte Carlo draws to perform per time window minute when calculating travel time matrices and when estimating accessibility. Defaults to 5. This would mean 300 draws in a 60-minute time window, for example. This parameter only affects the results when the GTFS feeds contain a frequencies.txt table. If the GTFS feed does not have a frequency table, r5r still allows for multiple runs over the set time_window but in a deterministic way.

n_threads

An integer. The number of threads to use when running the router in parallel. Defaults to use all available threads (Inf).

verbose

A logical. Whether to show R5 informative messages when running the function. Defaults to FALSE (please note that in such case R5 error messages are still shown). Setting verbose to TRUE shows detailed output, which can be useful for debugging issues not caught by r5r.

progress

A logical. Whether to show a progress counter when running the router. Defaults to FALSE. Only works when verbose is set to FALSE, so the progress counter does not interfere with R5's output messages. Setting progress to TRUE may impose a small penalty for computation efficiency, because the progress counter must be synchronized among all active threads.

output_dir

Either NULL or a path to an existing directory. When not NULL (the default), the function will write one .csv file with the results for each origin in the specified directory. In such case, the function returns the path specified in this parameter. This parameter is particularly useful when running on memory-constrained settings because writing the results directly to disk prevents r5r from loading them to RAM memory.

Value

A data.table with accessibility estimates for all origin points. This data.table contain columns listing the origin id, the type of opportunities to which accessibility was calculated, the travel time percentile considered in the accessibility estimate and the specified cutoff values (except in when decay_function is fixed_exponential, in which case the cutoff parameter is not used). If output_dir is not NULL, the function returns the path specified in that parameter, in which the .csv files containing the results are saved.

Decay functions

R5 allows one to use different decay functions when calculating accessibility. Please see the original R5 documentation from Conveyal for more information on each one one (https://docs.conveyal.com/learn-more/decay-functions). A summary of each available option, as well as the value passed to decay_function to use it (inside parentheses) are listed below:

Step, also known as cumulative opportunities ("step"):
a binary decay function used to find the sum of available opportunities within a specific travel time cutoff.
Logistic CDF ("logistic"):
This is the logistic function, i.e. the cumulative distribution function of the logistic distribution, expressed such that its parameters are the median (inflection point) and standard deviation. This function applies a sigmoid rolloff that has a convenient relationship to discrete choice theory. Its parameters can be set to reflect a whole population's tolerance for making trips with different travel times. The function's value represents the probability that a randomly chosen member of the population would accept making a trip, given its duration. Opportunities are then weighted by how likely it is that a person would consider them "reachable".
- Calibration: The median parameter is controlled by the cutoff parameter, leaving only the standard deviation to configure through the decay_value parameter.
Fixed Exponential ("fixed_exponential"):
This function is of the form exp(-Lt) where L is a single fixed decay constant in the range (0, 1). It is constrained to be positive to ensure weights decrease (rather than grow) with increasing travel time.
- Calibration: This function is controlled exclusively by the L constant, given by the decay_value parameter. Values provided in cutoffs are ignored.
Half-life Exponential Decay ("exponential"):
This is similar to the fixed-exponential option above, but in this case the decay parameter is inferred from the cutoffs parameter values, which is treated as the half-life of the decay.
Linear ("linear"):
This is a simple, vaguely sigmoid option, which may be useful when you have a sense of a maximum travel time that would be tolerated by any traveler, and a minimum time below which all travel is perceived to be equally easy.
- Calibration: The transition region is transposable and symmetric around the cutoffs parameter values, taking decay_value minutes to taper down from one to zero.

Transport modes

R5 allows for multiple combinations of transport modes. The options include:

Transit modes: TRAM, SUBWAY, RAIL, BUS, FERRY, CABLE_CAR, GONDOLA, FUNICULAR. The option TRANSIT automatically considers all public transport modes available.
Non transit modes: WALK, BICYCLE, CAR, BICYCLE_RENT, CAR_PARK.

Level of Traffic Stress (LTS)

When cycling is enabled in R5 (by passing the value BIKE to either mode or mode_egress), setting max_lts will allow cycling only on streets with a given level of danger/stress. Setting max_lts to 1, for example, will allow cycling only on separated bicycle infrastructure or low-traffic streets and routing will revert to walking when traversing any links with LTS exceeding 1. Setting max_lts to 3 will allow cycling on links with LTS 1, 2 or 3. Routing also reverts to walking if the street segment is tagged as non-bikable in OSM (e.g. a staircase), independently of the specified max LTS.

The default methodology for assigning LTS values to network edges is based on commonly tagged attributes of OSM ways. See more info about LTS in the original documentation of R5 from Conveyal at https://docs.conveyal.com/learn-more/traffic-stress. In summary:

LTS 1: Tolerable for children. This includes low-speed, low-volume streets, as well as those with separated bicycle facilities (such as parking-protected lanes or cycle tracks).
LTS 2: Tolerable for the mainstream adult population. This includes streets where cyclists have dedicated lanes and only have to interact with traffic at formal crossing.
LTS 3: Tolerable for "enthused and confident" cyclists. This includes streets which may involve close proximity to moderate- or high-speed vehicular traffic.
LTS 4: Tolerable only for "strong and fearless" cyclists. This includes streets where cyclists are required to mix with moderate- to high-speed vehicular traffic.

For advanced users, you can provide custom LTS values by adding a tag ⁠<key = "lts">⁠ to the osm.pbf file.

Datetime parsing

r5r ignores the timezone attribute of datetime objects when parsing dates and times, using the study area's timezone instead. For example, let's say you are running some calculations using Rio de Janeiro, Brazil, as your study area. The datetime as.POSIXct("13-05-2019 14:00:00", format = "%d-%m-%Y %H:%M:%S") will be parsed as May 13th, 2019, 14:00h in Rio's local time, as expected. But as.POSIXct("13-05-2019 14:00:00", format = "%d-%m-%Y %H:%M:%S", tz = "Europe/Paris") will also be parsed as the exact same date and time in Rio's local time, perhaps surprisingly, ignoring the timezone attribute.

Routing algorithm

The travel_time_matrix(), expanded_travel_time_matrix() and accessibility() functions use an R5-specific extension to the RAPTOR routing algorithm (see Conway et al., 2017). This RAPTOR extension uses a systematic sample of one departure per minute over the time window set by the user in the 'time_window' parameter. A detailed description of base RAPTOR can be found in Delling et al (2015). However, whenever the user includes transit fares inputs to these functions, they automatically switch to use an R5-specific extension to the McRAPTOR routing algorithm.

Conway, M. W., Byrd, A., & van der Linden, M. (2017). Evidence-based transit and land use sketch planning using interactive accessibility methods on combined schedule and headway-based networks. Transportation Research Record, 2653(1), 45-53. doi:10.3141/2653-06
Delling, D., Pajor, T., & Werneck, R. F. (2015). Round-based public transit routing. Transportation Science, 49(3), 591-604. doi:10.1287/trsc.2014.0534

Examples


library(r5r)

data_path <- system.file("extdata/poa", package = "r5r")
r5r_core <- setup_r5(data_path)
points <- read.csv(file.path(data_path, "poa_hexgrid.csv"))[1:5, ]

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

access <- accessibility(
  r5r_core,
  origins = points,
  destinations = points,
  opportunities_colnames = "schools",
  mode = "WALK",
  departure_datetime = departure_datetime,
  decay_function = "step",
  cutoffs = 30,
  max_trip_duration = 30
)
head(access)

# using a different decay function
access <- accessibility(
  r5r_core,
  origins = points,
  destinations = points,
  opportunities_colnames = "schools",
  mode = "WALK",
  departure_datetime = departure_datetime,
  decay_function = "logistic",
  cutoffs = 30,
  decay_value = 1,
  max_trip_duration = 30
)
head(access)

# using several cutoff values
access <- accessibility(
  r5r_core,
  origins = points,
  destinations = points,
  opportunities_colnames = "schools",
  mode = "WALK",
  departure_datetime = departure_datetime,
  decay_function = "step",
  cutoffs = c(15, 30),
  max_trip_duration = 30
)
head(access)

# calculating access to different types of opportunities
access <- accessibility(
  r5r_core,
  origins = points,
  destinations = points,
  opportunities_colnames = c("schools", "healthcare"),
  mode = "WALK",
  departure_datetime = departure_datetime,
  decay_function = "step",
  cutoffs = 30,
  max_trip_duration = 30
)
head(access)

stop_r5(r5r_core)

Assert fare structure

Description

Asserts whether the specified fare structure object complies with the structure set in setup_fare_structure().

Usage

assert_fare_structure(fare_structure)

Arguments

fare_structure

Value

Throws and error upon failure and invisibly returns TRUE on success.

Assign decay function and parameter values

Description

Checks and assigns decay function and values.

Usage

assign_decay_function(decay_function, decay_value)

Arguments

decay_function

A string, the name of the decay function.

decay_value

A number, the value of decay parameter.

Value

A list with the validated decay function and parameter value.

Check and convert POSIXct objects to strings

Description

Check and convert POSIXct objects to strings

Usage

assign_departure(datetime)

Arguments

datetime

An object of POSIXct class.

Value

A list with the date and time of the trip departure as characters.

Assign drop geometry

Description

Check the drop geometry input.

Usage

assign_drop_geometry(drop_geometry)

Arguments

drop_geometry

A logical.

Value

A logical.

Assign max street time from walk/bike distance and speed

Description

Checks the time duration and speed inputs and converts them to distance.

Usage

assign_max_street_time(max_time, speed, max_trip_duration, mode)

Arguments

max_time

A numeric of length 1. Maximum walking distance (in meters) for the whole trip. Passed from routing functions.

speed

A numeric of length 1. Average walk speed in km/h. Defaults to 3.6 Km/h. Passed from routing functions.

max_trip_duration

A numeric of length 1. Maximum trip duration in seconds. Defaults to 120 minutes (2 hours). Passed from routing functions.

mode

A string. Either "bike" or "walk".

Value

An integer representing the maximum number of minutes walking.

Assign max trip duration

Description

Check and convert the max trip duration input.

Usage

assign_max_trip_duration(
  max_trip_duration,
  modes,
  max_walk_time,
  max_bike_time
)

Arguments

max_trip_duration

A number.

Value

An integer representing the maximum trip duration in minutes.

Check and select transport modes from user input

Description

Selects the transport modes used in the routing functions. Only one direct and access/egress modes are allowed at a time.

Usage

assign_mode(mode, mode_egress, style)

Arguments

mode

A character vector, passed from routing functions.

mode_egress

A character vector, passed from routing functions.

Value

A list with the transport modes to be used in the routing.

Assign opportunities data

Description

Check and create an opportunities dataset.

Usage

assign_opportunities(destinations, opportunities_colnames)

Arguments

destinations

Either a data.frame or a ⁠POINT sf⁠.

opportunities_colnames

A character vector with the names of the opportunities columns in destinations.

Value

A list of Java-Array objects.

Assign osm_link_ids

Description

Check the osm_link_ids input.

Usage

assign_osm_link_ids(osm_link_ids, drop_geometry)

Arguments

osm_link_ids

A logical.

drop_geometry

A logical.

Value

A logical.

Check and convert origin and destination inputs

Description

Check and convert origin and destination inputs

Usage

assign_points_input(df, name)

Arguments

df

Either a data.frame or a ⁠POINT sf⁠.

name

Object name.

Value

A data.frame with columns id, lon and lat.

Assign shortest path

Description

Check the shortest path input.

Usage

assign_shortest_path(shortest_path)

Arguments

shortest_path

A logical.

Value

A logical.

Detailed itineraries between origin-destination pairs

Description

Returns detailed trip information between origin-destination pairs. The output includes the waiting and moving time in each trip leg, as well as some info such as the distance traveled, the routes used and the geometry of each leg. Please note that this function was originally conceptualized as a trip planning functionality, similar to other commercial and non-commercial APIs and apps (e.g. Moovit, Google's Directions API, OpenTripPlanning's PlannerResource API). Thus, it consumes much more time and memory than the other (more analytical) routing functions included in the package.

Usage

detailed_itineraries(
  r5r_core,
  origins,
  destinations,
  mode = "WALK",
  mode_egress = "WALK",
  departure_datetime = Sys.time(),
  time_window = 10L,
  suboptimal_minutes = 0L,
  fare_structure = NULL,
  max_fare = Inf,
  max_walk_time = Inf,
  max_bike_time = Inf,
  max_car_time = Inf,
  max_trip_duration = 120L,
  walk_speed = 3.6,
  bike_speed = 12,
  max_rides = 3,
  max_lts = 2,
  shortest_path = TRUE,
  all_to_all = FALSE,
  n_threads = Inf,
  verbose = FALSE,
  progress = FALSE,
  drop_geometry = FALSE,
  osm_link_ids = FALSE,
  output_dir = NULL
)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

origins, destinations

Either a ⁠POINT sf⁠ object with WGS84 CRS, or a data.frame containing the columns id, lon and lat.

mode

A character vector. The transport modes allowed for access, transfer and vehicle legs of the trips. Defaults to WALK. Please see details for other options.

mode_egress

A character vector. The transport mode used after egress from the last public transport. It can be either WALK, BICYCLE or CAR. Defaults to WALK. Ignored when public transport is not used.

departure_datetime

time_window

An integer. The time window in minutes for which r5r will calculate multiple itineraries departing each minute. Defaults to 10 minutes. If the same sequence of routes appear in different minutes of the time window, only the fastest of them will be kept in the output. This happens because the result is not aggregated by percentile, as opposed to other routing functions in the package. Because of that, the output may contain trips departing after the specified departure_datetime, but still within the time window. Please read the time window vignette for more details on how this argument affects the results of each routing function: vignette("time_window", package = "r5r").

suboptimal_minutes

A number. The difference in minutes that each non-optimal RAPTOR branch can have from the optimal branch without being disregarded by the routing algorithm. If, for example, users set suboptimal_minutes = 10, the routing algorithm will consider sub-optimal routes that arrive up to 10 minutes after the arrival of the optimal one. This argument emulates the real-life behaviour that makes people want to take a path that is technically not optimal in terms of travel time, for example, for some practical reasons (e.g. mode preference, safety, etc). In practice, the higher this value, the more itineraries will be returned in the final result.

fare_structure

max_fare

A number. The maximum value that trips can cost when calculating the fastest journey between each origin and destination pair.

max_walk_time

max_bike_time

max_car_time

max_trip_duration

An integer. The maximum trip duration in minutes. Defaults to 120 minutes (2 hours).

walk_speed

A numeric. Average walk speed in km/h. Defaults to 3.6 km/h.

bike_speed

A numeric. Average cycling speed in km/h. Defaults to 12 km/h.

max_rides

An integer. The maximum number of public transport rides allowed in the same trip. Defaults to 3.

max_lts

shortest_path

A logical. Whether the function should only return the fastest itinerary between each origin and destination pair (the default) or multiple alternatives.

all_to_all

A logical. Whether to query routes between the 1st origin to the 1st destination, then the 2nd origin to the 2nd destination, and so on (FALSE, the default) or to query routes between all origins to all destinations (TRUE).

n_threads

An integer. The number of threads to use when running the router in parallel. Defaults to use all available threads (Inf).

verbose

progress

drop_geometry

A logical. Whether the output should include the geometry of each trip leg or not. The default value of FALSE keeps the geometry column in the result.

osm_link_ids

A logical. Whether the output should include additional columns with the OSM ids of the road segments used along the trip geometry. Defaults to FALSE. Keep in mind that the osm_id for a road will be returned even if the route uses a small stretch of the road (e.g. 5m of a 600m street segment). If you want more precision you should use the column edge_id which returns segments of the exact length used in the trip, and you can later tie that back to the osm_id.

output_dir

Value

When drop_geometry is FALSE, the function outputs a ⁠LINESTRING sf⁠ with detailed information on the itineraries between the specified origins and destinations. When TRUE, the output is a data.table. All distances are in meters and travel times are in minutes. If output_dir is not NULL, the function returns the path specified in that parameter, in which the .csv files containing the results are saved.

Transport modes

R5 allows for multiple combinations of transport modes. The options include:

Transit modes: TRAM, SUBWAY, RAIL, BUS, FERRY, CABLE_CAR, GONDOLA, FUNICULAR. The option TRANSIT automatically considers all public transport modes available.
Non transit modes: WALK, BICYCLE, CAR, BICYCLE_RENT, CAR_PARK.

Level of Traffic Stress (LTS)

LTS 1: Tolerable for children. This includes low-speed, low-volume streets, as well as those with separated bicycle facilities (such as parking-protected lanes or cycle tracks).
LTS 2: Tolerable for the mainstream adult population. This includes streets where cyclists have dedicated lanes and only have to interact with traffic at formal crossing.
LTS 3: Tolerable for "enthused and confident" cyclists. This includes streets which may involve close proximity to moderate- or high-speed vehicular traffic.
LTS 4: Tolerable only for "strong and fearless" cyclists. This includes streets where cyclists are required to mix with moderate- to high-speed vehicular traffic.

For advanced users, you can provide custom LTS values by adding a tag ⁠<key = "lts">⁠ to the osm.pbf file.

Datetime parsing

Routing algorithm

The detailed_itineraries() and pareto_frontier() functions use an R5-specific extension to the McRAPTOR routing algorithm. The implementation used in detailed_itineraries() allows the router to find paths that are optimal and less than optimal in terms of travel time, with some heuristics around multiple access modes, riding the same patterns, etc. The specific extension to McRAPTOR to do suboptimal path routing is not documented yet, but a detailed description of base McRAPTOR can be found in Delling et al (2015). The implementation used in pareto_frontier(), on the other hand, returns only the fastest trip within a given monetary cutoff, ignoring slower trips that cost the same. A detailed discussion on the algorithm can be found in Conway and Stewart (2019).

Delling, D., Pajor, T., & Werneck, R. F. (2015). Round-based public transit routing. Transportation Science, 49(3), 591-604. doi:10.1287/trsc.2014.0534
Conway, M. W., & Stewart, A. F. (2019). Getting Charlie off the MTA: a multiobjective optimization method to account for cost constraints in public transit accessibility metrics. International Journal of Geographical Information Science, 33(9), 1759-1787. doi:10.1080/13658816.2019.1605075

Examples


library(r5r)

# build transport network
data_path <- system.file("extdata/poa", package = "r5r")
r5r_core <- setup_r5(data_path)

# load origin/destination points
points <- read.csv(file.path(data_path, "poa_points_of_interest.csv"))

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

det <- detailed_itineraries(
  r5r_core,
  origins = points[10,],
  destinations = points[12,],
  mode = c("WALK", "TRANSIT"),
  departure_datetime = departure_datetime,
  max_trip_duration = 60
)
head(det)

stop_r5(r5r_core)

Download `R5.jar`

Description

Downloads R5.jar and saves it locally, inside the package directory.

Usage

download_r5(
  version = NULL,
  quiet = FALSE,
  force_update = FALSE,
  temp_dir = FALSE
)

Arguments

version

A string. The version of R5 to be downloaded. When NULL, it defaults to the latest version.

quiet

A logical. Whether to show informative messages when downloading the file. Defaults to FALSE.

force_update

A logical. Whether to overwrite a previously downloaded R5.jar in the local directory. Defaults to FALSE.

temp_dir

A logical. Whether the file should be saved in a temporary directory. Defaults to FALSE.

Value

The path to the downloaded file.

Examples


library(r5r)

download_r5(temp_dir = TRUE)

Expand origin-destination pairs

Description

This function is used in detailed_itineraries() to update the origins and destinations datasets.

Usage

expand_od_pairs(origins, destinations, all_to_all)

Arguments

origins

Passed by detailed_itineraries().

destinations

Passed by detailed_itineraries().

all_to_all

Passed by detailed_itineraries().

Calculate minute-by-minute travel times between origin destination pairs

Description

Detailed computation of travel time estimates between one or multiple origin destination pairs. Results show the travel time of the fastest route alternative departing each minute within a specified time window. Please note this function can be very memory intensive for large data sets and time windows.

Usage

expanded_travel_time_matrix(
  r5r_core,
  origins,
  destinations,
  mode = "WALK",
  mode_egress = "WALK",
  departure_datetime = Sys.time(),
  time_window = 10L,
  breakdown = FALSE,
  max_walk_time = Inf,
  max_bike_time = Inf,
  max_car_time = Inf,
  max_trip_duration = 120L,
  walk_speed = 3.6,
  bike_speed = 12,
  max_rides = 3,
  max_lts = 2,
  draws_per_minute = 5L,
  n_threads = Inf,
  verbose = FALSE,
  progress = FALSE,
  output_dir = NULL
)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

origins, destinations

Either a ⁠POINT sf⁠ object with WGS84 CRS, or a data.frame containing the columns id, lon and lat.

mode

A character vector. The transport modes allowed for access, transfer and vehicle legs of the trips. Defaults to WALK. Please see details for other options.

mode_egress

A character vector. The transport mode used after egress from the last public transport. It can be either WALK, BICYCLE or CAR. Defaults to WALK. Ignored when public transport is not used.

departure_datetime

time_window

An integer. The time window in minutes for which r5r will calculate multiple travel time matrices departing each minute. Defaults to 10 minutes. The function returns the result based on median travel times. Please read the time window vignette for more details on its usage vignette("time_window", package = "r5r")

breakdown

A logical. Whether to include detailed information about each trip in the output. If FALSE (the default), the output lists the total time between each origin-destination pair and the routes used to complete the trip for each minute of the specified time window. If TRUE, the output includes the total access, waiting, in-vehicle and transfer time of each trip. Please note that setting this parameter to TRUE makes the function significantly slower.

max_walk_time

max_bike_time

max_car_time

max_trip_duration

An integer. The maximum trip duration in minutes. Defaults to 120 minutes (2 hours).

walk_speed

A numeric. Average walk speed in km/h. Defaults to 3.6 km/h.

bike_speed

A numeric. Average cycling speed in km/h. Defaults to 12 km/h.

max_rides

An integer. The maximum number of public transport rides allowed in the same trip. Defaults to 3.

max_lts

draws_per_minute

n_threads

An integer. The number of threads to use when running the router in parallel. Defaults to use all available threads (Inf).

verbose

progress

output_dir

Value

A data.table with travel time estimates (in minutes) and the routes used in each trip between origin and destination pairs, for each minute of the specified time window. Each set of origin, destination and departure minute can appear up to N times, where N is the number of Monte Carlo draws specified in the function arguments (please note that this only applies when the GTFS feeds that describe the transit network include a frequencies table, otherwise only a single draw is performed). A pair is completely absent from the final output if no trips could be completed in any of the minutes of the time window. If for a single pair trips could be completed in some of the minutes of the time window, but not for all of them, the minutes in which trips couldn't be completed will have NA travel time and routes used. If output_dir is not NULL, the function returns the path specified in that parameter, in which the .csv files containing the results are saved.

Transport modes

R5 allows for multiple combinations of transport modes. The options include:

Transit modes: TRAM, SUBWAY, RAIL, BUS, FERRY, CABLE_CAR, GONDOLA, FUNICULAR. The option TRANSIT automatically considers all public transport modes available.
Non transit modes: WALK, BICYCLE, CAR, BICYCLE_RENT, CAR_PARK.

Level of Traffic Stress (LTS)

LTS 1: Tolerable for children. This includes low-speed, low-volume streets, as well as those with separated bicycle facilities (such as parking-protected lanes or cycle tracks).
LTS 2: Tolerable for the mainstream adult population. This includes streets where cyclists have dedicated lanes and only have to interact with traffic at formal crossing.
LTS 3: Tolerable for "enthused and confident" cyclists. This includes streets which may involve close proximity to moderate- or high-speed vehicular traffic.
LTS 4: Tolerable only for "strong and fearless" cyclists. This includes streets where cyclists are required to mix with moderate- to high-speed vehicular traffic.

For advanced users, you can provide custom LTS values by adding a tag ⁠<key = "lts">⁠ to the osm.pbf file.

Datetime parsing

Routing algorithm

Conway, M. W., Byrd, A., & van der Linden, M. (2017). Evidence-based transit and land use sketch planning using interactive accessibility methods on combined schedule and headway-based networks. Transportation Research Record, 2653(1), 45-53. doi:10.3141/2653-06
Delling, D., Pajor, T., & Werneck, R. F. (2015). Round-based public transit routing. Transportation Science, 49(3), 591-604. doi:10.1287/trsc.2014.0534

Examples


library(r5r)

# build transport network
data_path <- system.file("extdata/poa", package = "r5r")
r5r_core <- setup_r5(data_path)

# load origin/destination points
points <- read.csv(file.path(data_path, "poa_points_of_interest.csv"))

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

# by default only returns the total time between each pair in each minute of
# the specified time window
ettm <- expanded_travel_time_matrix(
  r5r_core,
  origins = points,
  destinations = points,
  mode = c("WALK", "TRANSIT"),
  time_window = 20,
  departure_datetime = departure_datetime,
  max_trip_duration = 60
)
head(ettm)

# when breakdown = TRUE the output contains much more information
ettm <- expanded_travel_time_matrix(
  r5r_core,
  origins = points,
  destinations = points,
  mode = c("WALK", "TRANSIT"),
  time_window = 20,
  departure_datetime = departure_datetime,
  max_trip_duration = 60,
  breakdown = TRUE
)
head(ettm)

stop_r5(r5r_core)

Get most recent JAR file url from metadata

Description

Returns the most recent JAR file url from metadata, depending on the version.

Usage

fileurl_from_metadata(version = NULL)

Arguments

version

A string. The version of R5 to be downloaded. When NULL, it defaults to the latest version.

Value

A url a string.

Find snapped locations of input points on street network

Description

Finds the snapped location of points on R5 network. Snapping is an important step of the routing process, which is when the origins and destinations specified by the user are actually positioned on the network created by R5. The snapping process in R5 is composed of two rounds. First, it tries to snap the points within a radius of 300 meters from themselves. If the first round is unsuccessful, then R5 expands the search to the radius specified (by default 1.6km). If yet again it is unsuccessful, then the unsnapped points won't be used during the routing process. The snapped location of each point depends on the transport mode set by the user, because some network edges are not available to specific modes (e.g. a pedestrian-only street cannot be used to snap car trips).

Usage

find_snap(r5r_core, points, radius = 1600, mode = "WALK")

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

points

Either a ⁠POINT sf⁠ object with WGS84 CRS, or a data.frame containing the columns id, lon and lat.

radius

Numeric. The maximum radius in meters within which to snap. Defaults to 1600m.

mode

A string. Which mode to consider when trying to snap the points to the network. Defaults to WALK, also allows BICYCLE and CAR.

Value

A data.table with the original points, their respective snapped coordinates on the street network and the Euclidean distance (in meters) between the original points and their snapped location. Points that could not be snapped show NA coordinates and found = FALSE.

Examples


library(r5r)

path <- system.file("extdata/poa", package = "r5r")
r5r_core <- setup_r5(data_path = path)
points <- read.csv(file.path(path, "poa_hexgrid.csv"))

snap_df <- find_snap(r5r_core, points, radius = 2000, mode = "WALK")

stop_r5(r5r_core)

Estimate isochrones from a given location

Description

Fast computation of isochrones from a given location. The function can return either polygon-based or line-based isochrones. Polygon-based isochrones are generated as concave polygons based on the travel times from the trip origin to all nodes in the transport network. Meanwhile, line-based isochronesare based on travel times from each origin to the centroids of all segments in the transport network.

Usage

isochrone(
  r5r_core,
  origins,
  mode = "transit",
  mode_egress = "walk",
  cutoffs = c(0, 15, 30),
  sample_size = 0.8,
  departure_datetime = Sys.time(),
  polygon_output = TRUE,
  time_window = 10L,
  max_walk_time = Inf,
  max_bike_time = Inf,
  max_car_time = Inf,
  max_trip_duration = 120L,
  walk_speed = 3.6,
  bike_speed = 12,
  max_rides = 3,
  max_lts = 2,
  draws_per_minute = 5L,
  n_threads = Inf,
  verbose = FALSE,
  progress = TRUE
)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

origins

Either a ⁠POINT sf⁠ object with WGS84 CRS, or a data.frame containing the columns id, lon and lat.

mode

A character vector. The transport modes allowed for access, transfer and vehicle legs of the trips. Defaults to WALK. Please see details for other options.

mode_egress

A character vector. The transport mode used after egress from the last public transport. It can be either WALK, BICYCLE or CAR. Defaults to WALK. Ignored when public transport is not used.

cutoffs

numeric vector. Number of minutes to define the time span of each Isochrone. Defaults to c(0, 15, 30).

sample_size

numeric. Sample size of nodes in the transport network used to estimate isochrones. Defaults to 0.8 (80% of all nodes in the transport network). Value can range between 0.2 and 1. Smaller values increase computation speed but return results with lower precision. This parameter has no effect when polygon_output = FALSE.

departure_datetime

polygon_output

A Logical. If TRUE, the function outputs polygon-based isochrones (the default) based on travel times from each origin to a sample of a random sample nodes in the transport network (see parameter sample_size). If FALSE, the function outputs line-based isochrones based on travel times from each origin to the centroids of all segments in the transport network.

time_window

max_walk_time

An integer. The maximum walking time (in minutes) to access and egress the transit network, or to make transfers within the network. Defaults to no restrictions, as long as max_trip_duration is respected. The max time is considered separately for each leg (e.g. if you set max_walk_time to 15, you could potentially walk up to 15 minutes to reach transit, and up to another 15 minutes to reach the destination after leaving transit). Defaults to Inf, no limit.

max_bike_time

An integer. The maximum cycling time (in minutes) to access and egress the transit network. Defaults to no restrictions, as long as max_trip_duration is respected. The max time is considered separately for each leg (e.g. if you set max_bike_time to 15 minutes, you could potentially cycle up to 15 minutes to reach transit, and up to another 15 minutes to reach the destination after leaving transit). Defaults to Inf, no limit.

max_car_time

max_trip_duration

An integer. The maximum trip duration in minutes. Defaults to 120 minutes (2 hours).

walk_speed

A numeric. Average walk speed in km/h. Defaults to 3.6 km/h.

bike_speed

A numeric. Average cycling speed in km/h. Defaults to 12 km/h.

max_rides

An integer. The maximum number of public transport rides allowed in the same trip. Defaults to 3.

max_lts

draws_per_minute

n_threads

An integer. The number of threads to use when running the router in parallel. Defaults to use all available threads (Inf).

verbose

progress

Value

A ⁠POLYGON "sf" "data.frame"⁠ for each isochrone of each origin.

Transport modes

R5 allows for multiple combinations of transport modes. The options include:

Transit modes: TRAM, SUBWAY, RAIL, BUS, FERRY, CABLE_CAR, GONDOLA, FUNICULAR. The option TRANSIT automatically considers all public transport modes available.
Non transit modes: WALK, BICYCLE, CAR, BICYCLE_RENT, CAR_PARK.

Level of Traffic Stress (LTS)

LTS 1: Tolerable for children. This includes low-speed, low-volume streets, as well as those with separated bicycle facilities (such as parking-protected lanes or cycle tracks).
LTS 2: Tolerable for the mainstream adult population. This includes streets where cyclists have dedicated lanes and only have to interact with traffic at formal crossing.
LTS 3: Tolerable for "enthused and confident" cyclists. This includes streets which may involve close proximity to moderate- or high-speed vehicular traffic.
LTS 4: Tolerable only for "strong and fearless" cyclists. This includes streets where cyclists are required to mix with moderate- to high-speed vehicular traffic.

For advanced users, you can provide custom LTS values by adding a tag ⁠<key = "lts">⁠ to the osm.pbf file.

Datetime parsing

Routing algorithm

Conway, M. W., Byrd, A., & van der Linden, M. (2017). Evidence-based transit and land use sketch planning using interactive accessibility methods on combined schedule and headway-based networks. Transportation Research Record, 2653(1), 45-53. doi:10.3141/2653-06
Delling, D., Pajor, T., & Werneck, R. F. (2015). Round-based public transit routing. Transportation Science, 49(3), 591-604. doi:10.1287/trsc.2014.0534

Examples


options(java.parameters = "-Xmx2G")
library(r5r)
library(ggplot2)

# build transport network
data_path <- system.file("extdata/poa", package = "r5r")
r5r_core <- setup_r5(data_path = data_path)

# load origin/point of interest
points <- read.csv(file.path(data_path, "poa_points_of_interest.csv"))
origin <- points[2,]

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

# estimate polygon-based isochrone from origin
iso_poly <- isochrone(
  r5r_core,
  origins = origin,
  mode = "walk",
  polygon_output = TRUE,
  departure_datetime = departure_datetime,
  cutoffs = seq(0, 120, 30)
  )

head(iso_poly)


# estimate line-based isochrone from origin
iso_lines <- isochrone(
  r5r_core,
  origins = origin,
  mode = "walk",
  polygon_output = FALSE,
  departure_datetime = departure_datetime,
  cutoffs = seq(0, 100, 25)
  )

head(iso_lines)


# plot colors
colors <- c('#ffe0a5','#ffcb69','#ffa600','#ff7c43','#f95d6a',
            '#d45087','#a05195','#665191','#2f4b7c','#003f5c')

# polygons
ggplot() +
  geom_sf(data=iso_poly, aes(fill=factor(isochrone))) +
  scale_fill_manual(values = colors) +
  theme_minimal()

# lines
ggplot() +
  geom_sf(data=iso_lines, aes(color=factor(isochrone))) +
  scale_color_manual(values = colors) +
  theme_minimal()

stop_r5(r5r_core)

Java object to data.table

Description

Converts a Java object returned by r5r_core to an R data.table

Usage

java_to_dt(obj)

Arguments

obj

A Java Object reference

Value

An R data.table

Calculate travel time and monetary cost Pareto frontier

Description

Fast computation of travel time and monetary cost Pareto frontier between origin and destination pairs.

Usage

pareto_frontier(
  r5r_core,
  origins,
  destinations,
  mode = c("WALK", "TRANSIT"),
  mode_egress = "WALK",
  departure_datetime = Sys.time(),
  time_window = 10L,
  percentiles = 50L,
  max_walk_time = Inf,
  max_bike_time = Inf,
  max_car_time = Inf,
  max_trip_duration = 120L,
  fare_structure = NULL,
  fare_cutoffs = -1L,
  walk_speed = 3.6,
  bike_speed = 12,
  max_rides = 3,
  max_lts = 2,
  n_threads = Inf,
  verbose = FALSE,
  progress = FALSE,
  output_dir = NULL
)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

origins, destinations

Either a ⁠POINT sf⁠ object with WGS84 CRS, or a data.frame containing the columns id, lon and lat.

mode

A character vector. The transport modes allowed for access, transfer and vehicle legs of the trips. Defaults to WALK. Please see details for other options.

mode_egress

A character vector. The transport mode used after egress from the last public transport. It can be either WALK, BICYCLE or CAR. Defaults to WALK. Ignored when public transport is not used.

departure_datetime

time_window

percentiles

An integer vector (max length of 5). Specifies the percentile to use when returning travel time estimates within the given time window. Please note that this parameter is applied to the travel time estimates only (e.g. if the 25th percentile is specified, and the output between A and B is 15 minutes and 10 dollars, 25% of all trips cheaper than 10 dollars taken between these points are shorter than 15 minutes). Defaults to 50, returning the median travel time. If a vector with length bigger than 1 is passed, the output contains an additional column that specifies the percentile of each travel time and monetary cost combination. Due to upstream restrictions, only 5 percentiles can be specified at a time. For more details, please see R5 documentation at https://docs.conveyal.com/analysis/methodology#accounting-for-variability.

max_walk_time

max_bike_time

max_car_time

max_trip_duration

An integer. The maximum trip duration in minutes. Defaults to 120 minutes (2 hours).

fare_structure

fare_cutoffs

A numeric vector. The monetary cutoffs that should be considered when calculating the Pareto frontier. Most of the time you'll want this parameter to be the combination of all possible fares listed in you fare_structure. Choosing a coarse distribution of cutoffs may result in many different trips falling within the same cutoff. For example, if you have two different routes in your GTFS, one costing $3 and the other costing $4, and you set this parameter to 5, the output will tell you the fastest trips that costed up to $5, but you won't be able to identify which route was used to complete such trips. In this case, it would be more beneficial to set the parameter as c(3, 4) (you could also specify combinations of such values, such as 6, 7, 8 and so on, because a transit user could hypothetically benefit from making transfers between the available routes).

walk_speed

A numeric. Average walk speed in km/h. Defaults to 3.6 km/h.

bike_speed

A numeric. Average cycling speed in km/h. Defaults to 12 km/h.

max_rides

An integer. The maximum number of public transport rides allowed in the same trip. Defaults to 3.

max_lts

n_threads

An integer. The number of threads to use when running the router in parallel. Defaults to use all available threads (Inf).

verbose

progress

output_dir

Value

A data.table with the travel time and monetary cost Pareto frontier between the specified origins and destinations. An additional column identifying the travel time percentile is present if more than one value was passed to percentiles. Origin and destination pairs whose trips couldn't be completed within the maximum travel time using less money than the specified monetary cutoffs are not returned in the data.table. If output_dir is not NULL, the function returns the path specified in that parameter, in which the .csv files containing the results are saved.

Transport modes

R5 allows for multiple combinations of transport modes. The options include:

Transit modes: TRAM, SUBWAY, RAIL, BUS, FERRY, CABLE_CAR, GONDOLA, FUNICULAR. The option TRANSIT automatically considers all public transport modes available.
Non transit modes: WALK, BICYCLE, CAR, BICYCLE_RENT, CAR_PARK.

Level of Traffic Stress (LTS)

LTS 1: Tolerable for children. This includes low-speed, low-volume streets, as well as those with separated bicycle facilities (such as parking-protected lanes or cycle tracks).
LTS 2: Tolerable for the mainstream adult population. This includes streets where cyclists have dedicated lanes and only have to interact with traffic at formal crossing.
LTS 3: Tolerable for "enthused and confident" cyclists. This includes streets which may involve close proximity to moderate- or high-speed vehicular traffic.
LTS 4: Tolerable only for "strong and fearless" cyclists. This includes streets where cyclists are required to mix with moderate- to high-speed vehicular traffic.

For advanced users, you can provide custom LTS values by adding a tag ⁠<key = "lts">⁠ to the osm.pbf file.

Datetime parsing

Routing algorithm

Delling, D., Pajor, T., & Werneck, R. F. (2015). Round-based public transit routing. Transportation Science, 49(3), 591-604. doi:10.1287/trsc.2014.0534
Conway, M. W., & Stewart, A. F. (2019). Getting Charlie off the MTA: a multiobjective optimization method to account for cost constraints in public transit accessibility metrics. International Journal of Geographical Information Science, 33(9), 1759-1787. doi:10.1080/13658816.2019.1605075

Examples


library(r5r)

# build transport network
data_path <- system.file("extdata/poa", package = "r5r")
r5r_core <- setup_r5(data_path = data_path)

# load origin/destination points
points <- read.csv(file.path(data_path, "poa_hexgrid.csv"))[1:5,]

# load fare structure object
fare_structure_path <- system.file(
  "extdata/poa/fares/fares_poa.zip",
  package = "r5r"
)
fare_structure <- read_fare_structure(fare_structure_path)

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

pf <- pareto_frontier(
  r5r_core,
  origins = points,
  destinations = points,
  mode = c("WALK", "TRANSIT"),
  departure_datetime = departure_datetime,
  fare_structure = fare_structure,
  fare_cutoffs = c(4.5, 4.8, 9, 9.3, 9.6)
)
head(pf)

stop_r5(r5r_core)

Manage cached files from the r5r package

Description

Manage cached files from the r5r package

Usage

r5r_cache(list_files = TRUE, delete_file = NULL)

Arguments

list_files

Logical. Whether to print a message with the address of r5r JAR files cached locally. Defaults to TRUE.

delete_file

String. The file name (basename) of a JAR file cached locally that should be deleted. Defaults to NULL, so that no file is deleted. If delete_file = "all", then all cached files are deleted.

Value

A message indicating which file exist and/or which ones have been deleted from local cache directory.

Examples


# download r5 JAR
r5r::download_r5()

# list all files cached
r5r_cache(list_files = TRUE)

# delete r5 JAR
r5r_cache(delete_file = 'r5-v7.0')

Generate an r5r situation report to help debug errors

Description

The function reports a list with the following information:

The package version of {r5r} in use.
The installed version of R5.jar.
The Java version in use.
The amount of memory set to Java through the java.parameters option.
The user's Session Info.

Usage

r5r_sitrep()

Value

A list with information of the versions of the r5r package, Java and R5 Jar in use, the memory set to Java and user's Session Info.

Examples


r5r_sitrep()

Read a fare structure object from a file

Description

Read a fare structure object from a file

Usage

read_fare_structure(file_path, encoding = "UTF-8")

Arguments

file_path

A path pointing to a fare structure with a .zip extension.

encoding

A string. Passed to data.table::fread(), defaults to "UTF-8". Other possible options are "unknown" and "Latin-1". Please note that this is not used to re-encode the input, but to enable handling encoded strings in their native encoding.

Value

A fare structure object.

Examples


path <- system.file("extdata/poa/fares/fares_poa.zip", package = "r5r")
fare_structure <- read_fare_structure(path)

Set breakdown

Description

Sets whether travel time matrices should include detailed trip information or not.

Usage

set_breakdown(r5r_core, breakdown)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

breakdown

A logical.

Value

Invisibly returns TRUE.

Set cutoffs

Description

Sets the cutoffs used when calculating accessibility.

Usage

set_cutoffs(r5r_core, cutoffs, decay_function)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

cutoffs

A numeric vector.

decay_function

A string, the name of the decay function.

Value

Invisibly returns TRUE.

Set expanded travel times

Description

Sets whether travel time matrices should return results for each minute of the specified time window.

Usage

set_expanded_travel_times(r5r_core, expanded)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

expanded

A logical.

Value

Invisibly returns TRUE.

Set monetary cutoffs

Description

Sets the monetary cutoffs that should be considered when calculating the Pareto frontier.

Usage

set_fare_cutoffs(r5r_core, fare_cutoffs)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

fare_cutoffs

A path.

Value

Invisibly returns TRUE.

Set the fare structure used when calculating transit fares

Description

Sets the fare structure used by our "generic" fare calculator. A value of NULL is passed to fare_structure by the upstream routing and accessibility functions when fares are not to be calculated.

Usage

set_fare_structure(r5r_core, fare_structure)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

fare_structure

Value

Invisibly returns TRUE.

Set max fare

Description

Sets the max fare allowed when calculating transit fares.

Usage

set_max_fare(r5r_core, max_fare)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

max_fare

A number.

Value

Invisibly returns TRUE.

Set max Level of Transit Stress (LTS)

Description

Set max Level of Transit Stress (LTS)

Usage

set_max_lts(r5r_core, max_lts)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

max_lts

A number (between 1 and 4). The maximum level of traffic stress that cyclists will tolerate. A value of 1 means cyclists will only travel through the quietest streets, while a value of 4 indicates cyclists can travel through any road.

Value

Invisibly returns TRUE.

Set max number of rides

Description

Sets the maximum number of rides a trip can use in R5.

Usage

set_max_rides(r5r_core, max_rides)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

max_rides

A number. The max number of public transport rides allowed in the same trip. Passed from routing function.

Value

No return value, called for side effects.

Set number of Monte Carlo draws

Description

Sets the number of Monte Carlo draws to be used by R5.

Usage

set_monte_carlo_draws(r5r_core, draws_per_minute, time_window)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

draws_per_minute

A number.

time_window

A number.

Value

Invisibly returns TRUE.

Set number of threads

Description

Sets the number of threads to be used by the r5r .jar.

Usage

set_n_threads(r5r_core, n_threads)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

n_threads

A number, passed from the function above.

Value

Invisibly returns TRUE.

Set output directory

Description

Sets whether r5r should save output to a specified directory.

Usage

set_output_dir(r5r_core, output_dir)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

output_dir

A path.

Value

Invisibly returns TRUE.

Set percentiles

Description

Sets the percentiles to be used by R5.

Usage

set_percentiles(r5r_core, percentiles)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

percentiles

An integer vector of maximum length 5.

Value

Invisibly returns TRUE.

Set progress argument

Description

Indicates whether or not a progress counter must be printed during computations. Applies to all routing functions.

Usage

set_progress(r5r_core, progress)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

progress

A logical, passed from the function above.

Value

Invisibly returns TRUE.

Set walk and bike speed

Description

This function receives the walk and bike 'speed' inputs in Km/h from routing functions above and converts them to meters per second, which is then used to set these speed profiles in r5r JAR.

Usage

set_speed(r5r_core, speed, mode)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

speed

A number representing the speed in km/h.

mode

A string. Either "bike" or "walk".

Value

Invisibly returns TRUE.

Set suboptimal minutes

Description

Sets the number of suboptimal minutes considered in detailed_itineraries() routing. From R5 documentation: "This parameter compensates for the fact that GTFS does not contain information about schedule deviation (lateness). The min-max travel time range for some trains is zero, since the trips are reported to always have the same timings in the schedule. Such an option does not overlap (temporally) its alternatives, and is too easily eliminated by an alternative that is only marginally better. We want to effectively push the max travel time of alternatives out a bit to account for the fact that they don't always run on schedule".

Usage

set_suboptimal_minutes(
  r5r_core,
  suboptimal_minutes,
  fare_structure,
  shortest_path
)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

suboptimal_minutes

A number.

fare_structure

shortest_path

A logical.

Value

Invisibly returns TRUE.

Set time window

Description

Sets the time window to be used by R5.

Usage

set_time_window(r5r_core, time_window)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

time_window

A number.

Value

Invisibly returns TRUE.

Set verbose argument

Description

Indicates whether R5 should output informative messages or not. Please note that R5 error messages are still reported even when verbose is FALSE.

Usage

set_verbose(r5r_core, verbose)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

verbose

A logical, passed from function above.

Value

Invisibly returns TRUE.

Setup a fare structure to calculate the monetary costs of trips

Description

Creates a basic fare structure that describes how transit fares should be calculated in travel_time_matrix(), expanded_travel_time_matrix(), accessibility() and pareto_frontier(). This fare structure can be manually edited and adjusted to the existing rules in your study area, as long as they stick to some basic premises. Please see fare structure vignette for more information on how the fare structure works: vignette("fare_structure", package = "r5r").

Usage

setup_fare_structure(
  r5r_core,
  base_fare,
  by = "MODE",
  debug_path = NULL,
  debug_info = NULL
)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

base_fare

A numeric. A base value used to populate the fare structure.

by

A string. Describes how fare_types (a classification we created to assign fares to different routes) are distributed among routes. Possible values are MODE, AGENCY and GENERIC. MODE is used when the mode is what determines the price of a route (e.g. if all the buses of a given city cost $5). AGENCY is used when the agency that operates each route is what determines its price (i.e. when two different routes/modes operated by a single agency cost the same; note that you can also use AGENCY_NAME, if the agency_ids listed in your GTFS cannot be easily interpreted). GENERIC is used when all the routes cost the same. Please note that this classification can later be edited to better suit your needs (when, for example, two types of buses cost the same, but one offers discounts after riding the subway and the other one doesn't), but this parameter may save you some work.

debug_path

Either a path to a .csv file or NULL. When NULL (the default), fare debugging capabilities are disabled - i.e. there's no way to check if the fare calculation is correct. When a path is provided, r5r saves different itineraries and their respective fares to the specified file. How each itinerary is described is controlled by debug_info.

debug_info

Either a string (when debug_path is a path) or NULL (the default). Doesn't have any effect if debug_path is NULL. When a string, accepts the values MODE, ROUTE and MODE_ROUTE. These values dictates how itinerary information is written to the output. Let's suppose we have an itinerary composed by two transit legs: first a subway leg whose route_id is 001, and then a bus legs whose route_id is 007. If debug_info is MODE, then this itinerary will be described as SUBWAY|BUS. If ROUTE, as 001|007. If MODE_ROUTE, as ⁠SUBWAY 001|BUS 007⁠. Please note that the final debug information will contain not only the itineraries that were in fact used in the itineraries returned in travel_time_matrix(), accessibility() and pareto_frontier(), but all the itineraries that R5 checked when calculating the routes. This imposes a performance penalty when tracking debug information (but has the positive effect of returning a larger sample of itineraries, which might help finding some implementation issues on the fare structure).

Value

A fare structure object.

Examples


library(r5r)

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

fare_structure <- setup_fare_structure(r5r_core, base_fare = 5)

# to debug fare calculation
fare_structure <- setup_fare_structure(
  r5r_core,
  base_fare = 5,
  debug_path = "fare_debug.csv",
  debug_info = "MODE"
)

fare_structure$debug_settings

# debugging can be manually turned off by setting output_file to ""
fare_structure$debug_settings <- ""

Create a transport network used for routing in R5

Description

Builds a multimodal transport network used for routing in R5, combining multiple data inputs present in the directory where the network should be saved to. The directory must contain only one street network file (in .osm.pbf format). It may optionally contain one or more public transport GTFS feeds (in GTFS.zip format, where GTFS is the name of your feed), when used for public transport routing, and a .tif file describing the elevation profile of the study area. If there is more than one GTFS feed in the directory, all feeds are merged. If there is already a 'network.dat' file in the directory, the function will simply read it and load it to memory (unless specified not to do so).

Usage

setup_r5(
  data_path,
  verbose = FALSE,
  temp_dir = FALSE,
  elevation = "TOBLER",
  overwrite = FALSE
)

Arguments

data_path

A string pointing to the directory where data inputs are stored and where the built network.dat will be saved.

verbose

temp_dir

A logical. Whether the R5 Jar file should be saved to a temporary directory. Defaults to FALSE.

elevation

A string. The name of the impedance function to be used to calculate impedance for walking and cycling based on street slopes. Available options include TOBLER (Default) and MINETTI, or NONE to ignore elevation. R5 loads elevation data from .tif files saved inside the data_path directory. See more info in the Details below.

overwrite

A logical. Whether to overwrite an existing network.dat or to use a cached file. Defaults to FALSE (i.e. use a cached network).

Value

An rJava object to connect with R5 routing engine.

Details

More information about the TOBLER and MINETTI options to calculate the effects of elevation on travel times can be found in the references below:

Campbell, M. J., et al (2019). Using crowdsourced fitness tracker data to model the relationship between slope and travel rates. Applied geography, 106, 93-107. doi:10.1016/j.apgeog.2019.03.008.
Minetti, A. E., et al (2002). Energy cost of walking and running at extreme uphill and downhill slopes. Journal of applied physiology. doi:10.1152/japplphysiol.01177.2001.
Tobler, W. (1993). Three presentations on geographical analysis and modeling: Non-isotropic geographic modeling speculations on the geometry of geography global spatial analysis. Technical Report. National center for geographic information and analysis. 93 (1). https://escholarship.org/uc/item/05r820mz.

Examples


library(r5r)

# directory with street network and gtfs files
data_path <- system.file("extdata/poa", package = "r5r")

r5r_core <- setup_r5(data_path)

Stop running r5r core

Description

Stops running r5r cores.

Usage

stop_r5(...)

Arguments

...

r5r_core objects currently running. By default, if no cores are supplied all running cores are stopped.

Value

No return value, called for side effects.

Examples


library(r5r)

path <- system.file("extdata/poa", package = "r5r")

r5r_core <- setup_r5(path)

stop_r5(r5r_core)

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

Description

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

Usage

street_network_to_sf(r5r_core)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

Value

A list with two components of a street network in sf format: vertices (POINT) and edges (LINESTRING).

Examples


library(r5r)

# build transport network
path <- system.file("extdata/poa", package = "r5r")
r5r_core <- setup_r5(path)

# extract street network from r5r_core
street_net <- street_network_to_sf(r5r_core)

stop_r5(r5r_core)

Extract transit network in sf format

Description

Extracts the transit network from a network.dat file (built with setup_r5()) in sf format.

Usage

transit_network_to_sf(r5r_core)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

Value

A list with two components of a transit network in sf format: route shapes (LINESTRING) and transit stops (POINT). The same route_id/short_name might appear with different geometries. This occurs when the same route is associated to more than one shape_ids in the GTFS feed used to create the transit network. Some transit stops might be returned with geometry ⁠POINT EMPTY⁠ (i.e. missing spatial coordinates). This may occur when a transit stop is not snapped to the road network, possibly because the GTFS feed used to create the transit network covers an area larger than the .osm.pbf input data.

Examples


library(r5r)

# build transport network
path <- system.file("extdata/poa", package = "r5r")
r5r_core <- setup_r5(path)

# extract transit network from r5r_core
transit_net <- transit_network_to_sf(r5r_core)

stop_r5(r5r_core)

Calculate travel time matrix between origin destination pairs

Description

Fast computation of travel time estimates between one or multiple origin destination pairs.

Usage

travel_time_matrix(
  r5r_core,
  origins,
  destinations,
  mode = "WALK",
  mode_egress = "WALK",
  departure_datetime = Sys.time(),
  time_window = 10L,
  percentiles = 50L,
  fare_structure = NULL,
  max_fare = Inf,
  max_walk_time = Inf,
  max_bike_time = Inf,
  max_car_time = Inf,
  max_trip_duration = 120L,
  walk_speed = 3.6,
  bike_speed = 12,
  max_rides = 3,
  max_lts = 2,
  draws_per_minute = 5L,
  n_threads = Inf,
  verbose = FALSE,
  progress = FALSE,
  output_dir = NULL
)

Arguments

r5r_core

An object to connect with the R5 routing engine, created with setup_r5().

origins, destinations

Either a ⁠POINT sf⁠ object with WGS84 CRS, or a data.frame containing the columns id, lon and lat.

mode

A character vector. The transport modes allowed for access, transfer and vehicle legs of the trips. Defaults to WALK. Please see details for other options.

mode_egress

A character vector. The transport mode used after egress from the last public transport. It can be either WALK, BICYCLE or CAR. Defaults to WALK. Ignored when public transport is not used.

departure_datetime

time_window

percentiles

An integer vector (max length of 5). Specifies the percentile to use when returning travel time estimates within the given time window. For example, if the 25th travel time percentile between A and B is 15 minutes, 25% of all trips taken between these points within the specified time window are shorter than 15 minutes. Defaults to 50, returning the median travel time. If a vector with length bigger than 1 is passed, the output contains an additional column for each percentile specifying the percentile travel time estimate. each estimate. Due to upstream restrictions, only 5 percentiles can be specified at a time. For more details, please see R5 documentation at https://docs.conveyal.com/analysis/methodology#accounting-for-variability.

fare_structure

max_fare

A number. The maximum value that trips can cost when calculating the fastest journey between each origin and destination pair.

max_walk_time

max_bike_time

max_car_time

max_trip_duration

An integer. The maximum trip duration in minutes. Defaults to 120 minutes (2 hours).

walk_speed

A numeric. Average walk speed in km/h. Defaults to 3.6 km/h.

bike_speed

A numeric. Average cycling speed in km/h. Defaults to 12 km/h.

max_rides

An integer. The maximum number of public transport rides allowed in the same trip. Defaults to 3.

max_lts

draws_per_minute

n_threads

An integer. The number of threads to use when running the router in parallel. Defaults to use all available threads (Inf).

verbose

progress

output_dir

Value

A data.table with travel time estimates (in minutes) between origin and destination pairs. Pairs whose trips couldn't be completed within the maximum travel time and/or whose origin is too far from the street network are not returned in the data.table. If output_dir is not NULL, the function returns the path specified in that parameter, in which the .csv files containing the results are saved.

Transport modes

R5 allows for multiple combinations of transport modes. The options include:

Transit modes: TRAM, SUBWAY, RAIL, BUS, FERRY, CABLE_CAR, GONDOLA, FUNICULAR. The option TRANSIT automatically considers all public transport modes available.
Non transit modes: WALK, BICYCLE, CAR, BICYCLE_RENT, CAR_PARK.

Level of Traffic Stress (LTS)

LTS 1: Tolerable for children. This includes low-speed, low-volume streets, as well as those with separated bicycle facilities (such as parking-protected lanes or cycle tracks).
LTS 2: Tolerable for the mainstream adult population. This includes streets where cyclists have dedicated lanes and only have to interact with traffic at formal crossing.
LTS 3: Tolerable for "enthused and confident" cyclists. This includes streets which may involve close proximity to moderate- or high-speed vehicular traffic.
LTS 4: Tolerable only for "strong and fearless" cyclists. This includes streets where cyclists are required to mix with moderate- to high-speed vehicular traffic.

For advanced users, you can provide custom LTS values by adding a tag ⁠<key = "lts">⁠ to the osm.pbf file.

Datetime parsing

Routing algorithm

Conway, M. W., Byrd, A., & van der Linden, M. (2017). Evidence-based transit and land use sketch planning using interactive accessibility methods on combined schedule and headway-based networks. Transportation Research Record, 2653(1), 45-53. doi:10.3141/2653-06
Delling, D., Pajor, T., & Werneck, R. F. (2015). Round-based public transit routing. Transportation Science, 49(3), 591-604. doi:10.1287/trsc.2014.0534

Examples


library(r5r)

# build transport network
data_path <- system.file("extdata/poa", package = "r5r")
r5r_core <- setup_r5(data_path)

# load origin/destination points
points <- read.csv(file.path(data_path, "poa_points_of_interest.csv"))

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

ttm <- travel_time_matrix(
  r5r_core,
  origins = points,
  destinations = points,
  mode = c("WALK", "TRANSIT"),
  departure_datetime = departure_datetime,
  max_trip_duration = 60
)
head(ttm)

# using a larger time window
ttm <- travel_time_matrix(
  r5r_core,
  origins = points,
  destinations = points,
  mode = c("WALK", "TRANSIT"),
  departure_datetime = departure_datetime,
  time_window = 30,
  max_trip_duration = 60
)
head(ttm)

# selecting different percentiles
ttm <- travel_time_matrix(
  r5r_core,
  origins = points,
  destinations = points,
  mode = c("WALK", "TRANSIT"),
  departure_datetime = departure_datetime,
  time_window = 30,
  percentiles = c(25, 50, 75),
  max_trip_duration = 60
)
head(ttm)

# use a fare structure and set a max fare to take monetary constraints into
# account
fare_structure <- read_fare_structure(
  file.path(data_path, "fares/fares_poa.zip")
)
ttm <- travel_time_matrix(
  r5r_core,
  origins = points,
  destinations = points,
  mode = c("WALK", "TRANSIT"),
  departure_datetime = departure_datetime,
  fare_structure = fare_structure,
  max_fare = 5,
  max_trip_duration = 60,
)
head(ttm)

stop_r5(r5r_core)

Write a fare structure object to disk

Description

Writes a fare structure object do disk. Fare structure is saved as a collection of .csv files inside a .zip file.

Usage

write_fare_structure(fare_structure, file_path)

Arguments

fare_structure

file_path

A path to a .zip file. Where the fare structure should be written to.

Value

The path passed to file_path, invisibly.

Examples


library(r5r)

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

fare_structure <- setup_fare_structure(r5r_core, base_fare = 5)

tmpfile <- tempfile("sample_fare_structure", fileext = ".zip")
write_fare_structure(fare_structure, tmpfile)

r5r: Rapid Realistic Routing with 'R5'

Description

Usage

Author(s)

See Also

Calculate access to opportunities

Description

Usage

Arguments

Value

Decay functions

Transport modes

Level of Traffic Stress (LTS)

Datetime parsing

Routing algorithm

Examples

Assert fare structure

Description

Usage

Arguments

Value

Assign decay function and parameter values

Description

Usage

Arguments

Value

See Also

Check and convert POSIXct objects to strings

Description

Usage

Arguments

Value

See Also

Assign drop geometry

Description

Usage

Arguments

Value

See Also

Assign max street time from walk/bike distance and speed

Description

Usage

Arguments

Value

See Also

Assign max trip duration

Description

Usage

Arguments

Value

See Also

Check and select transport modes from user input

Description

Usage

Arguments

Value

See Also

Assign opportunities data

Description

Usage

Arguments

Value

See Also

Assign osm_link_ids

Description

Usage

Arguments

Value

See Also

Check and convert origin and destination inputs

Description

Usage

Arguments

Value

See Also

Assign shortest path

Description

Usage

Arguments

Value

Download `R5.jar`