An Implementation of IDW-PLUS (Inverse Distance Weighted Percent Land Use for Streams) in R

Description

Use R to call the hydrological toolboxes and functions in GRASS GIS to compute spatially explicit land-use metrics for stream survey sites. The package includes functions for preprocessing digital elevation and streams data, and one function to compute all the spatially explicit land use metrics described in Peterson et al. (2011) Freshwater Biology, 56(3), 590-610.

Author(s)

Maintainer: Alan Pearse alan.pearse@unimelb.edu.au

Authors:

• Grace Heron g.heron@qut.edu.au

• Erin Peterson erin@peterson-consulting.com

Burn in streams to a digital elevation model

Description

Burning-in streams (also called 'drainage reinforcement') ensures flow direction and accumulation grids based on the digital elevation model will correctly identify the stream path.

Usage

burn_in(dem, stream, out, burn = 10, overwrite = FALSE)

Arguments

Value

Nothing. A raster with the name out will be written to the current GRASS mapset.

Examples

# Will only run if a GRASS session is initialised
if(check_running()){
# Load data set
dem <- system.file("extdata", "dem.tif", package = "rdwplus")
stream_shp <- system.file("extdata", "streams.shp", package = "rdwplus")
set_envir(dem)
raster_to_mapset(dem)
vector_to_mapset(stream_shp)

# Create binary stream
rasterise_stream("streams", "streams_rast")
reclassify_streams("streams_rast", "streams_binary", out_type = "binary")

# Burn dem 
burn_in(dem = "dem.tif", stream = "streams_binary", 
out = "dem_burn", burn = 10, overwrite = FALSE)

# Plot
plot_GRASS("dem_burn", col = topo.colors(10))
}

Check whether a valid GRASS session is running

Description

This function is mostly used internally by other functions in the package. However, users may call this function to check whether they have correctly established a GRASS session prior to using the other functions in the package.

Usage

check_running()

Value

A logical. The logical indicates whether a valid GRASS session is currently running.

Examples

check_running()

Clear current raster mask

Description

This function has no parameters. It can be used to clear an existing raster mask.

Usage

clear_mask()

Examples

if(check_running()) clear_mask()

Compute iFLO weights

Description

Compute an iFLO weight raster outside of the compute_metrics() function.

Usage

compute_iFLO_weights(
  pour_point,
  watershed,
  null_streams,
  flow_dir,
  out_flow_length,
  out_iFLO,
  out_iFLO_no_stream,
  idwp = -1,
  remove_streams = FALSE,
  ...
)

Arguments

Value

Nothing.

Examples

if(check_running()){
# Retrieve paths to data sets
dem <- system.file("extdata", "dem.tif", package = "rdwplus")
lus <- system.file("extdata", "landuse.tif", package = "rdwplus")
sts <- system.file("extdata", "site.shp", package = "rdwplus")
stm <- system.file("extdata", "streams.shp", package = "rdwplus")

# Set environment
set_envir(dem)

# Get other data sets (stream layer, sites, land use, etc.)
raster_to_mapset(lus)
vector_to_mapset(c(stm, sts))

# Reclassify streams
out_stream <- paste0(tempdir(), "/streams.tif")
rasterise_stream("streams", out_stream, TRUE)
reclassify_streams("streams.tif", "streams01.tif", overwrite = TRUE)

# Burn in the streams to the DEM
burn_in("dem.tif", "streams01.tif", "burndem.tif", overwrite = TRUE)

# Fill dem
fill_sinks("burndem.tif", "filldem.tif", "fd1.tif", "sinks.tif", overwrite = TRUE)

# Derive flow direction and accumulation grids
derive_flow("dem.tif", "fd.tif", "fa.tif", overwrite = T)

# Derive a new stream raster from the FA grid
derive_streams("dem.tif", "fa.tif", "new_stm.tif", "new_stm", min_acc = 200, overwrite = T)

# Recode streams
reclassify_streams("new_stm.tif", "null_stm.tif", "none")

# Snap sites to streams and flow accumulation
snap_sites("site", "new_stm.tif", "fa.tif", 2, "snapsite", T)

# Get watersheds
get_watersheds("snapsite", "fd.tif", "wshed.tif", T)

#  Get pour points
coord_to_raster("snapsite", which = 1, out = "pour_point")

# Get iFLO weights
compute_iFLO_weights(
"pour_point", 
"wshed.tif", 
"null_stm.tif", 
"fd.tif", 
"fl_outlet.tif", 
"iFLO_weights.tif", 
idwp = -1, 
remove_streams = FALSE
)
plot_GRASS("iFLO_weights.tif", col = topo.colors(12))
}

Compute iFLS weights

Description

Compute an iFLO weight raster outside of the compute_metrics() function.

Usage

compute_iFLS_weights(
  streams,
  null_streams,
  flow_dir,
  out_flow_length,
  out_iFLS,
  out_iFLS_no_stream,
  watershed,
  idwp,
  remove_streams,
  ...
)

Arguments

Value

Nothing.

Examples

