diff --git a/.gitignore b/.gitignore index 3b77352..b21adb9 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,8 @@ # From: https://github.com/github/gitignore/blob/master/R.gitignore +# R osm cache +rosm.cache/ + # History files .Rhistory .Rapp.history diff --git a/R/enrich.R b/R/enrich.R index 770f0c9..6d1317e 100644 --- a/R/enrich.R +++ b/R/enrich.R @@ -1,5 +1,5 @@ #' @name enrich -#' @title Enrich OSM Data +#' @title Enrich `sf` object with OSM data #' @description Perform enriched query on osm and add as new column. #' #' The enrichment call works in the following way: an `enriched_overpass_query` @@ -18,10 +18,42 @@ #' @param ... `enriched_overpass_query` column or columns to add #' @param .verbose `bool` whether to print info during enrichment #' +#' @details +#' `Type` represents the feature type to be considered. Usually this would be +#' points, but polygons and multipolygons are also possible. This argument can +#' also be a vector of multiple types. Non-point types will be converted to +#' points using the st_centroid function from the sf package (NB this does not +#' necessarily work well for all features!) Available options are: +#' - points +#' - lines +#' - polygons +#' - multilines +#' - multipolygons +#' +#' `Distance` represents the metric used to compute the distances between the +#' rows in the dataset and the osm features. `Duration` represents the metric +#' that indicates the average duration to cover the distances between the +#' rows in the dataset and the osm features. The following metrics are +#' available in this package, assuming that the OSRM server is setup as +#' suggested in our guide at: +#' https://github.com/sodascience/osmenrich_docker: +#' - spherical ("as the crow flies") +#' - distance_by_foot +#' - duration_by_foot +#' - distance_by_car +#' - duration_by_car +#' - distance_by_bike +#' - duration_by_bike +#' +#' `Kernel` is a kernel function from the osmenrich package to be used in weighing +#' the features and the radius/distance where features are considered. For +#' simply counting the number of occurrences within a radius, use kernel_uniform +#' with radius r. +#' #' @examples -#' \dontrun{ +#' \donttest{ #' -#' #' # Enrich data creating new column `waste_baskets` +#' # Enrich data creating new column `waste_baskets` #' sf_enriched <- dataset %>% #' enrich_osm( #' name = "waste_baskets", diff --git a/R/opqenrich.R b/R/opqenrich.R index 836d6d7..811756b 100644 --- a/R/opqenrich.R +++ b/R/opqenrich.R @@ -12,38 +12,6 @@ #' @param .verbose `bool` whether to print info during enrichment #' @param ... arguments passed to the kernel function #' -#' @details -#' `Type` represents the feature type to be considered. Usually this would be -#' points, but polygons and multipolygons are also possible. This argument can -#' also be a vector of multiple types. Non-point types will be converted to -#' points using the st_centroid function from the sf package (NB this does not -#' necessarily work well for all features!) Available options are: -#' - points -#' - lines -#' - polygons -#' - multilines -#' - multipolygons -#' -#' `Distance` represents the metric used to compute the distances between the -#' rows in the dataset and the osm features. `Duration` represents the metric -#' that indicates the average duration to cover the distances between the -#' rows in the dataset and the osm features. The following metrics are -#' available in this package, assuming that the OSRM server is setup as -#' suggested in our guide at: -#' https://github.com/sodascience/osmenrich_docker: -#' - spherical ("as the crow flies") -#' - distance_by_foot -#' - duration_by_foot -#' - distance_by_car -#' - duration_by_car -#' - distance_by_bike -#' - duration_by_bike -#' -#' `Kernel` is a kernel function from the osmenrich package to be used in weighing -#' the features and the radius/distance where features are considered. For -#' simply counting the number of occurrences within a radius, use kernel_uniform -#' with radius r. -#' #' @importFrom methods is #' @rdname enrich_opq #' diff --git a/README.md b/README.md index 8b6845c..5ef9010 100644 --- a/README.md +++ b/README.md @@ -12,15 +12,16 @@


