Add all workshop materials

.gitignore

@@ -0,0 +1,4 @@
+.Rproj.user
+.Rhistory
+.RData
+.Ruserdata

README.Rmd

@@ -0,0 +1,54 @@
+---
+output: github_document
+---
+
+```{r setup, include=FALSE}
+knitr::opts_chunk$set(echo = TRUE)
+```
+
+# Introduction to R + OSM
+
+This is a workshop put together by Angela Li of the [Center for Spatial Data Science (CSDS)](https://spatial.uchicago.edu) at UChicago for [State of the Map 2018](https://2018.stateofthemap.us).
+
+## Learning Objectives
+By the end of this workshop, workshop attendees should be able to:
+
+1. Install useful R packages
+2. Download OSM data from the OpenStreetMap API, using the `osmdata` R package
+3. Map downloaded OSM data in R
+4. Understand the two formats in which R stores spatial data
+
+## `r emo::ji("star")` Do This Now! `r emo::ji("star")`
+### Install Necessary Packages
+Open RStudio and paste the following code into your console, then press Enter to run it:
+```{r eval = FALSE}
+# Download packages from CRAN
+install.packages(c("devtools", "knitr", "magrittr", "sf", "sp", "rmarkdown", "usethis"))
+
+# Download the osmdata package from Github
+devtools::install_github("ropensci/osmdata")
+```
+
+### Download Lesson Materials
+Download this entire lesson (all code, notebooks, and data) to your computer desktop by running the following code in your RStudio console. Respond `yes` to all prompts:
+```{r eval = FALSE}
+usethis::use_course("https://github.com/angela-li/sotmus-r/archive/master.zip")
+```
+
+Once you've downloaded this lesson, open the `.Rproj` file to get started.
+
+## Contents
+- [`code`](): Raw R code generated from notebooks
+- [`data`](): Intermediate R data objects (to be used in case of bad Internet connection)
+- [`notebooks`](): R Markdown notebooks with R code, produced during workshop. Includes empty notebook and filled-out notebook. 
+- [`slides`](): Intro slides
+
+## Additional Resources
+- `osmdata` [package website](https://ropensci.github.io/osmdata/index.html), [Github](https://github.com/ropensci/osmdata)
+- `sf` [package website](https://r-spatial.github.io/sf/), [Github](https://github.com/r-spatial/sf/)
+- [overpass turbo website](http://overpass-turbo.eu): try out sample Overpass API queries
+- [*Geocomputation in R*](https://geocompr.robinlovelace.net): free online book about analyzing, visualizing, and modeling spatial data in R
+- [*R for Data Science*](http://r4ds.had.co.nz): free online book about doing data science in R
+
+## References
+Thanks to [Jared Lander](https://swcarpentry.github.io/r-novice-gapminder/), [Chris Prener](https://github.com/slu-dss/lesson-template), [Jenny Bryan](https://github.com/jennybc/whattheyforgot), [Software Carpentry](https://swcarpentry.github.io/r-novice-gapminder/), and [RStudio Education](https://github.com/rstudio-education/datascience-box) for informing the design of this workshop repository. In the same vein, please feel free to use this workshop as a template for your own R workshop. (If you do, give me a hoot!)

README.md

@@ -1,2 +1,62 @@
-# sotmus-r
-Workshop materials for "Introduction to R + OSM", State of the Map 2018
+
+Introduction to R + OSM
+=======================
+
+This is a workshop put together by Angela Li of the [Center for Spatial Data Science (CSDS)](https://spatial.uchicago.edu) at UChicago for [State of the Map 2018](https://2018.stateofthemap.us).
+
+Learning Objectives
+-------------------
+
+By the end of this workshop, workshop attendees should be able to:
+
+1.  Install useful R packages
+2.  Download OSM data from the OpenStreetMap API, using the `osmdata` R package
+3.  Map downloaded OSM data in R
+4.  Understand the two formats in which R stores spatial data
+
+⭐️ Do This Now! ⭐️
+------------------
+
+### Install Necessary Packages
+
+Open RStudio and paste the following code into your console, then press Enter to run it:
+
+``` r
+# Download packages from CRAN
+install.packages(c("devtools", "knitr", "magrittr", "sf", "sp", "rmarkdown", "usethis"))
+
+# Download the osmdata package from Github
+devtools::install_github("ropensci/osmdata")
+```
+
+### Download Lesson Materials
+
+Download this entire lesson (all code, notebooks, and data) to your computer desktop by running the following code in your RStudio console. Respond `yes` to all prompts:
+
+``` r
+usethis::use_course("https://github.com/angela-li/sotmus-r/archive/master.zip")
+```
+
+Once you've downloaded this lesson, open the `.Rproj` file to get started.
+
+Contents
+--------
+
+-   [`code`](): Raw R code generated from notebooks
+-   [`data`](): Intermediate R data objects (to be used in case of bad Internet connection)
+-   [`notebooks`](): R Markdown notebooks with R code, produced during workshop. Includes empty notebook and filled-out notebook.
+-   [`slides`](): Intro slides
+
+Additional Resources
+--------------------
+
+-   `osmdata` [package website](https://ropensci.github.io/osmdata/index.html), [Github](https://github.com/ropensci/osmdata)
+-   `sf` [package website](https://r-spatial.github.io/sf/), [Github](https://github.com/r-spatial/sf/)
+-   [overpass turbo website](http://overpass-turbo.eu): try out sample Overpass API queries
+-   [*Geocomputation in R*](https://geocompr.robinlovelace.net): free online book about analyzing, visualizing, and modeling spatial data in R
+-   [*R for Data Science*](http://r4ds.had.co.nz): free online book about doing data science in R
+
+References
+----------
+
+Thanks to [Jared Lander](https://swcarpentry.github.io/r-novice-gapminder/), [Chris Prener](https://github.com/slu-dss/lesson-template), [Jenny Bryan](https://github.com/jennybc/whattheyforgot), [Software Carpentry](https://swcarpentry.github.io/r-novice-gapminder/), and [RStudio Education](https://github.com/rstudio-education/datascience-box) for informing the design of this workshop repository. In the same vein, please feel free to use this workshop as a template for your own R workshop. (If you do, give me a hoot!)

code/sotmus-r-complete.R

@@ -0,0 +1,59 @@
+# All the code from the RMarkdown doc, in one script
+
+pkgs <- installed.packages()
+head(pkgs)
+
+nrow(pkgs)
+
+## update.packages()
+## remove.packages("osmdata")
+
+library(magrittr)
+library(osmdata)
+library(sf)
+library(sp)
+
+## opq(bbox = 'detroit') %>%
+##     add_osm_feature(key = 'highway', value = "cycleway") %>%
+##     osmdata_sp()
+
+detroit_bb <- getbb(place_name = "detroit")
+
+opq(detroit_bb)
+opq(bbox = "detroit") # Produces the same thing
+opq(bbox = c("42.255192,-83.287959,42.450232,-82.9104391")) # Also produces the same thing
+
+opq(detroit_bb) %>% 
+  add_osm_feature(key = "highway", value = "cycleway")
+
+opq(detroit_bb) %>% 
+  add_osm_feature(key = "highway", value = "cycleway") %>% 
+  opq_string()
+
+available_features()
+
+available_tags("highway")
+
+opq(detroit_bb) %>% 
+  add_osm_feature(key = "highway", value = "cycleway") %>% 
+  osmdata_sp()
+
+opq(detroit_bb) %>% 
+  add_osm_feature(key = "highway", value = "cycleway") %>% 
+  osmdata_sf()
+
+detroit_cycleways <- opq(detroit_bb) %>% 
+  add_osm_feature(key = "highway", value = "cycleway") %>% 
+  osmdata_sp()
+
+plot(detroit_cycleways$osm_lines)
+
+## kunming_water <- opq(bbox = 'Kunming, China') %>%
+##     add_osm_feature(key = 'natural', value = 'water') %>%
+##     osmdata_sf()
+## 
+## kunming_dian_names <- opq(bbox = 'Kunming, China') %>%
+##     add_osm_feature(key = 'name:en', value = 'Dian', value_exact = FALSE) %>%
+##     osmdata_sf()
+## 
+## kunming_all_features <- c(kunming_water, kunming_dian_names)

notebooks/sotmus-r-complete.Rmd

@@ -0,0 +1,170 @@
+---
+title: "Introduction to R + OSM: Completed Notebook"
+output: html_document
+---
+
+```{r setup, include=FALSE}
+knitr::opts_chunk$set(echo = TRUE)
+```
+
+This notebook provides an introduction to R, RStudio, and the osmdata packages. It's intended for R beginners, so you can skip the first section if you have a background in R.
+
+## Using R and RStudio
+
+### R Markdown
+
+This is an R Markdown document. It enables you to do "literate programming", where you can include code and written text in the same document. You can run chunks of code separately through the document. If you're familiar with Jupyter notebooks, it's basically the same idea. For more details on using R Markdown see <http://rmarkdown.rstudio.com>.
+
+You can execute a chunk of code by putting your cursor in the chunk and pressing *Ctrl-Shift-Enter*, or by clicking the Run button (the green triangle) in the chunk. You can execute all code by clicking the Run button at the top of this document.
+
+Try running the following code to check what packages you have installed:
+
+```{r }
+pkgs <- installed.packages()
+head(pkgs)
+```
+You can also count how many packages you have installed.
+```{r }
+nrow(pkgs)
+```
+
+### Packages
+
+What is a package anyway? It's a way to extend R by grouping together useful functions (you can write your own and put it on Github/submit it to CRAN!). You should have already installed all the packages you need for this tutorial. 
+
+To update your installed packages, run the following command:
+
+```{r eval = FALSE}
+update.packages()
+```
+
+To remove packages, run the following command:
+```{r eval = FALSE}
+remove.packages("osmdata")
+```
+
+Before you use a package, you need to load it into your workspace with a library command. Here, we're loading all the packages we need for this tutorial. Go ahead and load all the packages you just downloaded. 
+
+```{r}
+library(magrittr)
+library(osmdata)
+library(sf)
+library(sp)
+```
+
+## Download OSM data
+
+The `osmdata` package works by taking R input, creating an Overpass API query, and returning the API output to R.
+
+For the Overpass query, you need:
+
+- The bounding box of your area
+- The name of the feature you're looking for (i.e. "name", "highway")
+- The desired value of that feature (i.e. "Detroit", "bikeway")
+
+The final overpass query looks something like this:
+```{r eval = FALSE}
+opq(bbox = 'detroit') %>%
+    add_osm_feature(key = 'highway', value = "cycleway") %>%
+    osmdata_sp()
+```
+
+### Get the bounding box
+
+Let's look at how we can construct a query. First, let's get the bounding box for Detroit.
+```{r}
+detroit_bb <- getbb(place_name = "detroit")
+```
+
+Pass the bounding box to the `opq()` command.
+```{r}
+opq(detroit_bb)
+opq(bbox = "detroit") # Produces the same thing
+opq(bbox = c("42.255192,-83.287959,42.450232,-82.9104391")) # Also produces the same thing
+```
+
+### Add the feature(s) we're interested in
+
+Let's say we want to find all OSM cycleways in Detroit. Take the output from the previous section and add a feature!
+
+```{r}
+opq(detroit_bb) %>% 
+  add_osm_feature(key = "highway", value = "cycleway")
+```
+
+Compare this to the output of the previous and you can see the `$features` section now has XML content. 
+
+#### Under the hood
+What `osmdata` does is paste all this information together in a query that will work with the Overpass API. You can see the query that gets submitted to the API by using the `opq_string` function. 
+
+```{r}
+opq(detroit_bb) %>% 
+  add_osm_feature(key = "highway", value = "cycleway") %>% 
+  opq_string()
+```
+
+#### How do I know the OSM names of the features I want?
+For a list of all features, run the `available_features()` command:
+```{r}
+available_features()
+```
+
+And for the values associated with that feature, run the `available_tags` function:
+```{r}
+available_tags("highway")
+```
+
+### Submit query to Overpass API
+
+Let's submit this query to the Overpass API.
+
+```{r}
+opq(detroit_bb) %>% 
+  add_osm_feature(key = "highway", value = "cycleway") %>% 
+  osmdata_sp()
+```
+
+We request this back as an `sp` object, but I actually prefer `sf` objects for analysis. If you've used PostGIS before, `sf` data is essentially in the same format. 
+```{r}
+opq(detroit_bb) %>% 
+  add_osm_feature(key = "highway", value = "cycleway") %>% 
+  osmdata_sf()
+```
+
+However, for ease of mapping, I'm going to go ahead and use the `sp` data format. I'm going to save this as a local variable so I don't have to hit the API each time.
+```{r}
+detroit_cycleways <- opq(detroit_bb) %>% 
+  add_osm_feature(key = "highway", value = "cycleway") %>% 
+  osmdata_sp()
+```
+
+### Map the output
+
+Now let's map the data!
+```{r}
+plot(detroit_cycleways$osm_lines)
+```
+
+## Try it yourself
+
+Maybe you want to add boundaries? Try a different features, or a different city? Try it out!
+Go to the [detailed lesson](https://ropensci.github.io/osmdata/articles/osmdata.html) and the [function reference](https://ropensci.github.io/osmdata/reference/index.html) for help. 
+
+Note that some data may take a while to download from Overpass.
+
+FYI, this is the syntax for adding multiple features to the same map. You can unfortunately only do this with `sf` for the time being:
+```{r eval = FALSE}
+kunming_water <- opq(bbox = 'Kunming, China') %>%
+    add_osm_feature(key = 'natural', value = 'water') %>%
+    osmdata_sf()
+
+kunming_dian_names <- opq(bbox = 'Kunming, China') %>%
+    add_osm_feature(key = 'name:en', value = 'Dian', value_exact = FALSE) %>%
+    osmdata_sf()
+
+kunming_all_features <- c(kunming_water, kunming_dian_names)
+```
+
+```{r}
+# Put your code here!
+```