if(check_running()){
# Retrieve paths to data sets
dem <- system.file("extdata", "dem.tif", package = "rdwplus")
lus <- system.file("extdata", "landuse.tif", package = "rdwplus")
sts <- system.file("extdata", "site.shp", package = "rdwplus")
stm <- system.file("extdata", "streams.shp", package = "rdwplus")

# Set environment
set_envir(dem)

# Get other data sets (stream layer, sites, land use, etc.)
raster_to_mapset(lus)
vector_to_mapset(c(stm, sts))

# Reclassify streams
out_stream <- paste0(tempdir(), "/streams.tif")
rasterise_stream("streams", out_stream, TRUE)
reclassify_streams("streams.tif", "streams01.tif", overwrite = TRUE)

# Burn in the streams to the DEM
burn_in("dem.tif", "streams01.tif", "burndem.tif", overwrite = TRUE)

# Fill dem
fill_sinks("burndem.tif", "filldem.tif", "fd1.tif", "sinks.tif", overwrite = TRUE)

# Derive flow direction and accumulation grids
derive_flow("dem.tif", "fd.tif", "fa.tif", overwrite = T)

# Derive a new stream raster from the FA grid
derive_streams("dem.tif", "fa.tif", "new_stm.tif", "new_stm", min_acc = 200, overwrite = T)

# Recode streams
reclassify_streams("new_stm.tif", "null_stm.tif", "none")

# Snap sites to streams and flow accumulation
snap_sites("site", "new_stm.tif", "fa.tif", 2, "snapsite", T)

# Get watersheds
get_watersheds("snapsite", "fd.tif", "wshed.tif", T)

# Get iFLS weights
compute_iFLS_weights(
"new_stm.tif", 
"null_stm.tif", 
"fd.tif", 
"fl_streams.tif", 
"iFLS_weights.tif", 
idwp = -1, 
watershed = "wshed.tif", 
remove_streams = FALSE, 
overwrite = T
)
plot_GRASS("iFLS_weights.tif", col = topo.colors(12))
}

Compute spatially explicit watershed attributes for survey sites on streams

Description

Workhorse function for rdwplus. This function computes the spatially explicit landuse metrics in IDW-Plus (Peterson and Pearse, 2017).

Usage

compute_metrics(
  metrics = c("lumped", "iFLO", "iFLS", "HAiFLO", "HAiFLS"),
  landuse,
  sites,
  out_fields,
  watersheds,
  flow_dir,
  flow_acc,
  streams,
  idwp = -1,
  percentage = TRUE,
  remove_streams = TRUE,
  max_memory = 300
)

Arguments

Value

A sf object of the snapped survey sites that also contains the computed landscape metrics.

References

Peterson, E.E. & Pearse, A.R. (2017). IDW-Plus: An ArcGIS toolset for calculating spatially explicit watershed attributes for survey sites. JAWRA, 53(5), 1241-1249.

Examples

# Will only run if GRASS is running
# You should load rdwplus and initialise GRASS via the initGRASS function
if(check_running()){
# Retrieve paths to data sets
dem <- system.file("extdata", "dem.tif", package = "rdwplus")
lus <- system.file("extdata", "landuse.tif", package = "rdwplus")
sts <- system.file("extdata", "site.shp", package = "rdwplus")
stm <- system.file("extdata", "streams.shp", package = "rdwplus")

# Set environment 
set_envir(dem)

# Get other data sets (stream layer, sites, land use, etc.)
raster_to_mapset(lus)
vector_to_mapset(c(stm, sts))

# Reclassify streams
out_stream <- paste0(tempdir(), "/streams.tif")
rasterise_stream("streams", out_stream, TRUE)
reclassify_streams("streams.tif", "streams01.tif", overwrite = TRUE)

# Burn in the streams to the DEM
burn_in("dem.tif", "streams01.tif", "burndem.tif", overwrite = TRUE)

# Fill dem
fill_sinks("burndem.tif", "filldem.tif", "fd1.tif", "sinks.tif", overwrite = TRUE)

# Derive flow direction and accumulation grids
derive_flow("dem.tif", "fd.tif", "fa.tif", overwrite = T)

# Derive a new stream raster from the FA grid
derive_streams("dem.tif", "fa.tif", "new_stm.tif", "new_stm", min_acc = 200, overwrite = T)

# Snap sites to streams and flow accumulation
snap_sites("site", "new_stm.tif", "fa.tif", 2, "snapsite", T)

# Get watersheds
get_watersheds("snapsite", "fd.tif", "wshed.tif", T)

compute_metrics(
  metrics = c("lumped", "iFLO", "iEDO", "HAiFLO", "iFLS", "iEDS", "HAiFLS"),
  landuse = "landuse.tif",
  sites = "snapsite",
  out_fields = c("lumped", "iFLO", "iEDO", "HAiFLO", "iFLS", "iEDS", "HAiFLS"),
  watersheds = "wshed.tif",
  flow_dir = "fd.tif",
  flow_acc = "fa.tif",
  streams = "new_stm.tif",
  idwp = -1
)
}

