---
title: "4. Valley delineation"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{4. Valley delineation}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
bibliography: references.bib
csl: apa.csl
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  message = FALSE
)
```

```{r srr-tags, eval=FALSE, echo=FALSE}
#' @srrstats {G1.0} This vignette provides several literature references used
#'   for the method of valley delineation.
#' @srrstats {G1.3} Literature references are given for the Cost Distance
#'   algorithm used for valley delineation.
#' @srrstats {G2.10} This vignette uses `sf::st_geometry()` to extract the
#'   geometry column from the `bucharest_osm$river_centerline` and
#'   `bucharest_osm$river_surface`. This is used when only geometry information
#'   is needed from that point onwards and all other attributes (i.e., columns)
#'   can be safely discarded. The object returned by `sf::st_geometry()` is a
#'   simple feature geometry list column of class `sfc`.
#' @srrstats {SP2.2a} This vignette demonstrates the compatibility of `rcrisp`
#'   routines with `terra` workflows.
```

In a typical rcrisp workflow, valley delineation is used in the context of corridor delineation. When the parameter `method = "valley"` is set (this is the default value) in `delineate_corridor()`, first the river valley is extracted from a Digital Elevation Model (DEM) with `delineate_valley()` and then the resulting valley edge is used to "guide" the delineation of the corridor on the street network, as shown in `vignette("corridor-delineation")`.

In this article, we describe how `delineate_valley()` works and how it can be used independently. `delineate_valley()` uses a Cost Distance algorithm, variants of which are mostly used for the delineation of wet area mapping and valley bottom delineation in non-urban contexts [@agren2014; @murphy2009; @white2012].

As the resulting valley boundary is only used as an intermediate step in `delineate_corridor()`, valley delineation does not require high-resolution DEM data, as required for non-urban applications [e.g., @lidberg2020; @nardi2019]. By default, the valley is delineated on the openly available 30m-resolution [Copernicus DEM GLO-30](https://dataspace.copernicus.eu/explore-data/data-collections/copernicus-contributing-missions/collections-description/COP-DEM).

We demonstrate valley delineation using data from rcrisp example data, namely the DEM of Bucharest as the input raster and the river centerline and surface as the source for which the Cost Distance is calculated.

```{r setup}
# Attach required packages
library(rcrisp)
library(sf)

bucharest_osm <- get_osm_example_data()
bucharest_dem <- get_dem_example_data()

if (any(is.null(bucharest_osm), is.null(bucharest_dem))) {
  cat("NOTE: Example data was not found; ",
      "subsequent code chunks will be skipped.\n", sep = "")
  knitr::opts_chunk$set(eval = FALSE)
}

# Load data for valley delineation
dem <- bucharest_dem
river_centerline <- st_geometry(bucharest_osm$river_centerline)
river_surface <- st_geometry(bucharest_osm$river_surface)
river <- c(river_centerline, river_surface)
```

```{r}
#| echo: false
#| fig.alt: "DEM of the area enclosing River Dâmbovița in Bucharest"
#| fig.cap: "DEM of the area enclosing River Dâmbovița in Bucharest"
terra::plot(dem)
plot(river, col = "white", border = NA, add = TRUE)
```

```{r}
valley <- delineate_valley(dem, river)
```

```{r}
#| echo: false
#| fig.alt: "Valley polygon derived from the DEM"
#| fig.cap: "Valley polygon derived from the DEM"
terra::plot(dem)
plot(valley, border = "white", add = TRUE)
```

## References