SELECTRshed

Delineate watersheds using whitebox tools and terra objects. These functions are designed to interact kindly with {SELECTRdata} and {SELECTR}. Largely a wrapper around the {whitebox} package.

Create Subbasins for SELECT

Pseudo-workflow goes like this:

1 - Read DEM as a terra SpatRaster object
2 - Read watershed outlet location as terra SpatVector object

3 - Breach depressions in the DEM (from step 1)
4 - Create a flow direction raster from DEM in step 3.
5 - Create a flow accumulation raster from the flow direction raster in step 4.
6 - Create a streams raster from the flow accumulation raster (step 5) and threshold for number of upstream cells.

7 - Snap the vector pour point to the stream raster.
8 - Rasterize the snapped vector pour point.
9 - Delineate the watershed with flow direction raster and pour point raster.

10 - Clip flow direction and stream rasters with the watershed.
11 - Create subbasin using the clipped streams and flow direction rasters.

Example workflow

This example walks through using a DEM and vector pour point to delineate a watershed and delineate subbasins. This package requires the whitebox R package and the Whitebox Tools Open Core binary package.

Installing

Install whitebox from CRAN and then install the Whitebox Tools binary. whitebox provides methods for installing the binaries on Windows, Linux, and Mac.

install.packages("whitebox")
whitebox::install_whitebox()

Install SELECTRshed:

# pak::pkg_install("TxWRI/SELECTRshed")
install.packages("SELECTRshed", repos = c('https://txwri.r-universe.dev', 'https://cloud.r-project.org'))

Currently only available as source through GitHub, prebuilt binaries will be available through r-universe soon.

library(SELECTRdata)
library(SELECTRshed)
#> Loading required package: whitebox
library(terra)
#> Warning: package 'terra' was built under R version 4.3.3
#> terra 1.8.29

## download a DEM using a bounding box from an area we
## are interested in using WGS84 EPSG:4326

xmin <- -96.596260
ymin <- 30.578519 
xmax <- -96.348038
ymax <- 30.801423
bbox_extent <- ext(xmin, xmax, ymin, ymax)
bbox_polygon <- as.polygons(bbox_extent, crs = "EPSG:4326")

dem <- download_dem(bbox_polygon)

## create a pourpoint near the exit of Thompson's Creek -96.423011 30.588226
pourpoint <- vect(data.frame(id = "Thompsons",
                             lon = -96.423011,
                             lat = 30.588226),
                  geom = c("lon", "lat"),
                  crs = "EPSG:4326")

plot(dem)
plot(pourpoint, add = TRUE)

Process the DEM

The general workflow for watershed delineation includes

## preprocess the DEM
breached <- create_breach_depression(dem, fill_pits = TRUE)
## create the flow direction raster
fdr <- create_d8_pointer(breached)
## create the flow accumulation raster
fa <- create_d8_fa(fdr)
## create the streams raster
streams_ras <- create_streams(fa, threshold = 1500)

## write pourpoints to temp folder
temp_pour_point_file <- paste0(tempdir(), "snapped.shp")
snapped_pour_point <- snap_pour_point(pour_pts = pourpoint,
                                      streams = streams_ras,
                                      output = temp_pour_point_file)
## snapped_pour_point returns a SpatVectorProxy, we need a SpatVector
## so use vect() on the output.
snapped_pour_point <- vect(temp_pour_point_file)

## convert to Spatraster
pour_point_rast <-  rasterize(snapped_pour_point, streams_ras)

## create the watershed
watershed <- create_watershed(d8_pntr = fdr, 
                              pour_pts = pour_point_rast)
plot(watershed)

Create Subbasins

## clip d8_pntr and streams to watershed
fdr <- watershed * fdr
streams_ras <- watershed * streams_ras

## create subbasins will create subwatersheds at the
## nodes of stream segments
subbasins <- create_subbasins(d8_pntr = fdr,
                              streams = streams_ras)
plot(as.factor(subbasins))
plot(as.polygons(streams_ras), add = TRUE)

Other Notes

Why whitebox tools? Watersheding functions are available through the terra and traudem packages, so why use whitebox?