Compute spatially explicit watershed attributes for survey sites on streams

Description

Workhorse function for rdwplus. This function computes the spatially explicit landuse metrics in IDW-Plus (Peterson and Pearse, 2017). In contrast to compute_metrics(), this version of the function assumes most of the intermediate data layers (i.e., flow path distance and inverse-distance weight rasters) have been precomputed.

Usage

compute_metrics_precomputed(
  metrics = c("lumped", "iFLO", "iFLS", "HAiFLO", "HAiFLS"),
  landuse,
  sites,
  out_fields,
  watersheds,
  flow_dir,
  flow_acc,
  iEDO_weights,
  iFLO_weights,
  HAiFLO_weights,
  iEDS_weights,
  iFLS_weights,
  HAiFLS_weights,
  percentage = TRUE,
  max_memory = 300
)

Arguments

Value

A sf object of the snapped survey sites that also contains the computed landscape metrics.

References

Peterson, E.E. & Pearse, A.R. (2017). IDW-Plus: An ArcGIS toolset for calculating spatially explicit watershed attributes for survey sites. JAWRA, 53(5), 1241-1249.

Examples

# Will only run if GRASS is running
# You should load rdwplus and initialise GRASS via the initGRASS function
if(check_running()){
# Retrieve paths to data sets
dem <- system.file("extdata", "dem.tif", package = "rdwplus")
lus <- system.file("extdata", "landuse.tif", package = "rdwplus")
sts <- system.file("extdata", "site.shp", package = "rdwplus")
stm <- system.file("extdata", "streams.shp", package = "rdwplus")

# Set environment
set_envir(dem)

# Get other data sets (stream layer, sites, land use, etc.)
raster_to_mapset(lus)
vector_to_mapset(c(stm, sts))

# Reclassify streams
out_stream <- paste0(tempdir(), "/streams.tif")
rasterise_stream("streams", out_stream, TRUE)
reclassify_streams("streams.tif", "streams01.tif", overwrite = TRUE)

# Burn in the streams to the DEM
burn_in("dem.tif", "streams01.tif", "burndem.tif", overwrite = TRUE)

# Fill dem
fill_sinks("burndem.tif", "filldem.tif", "fd1.tif", "sinks.tif", overwrite = TRUE)

# Derive flow direction and accumulation grids
derive_flow("dem.tif", "fd.tif", "fa.tif", overwrite = T)

# Derive a new stream raster from the FA grid
derive_streams("dem.tif", "fa.tif", "new_stm.tif", "new_stm", min_acc = 200, overwrite = T)

# Recode streams
reclassify_streams("new_stm.tif", "null_stm.tif", "none")

# Snap sites to streams and flow accumulation
snap_sites("site", "new_stm.tif", "fa.tif", 2, "snapsite", T)

# Get watersheds
get_watersheds("snapsite", "fd.tif", "wshed.tif", T)

#  Get pour points
coord_to_raster("snapsite", which = 1, out = "pour_point")

# Get iFLO weights
compute_iFLO_weights(
"pour_point", 
"wshed.tif", 
"null_stm.tif", 
"fd.tif", 
"fl_outlet.tif", 
"iFLO_weights.tif", 
idwp = -1, 
remove_streams = FALSE
)

# Get iFLS weights
compute_iFLS_weights(
"new_stm.tif", 
"null_stm.tif", 
"fd.tif", 
"fl_streams.tif", 
"iFLS_weights.tif", 
idwp = -1, 
watershed = "wshed.tif", 
remove_streams = FALSE, 
overwrite = T
)

# Compute metrics for this site
compute_metrics_precomputed(
  metrics = c("iFLO", "iFLS"),
  landuse = "landuse.tif",
  sites = "snapsite",
  out_fields = c("iFLO", "iFLS"),
  watersheds = "wshed.tif",
  iFLO_weights = "iFLO_weights.tif",
  iFLS_weights = "iFLS_weights.tif",
  flow_dir = "fd.tif",
  flow_acc = "fa.tif"
)
}

Convert a raster to integer format

Description

Given a raster in float, double or any other format, this function will convert it to integer format. This can be important because it is often an unstated requirement of GRASS modules such as the one for zonal statistics.

Usage

convert_to_integer(x, out)

Arguments

Value

Nothing. A raster with the name out will be added to the current GRASS mapset.

Examples

# Will only run if GRASS is running
if(check_running()){

# Load data set
dem <- system.file("extdata", "dem.tif", package = "rdwplus")

# Set environment 
set_envir(dem)

# Make an integer-valued version of 'dem.tif'
convert_to_integer("dem.tif", "int_dem.tif")

# Compare
plot_GRASS("dem.tif")
plot_GRASS("int_dem.tif")

}

Turn coordinates of outlets into rasters

Description

Given a set of x-y coordinates, this function will return a raster with a single cell at those coordinates.

Usage

coord_to_raster(outlets, which, out, overwrite = FALSE)

Arguments

Details

