% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lump_grass_post.R
\name{lump_grass_post}
\alias{lump_grass_post}
\title{Post-processing of Landscape Unit deviation using GRASS GIS}
\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{
\item{mask}{Name of mask raster map masking the study area. E.g. output \code{basin_out}
of \code{\link[lumpR]{calc_subbas}}.}

\item{dem}{DEM raster map in GRASS location as used in \code{\link[lumpR]{lump_grass_prep}}.}

\item{recl_lu}{Name of GRASS reclassification file: EHA -> LU. Output of
\code{\link[lumpR]{prof_class}}. If omitted, the existing raster layer \code{lu} is used.}

\item{lu}{Input or Output: Name of Landscape Units (LU) raster map already existing in
GRASS location or to be generated using \code{recl_lu}.}

\item{subbasin}{Subbasin raster map in GRASS location as used in \code{\link[lumpR]{lump_grass_prep}}
and/or created by \code{\link[lumpR]{calc_subbas}}.}

\item{eha}{Name of Elementary Hillslope Areas (EHA) raster map in GRASS
location. Output of \code{\link[lumpR]{lump_grass_prep}}.}

\item{flowacc}{Name of flow accumulation raster map in GRASS location. Can
be created with \code{\link[lumpR]{lump_grass_prep}}.}

\item{flowdir}{Name of flow direction raster map in GRASS location. Can
be created with \code{\link[lumpR]{lump_grass_prep}}.}

\item{stream_horton}{Name of Horton stream order raster map in GRASS location. Can
be created with \code{\link[lumpR]{lump_grass_prep}}. If left empty, the channel length,
slope and retention times are set to \code{NA}.}

\item{soil_depth}{Name of soil depth [mm] raster map in GRASS location. If \code{NULL}
(default), \code{na_val} is used.}

\item{sdr}{Name of sediment delivery ratio [-] raster map in GRASS location. If empty,
this optional column is omitted.}

\item{dir_out}{Character string specifying output directory (will be created;
any overwriting will be prompted).}

\item{sub_ofile}{Output: Name of subbasin statistics file containing subbasin
parameters. See \code{Details} below. If \code{NULL} (default) this file
will not be generated.}

\item{lu_ofile}{Output: Name of file containing subbasins and the corresponding
LUs with their fraction of area in the subbasin. If \code{NULL} (default)
this file will not be generated.}

\item{lupar_ofile}{Output: Name of file containing LUs and related parameters.
See \code{Details} below. If \code{NULL} (default) this file will not be generated.}

\item{fill_holes}{TRUE: fill any holes in map \code{eha} (e.g. as result of skipped/non-classified
EHAs) by growing}

\item{groundwater}{Flag: 1: respect groundwater and infer parameters. 0 (default):
Ignore groundwater and associated parameters.}

\item{na_val}{Value used to indicate \code{NA} values in output files. Default: \code{NA}.}

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

\item{overwrite}{\code{logical}. Shall output of previous calls of this function be
deleted? If \code{FALSE} the function returns an error if output already exists.
Default: \code{FALSE}.}

\item{silent}{\code{logical}. Shall the function be silent (also suppressing warnings
of internally used GRASS functions)? Default: \code{FALSE}.}
}
\value{
Function returns nothing. Output files (\code{sub_ofile, lupar_ofile, lu_ofile})
     are written into output directory and raster map (\code{lu}) exported into GRASS
     location as specified in arguments.
}
\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 \code{\link[lumpR]{lump_grass_prep}} and \code{\link[lumpR]{prof_class}}.
}
\details{
\bold{Subbasin parameters}\cr
     Subbasin parameter estimation given in \code{sub_ofile} contains:
     
     \emph{pid}\cr
     Subbasin identifier.
     
     \emph{description}\cr
     Subbasin description you can fill in manually if needed.
     
     \emph{lat}\cr
     Latitude of subbasin centroid in \emph{decimal degrees} (negative values for southern hemisphere).
     
     \emph{lon}\cr
     Longitude of subbasin centroid in \emph{decimal degrees west of Greenwhich}, e.g.
     Greenwich: 0°, New York: 75°, Berlin: 345°.
     
     \emph{elev}\cr
     Average elevation above sea level of subbasin \emph{m}.
     
     \emph{area}\cr
     Subbasin area in \emph{km^2}.
     
     \emph{x}\cr
     X-coordinate of subbasin centroid in units of GRASS location.
     
     \emph{y}\cr
     Y-coordinate of subbasin centroid in units of GRASS location.
     
     \emph{drains_to}\cr
     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.
     
     \emph{lag_time}\cr
     Time in \emph{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).
     
     \emph{retention}\cr
     Maximum time period in \emph{days} over which a runoff signal is distributed by
     the routing process. Estimated from channel geometry (see below).
     
     \emph{chan_len}\cr
     Length of the main channel of the respective subbasin in \emph{m}. Estimated
     from channel geometry (see below).
     
     \emph{channel geometry}\cr
     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.\cr
     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.\cr
     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.\cr
     Channel depth: Empirical formula based on drainage area: depth[m] = 0.13 * darea[km2] ^ 0.4.\cr
     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).
     
     
     \bold{Landscape Units in Subbasins}\cr
     \code{lu_ofile} contains:
           
     \emph{subbas_id}\cr
     Subbasin identifier.
     
     \emph{lu_id}\cr
     Landscape Unit identifier.
     
     \emph{fraction}\cr
     Areal fraction of Landscape Unit within corresponding Subbasin.
     
     
     \bold{Landscape Unit parameters}\cr
     Landscape Unit parameter estimation given in \code{lupar_ofile} contains:
     
     \emph{pid}\cr
     Landscape Unit identifier.
     
     \emph{description}\cr
     Description for this Landscape Unit. Can be adjusted manually if you want.
     Generally set to \code{na_val}.
     
     \emph{kf_bedrock}\cr
     Hydraulic conductivity of bedrock. Fill in values manually. Generally set
     to \code{na_val}. Use in WASA model is optional (see WASA documentation
     -> 'kfsu' and notes on 'bedrock').
     
     \emph{slopelength}\cr
     Slope length of Landscape Unit [m]. Value can be obtained from output of
     \code{\link[lumpR]{prof_class}}. Herein set to \code{na_val}.
     
     \emph{soil_depth}\cr
     Soil depth in \emph{mm} averaged over respective landscape unit. Use in
     WASA model is optional (see WASA documentation -> 'meandep' and notes on
     'bedrock'). Herein set to \code{na_val}.
     
     \emph{allu_depth}\cr
     Depth of alluvial soils in \emph{mm}. Use in WASA model is optional (see
     WASA documentation -> 'maxdep' and notes on 'bedrock'). Herein set to \code{na_val}.
     
     \emph{riverbed_depth}\cr
     Depth of river bed below Terrain Component in \emph{mm}. Use in WASA model
     is optional (see WASA documentation -> 'riverbed' and notes on 'bedrock').
     Herein set to \code{na_val}.
     
     \emph{gw_flag}\cr
     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).
     
     \emph{gw_dist}\cr
     Initial depth of groundwater below surface in \emph{mm}. At the moment set to
     1000 by default for every LU if \code{groundwater = 1}. Use in WASA model is optional
     (see WASA documentation -> 'gw_dist' and notes on groundwater).
     
     \emph{frgw_delay}\cr
     Storage coefficient for groundwater outflow in \emph{days}. At the moment set to
     200 by default for every LU if \code{groundwater = 1}. Use in WASA model is optional
     (see WASA documentation -> 'frgw_delay' and notes on groundwater).
     
     \emph{sdr_lu} (optional)\cr
     sediment delivery ratio from raster map \code{sdr}, if specified
}
\note{
Prepare GRASS location and necessary raster files in advance (e.g. using
     \code{\link[lumpR]{lump_grass_prep}}) and start GRASS session in R using 
     \code{\link[rgrass7]{initGRASS}}.
     
     \bold{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:\cr
       - check empirical formulas for channel width and channel depth\cr
       - LU parameter estimation\cr
       - include options to add parameters manually in case data are available\cr
       - 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
}
\references{
Source code based on \code{SHELL} and \code{MATLAB} scripts of Till Francke.

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

     Theory of LUMP:\cr
     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. \emph{International Journal of Geographical
     Information Science, Informa UK Limited}, 22(2), 111-132, DOI: 10.1080/13658810701300873
     
     Subbasin Parameters:\cr
     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. \emph{Kassel University Press}, Kassel,
     Germany, 31-40.
     
     Guentner, A. (2002): Large-scale hydrological modelling in the semi-arid 
     North-East of Brazil. \emph{PIK Report 77}, Potsdam Institute for Climate
     Impact Research, Potsdam, Germany.
}
\author{
Tobias Pilz \email{tpilz@uni-potsdam.de}
}
