Skip to content

Commit 3bd76ae

Browse files
J535D165leonardovidavankesteren
committed
Release of osmenrich package
Co-authored-by: Leonardo Vida <lleonardovida@gmail.com> Co-authored-by: Erik-Jan van Kesteren <erikjanvankesteren@pm.me>
0 parents  commit 3bd76ae

File tree

4 files changed

+184
-0
lines changed

4 files changed

+184
-0
lines changed

‎README.md

+184
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
<p align="center">
2+
<img src="man/figures/logo.png" width="250px"></img>
3+
<!-- badges: start
4+
<br/>
5+
<span>
6+
<a href="https://travis-ci.org/vankesteren/tensorsem"><img src="https://travis-ci.org/vankesteren/tensorsem.svg?branch=master"></img></a>
7+
<a href="https://zenodo.org/badge/latestdoi/168356695"><img src="https://zenodo.org/badge/168356695.svg" alt="DOI"></a>
8+
[![R build status](https://github.com/sodascience/osmenrich/workflows/R-CMD-check/badge.svg)](https://github.com/sodascience/osmenrich/actions)
9+
[![Codecov test coverage](https://codecov.io/gh/sodascience/osmenrich/branch/master/graph/badge.svg)](https://codecov.io/gh/sodascience/osmenrich?branch=master)
10+
</span>
11+
badges: end -->
12+
</p>
13+
<br/>
14+
15+
# Enrich geocoded data using openstreetmaps (Coming soon!!!)
16+
17+
![Github Action test](https://github.com/sodascience/osmenrich/workflows/.github/workflows/R-CMD-check.yaml/badge.svg)
18+
19+
The goal of `osmenrich` is to easily enrich geocoded data
20+
(`latitude`/`longitude`) with geographic features from OpenStreetMap (OSM).
21+
The main language of the package is `R` and this package is designed to work
22+
with the `sf` and `osmdata` packages for collecting and manipulating geodata.
23+
24+
## Installation
25+
26+
To install the package, run:
27+
28+
```r
29+
remotes::install_github("sodascience/osmenrich")
30+
```
31+
32+
or, for the development version, run:
33+
34+
```r
35+
remotes::install_github("sodascience/osmenrich@develop")
36+
```
37+
38+
This will use the default public APIs for OSM data and routing (for computing
39+
driving/walking distances and durations). __Do not use `osmenrich` with
40+
default APIs for large datasets!__ If you want to learn how to use `osmenrich`
41+
for large queries follow the instructions in section
42+
[Local API Setup](#local-api-setup) below.
43+
44+
## Usage
45+
46+
### Simple enrichment example
47+
48+
Let's enrich a spatial (`sf`) dataset (`sf_example`) with the number of waste
49+
baskets in a radius of 100 meters from each of the point specified in a
50+
dataset:
51+
52+
```r
53+
# Import libraries
54+
library(tidyverse)
55+
library(sf)
56+
library(osmdata)
57+
library(osmenrich)
58+
59+
# Create an example dataset to enrich
60+
sf_example <-
61+
tribble(
62+
~person, ~id, ~lat, ~lon, ~val,
63+
"Alice", 1, 52.12, 5.09, 5L,
64+
"Bob", 2, 52.13, 5.08, 2L
65+
) %>%
66+
sf::st_as_sf(coords = c("lon", "lat"), crs = 4326)
67+
68+
# Print it
69+
sf_example
70+
#> Simple feature collection with 2 features and 3 fields
71+
#> geometry type: POINT
72+
#> dimension: XY
73+
#> bbox: xmin: 5.08 ymin: 52.12 xmax: 5.09 ymax: 52.13
74+
#> CRS: EPSG:4326
75+
#> # A tibble: 2 x 4
76+
#> person id val geometry
77+
#> * <chr> <dbl> <int> <POINT [°]>
78+
#> 1 Alice 1 5 (5.09 52.12)
79+
#> 2 Bob 2 2 (5.08 52.13)
80+
```
81+
82+
To enrich the `sf_example` dataset with "waste baskets" in a 100m radius, we
83+
create a query using the `enrich_osm()` function. This function uses the
84+
bounding box created by the points present in the example dataset and searches
85+
for the specified `key = "amenity"` and `value = "waste_basket`. We also add a
86+
custom `name` for the newly created column and specify the radius (`r`) used
87+
in the search.
88+
89+
```r
90+
# Simple OSMEnrich query
91+
sf_example_simple <- sf_example %>%
92+
enrich_osm(
93+
name = "waste_baskets",
94+
key = "amenity",
95+
value = "waste_basket",
96+
r = 100
97+
)
98+
#> Downloading data for waste_baskets... Done.
99+
#> Downloaded 26 points, 0 lines, 0 polygons, 0 mlines, 0 mpolygons.
100+
#> Computing distance matrix for wastebaskets...Done.
101+
#> Adding waste_baskets to data.
102+
103+
```
104+
105+
The resulting enriched dataset is a `sf` object and can be printed as usual
106+
and we can inspect the newly added column `waste_baskets`.
107+
108+
```r
109+
sf_example_enriched
110+
#> Simple feature collection with 2 features and 4 fields
111+
#> geometry type: POINT
112+
#> dimension: XY
113+
#> bbox: xmin: 5.08 ymin: 52.12 xmax: 5.09 ymax: 52.13
114+
#> CRS: EPSG:4326
115+
#> A tibble: 2 x 5
116+
#> person id val geometry waste_baskets
117+
#> * <chr> <dbl> <int> <POINT [°]> <int>
118+
#> 1 Alice 1 5 (5.09 52.12) 3
119+
#> 2 Bob 2 2 (5.08 52.13) 0
120+
```
121+
122+
123+
## Local API setup
124+
125+
OSM enrichment can ask for a lot of data, which can overload public APIs. If
126+
you intend to enrich large amounts of data or compute routing distances (e.g.,
127+
driving duration) between many points, you should set up a local API endpoint.
128+
129+
We provide a `docker-compose` workflow for this in the separate
130+
[osmenrich_docker
131+
repository](https://github.com/sodascience/osmenrich_docker). Use the `README`
132+
on the repository for setup instructions.
133+
134+
135+
<img src="man/figures/docker.png" width="250px"></img>
136+
137+
<!-- CONTRIBUTING -->
138+
## Contributing
139+
140+
Contributions are what make the open source community an amazing place to
141+
learn, inspire, and create. Any contributions you make are **greatly
142+
appreciated**.
143+
144+
In this project we use the
145+
[Gitflow workflow](https://nvie.com/posts/a-successful-git-branching-model/)
146+
to help us with continious development. Instead of having a single
147+
`master`/`main` branch we use two branches to record the history of the
148+
project: `develop` and `master`. The `master` branch is used only for the
149+
official releases of the project, while the `develop` branch is used to
150+
integrate the new features developed. Finally, `feature` branches are used to
151+
develop new features or additions to the project that will be `rebased and
152+
squash` in the `develop` branch.
153+
154+
The workflow to contribute with Gitflow becomes:
155+
156+
1. Fork the Project
157+
2. Create your Feature Branch (`git checkout -b feature/<AmazingFeature>`)
158+
3. Commit your Changes (`git commit -m 'Add some <AmazingFeature>'`)
159+
4. Push to the Branch (`git push origin feature/<AmazingFeature>`)
160+
5. Open a Pull Request
161+
162+
## License and citation
163+
164+
The `osmenrich` package is published under the MIT license. When using
165+
`osmenrich` for academic work, please cite:
166+
167+
```
168+
Will soon follow.
169+
```
170+
171+
<!-- CONTACT -->
172+
## Contact
173+
174+
This package is developed and maintained by the [ODISSEI Social Data Science
175+
(SoDa)](https://odissei-data.nl/nl/soda/) team.
176+
177+
Do you have questions, suggestions, or remarks? File an issue in our issue
178+
tracker or feel free to contact [Erik-Jan van
179+
Kesteren](https://github.com/vankesteren)
180+
([@ejvankesteren](https://twitter.com/ejvankesteren)) or [Leonardo
181+
Vida](https://github.com/leonardovida)
182+
([@leonardojvida](https://twitter.com/leonardojvida))
183+
184+
<img src="man/figures/word_colour-l.png" width="250px"></img>

‎man/figures/docker.png

35.9 KB
Loading

‎man/figures/logo.png

69.4 KB
Loading

‎man/figures/word_colour-l.png

46 KB
Loading

0 commit comments

Comments
 (0)