lump_grass_prep: Pre-processing for Landscape Unit deviation using GRASS GIS

In tpilz/lumpR: Landscape Unit Mapping Program for R

Pre-processing for Landscape Unit deviation using GRASS GIS

Description

Takes raster data from a GRASS location and calculates elementary hillslopes, soil-vegetation-components, and Horton stream order using GRASS functions needed for further Landscape Unit deviation.

Usage

lump_grass_prep(mask = NULL, dem = NULL, lcov = NULL, soil = NULL,
  watermask = NULL, imperviousmask = NULL, eha = NULL,
  flowdir = NULL, flowacc = NULL, stream = NULL,
  stream_horton = NULL, elevriv = NULL, distriv = NULL,
  mask_corr = NULL, svc = NULL, dir_out = NULL, svc_ofile = NULL,
  eha_thres = NULL, sizefilter = NULL, growrad = NULL,
  keep_temp = F, overwrite = F, silent = F, addon_path = NULL,
  things2do = c("eha", "river", "svc"))

Arguments

mask	Mask in GRASS location defining the catchment area. E.g. subbasin raster map.
dem	Digital elevation model in GRASS location used for delineation of environmental hillslope areas. Should be larger than the expected catchment, otherwise artefacts close to boundaries may occur.
lcov	Landcover / vegetation raster map in GRASS location.
soil	Soil raster map in GRASS location.
watermask	Raster in GRASS location masking water surfaces (value '1') from other areas (value '0'). Map is used for svc creation such that a svc is completely covered with water ('special_area' in svc_ofile equal to 1) or contains no water surface. The map must NOT contain NULL values within mask! Default: NULL.
imperviousmask	The same as for watermask but for impervious (e.g. urban and/or rocky) areas. 'special_area' flag in svc_ofile equal to 2. The map must NOT contain NULL values within mask!
eha	Output: Name of Environmental Hillslope Areas (EHA) raster map exported into GRASS location.
flowdir	Output: Name of flow direction raster map exported into GRASS location. Provides the "aspect" for each cell measured counterclockwise from East. Multiplying positive values by 45 will give the direction in degrees that the surface runoff will travel from that cell; zero indicates a depression; negative values that surface runoff is leaving the defined region.
flowacc	Output: Name of flow accumulation raster map exported into GRASS location. Gives the number of upslope cells plus one. Negative values indicate surface runoff from outside the defined region.
stream	Output: Name of stream segments raster map exported into GRASS location. If you want to convert it into a vector map apply GRASS function r.thin beforehand!
stream_horton	Output: Name of stream segments raster map in Horton stream order exported into GRASS location.
elevriv	Output: Name of relative elevation raster map exported into GRASS location. Provides the elevations above stream node in units of dem.
distriv	Output: Name of distance to river raster map exported into GRASS location. Provides distances to stream node in number of grid cells.
mask_corr	DEPRECATED! Argument kept for backwards compatibility.
svc	Output: Name of Soil Vegetation Components raster map exported into GRASS location; cross product of categories of soil and lcov.
dir_out	Character string specifying output directory (will be created; nothing will be overwritten).
svc_ofile	Output: Name of file containing properties of svcs. For 'special_area' flag values of 1 for water areas, 2 for impervious areas and 0 in case it is an ordinary SVC are defined.
eha_thres	Integer specifying threshold for delineation of EHA in cells; parameter for GRASS function r.watershed. This is a crucial parameter affecting the size of delineated hillslopes and the degree of detail of the landscape discretisation! As a rule of thumb, a value 10-100 times smaller than thresh_sub of function calc_subbas is usually a good choice.
sizefilter	Integer specifying the minimum size of EHAs in hectares. Smaller EHAs (possibly artefacts) will be removed. Parameter for GRASS function r.reclass.area. If set to NULL (default), it will be automatically set to a value equivalent to 50 grid cells (ATTENTION: meters will be assumed as unit of the GRASS projection!).
growrad	Integer specifying growing radius (in raster cells) to remove holes in the EHA raster resulting from cleaning of artefacts; parameter for GRASS function r.grow. If set to NULL (default), it will be automatically set to 25 (should be but less than 100 due to long computation times!).
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.
addon_path	Character string giving the path to your locally installed GRASS add-ons. Must only be given if necessary, see Note.
things2do	c("eha","river","svc"). Enables the specification of sub-tasks only. "eha": do EHA generation, "river": calculate river network and morphological parameters, "svc": generate SVC map

Value

Function returns nothing. Output raster files as specified in arguments (see above) are written into GRASS location.

Note

Prepare GRASS location and necessary raster files in advance and start GRASS session in R using initGRASS.

Make sure that the GRASS functions r.stream.distance and r.stream.order are available to your GRASS installation. If not, consider g.extension to install add-ons. If you installed add-ons locally it might occur that from within R the path to add-ons is not recognised. In such a case locate the local installation path (in a GRASS terminal check g.extension -a, echo $GRASS_ADDON_BASE and which r.stream.distance / where r.stream.distance, and specify the absolute path to add-ons via argument addon_path. In Windows, replace backslahes for slashes. For more information, see also http://grasswiki.osgeo.org/wiki/AddOns/GRASS_7.

See GRASS documentation for further information on GRASS functions and parameters.

Author(s)

Tobias Pilz [e-mail]

References

Source code based on SHELL and MATLAB scripts of Till Francke.

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

Theory of LUMP:
Francke, T.; Guentner, A.; Mamede, G.; Mueller, E. N. and Bronstert, A (2008): Automated catena-based discretization of landscapes for the derivation of hydrological modelling units. International Journal of Geographical Information Science, Informa UK Limited, 22(2), 111-132, DOI: 10.1080/13658810701300873

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