This function is exposed to the user, and users are welcome to use if convenient for them, this function is intended for internal use in other functions.

Value

Nothing.

Examples

# Will only run if GRASS is running
if(check_running()){
# Load data set
dem <- system.file("extdata", "dem.tif", package = "rdwplus")
sts <- system.file("extdata", "sites.shp", packages = "rdwplus")

# Set environment parameters
set_envir(dem)

# Read in sites
vector_to_mapset(sts)

# Convert first site to raster
coord_to_raster("site", 1, "coords", overwrite = TRUE)
}

Obtain flow direction and accumulation over a digital elevation model (DEM)

Description

This function computes flow direction and accumulation (among other things) from a DEM. This is done using the r.watershed tool in GRASS.

Usage

derive_flow(
  dem,
  flow_dir,
  flow_acc,
  d8 = TRUE,
  overwrite = FALSE,
  max_memory = 300,
  ...
)

Arguments

Value

Nothing. Files are written in the current GRASS mapset.

Examples

if(check_running()){
# Load data set
dem <- system.file("extdata", "dem.tif", package = "rdwplus")
stream_shp <- system.file("extdata", "streams.shp", package = "rdwplus")

# Set environment parameters and import data to GRASS
set_envir(dem)
vector_to_mapset(vectors = c(stream_shp))

# Create binary stream
out_name <- paste0(tempdir(), "/streams_rast.tif")
rasterise_stream("streams", out_name, overwrite = TRUE)
reclassify_streams("streams_rast.tif", "streams_binary.tif", 
out_type = "binary", overwrite = TRUE)

# Burn dem 
burn_in(dem = "dem.tif", stream = "streams_binary.tif", out = "dem_burn.tif",
 burn = 10, overwrite = TRUE)

# Fill sinks
fill_sinks(dem = "dem_burn.tif", out_dem =  "dem_fill.tif", out_fd = "fd1.tif", overwrite = TRUE)

# Derive flow accumulation and direction grids
derive_flow(dem = "dem_fill.tif", 
flow_dir = "fdir.tif", 
flow_acc = "facc.tif", 
overwrite = TRUE)

# Plot
plot_GRASS("fdir.tif", col = topo.colors(6))
plot_GRASS("facc.tif", col = topo.colors(6))
}

Extract streams from a flow accumulation raster

Description

Derive a raster and a vector layer of stream lines from a flow accumulation raster.

Usage

derive_streams(
  dem,
  flow_acc,
  out_rast,
  out_vect,
  min_acc = 1000,
  min_length = 0,
  overwrite = FALSE,
  ...
)

Arguments

Value

Nothing. A vector dataset with the name basename(out) will appear in the current GRASS mapset.

Examples

 
# Will only run if GRASS is running
if(check_running()){
# Retrieve paths to data sets
dem <- system.file("extdata", "dem.tif", package = "rdwplus")
lus <- system.file("extdata", "landuse.tif", package = "rdwplus")
sts <- system.file("extdata", "site.shp", package = "rdwplus")
stm <- system.file("extdata", "streams.shp", package = "rdwplus")

# Set environment
set_envir(dem)

# Get other data sets (stream layer, sites, land use, etc.)
raster_to_mapset(lus)
vector_to_mapset(c(stm, sts))

# Reclassify streams
out_stream <- paste0(tempdir(), "/streams.tif")
rasterise_stream("streams", out_stream, TRUE)
reclassify_streams("streams.tif", "streams01.tif", overwrite = TRUE)

# Burn in the streams to the DEM
burn_in("dem.tif", "streams01.tif", "burndem.tif", overwrite = TRUE)

# Fill dem
fill_sinks("burndem.tif", "filldem.tif", "fd1.tif", "sinks.tif", overwrite = TRUE)

# Derive flow direction and accumulation grids
derive_flow("dem.tif", "fd.tif", "fa.tif", overwrite = T)

# Derive a new stream raster from the FA grid
derive_streams("dem.tif", "fa.tif", "new_stm.tif", "new_stm", min_acc = 200, overwrite = T)
}

Fill sinks in a digital elevation model (DEM)

Description

Remove sinks in a DEM (see the 'Details' section)

Usage

fill_sinks(dem, out_dem, out_fd, out_sinks, overwrite = FALSE, ...)

Arguments

Details

A sink is a depression in a DEM. Water flows into these depressions but does not flow out of them. These depressions, although often real features of landscapes, are problematic for flow direction and accumulation algorithms. Therefore, it is common practice to remove these depressions.

Value

Nothing. A file with the name out will be created in the current GRASS mapset.

Examples

