Draft package vignettes

_pkgdown.yml

@@ -4,3 +4,32 @@ template:
 authors:
   sidebar:
     roles: [aut, cre]
+articles:
+- title: Articles
+  navbar: ~
+  contents:
+  - method
+  - corridor-delineation
+  - corridor-segmentation
+  - riverspace-delineation
+  - multiple-cities
+  - poi-study-area
+navbar:
+  components:
+    articles:
+      text: Articles
+      menu:
+        - text: 1. The method
+          href: articles/method.html
+        - text: 2. Corridor delineation
+          href: articles/corridor-delineation.html
+        - text: 3. Corridor segmentation
+          href: articles/corridor-segmentation.html
+        - text: 4. Riverspace delineation
+          href: articles/riverspace-delineation.html
+        - text: -------
+        - text: Use cases
+        - text: 5. Multiple delineations
+          href: articles/multiple-cities.html
+        - text: 6. Study area around a POI
+          href: articles/poi-study-area.html

vignettes/corridor-delineation.Rmd

@@ -1,8 +1,8 @@
 ---
-title: "Corridor delineation"
+title: "2. Corridor delineation"
 output: rmarkdown::html_vignette
 vignette: >
-  %\VignetteIndexEntry{Corridor delineation}
+  %\VignetteIndexEntry{2. Corridor delineation}
   %\VignetteEngine{knitr::rmarkdown}
   %\VignetteEncoding{UTF-8}
 ---
@@ -14,17 +14,18 @@
 )
 ```
 
-```{r setup}
+```{r setup, warning=FALSE, message=FALSE}
 library(CRiSp)
-library(sf)
 library(dplyr)
+library(sf)
+library(osmdata)
 ```
 
-In this notebook we explore how to delineate a river corridor using Bucharest as the study area. We focus on one of the rivers and use a specific projected CRS for the analysis. Also, we make sure that we include a given area around the city boundaries.
+In this notebook we explore how to delineate a river corridor using Bucharest as the study area. We focus on one of the rivers and use a specific projected CRS (coordinate reference system) for the analysis. A project CRS is required for calculating distances along the street network during delineation. Also, we make sure that we include a given area around the city boundaries.
 
 ```{r variables}
-city_name <- "Bucharest, Romania"   # Be specific and spell as it appears in OSM
-river_name <- "Dâmbovița"           # Spell as it appears in OpenStreetMap
+city_name <- "Bucharest, Romania"   # Be specific and spell as in OpenStreetMap (OSM)
+river_name <- "Dâmbovița"           # Spell as in OpenStreetMap (OSM)
 epsg_code <- 32635                  # UTM zone 35N
 bbox_buffer <- 2000                 # Buffer around the city boundary in meters
 ```
@@ -33,8 +34,7 @@
 
 ```{r aoi}
 # Get the bounding box from the Nominatim API provided by OSM.
-bb <- osm_bb(city_name)
-
+bb <- getbb(city_name)
 aoi <- define_aoi(bb, epsg_code, bbox_buffer)
 ```
 
@@ -148,10 +148,29 @@
 
 Note that this is not ideal, as the municipal boundaries can be arbitrary and might exclude important end features of the corridors, so the user should have the option to input their own feature to cap the corridor ends. In the case of Bucharest, this can be the ring road.
 
-## All in one step
+## All in one
+
+The `delineate_corridor()` function carries out the entire delineation in one step and returns a list that by default contains the following output elements: `corridor`, `segments`, and `riverspace`. Although not included by default, the used input objects `river_line`, `river_polygon`, and `buildings` can also be included in the resulting object. The initial corridor boundary, either a buffer or valley edges derived from the digital elevation model, can also be included in the output object.
 
 ```{r eval=FALSE}
-# TODO this function should run the entire delineation process
-delineate_corridor(city_name, river_name, epsg_code)
+# TODO this function should run the entire urc delineation process in one step
+urc <- delineate_corridor(city_name, river_name,
+                          segments = TRUE, riverspace = TRUE)
+
+# `$corridor` of the resulting object is an sf polygon representing the corridor
+urc$corridor
+
+# `$segments` is an sf polygon representing the segments of the corridor,
+# TODO make sure the segments are numbered from upstream to downstream
+urc$segments
+
+# `$riverspace` is an sf polygon representing the delineated river space
+urc$riverspace
+
+# All three elements of delineation
+plot(urc$riverspace, col = "green")
+plot(urc$river, col = "blue")
+plot(urc$segments, col = "lightblue", add = TRUE)
+plot(urc$corridor, add = TRUE, col = "red", wt = 2, add = TRUE)
 ```
 

