lump_grass_post: Post-processing of Landscape Unit deviation using GRASS GIS
In tpilz/LUMP: Landscape Unit Mapping Program for R
View source: R/lump_grass_post.R
lump_grass_post R Documentation
Post-processing of Landscape Unit deviation using GRASS GIS
Description
Creates raster map of Landscape Units and files containing information of
and parameter estimation for Subbasins and Landscape Units in the catchment
using outputs of lump_grass_prep and prof_class.
Usage
lump_grass_post(mask = NULL, dem = NULL, recl_lu = NULL, lu = NULL,
subbasin = NULL, eha = NULL, flowacc = NULL, flowdir = NULL,
stream_horton = NULL, soil_depth = NULL, sdr = NULL,
dir_out = "./", sub_ofile = NULL, lu_ofile = NULL,
lupar_ofile = NULL, fill_holes = T, groundwater = 0, na_val = NA,
keep_temp = F, overwrite = F, silent = F)
Arguments
mask
Name of mask raster map masking the study area. E.g. output basin_out
of calc_subbas.
dem
DEM raster map in GRASS location as used in lump_grass_prep.
recl_lu
Name of GRASS reclassification file: EHA -> LU. Output of
prof_class. If omitted, the existing raster layer lu is used.
lu
Input or Output: Name of Landscape Units (LU) raster map already existing in
GRASS location or to be generated using recl_lu.
subbasin
Subbasin raster map in GRASS location as used in lump_grass_prep
and/or created by calc_subbas.
eha
Name of Elementary Hillslope Areas (EHA) raster map in GRASS
location. Output of lump_grass_prep.
flowacc
Name of flow accumulation raster map in GRASS location. Can
be created with lump_grass_prep.
flowdir
Name of flow direction raster map in GRASS location. Can
be created with lump_grass_prep.
stream_horton
Name of Horton stream order raster map in GRASS location. Can
be created with lump_grass_prep. If left empty, the channel length,
slope and retention times are set to NA.
soil_depth
Name of soil depth [mm] raster map in GRASS location. If NULL
(default), na_val is used.
sdr
Name of sediment delivery ratio [-] raster map in GRASS location. If empty,
this optional column is omitted.
dir_out
Character string specifying output directory (will be created;
any overwriting will be prompted).
sub_ofile
Output: Name of subbasin statistics file containing subbasin
parameters. See Details below. If NULL (default) this file
will not be generated.
lu_ofile
Output: Name of file containing subbasins and the corresponding
LUs with their fraction of area in the subbasin. If NULL (default)
this file will not be generated.
lupar_ofile
Output: Name of file containing LUs and related parameters.
See Details below. If NULL (default) this file will not be generated.
fill_holes
TRUE: fill any holes in map eha (e.g. as result of skipped/non-classified
EHAs) by growing
groundwater
Flag: 1: respect groundwater and infer parameters. 0 (default):
Ignore groundwater and associated parameters.
na_val
Value used to indicate NA values in output files. Default: NA.
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
Subbasin parameters
Subbasin parameter estimation given in sub_ofile contains:
pid
Subbasin identifier.
description
Subbasin description you can fill in manually if needed.
lat
Latitude of subbasin centroid in decimal degrees (negative values for southern hemisphere).
lon
Longitude of subbasin centroid in decimal degrees west of Greenwhich, e.g.
Greenwich: 0°, New York: 75°, Berlin: 345°.
elev
Average elevation above sea level of subbasin m.
area
Subbasin area in km^2.
x
X-coordinate of subbasin centroid in units of GRASS location.
y
Y-coordinate of subbasin centroid in units of GRASS location.
drains_to
Pid of subbasin the current subbasin drains to. It is determined by identifying
the cell with the highest flow accumulation value (= subbasin outlet). By
deriving the drainage direction value of that raster cell the next downstream
cell is identified along with corresponding subbasin number.
lag_time
Time in days a runoff signal in the current subbasin needs to be directed
from the subbasin input to the outlet. Estimated from channel geometry (see below).
retention
Maximum time period in days over which a runoff signal is distributed by
the routing process. Estimated from channel geometry (see below).
chan_len
Length of the main channel of the respective subbasin in m. Estimated
from channel geometry (see below).
channel geometry
Main channel length: For each subbasin the main channel is determined from Horton
stream raster map. Its length is then calculated depending on raster resolution
and flow direction.
Channel slope: Minimum (= inflow) and maximum (= outflow) flow accumulation and
elevation of the corresponding raster cells are determined. The difference in
elevation is divided by main channel length.
Channel width: Maximum flow accumulation is determined and the corresponding
drainage area calculated by resolution of raster cells. Channel width is then
calculated from the empirical formula: width[m] = 1.29 * darea[km2] ^ 0.6.
Channel depth: Empirical formula based on drainage area: depth[m] = 0.13 * darea[km2] ^ 0.4.
Flow velocity: Is calculated using Mannings equation with an n-value of 0.075.
Flow velocities are calculated to derive flow travel times (velocity / channel
length) for bankfull (= high flow condition), 2/3 (= average conditions) and
1/10 (= low flow conditions) water levels to derive lag time (travel time for
average conditions) and retention time (max - min travel time).
Landscape Units in Subbasins
lu_ofile contains:
subbas_id
Subbasin identifier.
lu_id
Landscape Unit identifier.
fraction
Areal fraction of Landscape Unit within corresponding Subbasin.
Landscape Unit parameters
Landscape Unit parameter estimation given in lupar_ofile contains:
pid
Landscape Unit identifier.
description
Description for this Landscape Unit. Can be adjusted manually if you want.
Generally set to na_val.
kf_bedrock
Hydraulic conductivity of bedrock. Fill in values manually. Generally set
to na_val. Use in WASA model is optional (see WASA documentation
-> 'kfsu' and notes on 'bedrock').
slopelength
Slope length of Landscape Unit [m]. Value can be obtained from output of
prof_class. Herein set to na_val.
soil_depth
Soil depth in mm averaged over respective landscape unit. Use in
WASA model is optional (see WASA documentation -> 'meandep' and notes on
'bedrock'). Herein set to na_val.
allu_depth
Depth of alluvial soils in mm. Use in WASA model is optional (see
WASA documentation -> 'maxdep' and notes on 'bedrock'). Herein set to na_val.
riverbed_depth
Depth of river bed below Terrain Component in mm. Use in WASA model
is optional (see WASA documentation -> 'riverbed' and notes on 'bedrock').
Herein set to na_val.
gw_flag
Groundwater flag: 0: no groundwater in this LU. 1: LU contains groundwater.
At the moment set to 0 by default for every LU. Use in WASA model is optional
(see WASA documentation -> 'gw_flag' and notes on groundwater).
gw_dist
Initial depth of groundwater below surface in mm. At the moment set to
1000 by default for every LU if groundwater = 1. Use in WASA model is optional
(see WASA documentation -> 'gw_dist' and notes on groundwater).
frgw_delay
Storage coefficient for groundwater outflow in days. At the moment set to
200 by default for every LU if groundwater = 1. Use in WASA model is optional
(see WASA documentation -> 'frgw_delay' and notes on groundwater).
sdr_lu (optional)
sediment delivery ratio from raster map sdr, if specified
Value
Function returns nothing. Output files (sub_ofile, lupar_ofile, lu_ofile)
are written into output directory and raster map (lu) exported into GRASS
location 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.
TODO:
- check empirical formulas for channel width and channel depth
- LU parameter estimation
- include options to add parameters manually in case data are available
- include option to make function more efficient regarding RAM usage (e.g. by
wrting/reading temporary raster data to/from disk) at the cost of higher computational burden
Author(s)
Tobias Pilz tpilz@uni-potsdam.de
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
Subbasin Parameters:
Bronstert, A., Guentner, A., Jaeger, A., Krol, M. & Krywkow, J. (1999): Grossraeumige
hydrologische Parametrisierung und Modellierung als Teil der integrierten
Modellierung. In: Fohrer, N. & Doell, P. (Eds.): Modellierung des Wasser- und
Stofftransports in grossen Einzugsgebieten. Kassel University Press, Kassel,
Germany, 31-40.
Guentner, A. (2002): Large-scale hydrological modelling in the semi-arid
North-East of Brazil. PIK Report 77, Potsdam Institute for Climate
Impact Research, Potsdam, Germany.
tpilz/LUMP documentation built on Aug. 5, 2023, 1:31 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
View source: R/lump_grass_post.R
| lump_grass_post | R Documentation |
Post-processing of Landscape Unit deviation using GRASS GIS
Description
Creates raster map of Landscape Units and files containing information of
and parameter estimation for Subbasins and Landscape Units in the catchment
using outputs of lump_grass_prep and prof_class.
Usage
lump_grass_post(mask = NULL, dem = NULL, recl_lu = NULL, lu = NULL,
subbasin = NULL, eha = NULL, flowacc = NULL, flowdir = NULL,
stream_horton = NULL, soil_depth = NULL, sdr = NULL,
dir_out = "./", sub_ofile = NULL, lu_ofile = NULL,
lupar_ofile = NULL, fill_holes = T, groundwater = 0, na_val = NA,
keep_temp = F, overwrite = F, silent = F)
Arguments
mask |
Name of mask raster map masking the study area. E.g. output |
dem |
DEM raster map in GRASS location as used in |
recl_lu |
Name of GRASS reclassification file: EHA -> LU. Output of
|
lu |
Input or Output: Name of Landscape Units (LU) raster map already existing in
GRASS location or to be generated using |
subbasin |
Subbasin raster map in GRASS location as used in |
eha |
Name of Elementary Hillslope Areas (EHA) raster map in GRASS
location. Output of |
flowacc |
Name of flow accumulation raster map in GRASS location. Can
be created with |
flowdir |
Name of flow direction raster map in GRASS location. Can
be created with |
stream_horton |
Name of Horton stream order raster map in GRASS location. Can
be created with |
soil_depth |
Name of soil depth [mm] raster map in GRASS location. If |
sdr |
Name of sediment delivery ratio [-] raster map in GRASS location. If empty, this optional column is omitted. |
dir_out |
Character string specifying output directory (will be created; any overwriting will be prompted). |
sub_ofile |
Output: Name of subbasin statistics file containing subbasin
parameters. See |
lu_ofile |
Output: Name of file containing subbasins and the corresponding
LUs with their fraction of area in the subbasin. If |
lupar_ofile |
Output: Name of file containing LUs and related parameters.
See |
fill_holes |
TRUE: fill any holes in map |
groundwater |
Flag: 1: respect groundwater and infer parameters. 0 (default): Ignore groundwater and associated parameters. |
na_val |
Value used to indicate |
keep_temp |
|
overwrite |
|
silent |
|
Details
Subbasin parameters
Subbasin parameter estimation given in sub_ofile contains:
pid
Subbasin identifier.
description
Subbasin description you can fill in manually if needed.
lat
Latitude of subbasin centroid in decimal degrees (negative values for southern hemisphere).
lon
Longitude of subbasin centroid in decimal degrees west of Greenwhich, e.g.
Greenwich: 0°, New York: 75°, Berlin: 345°.
elev
Average elevation above sea level of subbasin m.
area
Subbasin area in km^2.
x
X-coordinate of subbasin centroid in units of GRASS location.
y
Y-coordinate of subbasin centroid in units of GRASS location.
drains_to
Pid of subbasin the current subbasin drains to. It is determined by identifying
the cell with the highest flow accumulation value (= subbasin outlet). By
deriving the drainage direction value of that raster cell the next downstream
cell is identified along with corresponding subbasin number.
lag_time
Time in days a runoff signal in the current subbasin needs to be directed
from the subbasin input to the outlet. Estimated from channel geometry (see below).
retention
Maximum time period in days over which a runoff signal is distributed by
the routing process. Estimated from channel geometry (see below).
chan_len
Length of the main channel of the respective subbasin in m. Estimated
from channel geometry (see below).
channel geometry
Main channel length: For each subbasin the main channel is determined from Horton
stream raster map. Its length is then calculated depending on raster resolution
and flow direction.
Channel slope: Minimum (= inflow) and maximum (= outflow) flow accumulation and
elevation of the corresponding raster cells are determined. The difference in
elevation is divided by main channel length.
Channel width: Maximum flow accumulation is determined and the corresponding
drainage area calculated by resolution of raster cells. Channel width is then
calculated from the empirical formula: width[m] = 1.29 * darea[km2] ^ 0.6.
Channel depth: Empirical formula based on drainage area: depth[m] = 0.13 * darea[km2] ^ 0.4.
Flow velocity: Is calculated using Mannings equation with an n-value of 0.075.
Flow velocities are calculated to derive flow travel times (velocity / channel
length) for bankfull (= high flow condition), 2/3 (= average conditions) and
1/10 (= low flow conditions) water levels to derive lag time (travel time for
average conditions) and retention time (max - min travel time).
Landscape Units in Subbasins
lu_ofile contains:
subbas_id
Subbasin identifier.
lu_id
Landscape Unit identifier.
fraction
Areal fraction of Landscape Unit within corresponding Subbasin.
Landscape Unit parameters
Landscape Unit parameter estimation given in lupar_ofile contains:
pid
Landscape Unit identifier.
description
Description for this Landscape Unit. Can be adjusted manually if you want.
Generally set to na_val.
kf_bedrock
Hydraulic conductivity of bedrock. Fill in values manually. Generally set
to na_val. Use in WASA model is optional (see WASA documentation
-> 'kfsu' and notes on 'bedrock').
slopelength
Slope length of Landscape Unit [m]. Value can be obtained from output of
prof_class. Herein set to na_val.
soil_depth
Soil depth in mm averaged over respective landscape unit. Use in
WASA model is optional (see WASA documentation -> 'meandep' and notes on
'bedrock'). Herein set to na_val.
allu_depth
Depth of alluvial soils in mm. Use in WASA model is optional (see
WASA documentation -> 'maxdep' and notes on 'bedrock'). Herein set to na_val.
riverbed_depth
Depth of river bed below Terrain Component in mm. Use in WASA model
is optional (see WASA documentation -> 'riverbed' and notes on 'bedrock').
Herein set to na_val.
gw_flag
Groundwater flag: 0: no groundwater in this LU. 1: LU contains groundwater.
At the moment set to 0 by default for every LU. Use in WASA model is optional
(see WASA documentation -> 'gw_flag' and notes on groundwater).
gw_dist
Initial depth of groundwater below surface in mm. At the moment set to
1000 by default for every LU if groundwater = 1. Use in WASA model is optional
(see WASA documentation -> 'gw_dist' and notes on groundwater).
frgw_delay
Storage coefficient for groundwater outflow in days. At the moment set to
200 by default for every LU if groundwater = 1. Use in WASA model is optional
(see WASA documentation -> 'frgw_delay' and notes on groundwater).
sdr_lu (optional)
sediment delivery ratio from raster map sdr, if specified
Value
Function returns nothing. Output files (sub_ofile, lupar_ofile, lu_ofile)
are written into output directory and raster map (lu) exported into GRASS
location 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.
TODO:
- check empirical formulas for channel width and channel depth
- LU parameter estimation
- include options to add parameters manually in case data are available
- include option to make function more efficient regarding RAM usage (e.g. by
wrting/reading temporary raster data to/from disk) at the cost of higher computational burden
Author(s)
Tobias Pilz tpilz@uni-potsdam.de
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
Subbasin Parameters:
Bronstert, A., Guentner, A., Jaeger, A., Krol, M. & Krywkow, J. (1999): Grossraeumige
hydrologische Parametrisierung und Modellierung als Teil der integrierten
Modellierung. In: Fohrer, N. & Doell, P. (Eds.): Modellierung des Wasser- und
Stofftransports in grossen Einzugsgebieten. Kassel University Press, Kassel,
Germany, 31-40.
Guentner, A. (2002): Large-scale hydrological modelling in the semi-arid North-East of Brazil. PIK Report 77, Potsdam Institute for Climate Impact Research, Potsdam, Germany.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.