# Will only run if GRASS is running
if(check_running()){
# Retrieve paths to data sets
dem <- system.file("extdata", "dem.tif", package = "rdwplus")
lus <- system.file("extdata", "landuse.tif", package = "rdwplus")
sts <- system.file("extdata", "site.shp", package = "rdwplus")
stm <- system.file("extdata", "streams.shp", package = "rdwplus")

# Set environment
set_envir(dem)

# Get other data sets (stream layer, sites, land use, etc.)
raster_to_mapset(lus)
vector_to_mapset(c(stm, sts))

# Reclassify streams
out_stream <- paste0(tempdir(), "/streams.tif")
rasterise_stream("streams", out_stream, TRUE)
reclassify_streams("streams.tif", "streams01.tif", overwrite = TRUE)

# Burn in the streams to the DEM
burn_in("dem.tif", "streams01.tif", "burndem.tif", overwrite = TRUE)

# Fill dem
fill_sinks("burndem.tif", "filldem.tif", "fd1.tif", "sinks.tif", overwrite = TRUE)
}

Compute Euclidean distance to a survey site or stream line within a watershed

Description

This function is needed to compute Euclidean distance from a feature of interest in a watershed raster.

Usage

get_distance(target, out, overwrite = FALSE)

Arguments

Value

Nothing. A file with the name basename(out) will be created in the current GRASS mapset.

Examples

if(check_running()){

# Retrieve paths to data sets
dem <- system.file("extdata", "dem.tif", package = "rdwplus")
lus <- system.file("extdata", "landuse.tif", package = "rdwplus")
sts <- system.file("extdata", "site.shp", package = "rdwplus")
stm <- system.file("extdata", "streams.shp", package = "rdwplus")

# Set environment
set_envir(dem)

# Get other data sets (stream layer, sites, land use, etc.)
raster_to_mapset(lus)
vector_to_mapset(c(stm, sts))

# Reclassify streams
out_stream <- paste0(tempdir(), "/streams.tif")
rasterise_stream("streams", out_stream, TRUE)
reclassify_streams("streams.tif", "streams01.tif", overwrite = TRUE)

# Burn in the streams to the DEM
burn_in("dem.tif", "streams01.tif", "burndem.tif", overwrite = TRUE)

# Fill dem
fill_sinks("burndem.tif", "filldem.tif", "fd1.tif", "sinks.tif", overwrite = TRUE)

# Derive flow direction and accumulation grids
derive_flow("dem.tif", "fd.tif", "fa.tif", overwrite = T)

# Derive a new stream raster from the FA grid
derive_streams("dem.tif", "fa.tif", "new_stm.tif", "new_stm", min_acc = 200, overwrite = T)

# Get distances
get_distance("new_stm.tif", "dist_from_stream.tif", T)

}

Derive a flow length to streams and outlets

Description

Given a (hydrologically corrected, see fill_sinks) DEM, this function produces a flow accumulation grid which shows the upstream area that flows into each cell in the DEM. Note that this function calls r.stream.distance, which is a GRASS GIS add-on. It can be installed through the GRASS GUI.

Usage

get_flow_length(
  str_rast,
  flow_dir,
  out,
  to_outlet = FALSE,
  overwrite = FALSE,
  max_memory = 300
)

Arguments

Value

Nothing. A file with the name out will be written to GRASS's current workspace.

Examples

# Will only run if GRASS is running
if(check_running()){
# Load data set
dem <- system.file("extdata", "dem.tif", package = "rdwplus")
sites <- system.file("extdata", "site.shp", package = "rdwplus")
stream_shp <- system.file("extdata", "streams.shp", package = "rdwplus")

# Set environment parameters and import data to GRASS
set_envir(dem)
raster_to_mapset(rasters = dem, as_integer = FALSE)
vector_to_mapset(vectors = c(sites, stream_shp))

# Create binary stream
rasterise_stream("streams", "streams_rast.tif", overwrite = TRUE)

# Burn dem
burn_in(dem = "dem.tif", stream = "streams_binary.tif",
        out = "dem_burn.tif", burn = 10, overwrite = TRUE)

# Fill sinks
fill_sinks(dem = "dem_burn.tif", out_dem = "dem_fill.tif", out_fd = "fd1.tif", overwrite = TRUE)

# Derive flow accumulation and direction grids
derive_flow(dem = "dem_fill.tif", flow_dir = "fdir.tif",
            flow_acc = "facc.tif", overwrite = TRUE)

# Derive watershed
get_watersheds(sites = "site", flow_dir = "fdir.tif", out = "wshed.tif", overwrite = T)

# Set mask
set_mask("wshed.tif")

# Get flow length
get_flow_length(
  str_rast = "streams_rast.tif",
  flow_dir = "fdir.tif",
  out = "flowlength.tif",
  to_outlet = TRUE,
  overwrite = TRUE
)

# Plot
plot_GRASS("flowlength.tif", col = topo.colors(15))
}

Delineate watersheds for survey sites

Description

This function delineates watersheds around a set of survey sites.

Usage

get_watersheds(sites, flow_dir, out, overwrite = FALSE, lessmem = FALSE)

Arguments

Value

Nothing. A raster file with the name out may be written to file if you have set the write_file argument accordingly. A raster with the name basename(out) will be imported into the current GRASS mapset.

Examples

