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")

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, using fill and/or breach depressions tools
• create a flow direction raster from the preprocessed DEM
• create a flow accumulation raster from the flow direction raster
• create a stream raster from the flow accumulaiton raster based on the number of upstream cells.
• snap the outlet point to the stream network created by the stream raster
• create the watershed using the snapped pour point and flow direction raster

## 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?

• I’ve had difficulties getting reliable results using the recently added flow accumulation and related functions in terra. That is the only reason for this package.

• traudem can be difficult to install on some OS’s, whitebox seems readily available.

• You can accomplish all of this using functions available in the whitebox R package. This is largely a wrapper that more easily allows the use of terra SpatRaster and SpatVector objects for users uncomfortable dealing with file paths or system commands.

• Really this is just to make a reproducible workflow for implementing SELECT in R.