-# Enrich geocoded data using openstreetmaps +# Enrich geocoded data using OpenStreetMap ![Github Action test](https://github.com/sodascience/osmenrich/workflows/R-CMD-check/badge.svg) [![DOI](https://zenodo.org/badge/337555188.svg)](https://zenodo.org/badge/latestdoi/337555188) - 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` and `osmdata` packages for collecting and manipulating geodata. +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 @@ -54,72 +55,76 @@ dataset: # Import libraries library(tidyverse) library(sf) -library(osmdata) library(osmenrich) # Create an example dataset to enrich sf_example <- tribble( - ~person, ~id, ~lat, ~lon, ~val, - "Alice", 1, 52.12, 5.09, 5L, - "Bob", 2, 52.13, 5.08, 2L + ~person, ~lat, ~lon, + "Alice", 52.12, 5.09, + "Bob", 52.13, 5.08, ) %>% - sf::st_as_sf(coords = c("lon", "lat"), crs = 4326) + sf::st_as_sf( + coords = c("lon", "lat"), + crs = 4326 + ) # Print it sf_example -#> Simple feature collection with 2 features and 3 fields +#> 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 4 -#> person id val geometry -#> * -#> 1 Alice 1 5 (5.09 52.12) -#> 2 Bob 2 2 (5.08 52.13) +#> # A tibble: 2 x 2 +#> person geometry +#> * +#> 1 Alice (5.09 52.12) +#> 2 Bob (5.08 52.13) ``` -To enrich the `sf_example` dataset with "waste baskets" in a 100m radius, we -create a query using the `enrich_osm()` function. This function uses the +To enrich the `sf_example` dataset with "waste baskets" in a 100m 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`. We also add a +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. +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_simple <- sf_example %>% +sf_example_enriched <- sf_example %>% enrich_osm( - name = "waste_baskets", + name = "n_waste_baskets", key = "amenity", value = "waste_basket", - r = 100 + r = 500 ) #> Downloading data for waste_baskets... Done. -#> Downloaded 26 points, 0 lines, 0 polygons, 0 mlines, 0 mpolygons. -#> Computing distance matrix for wastebaskets...Done. -#> Adding waste_baskets to data. - +#> Downloaded 147 points, 0 lines, 0 polygons, 0 mlines, 0 mpolygons. +#> Computing distance matrix for waste_baskets...Done. ``` -The resulting enriched dataset is a `sf` object and can be printed as usual -and we can inspect the newly added column `waste_baskets`. +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 4 fields +#> 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 -#> CRS: EPSG:4326 -#> A tibble: 2 x 5 -#> person id val geometry waste_baskets -#> * -#> 1 Alice 1 5 (5.09 52.12) 3 -#> 2 Bob 2 2 (5.08 52.13) 0 +#> geographic CRS: WGS 84 +#> # A tibble: 2 x 3 +#> person geometry waste_baskets +#> * +#> 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: +![](man/figures/example_wastebaskets_r500.png) ## Local API setup @@ -127,11 +132,10 @@ 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. -We provide a `docker-compose` workflow for this in the separate +Multiple `docker-compose` workflows for doing this are avaialble in the separate [osmenrich_docker repository](https://github.com/sodascience/osmenrich_docker). Use the `README` -on the repository for setup instructions. - +in the repository to select the workflow that fits your desired outcome. @@ -142,15 +146,14 @@ Contributions are what make the open source community an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. -In this project we use the -[Gitflow workflow](https://nvie.com/posts/a-successful-git-branching-model/) -to help us with continious development. Instead of having a single -`master`/`main` branch we use two branches to record the history of the +In this project, the [Gitflow workflow](https://nvie.com/posts/a-successful- +git-branching-model/) is used. Instead of having a single `master`/`main` +branch, the project makes use of two branches to record the history of the project: `develop` and `master`. The `master` branch is used only for the official releases of the project, while the `develop` branch is used to integrate the new features developed. Finally, `feature` branches are used to -develop new features or additions to the project that will be `rebased and -squash` in the `develop` branch. +develop new features or additions to the project that will be `rebased and squashed` +in the `develop` branch. The workflow to contribute with Gitflow becomes: @@ -176,7 +179,7 @@ Enrich sf Data with Geographic Features from OpenStreetMaps (Version v1.0). Zeno 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 our issue +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 diff --git a/man/figures/example_wastebaskets_r500.png b/man/figures/example_wastebaskets_r500.png new file mode 100644 index 0000000..353e4c9 Binary files /dev/null and b/man/figures/example_wastebaskets_r500.png differ