# Will only run if GRASS is running
if(check_running()){
# Retrieve paths to data sets
dem <- system.file("extdata", "dem.tif", package = "rdwplus")
lus <- system.file("extdata", "landuse.tif", package = "rdwplus")
sts <- system.file("extdata", "site.shp", package = "rdwplus")
stm <- system.file("extdata", "streams.shp", package = "rdwplus")

# Set environment
set_envir(dem)

# Get other data sets (stream layer, sites, land use, etc.)
raster_to_mapset(lus)
vector_to_mapset(c(stm, sts))

# Reclassify streams
out_stream <- paste0(tempdir(), "/streams.tif")
rasterise_stream("streams", out_stream, TRUE)
reclassify_streams("streams.tif", "streams01.tif", overwrite = TRUE)

# Burn in the streams to the DEM
burn_in("dem.tif", "streams01.tif", "burndem.tif", overwrite = TRUE)

# Fill dem
fill_sinks("burndem.tif", "filldem.tif", "fd1.tif", "sinks.tif", overwrite = TRUE)

# Derive flow direction and accumulation grids
derive_flow("dem.tif", "fd.tif", "fa.tif", overwrite = T)

# Derive a new stream raster from the FA grid
derive_streams("dem.tif", "fa.tif", "new_stm.tif", "new_stm", min_acc = 200, overwrite = T)

# Recode streams
reclassify_streams("new_stm.tif", "null_stm.tif", "none")

# Snap sites to streams and flow accumulation
snap_sites("site", "new_stm.tif", "fa.tif", 2, "snapsite", T)

# Get watersheds
get_watersheds("snapsite", "fd.tif", "wshed.tif", T)
}

Install required extension(s)

Description

Some functions in the rdwplus package rely on GRASS extensions that need to be installed prior to use. This function installs those extensions.

Usage

install_extensions()

Details

This function has no arguments. Simply run it and it will install a pre-set list of GRASS extensions.

Currently, the GRASS extension required are r.stream.snap, r.stream.distance, and r.wateroutlet.lessmem.

Value

Nothing.

Examples

# Will only run if GRASS is running
if(check_running()){
    install_extensions()
}

A function to plot a raster from the current GRASS mapset

Description

Given the name of a raster in the current GRASS mapset, this function will plot it as a stars object.

Usage

plot_GRASS(x, colours, out_x, ...)

Arguments

Value

Nothing.

Examples

# Will only run if GRASS is running
# You should load rdwplus and initialise GRASS via the initGRASS function
if(check_running()){

# Load data set
dem <- system.file("extdata", "dem.tif", package = "rdwplus")

# Set environment 
set_envir(dem)

# Plot
plot_GRASS("dem.tif") # argument must match name of data set in the mapset
plot_GRASS("dem.tif", heat.colors(10)) # with different colour scale

}

Convert outlet of a watershed from shapefile format into raster format

Description

Given a shapefile of outlet(s), this function will convert its contents into a raster.

Usage

point_to_raster(outlets, out, overwrite = FALSE, max_memory = 300)

Arguments

Value

Nothing. A file called out will be created in the current GRASS mapset.

Examples

# Will only run if GRASS is running
if(check_running()){

# Load data set
dem <- system.file("extdata", "dem.tif", package = "rdwplus")
sites <- system.file("extdata", "site.shp", package = "rdwplus")

# Set environment parameters and import data to GRASS
set_envir(dem)
vector_to_mapset(vectors = sites)

# Point to raster
point_to_raster(outlets = "site", out = "sites_rast.tif", overwrite = TRUE)

# Check conversion success
vibe_check()

}

Raster calculator (wrapper for "r.mapcalc")

Description

Raster calculator (wrapper for "r.mapcalc")

Usage

rast_calc(ex, overwrite = TRUE)

Arguments

Value

Nothing.

Import rasters into GRASS mapset

Description

GRASS can only deal with raster and vector data in a GRASS mapset. This function takes external rasters and imports them into the current GRASS mapset.

Usage

raster_to_mapset(
  rasters,
  as_integer = rep(FALSE, length(rasters)),
  overwrite = FALSE,
  max_memory = 300,
  ...
)

Arguments

Value

A vector of raster layer names in the GRASS mapset.

Examples

 
# Will only run if a GRASS session is initialised
if(check_running()){
   dem <- system.file("extdata", "dem.tif", package = "rdwplus")
   raster_to_mapset(dem)
}

Turn a shapefile of stream edges into a raster

Description

Given a shapefile of lines representing the channels of a stream network, this function will return a rasterised version of the shapefile. The raster will have the parameters of the current GRASS mapset.

Usage

rasterise_stream(streams, out, overwrite = FALSE, max_memory = 300, ...)

Arguments

Value

Nothing. A file will be written to out. Note that out can be a full file path to any location in your file system. A raster with the name basename(out) will be written to the current GRASS mapset.

Examples

# Will only run if GRASS is running
if(check_running()){
# Load data set
dem <- system.file("extdata", "dem.tif", package = "rdwplus")
stream_shp <- system.file("extdata", "streams.shp", package = "rdwplus")

# Set environment parameters and import data to GRASS
set_envir(dem)
vector_to_mapset(vectors = stream_shp)

# Create rasterised stream
rasterise_stream("streams", "streams_rast.tif", overwrite = TRUE)

# Plot
plot_GRASS("streams_rast.tif")

}

