-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathREADME.Rmd
197 lines (156 loc) · 6.42 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
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
---
output: github_document
---
<!-- README.md is generated from README.Rmd-->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/"
)
```
<p align="center">
<a href="https://github.com/sodascience/osmenrich">
<img width="30%" height="30%" src="man/figures/logo.png">
</a>
</p>
# osmenrich: enrich geocoded data using OpenStreetMap
<!-- badges: start -->
[](https://github.com/sodascience/osmenrich/actions)
[](https://zenodo.org/badge/latestdoi/337555188)
[](https://www.repostatus.org/#active)
<!-- badges: end -->
The goal of `osmenrich` is to easily enrich geocoded data
(`latitude`/`longitude`) with geographic features from OpenStreetMap (OSM).
The main language of the package is `R` and this package is designed to work
with the [`sf`](https://r-spatial.github.io/sf/) and [`osmdata`](
https://cran.r-project.org/web/packages/osmdata/vignettes/osmdata.html)
packages for collecting and manipulating geodata.
## Installation
To install the package, you first need to have the `remotes` package installed.
If you do not have this package yet, please install it first with:
```r
install.packages("remotes")
```
If you do have this package, due to recent changes in GitHub's naming of branches,
please make sure you have the latest version of `remotes` or at least version
`2.2`.
Once you did this, to continue the installation of the `osmenrich` package, run:
```r
remotes::install_github("sodascience/osmenrich@main")
```
or, for the development version, run:
```r
remotes::install_github("sodascience/osmenrich@develop")
```
This will use the default public APIs for OSM data and routing (for computing
driving/walking distances and durations). __Do not use `osmenrich` with
default APIs for large datasets!__ If you want to learn how to use `osmenrich`
for large queries follow the instructions in section
[Local API Setup](#local-api-setup) below.
## Usage
### Simple enrichment example
Let's enrich a spatial (`sf`) dataset (`sf_example`) with the number of waste
baskets in a radius of 500 meters from each of the point specified in a
dataset:
```r
# Import libraries
library(tidyverse)
library(sf)
library(osmenrich)
# Create an example dataset to enrich
sf_example <-
tribble(
~person, ~lat, ~lon,
"Alice", 52.12, 5.09,
"Bob", 52.13, 5.08,
) %>%
sf::st_as_sf(
coords = c("lon", "lat"),
crs = 4326
)
# Print it
sf_example
#> Simple feature collection with 2 features and 1 field
#> geometry type: POINT
#> dimension: XY
#> bbox: xmin: 5.08 ymin: 52.12 xmax: 5.09 ymax: 52.13
#> CRS: EPSG:4326
#> # A tibble: 2 x 2
#> person geometry
#> * <chr> <POINT [°]>
#> 1 Alice (5.09 52.12)
#> 2 Bob (5.08 52.13)
```
To enrich the `sf_example` dataset with "waste baskets" in a 500m radius, you
can create a query using the `enrich_osm()` function. This function uses the
bounding box created by the points present in the example dataset and searches
for the specified `key = "amenity"` and `value = "waste_basket`. You can also add a
custom `name` for the newly created column and specify the radius (`r`) used
in the search. See
[Map Features on the website of OSM](https://wiki.openstreetmap.org/wiki/Map_features)
for a complete list of `key` and `value` combinations.
```r
# Simple OSMEnrich query
sf_example_enriched <- sf_example %>%
enrich_osm(
name = "n_waste_baskets",
key = "amenity",
value = "waste_basket",
r = 500
)
#> Downloading data for waste_baskets... Done.
#> Downloaded 147 points, 0 lines, 0 polygons, 0 mlines, 0 mpolygons.
#> Computing distance matrix for n_waste_baskets...Done.
```
The resulting enriched dataset `sf_example_enriched` is a `sf` object and can be printed as usual
to inspect the newly added column `n_waste_baskets`.
```r
sf_example_enriched
#> Simple feature collection with 2 features and 2 fields
#> geometry type: POINT
#> dimension: XY
#> bbox: xmin: 5.08 ymin: 52.12 xmax: 5.09 ymax: 52.13
#> geographic CRS: WGS 84
#> # A tibble: 2 x 3
#> person geometry n_waste_baskets
#> * <chr> <POINT [°]> <int>
#> 1 Alice (5.09 52.12) 75
#> 2 Bob (5.08 52.13) 1
```
The waste baskets column is now the result of summing all the wastebaskets in a 500 meter radius for Alice and Bob:
## Local API setup
OSM enrichment can ask for a lot of data, which can overload public APIs. If
you intend to enrich large amounts of data or compute routing distances (e.g.,
driving duration) between many points, you should set up a local API endpoint.
Multiple `docker-compose` workflows for doing this are avaialble in the separate
[osmenrich_docker
repository](https://github.com/sodascience/osmenrich_docker). Use the `README`
in the repository to select the workflow that fits your desired outcome.
<img src="man/figures/docker.png" alt="Docker logo" width="250px"/>
<!-- CONTRIBUTING -->
## Contributing
Contributions are what make the open source community an amazing place to
learn, inspire, and create. Any contributions you make are **greatly
appreciated**.
Please refer to the [CONTRIBUTING](https://github.com/sodascience/osmenrich/blob/main/CONTRIBUTING.md)
file for more information on issues and pull requests.
## License and citation
The `osmenrich` package is published under the MIT license. When using
`osmenrich` for academic work, please cite:
```
van Kesteren, Erik-Jan, Vida, Leonardo, de Bruin, Jonathan, & Oberski, Daniel. (2021, February 11).
Enrich sf Data with Geographic Features from OpenStreetMaps (Version v1.0). Zenodo. http://doi.org/10.5281/zenodo.4534188
```
<!-- CONTACT -->
## Contact
This package is developed and maintained by the [ODISSEI Social Data Science
(SoDa)](https://odissei-data.nl/nl/soda/) team.
Do you have questions, suggestions, or remarks? File an issue in the issue
tracker or feel free to contact [Erik-Jan van
Kesteren](https://github.com/vankesteren)
([@ejvankesteren](https://twitter.com/ejvankesteren)) or [Leonardo
Vida](https://github.com/leonardovida)
([@leonardojvida](https://twitter.com/leonardojvida))
<img src="man/figures/word_colour-l.png" alt="SoDa logo" width="250px"/>