area2catena: Calculates mean catena from spatial data

In tpilz/lumpR: Landscape Unit Mapping Program for R

Calculates mean catena from spatial data

Description

Takes raster data from a GRASS location and calculates catena properties.

Usage

area2catena(
  mask = NULL,
  flowacc = NULL,
  eha = NULL,
  distriv = NULL,
  elevriv = NULL,
  supp_quant = NULL,
  supp_qual = NULL,
  dir_out = "./",
  catena_out = NULL,
  catena_head_out = NULL,
  ridge_thresh = 1,
  min_cell_in_slope = 30,
  min_catena_length = 3,
  max_riv_dist = 10,
  plot_catena = F,
  grass_files = F,
  ncores = 1,
  eha_subset = NULL,
  overwrite = F,
  silent = F
)

Arguments

mask	Raster file to be used as MASK in the GRASS location defining the area of interest. E.g. basin_out of calc_subbas.
flowacc	Name of flow accumulation raster map in GRASS location. Can be created with lump_grass_prep.
eha	Name of elementary hillslope area raster map in GRASS location. Can be created with lump_grass_prep.
distriv	Name of distance to river raster map in GRASS location. Can be created with lump_grass_prep.
elevriv	Name of relative elevation raster map in GRASS location. Can be created with lump_grass_prep.
supp_quant	Character vector containing names of quantitative supplemental raster maps in GRASS location; leave empty if you have none.
supp_qual	Character vector containing names of qualitative supplemental raster maps in GRASS location; leave empty if you have none.
dir_out	Character string specifying output directory (will be created; nothing will be overwritten).
catena_out	Output: Name of output file containing mean catena information as input for prof_class. To save computation time and memory in cases of large catchments and/or high resolution, specify a file name with ending *.RData. In such a case, a compressed RData file will be written instead of a text file.
catena_head_out	Output: Name of output header file containing meta-information as input for prof_class; manual adjustment necessary.
ridge_thresh	Integer specifying threshold of flow accumulation, below which a cell is considered a start of a flowpath (usually 1 for D8 flowaccumulation grids, DEFAULT).
min_cell_in_slope	Integer specifying minimum number of cells a hillslope area must have, all smaller ones are skipped. Default: 30.
min_catena_length	Integer specifying minimum number of sampling points (cells) a catena should have. If there are less, the catena is not saved. Default: 3.
max_riv_dist	Integer specifying maximum distance to river [in cells]: if the closest cell of an EHA is farther than max_riv_dist, the EHA is skipped, otherwise all distances within the EHA are redurced by the distance of the closest cell to river. Default: 10.
plot_catena	logical; produce plots (scatter, mean catena, etc.) for each area / class (written into sub-directory plots_area2catena).
grass_files	logical; produce GRASS reclassification files for qualitative raster data. If an attribute name starting with 'svc' is found, the respective reclass file is produced anyway.
ncores	Integer specifying number of cores that should be used for computation - allows faster parallel computations (see Details).
eha_subset	NULL or integer vector with subset of EHA ids that shall be processed (for debugging and testing).
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 summary after function execution)? Default: FALSE.

Value

Function returns nothing. Output files are written into output directory as specified in arguments.

Note

Prepare GRASS location and necessary raster files in advance (e.g. using lump_grass_prep) and start GRASS session in R using initGRASS.

IMPORTANT: Herein, when specifying the GRASS input maps, please do explicitly refer to the mapset if it is different from the mapset given in initGRASS() (even PERMANENT!), as otherwise internally used readRAST() command resulted in errors under Windows.

In case of long computation times or memory issues, try plot_catena = FALSE and specify an RData file as catena_out. Furthermore, make sure your raster maps are not overly large (i.e. containing lots of NULL values around the region of interest) and are of type CELL (i.e. integer) where it makes sense (check with r.info in GRASS).

Parallel option (ncores>1) may speed-up computations. It requires the packages doMC and doParallel. Set ncores to a value less than the number of cores your computer has; larger values will decrease performance. GUIs such as RStudio may not produce some runtime messages (within parallel foreach loop).

File catena_out contains information about the representative catena for each hillslope (EHA). For meaning of columns see file catena_head_out. It usually contains the catena ID, the catena's profile point IDs, relative vertical elevation above hillside toe, and supplemental information averaged over all raster cells associated with a specific catena profile point. For qualitative data the latter means the areal fraction of a specific attribute class (sum over all classes of an attribute should be equal to one for a profile point), for quantitative data it is a numerical value. Averages over raster cells are weighted by relative flow path densities of the raster cells. For more details on the algorithm see the reference below.

Author(s)

Tobias Pilz [e-mail], Till Francke [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.