Reclassify streams into various formats

Description

Re-format a stream raster.

Usage

reclassify_streams(stream, out, out_type = "binary", overwrite = FALSE)

Arguments

Details

Given a streams raster, this function will either create a binary streams raster (0 for non-stream cells and 1 for stream cells) or a unary streams raster (1 for stream cells and NoData for all other cells). Another option is to reclassify the streams raster such that stream cells are given the value NoData and non-stream cells are given the value 1.

Do not use raster names containing dashes/hyphens. The underlying call to r.calc will crash if the raster name contains these symbols because they are misinterpreted as math symbols.

Value

Nothing. A file with the name out will be written to the current GRASS mapset. This raster will be in unsigned integer format.

Examples

# Will only run if GRASS is running
if(check_running()){
# Retrieve paths to data sets
dem <- system.file("extdata", "dem.tif", package = "rdwplus")
lus <- system.file("extdata", "landuse.tif", package = "rdwplus")
sts <- system.file("extdata", "site.shp", package = "rdwplus")
stm <- system.file("extdata", "streams.shp", package = "rdwplus")

# Set environment 
set_envir(dem)

# Get other data sets (stream layer, sites, land use, etc.)
raster_to_mapset(lus)
vector_to_mapset(c(stm, sts))

# Reclassify streams
out_stream <- paste0(tempdir(), "/streams.tif")
rasterise_stream("streams", out_stream, TRUE)
reclassify_streams("streams.tif", "streams01.tif", overwrite = TRUE)
}

Identify current mapset or list all possible mapsets

Description

GRASS GIS uses a system of mapsets.

Usage

report_mapset(which = "current")

Arguments

Value

Nothing.

Write a raster layer from the current GRASS mapset to file

Description

This function writes a GRASS mapset raster to file.

Usage

retrieve_raster(layer, out_layer, overwrite = FALSE, ...)

Arguments

Value

Nothing.

Examples

# Will only run if GRASS is running
if(check_running()){

# Load data set
dem <- system.file("extdata", "dem.tif", package = "rdwplus")

# Set environment parameters and import data to GRASS
set_envir(dem)
raster_to_mapset(rasters = dem, as_integer = FALSE)

# Retrieve raster 
out_name <- paste0(tempdir(), "/retrieved_dem.tif")
retrieve_raster("dem.tif", out_layer = out_name, overwrite = TRUE)

}

Write a vector layer from the current GRASS mapset to file

Description

This function writes a GRASS mapset vector layer (like a shapefile) to file.

Usage

retrieve_vector(layer, out_layer, overwrite = FALSE, ...)

Arguments

Value

Nothing.

Examples

# Will only run if GRASS is running
if(check_running()){

# Load data set
dem <- system.file("extdata", "dem.tif", package = "rdwplus")
stream_shp <- system.file("extdata", "streams.shp", package = "rdwplus")

# Set environment parameters and import data to GRASS
set_envir(dem)
vector_to_mapset(vectors = stream_shp)

# Retrieve raster 
out_name <- paste0(tempdir(), "/", "retrieved_streams.shp")
retrieve_vector("streams", out_layer = out_name, overwrite = TRUE)

}

Find GRASS installations

Description

This function finds the path to potential GRASS installations. It does so in a very crude way; that is, by searching for directories that match the string 'GRASS'.

Warning: this function works by brute force, so it may take a few minutes to find potential GRASS installations.

Note: This is not guaranteed to work. It is not hard to find the path to your computer's GRASS installation yourself. This is the preferred course of action.

Usage

search_for_grass(guide)

Arguments

Value

A vector of file paths to potential GRASS installations.

Examples

 

my_grass <- search_for_grass()
my_grass

Set projection and computation region from a raster file.

Description

This function simplifies the process of setting up a GRASS environment with parameters such as cell snapping, size and mapset extent.

Usage

set_envir(file, ...)

Arguments

Value

Nothing. Displays current environment settings.

Examples

# Will only run if GRASS is running
# You should load rdwplus and initialise GRASS with initGRASS
if(check_running()){

# Load data set
dem <- system.file("extdata", "dem.tif", package = "rdwplus")

# Set environment 
set_envir(dem)

}

Set a raster mask

Description

Set a raster mask

Usage

set_mask(x, inverse = FALSE, overwrite = TRUE, ...)

Arguments

Value

Nothing.

Examples

