-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathREADME.Rmd
177 lines (126 loc) · 7.17 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
---
output: github_document
---
# valh <img src="man/figures/logo.png" align="right" width="140"/>
[](https://CRAN.R-project.org/package=valh)
[](https://github.com/riatelab/valh/actions)
[](https://app.codecov.io/gh/riatelab/valh)
[](https://www.repostatus.org/#active)
[Valhalla](https://valhalla.github.io/valhalla/) is a routing service that is based on OpenStreetMap data.
This package provides an interface to the Valhalla API from R.
It allows you to query the Valhalla API for routes, isochrones, time-distance matrices,
nearest point on the road network, and elevation data.
This package relies on the usage of a [running Valhalla server](https://github.com/riatelab/valh?tab=readme-ov-file#installing-your-own-valhalla-server) (tested with versions 3.4.x and 3.5.x of Valhalla).
<img src="man/figures/map.png" align="center" width="500"/>
[code for the map](https://gist.github.com/rCarto/8dfba641b807c20c8cbf72ef8ed0c9c5)
## Features
- `vl_route()`: Get route between locations.
- `vl_matrix()`: Get travel time matrices between points.
- `vl_locate()`: Get the nearest point on the road network.
- `vl_elevation()`: Get elevation data at given location(s).
- `vl_isochrone()`: Get isochrone polygons.
- `vl_optimized_route()`: Get optimized route between locations.
- `vl_status()`: Get information on Valhalla service.
## Installation
- Stable version from CRAN:
```{r}
#| eval: false
install.packages("valh")
```
- Development version from the r-universe.
```{r, eval=FALSE}
install.packages("valh", repos = "https://riatelab.r-universe.dev")
```
## Demo
This is a short overview of the main features of `valh`. The dataset
used here is shipped with the package, it is a sample of 100 random
pharmacies in Berlin ([© OpenStreetMap
contributors](https://www.openstreetmap.org/copyright/en)) stored in a
[geopackage](https://www.geopackage.org/) file.
It demonstrates the use of `vl_matrix`, `vl_route` and `vl_elevation` functions.
```{r}
library(valh)
library(sf)
pharmacy <- st_read(system.file("gpkg/apotheke.gpkg", package = "valh"), quiet = TRUE)
pharmacy <- pharmacy[1:10, ]
```
One of valhalla's strengths is that it allows you to use dynamic costing options at query time.
For example, we can compare the travel time between each pharmacy by bicycle:
- with the default bicycle parameters (type of bicycle "hybrid" with an average speed
of 18 km/h and a propensity to use roads, alongside other vehicles, of 0.5 out of 1 - the
default value),
- with the road bicycle parameters (type of bicycle "road" with an average speed of
25 km/h and a propensity to use roads, alongside other vehicles, of 1 out of 1).
These costing options for each costing model ('auto', 'bicycle', etc.) are documented in
[Valhalla's documentation](https://valhalla.github.io/valhalla/api/turn-by-turn/api-reference/#costing-models).
```{r}
default_bike <- vl_matrix(loc = pharmacy, costing = "bicycle")
road_bike <- vl_matrix(loc = pharmacy, costing = "bicycle",
costing_options = list(bicycle_type = "Road", use_roads = "1"))
```
The object returned by `vl_matrix` is a list with 4 elements:
- `sources`: origin point coordinates,
- `destinations`: destination point coordinates,
- `distances` : distance matrix between sources and destinations,
- `durations` : travel time matrix between sources and destinations.
```{r}
default_bike$durations[1:5, 1:5]
road_bike$durations[1:5, 1:5]
```
We can see not only that travel times are different (which is to be expected,
given that we've changed the cyclist's default speed), but also that the path
taken are different (as a consequence of the change in preference for using
roads rather than cycle paths).
```{r}
default_bike$distances - road_bike$distances
```
We now calculate a route between two points, by foot, using the `vl_route`
function and calculate the elevation profile of the returned route, using
the `vl_elevation` function.
```{r, eval = FALSE}
p1 <- pharmacy[3, ]
p2 <- pharmacy[6, ]
route <- vl_route(p1, p2, costing = "pedestrian")
plot(st_geometry(route), main = "Route between 2 pharmacies")
plot(c(st_geometry(p1), st_geometry(p2)), pch = 21, cex = 2, add = TRUE)
```
```{r, echo=FALSE, fig.path="man/figures/README", fig.width=3, fig.height=4, }
p1 <- pharmacy[3, ]
p2 <- pharmacy[6, ]
route <- vl_route(p1, p2, costing = "pedestrian")
par(mar = c(0, 0, 2, 0))
# We plot the route and pharmacies
plot(st_geometry(route), main = "Route between 2 pharmacies")
plot(c(st_geometry(p1), st_geometry(p2)), pch = 21, cex = 2, add = TRUE)
```
```{r}
# We transform the LineString to Point geometries
pts_route <- sf::st_cast(st_geometry(route), "POINT")
elev <- vl_elevation(loc = pts_route, sampling_dist = 100)
```
The object returned is an sf object with a point for each location where the
altitude has been sampled and with the attributes 'distance' (the cumulative
distance to the first point) and 'height' (the altitude).
We can use it to plot the elevation profile of the route.
```{r, fig.width=7, fig.height=4, fig.path="man/figures/README"}
plot(as.matrix(st_drop_geometry(elev)), type = "l", lwd = 2, ylim = c(20, 70), asp = 100,
main = "Elevation Profile")
```
## Installing your own Valhalla server
We've included a [vignette](https://CRAN.R-project.org/package=valh/vignettes/install-valhalla.html) showing how to install
your own instance of Valhalla, either locally or on a remote server, using Docker.
## Motivation & Alternatives
The package is designed to provide an easy-to-use interface to the Valhalla routing service from R.
Special care has been taken to support multiple input formats,
and the package treats `sf` objects as first-class citizens in both input and output.
Additionally, we have tried to maintain a minimal number of dependencies.
This package offers an API that closely resembles that of the [`osrm`](https://github.com/riatelab/osrm)
package which provides an R interface to the OSRM routing service.
Note that there are other packages that provide an interface to Valhalla API from R :
- [valhallr](https://github.com/chris31415926535/valhallr/): This package is on CRAN. It provides access to some of Valhalla's services (*height*, *locate* and *optimized route* are notably missing). It depends on a number of rather heavy packages and it does not allow `sf` objects as input.
- [rvalhalla](https://github.com/Robinlovelace/rvalhalla): This package is not on CRAN. Although it can provide access to several Valhalla services, it only makes it easy to use two of them (*route* and *sources_to_target*). It does not accept `sf` objects as input.
## Community Guidelines
One can contribute to the package through [pull requests](https://github.com/riatelab/valh/pulls) and
report issues or ask questions [here](https://github.com/riatelab/valh/issues).
See the [CONTRIBUTING.md](https://github.com/riatelab/valh/blob/master/CONTRIBUTING.md)
file for detailed instructions.