calc_subbas: Calculation of hydrological subbasins using GRASS GIS

View source: R/subbasin.R

calc_subbasR Documentation

Calculation of hydrological subbasins using GRASS GIS

Description

Takes DEM from a GRASS location and a file of drainage locations to calculate hydrological subbasins for each drainage point using GRASS functions.

Usage

calc_subbas(
  dem = NULL,
  drain_points = NULL,
  river = NULL,
  flowaccum = NULL,
  drainage_dir = NULL,
  disk_swap = FALSE,
  basin_out = NULL,
  stream = NULL,
  points_processed = NULL,
  outlet = NULL,
  thresh_stream = NULL,
  thresh_sub = NULL,
  snap_dist = NULL,
  rm_spurious = 0.01,
  keep_temp = F,
  overwrite = F,
  silent = F
)

Arguments

dem

Digital Elevation Model in GRASS location used for delineation of subbasins. Should be larger than the expected catchment, otherwise artefacts close to boundaries may occur.

drain_points

SpatialPoints object containing drainage locations in units of and compliant with the projection of your respective GRASS location. Can, e.g., be imported from GRASS with drain_points = readVECT(vname = "subbas_outlets", layer=1). At least the watershed drainage point has to be given. If it contains column 'subbas_id' in the attribute table, this will be used for numbering the subbasins. IDs of additionally delineated subbasins (if thresh_sub != NULL) will be appended.

river

River vector map in GRASS location if available. If set to NULL (default value) river network will be calculated by GRASS function r.watershed.

flowaccum

(optional) Existing raster map of flow accumulation in GRASS location. Must correspond to map generated by r.watershed. If drainage_dir or flowaccum is set to NULL (default value), both will be calculated by GRASS function r.watershed.

drainage_dir

(optional) Existing raster map of drainage direction in GRASS location. Must correspond to map generated by r.watershed. If flowaccum or flowaccum is set to NULL (default value), both will be calculated by GRASS function r.watershed.

disk_swap

(optional) Only needed if memory requirements exceed available RAM (large DEMs): If set to TRUE, r.watershed uses the "-m"-flag (slow)

basin_out

Output: Name of subbasins raster map exported into GRASS location.

stream

Output: Prefix of calculated stream segments vector (<stream>_vect) and raster (<stream>_rast) maps exported into GRASS location. Only generated if river is not set. Default: NULL.

points_processed

Output: Prefix of point vector files exported to GRASS location. <points_processed>_snapped_t are given drain_points snapped to river. <points_processed>_calc_t are internally calculated drain points (only if parameter thresh_sub is not NULL, see below).

outlet

Integer (row number) defining the catchment outlet in drain_points. If there are drain_points outside the watershed delineated for the outlet point these will be omitted. If NULL (default) and drain_points contains only one point this will be assumed as catchment outlet.

thresh_stream

Integer defining threshold for stream calculation. Raster cells in accumulation map with values greater than thresh_stream are considered as streams. Needs to be set only if river is not set. Default: NULL.

thresh_sub

Integer defining threshold for subbasin calculation. Parameter for GRASS function r.watershed defining the minimum size of an exterior watershed basin in number of grid cells. If NULL (default) only the given drainage points are used for subbasin delineation.

snap_dist

Integer defining maximum distance for snapping of drain_points to stream segments in units of your GRASS location.

rm_spurious

numeric. If greater zero, spurious subbasins will be removed, i.e. those subbasins being smaller than rm_spurious times thresh_sub. Spurious subbasins are 'interior' watersheds created by GRASS function r.watershed around stream segments below multiple tributaries. If they are very small they induce unnecessary computational burden when used within a hydrological model. If removed, these areas will be related to the next upstream subbasins, respectively. If thresh_sub = NULL (default) rm_spurious will be automatically set to 0. Default: 0.01.

keep_temp

logical. Set to TRUE if temporary files shall be kept in the GRASS location, e.g. for debugging or further analyses. Default: FALSE.

overwrite

logical. Shall output of previous calls of this function be deleted? If FALSE the function returns an error if output already exists. Default: FALSE.

silent

logical. Shall the function be silent (also suppressing warnings of internally used GRASS functions)? Default: FALSE.

Details

The function constructs subbasins based on param drain_points (if given) and param thresh_sub (if given). Both are merged, preserving the former outlet points, if present.

Value

Function returns nothing. Various output is generated in the GRASS-location:

  • stream segmentsIf river is not supplied, vector (<stream>_vect) and raster (<stream>_rast) will be generated.

  • Subbasin mapraster map basin_out

If keep_temp=TRUE, the following temporary maps are preserved and can be used for tracing errors:

  • accum_tIf flowaccum is not supplied, contains map of flow accumulation.

  • drain_tIf flowaccum is not supplied, contains map of darinage direction.

  • <points_processed>_tRaw subbasin outlet points.

  • <points_processed>_centered_tSubbasin outlet points centered at cell centers.

  • <points_processed>_shifted_tSubbasin outlet points shifted slightly out of centers (for preventing pathological cases while snapping).

  • <points_processed>_snapped_tRaw subbasin outlet points snapped to closest river.

  • <points_processed>_calc_tinternally calculated drain points (only if parameter thresh_sub is not NULL).

  • <points_processed>_all_tcombined drain points as raster (easier to identify double drain points sharing one raster cell).

Note

Prepare GRASS location and necessary raster files in advance and start GRASS session in R using initGRASS. Location should not contain any maps ending on *_t as these will be removed by calling the function to remove temporary maps.

You should select your DEM sufficiently large. Otherwise, the resulting catchment might be truncated or boundaries influence the calculation of stream segments.

Check the results (subbasins and snapped points). In case points have been snapped to the wrong stream segment, adjust point locations manually in GRASS and re-run the function with the updated locations (use readVECT to import the updated drainage points).

Generated raster and vector stream maps might slightly deviate from each other as the raster map is thinned (GRASS function r.thin) prior to conversion to a vector map to ensure strictly linear features.

If you run into memory issues, consider argument disk_swap (see also https://grass.osgeo.org/grass74/manuals/r.watershed.html#in-memory-mode-and-disk-swap-mode) and see discussion on https://github.com/tpilz/lumpR/issues/16.

Author(s)

Tobias Pilz tpilz@uni-potsdam.de

References

lumpR package introduction with literature study and sensitivity analysis:
Pilz, T.; Francke, T.; Bronstert, A. (2017): lumpR 2.0.0: an R package facilitating landscape discretisation for hillslope-based hydrological models. Geosci. Model Dev., 10, 3001-3023, doi: 10.5194/gmd-10-3001-2017


tpilz/LUMP documentation built on Aug. 5, 2023, 1:31 a.m.