if(check_running()){
# Load data set
dem <- system.file("extdata", "dem.tif", package = "rdwplus")
sites <- system.file("extdata", "site.shp", package = "rdwplus")
stream_shp <- system.file("extdata", "streams.shp", package = "rdwplus")

# Set environment parameters and import data to GRASS
set_envir(dem)
raster_to_mapset(rasters = dem, as_integer = FALSE)
vector_to_mapset(vectors = c(sites, stream_shp))

# Create binary stream
rasterise_stream("streams", "streams_rast.tif", overwrite = TRUE)

# Burn dem
burn_in(dem = "dem.tif", stream = "streams_binary.tif",
        out = "dem_burn.tif", burn = 10, overwrite = TRUE)

# Fill sinks
fill_sinks(dem = "dem_burn.tif", out_dem = "dem_fill.tif", out_fd = "fd1.tif", overwrite = TRUE)

# Derive flow accumulation and direction grids
derive_flow(dem = "dem_fill.tif", flow_dir = "fdir.tif",
            flow_acc = "facc.tif", overwrite = TRUE)

# Derive watershed
get_watersheds(sites = "site", flow_dir = "fdir.tif", out = "wshed.tif", overwrite = T)

# Set mask
set_mask("wshed.tif")

# Get flow length
get_flow_length(
  str_rast = "streams_rast.tif",
  flow_dir = "fdir.tif",
  out = "flowlength.tif",
  to_outlet = TRUE,
  overwrite = TRUE
)

# Plot
plot_GRASS("flowlength.tif", col = topo.colors(15))
}

Function to suppress messages, warnings, errors from GRASS commands

Description

Prevents the printing GRASS warnings, etc. Use with extreme caution. This is only helpful IF AND ONLY IF you are SURE that any printed messages, warnings, and errors are spurious.

Usage

silence(value)

Arguments

Value

A logical indicating the current status of the option.

Examples

silence(TRUE)
silence(FALSE)

A function to snap survey sites to a stream raster and a flow accumulation raster

Description

This function takes a set of survey site locations and snaps them to the highest-value cell within a flow accumulation raster, within a specified distance. Note that this function calls r.stream.snap, which is a GRASS GIS add-on. It can be installed through the GRASS GUI.

Usage

snap_sites(
  sites,
  stream,
  flow_acc,
  max_move,
  out,
  overwrite = FALSE,
  max_memory = 300,
  ...
)

Arguments

Value

Nothing.

Examples

# Will only run if GRASS is running
# You should load rdwplus and initialise GRASS via the initGRASS function
if(check_running()){
# Retrieve paths to data sets
dem <- system.file("extdata", "dem.tif", package = "rdwplus")
lus <- system.file("extdata", "landuse.tif", package = "rdwplus")
sts <- system.file("extdata", "site.shp", package = "rdwplus")
stm <- system.file("extdata", "streams.shp", package = "rdwplus")

# Set environment 
set_envir(dem)

# Get other data sets (stream layer, sites, land use, etc.)
raster_to_mapset(lus)
vector_to_mapset(c(stm, sts))

# Reclassify streams
out_stream <- paste0(tempdir(), "/streams.tif")
rasterise_stream("streams", out_stream, TRUE)
reclassify_streams("streams.tif", "streams01.tif", overwrite = TRUE)

# Burn in the streams to the DEM
burn_in("dem.tif", "streams01.tif", "burndem.tif", overwrite = TRUE)

# Fill dem
fill_sinks("burndem.tif", "filldem.tif", "fd1.tif", "sinks.tif", overwrite = TRUE)

# Derive flow direction and accumulation grids
derive_flow("dem.tif", "fd.tif", "fa.tif", overwrite = T)

# Derive a new stream raster from the FA grid
derive_streams("dem.tif", "fa.tif", "new_stm.tif", "new_stm", min_acc = 200, overwrite = T)

# Snap sites to streams and flow accumulation
snap_sites("site", "new_stm.tif", "fa.tif", 2, "snapsite", T)
}

Toggle between silence on and silence off

Description

This function detects whether output suppression is on or off, and switches it to its opposite state. Under one setting, this function can be used as an off-switch for the GRASS message/warning/error suppression enforced via the use of silence(value = TRUE).

Usage

toggle_silence(stay_off = TRUE)

Arguments

Value

A logical indicating whether output suppression is active.

Examples

# Even if silence is currently off, silence will stay off
toggle_silence(TRUE) 

# If silence is currently off, silence will be turned on.
toggle_silence(FALSE)

Import rasters into GRASS mapset

Description

GRASS can only deal with raster and vector data in a GRASS mapset. This function takes external vectors and imports them into the current GRASS mapset.

Usage

vector_to_mapset(vectors, overwrite = FALSE, ...)

Arguments

Value

A vector of vector layer names in the GRASS mapset.

Examples

# Will only run if GRASS is running
if(check_running()){

# Load data set
dem <- system.file("extdata", "dem.tif", package = "rdwplus")
stream_shp <- system.file("extdata", "streams.shp", package = "rdwplus")

# Set environment parameters
set_envir(dem)

# Import vector data to mapset
vector_to_mapset(vectors = stream_shp)

}

A function to summarise the computation region, vectors and rasters in the mapset.

Description

This function takes no inputs. It prints a list of data sets in the current GRASS mapset, as well as the parameters of the current computation region.

Usage

vibe_check()

Value

Nothing.

Examples

if(check_running()) vibe_check()