vignettes/corridor-segmentation.Rmd

@@ -0,0 +1,28 @@
+---
+title: "3. Corridor segmentation"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{3. Corridor segmentation}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+```{r setup}
+library(CRiSp)
+```
+
+For a more detailed analysis of an urban river corridor, corridor-level delineation may not be sufficient. The corridor needs to be subdivided into smaller morphological units. Segmentation is a process of subdividing the corridor by using major transversal road or rail infrastructure lines.
+
+By default, the all-in-one function `delineate_corridor()` divides the corridor into segments. It is also possible to use the `delineate_segment()` function to divide the corridor in a separate step. To demonstrate this as a separate step, we will use the built-in `bucharest_corridor` and `bucharest_streets` as input.
+
+```{r eval=FALSE}
+segmented_corridor <- delineate_segments(bucharest_corridor, bucharest_streets)
+```
+

vignettes/method.Rmd

@@ -0,0 +1,29 @@
+---
+title: "1. The method"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{1. The method}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include=FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+CRiSp implements a spatial morphological method of delineation ([Forgaci, 2018](https://doi.org/10.7480/abe.2018.31)) that considers both the terrain of the river valley and the urban fabric, as shown in the diagram below.
+
+```{r fig.align='center', fig.alt='Diagram of the method of delineation', echo=FALSE}
+knitr::include_graphics("img/delineation.jpg")
+```
+
+The method consists of three steps, each explained on this website in a separate article:
+
+1. The **corridor boundary** of the urban area surrounding the river is delineated on the street network considering a given **walkshed** (the urban area reached along the street network within a given walking distance from the river, 500m by default) and the **valley edge** derived from a digital elevation model, as shown in `vignette("corridor-delineation")`.
+2. The delineated corridor is divided into **corridor segments** bounded by the main transversal streets, as shown in `vignette("corridor-segmentation")`.
+3. The **river space**, i.e., the space between the river and the first line of buildings is determined, as shown in `vignette("riverspace-delineation")`.
+
+

vignettes/multiple-cities.Rmd

@@ -0,0 +1,65 @@
+---
+title: "5. Multiple delineations"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{5. Multiple delineations}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+```{r setup}
+library(CRiSp)
+```
+
+## Motivation
+
+Comparative analysis can shed light on patterns that are not visible in a single case. The automated delineation provided by CRiSp allows for a reliable frame of reference for such comparisons, including:
+
+1. all cities along a large river;
+1. all river-crossed cities of a given size;
+1. all cities crossed by rivers of the same kind in a given region.
+
+We can use the `delineate_corridor()` function repeatedly to extract data for multiple cities and rivers, and subsequently compare them. This vignette demonstrates how to perform such an analysis using CRiSp.
+
+## Data
+
+We focus on the following five cities and rivers:
+
+```{r, eval=FALSE}
+cities <- c("Bucharest, Romania", "Vienna, Austria", "Paris, France",
+            "London, United Kingdom", "Berlin, Germany")
+rivers <- c("Dâmbovița", "Wienfluss", "Seine", "Thames", "Spree")
+```
+
+## Delineation
+
+We can use the `map2()` function form the `purrr` package to iterate over the cities and rivers and extract their corridor boundaries. We can skip parts of the delineation by passing the respective parameters to the `purrrr::map2()` function. We skip riverspace delineation in this case. The result is a list of delineated corridors.
+
+```{r, eval=FALSE}
+corridors <- purrr::map2(cities, rivers, delineate_corridor, riverspace = FALSE)
+corridors[[1]]
+```
+
+## Validation
+
+We can validate the results either by plotting the corridors of each city or by checking if the delineation resulted in any empty geometries. While the former can be a quick way to validate a small number of cities, the latter is better suited for a larger number of cases.
+
+```{r, eval=FALSE}
+purrr::map(corridors, ~ .x |> st_is_empty())
+```
+
+## Parallelisation
+
+When used on multiple cities this can quickly become computationally expensive. To improve computation, we can run the function in parallel with an homologous function from the `furrr` package. 
+
+```{r, eval=FALSE}
+future::plan(multisession)
+corridors <- furrr::future_map2(cities, rivers, delineate_corridor)
+```

vignettes/poi-study-area.Rmd

@@ -0,0 +1,44 @@
+---
+title: "6. Study area around POI"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{6. Study area around POI}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>",
+  eval = FALSE
+)
+```
+
+```{r setup}
+library(CRiSp)
+```
+
+## Introduction
+
+In this article we explore how to delineate a study area around a point of interest (POI) using Bucharest as the study area. We choose a location along the River Dâmbovița. The POI is represented as a point in the WGS84 coordinate reference system.
+
+```{r}
+poi <- st_sfc(st_point(c(26.074123, 44.432875)), crs = 4326)
+```
+
+The `delineate_segment()` takes the POI as input. By default, it tries to identify the city and the river closest to it. Alternatively, it can take an already delineated corridor and street network as input. We will use the built-in data `bucharest_corridor` and `bucharest_streets`. It also takes care of any CRS transformations needed. Optionally, it can also generate the riverspace.
+
+```{r}
+segment_poi <- delineate_segment(poi, bucharest_corridor, bucharest_streets,
+                                 riverspace = TRUE)
+```
+
+The output is a list object with three elements: `$poi`, `$segment` and `$riverspace`.
+
+```{r}
+plot(segment_poi$riverspace, col = "lightblue")
+plot(segment_poi$segment, col = "blue", add = TRUE)
+plot(segment_poi$poi, col = "red", size = 3, add = TRUE)
+```
+

vignettes/riverspace-delineation.Rmd

@@ -0,0 +1,73 @@
+---
+title: "4. Riverspace delineation"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{4. Riverspace delineation}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>",
+  eval = FALSE
+)
+```
+
+```{r setup}
+library(CRiSp)
+library(osmdata)
+library(sf)
+```
+
+River space delineation is a delineation step that uses the river and buildings as input to generate a polygon representing the space between the river and the first line of buildings. We will use Bucharest as the study area and the River Dâmbovița as the river.
+
+```{r}
+city_name <- "Bucharest, Romania"   # Be specific and spell as in OSM
+river_name <- "Dâmbovița"           # Spell as it appears in OSM
+epsg_code <- 32635                  # UTM zone 35N
+bbox_buffer <- 2000                 # Buffer around the city boundary in meters
+```
+
+```{r aoi}
+# Get the bounding box from the Nominatim API provided by OSM.
+bb <- getbb(city_name)
+aoi <- define_aoi(bb, epsg_code, bbox_buffer)
+```
+
+```{r city}
+city_boundary <- osmdata_as_sf("place", "city", bb)$osm_multipolygons |>
+  st_transform(epsg_code) |>
+  st_geometry()
+```
+
+```{r river}
+river_centerline <- osmdata_as_sf("waterway", "river", bb)$osm_multilines |>
+  filter(name == river_name) |>
+  st_transform(epsg_code) |>
+  st_geometry() |>
+  st_intersection(st_buffer(aoi, bbox_buffer))
+
+river_surface <- osmdata_as_sf("natural", "water", bb)
+river_surface <- river_surface$osm_multipolygons |>
+  bind_rows(river_surface$osm_polygons) |>
+  st_transform(epsg_code) |>
+  st_filter(river_centerline, .predicate = st_intersects) |>
+  st_geometry() |>
+  st_union()
+```
+
+```{r}
+buildings <- osmdata_as_sf("building", "yes", bb)$osm_multipolygons |>
+  st_transform(epsg_code) |>
+  st_geometry()
+```
+
+The `delineate_riverspace()` function takes the city boundary, river surface and building polygons as input. If no river is found, it will return an error message. If buildings are not found, it will return an unobstructed buffer of a given radius with a warning message. By default, the river space will be capped by the city boundaries. The function returns an sf polygon.
+
+```{r}
+riverspace <- delineate_riverspace(city_boundary, river_surface, buildings)
+```
+
+