Pairwise routing

ors_pairwise calculates the pairwise routing distance between two datasets using the Directions service from ORS. In other words, routes are computed between the ith row of src and dst, respectively.

ors_shortest_distances is a wrapper around ors_pairwise that matches each point of the source dataset to a destination dataset and then extracts the route with the shortest distance.

Usage

ors_pairwise(
  src,
  dst,
  profile = NULL,
  units = c("m", "km", "mi"),
  geometry = FALSE,
  progress = FALSE,
  instance = NULL,
  ...,
  params = NULL
)

ors_shortest_distances(
  src,
  dst,
  group = NULL,
  profile = NULL,
  units = c("m", "km", "mi"),
  geometry = FALSE,
  instance = NULL,
  ...,
  proximity_type = c("duration", "distance"),
  progress = TRUE
)

Arguments

src

[sf/sfc]

Source dataset containing point geometries that should be routed from.

dst

[sf/sfc]

Destination dataset containing point geometries that should be routed to. For ors_shortest_distances, the destination argument can also be a dataframe containing a grouping column specified by the group argument that indicates which destinations refer to which row in the source dataset (as returned by group_by_proximity). This is recommended for large datasets because passing a plain sf dataframe routes from each source point to each point in the entire destination dataset.

profile

[character]

Means of transport as supported by OpenRouteService. Defaults to the first profile in a call to get_profiles. For ors_shortest_distances, profile can be a character vector, for all other functions it needs to be a character scalar. For details on all profiles, refer to the backend reference.

units

[character]

Distance unit for distance calculations ("m", "km" or "mi")

geometry

[logical]

If TRUE, returns a sf object containing route geometries. If FALSE, returns route distance measures. Defaults to FALSE, to increase performance.

progress

[logical]

Whether to show a progress bar for longer operations.

instance

[ors_instance]

Object of an OpenRouteService instance that should be used for route computations. It is recommended to use ors_instance to set an instance globally. This argument should only be used if activating an instance globally is not feasible.

...

Additional arguments passed to the ORS API. Convenience way to directly pass arguments of ors_params.

params

List of additional arguments passed to the ORS API. See ors_params for details.

group

[character/numeric]

Column name or index providing a grouping column that indicates which row in the destination dataset corresponds to which row in the source dataset (as in the output of group_by_proximity). Providing a grouping column can considerably reduce the processing load for larger datasets.

proximity_type

[character]

Type of proximity that the calculations should be based on. If distance, the shortest physical distance will be calculated and if duration, the shortest temporal distance will be calculated.

Value

ors_pairwise returns a dataframe with distances and travel durations between source and destination. Distances are specified in the unit given by the units arguments and durations are specified in seconds.

ors_shortest_distances returns a dataframe containing distances, travel durations and the index number of the point of interest with the shortest routing distance to the respective place of the source dataset.

Depending on the geometry argument, the output of both functions can either be simple dataframes or objects of class sf containing the linestring geometries of the respective routes.

Details

For ors_pairwise, the profile argument supports only length-1 vectors while ors_shortest_distances supports multiple profiles. ors_shortest_distances finds the shortest route for each source point and each profile, respectively.

Responses are kept as small as possible by automatically setting the navigation parameter to FALSE. Pairwise computations only exploit route summary statistics and do not benefit from any extra information.

Error handling

Since ors_pairwise is supposed to conduct a lot of calculations in one go, errors might occur even in well-conceived service setups. In order to make debugging less painful, errors do not tear down the whole process. They are saved to an environment and issue a warning containing the indices of the routes in question. After the process has finished, they can be accessed by calling last_ors_conditions. Specific routes can be examined by inspecting its route attributes using ors_inspect.

Examples

if (any_mounted() && ors_ready()) {
  data("pharma")

  set.seed(123)
  dest <- ors_sample(10)

  car <- "driving-car"
  bike <- "cycling-regular"

  # Running with sf objects
  ors_pairwise(pharma, dest, profile = car)

  # Running with coordinate pairs
  ors_pairwise(pharma, dest, profile = bike)

  # Returns route geometries
  ors_pairwise(
    pharma,
    dest,
    profile = car,
    geometry = TRUE
  )

  # Returns routes in kilometers
  ors_pairwise(
    pharma,
    dest,
    profile = bike,
    units = "km"
  )

  # Running with additional arguments
  ors_pairwise(
    pharma,
    dest,
    profile = car,
    continue_straight = TRUE,
    preference = "fastest"
  )

  # Finding shortest routes from each point in sample_a to sample_b
  ors_shortest_distances(pharma, dest, units = "km")

  # Pre-filter the nearest 5 destination points by Euclidian distance
  pois <- group_by_proximity(pharma, dest, n = 5)

  # Only route from each pharmacy to one of the closest 5 destination points
  # respectively. For larger datasets, this can increase performance.
  ors_shortest_distances(
    pharma,
    pois,
    group = ".group",
    geometry = TRUE
  )
}