derive_streams: Derive stream network from DEM.

Description

Streams are derived from a digital elevation model (DEM) using the GRASS function r.stream.extract. If a stream network is available (see import_data) and burn > 0 it will be first burnt into DEM. Stream topology is derived using the GRASS function r.stream.order.

Usage

derive_streams(
  burn = 0,
  accum_threshold = 700,
  condition = TRUE,
  min_stream_length = 0,
  dem_name = NULL,
  clean = TRUE,
  mem = FALSE
)

Arguments

burn

numeric; how many meters should the streams be burned into the DEM? Only applicable if a mapped stream network is provided in import_data. Defaults to 0.

accum_threshold

integer; accumulation threshold to use (i.e. minimum flow accumulation value in cells that will initiate a new stream). A small value results in many small streams. Defaults to 700 but a reasonable value strongly depends on the raster resolution. See details below.

condition

logical; should the DEM be conditioned using the GRASS function r.hydrodem; default: TRUE.

min_stream_length

integer: minimum stream length in number of DEM raster cells; shorter first order stream segments are deleted. Defaults to 0 but a reasonable value strongly depends on the raster resolution. See details below.

dem_name

character vector, optional; default: 'dem'; useful if conditioned and / or burnt in DEM raster from previous runs shall be used.

clean

logical; should intermediate raster layer of imported streams ('streams_or') be removed from the GRASS session? Defaults to TRUE.

mem

logical; should -m flag in the GRASS function r.watershed be used (for data preparation)? Defaults to FALSE; if set to TRUE the calculation uses disk swap mode, i.e. it is not carried out in the RAM but also using disk space. Useful for large data sets but also slower.

Value

Nothing. The function produces the following maps:

'streams_v' derived streams with topology (vector)
'dirs' flow directions (raster)
'accums' accumulation values (raster)
'dem_cond' conditioned dem (raster) if condition is TRUE
'dem_[cond]_burn[X]' burnt in DEM (raster) if burn is > 0

The original GRASS map 'dem' is not modified if condition is TRUE and / or burn > 0.

Details

For details on accum_threshold and min_stream_length see the parameters 'threshold' and 'stream_length' at r.stream.extract. It might be useful to not burn in the whole available stream network but only parts of it (e.g., larger streams with higher Strahler stream order only). For this, the stream network needs to be pre-processed (parts could be deleted) before loading it with import_data.

Examples

Run this code

# NOT RUN {
dem_path <- system.file("extdata", "nc", "elev_ned_30m.tif", package = "openSTARS")
if(.Platform$OS.type == "windows"){
  grass_program_path = "c:/Program Files/GRASS GIS 7.6"
  } else {
  grass_program_path = "/usr/lib/grass78/"
  }

setup_grass_environment(dem = dem_path, 
                        gisBase = grass_program_path,      
                        remove_GISRC = TRUE,
                        override = TRUE
                        )
gmeta()
                        
# Load files into GRASS
dem_path <- system.file("extdata", "nc", "elev_ned_30m.tif", package = "openSTARS")
sites_path <- system.file("extdata", "nc", "sites_nc.shp", package = "openSTARS")
streams_path <- system.file("extdata", "nc", "streams.shp", package = "openSTARS")
import_data(dem = dem_path, sites = sites_path, streams = streams_path)

# Derive streams from DEM
derive_streams(burn = 10, accum_threshold = 700, condition = TRUE, clean = TRUE)

# Plot
library(sp)
dem <- readRAST('dem', ignore.stderr = TRUE)
sites <- readVECT('sites_o', ignore.stderr = TRUE)
streams_o <- readVECT('streams_o', ignore.stderr = TRUE)
streams <- readVECT('streams_v', ignore.stderr = TRUE)
plot(dem, col = terrain.colors(20))
lines(streams, col = 'blue', lwd = 2)
lines(streams_o, col = 'lightblue', lwd = 1)
legend("topright", col = c("lightblue", "blue"),  lwd = c(1,2), 
       legend = c("read in streams for burn in", "derived streams"))#' 
# }
# NOT RUN {
# }