% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lump_grass_prep.R
\name{lump_grass_prep}
\alias{lump_grass_prep}
\title{Pre-processing for Landscape Unit deviation using GRASS GIS}
\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{
\item{mask}{Mask in GRASS location defining the catchment area. E.g. subbasin raster map.}

\item{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.}

\item{lcov}{Landcover / vegetation raster map in GRASS location.}

\item{soil}{Soil raster map in GRASS location.}

\item{watermask}{Raster in GRASS location masking water surfaces (value '1') from
other areas (value '0'). Map is used for \code{svc} creation such that a
\code{svc} is completely covered with water ('special_area' in \code{svc_ofile}
equal to 1) or contains no water surface. The map must NOT contain NULL
values within \code{mask}! Default: \code{NULL}.}

\item{imperviousmask}{The same as for \code{watermask} but for impervious (e.g. urban
and/or rocky) areas. 'special_area' flag in \code{svc_ofile} equal to 2. The map
must NOT contain NULL values within \code{mask}!}

\item{eha}{Output: Name of Environmental Hillslope Areas (EHA) raster map
exported into GRASS location.}

\item{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.}

\item{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.}

\item{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
\emph{r.thin} beforehand!}

\item{stream_horton}{Output: Name of stream segments raster map in Horton stream
order exported into GRASS location.}

\item{elevriv}{Output: Name of relative elevation raster map exported into GRASS
location. Provides the elevations above stream node in units of \code{dem}.}

\item{distriv}{Output: Name of distance to river raster map exported into GRASS
location. Provides distances to stream node in number of grid cells.}

\item{mask_corr}{DEPRECATED! Argument kept for backwards compatibility.}

\item{svc}{Output: Name of Soil Vegetation Components raster map exported into
GRASS location; cross product of categories of \code{soil} and \code{lcov}.}

\item{dir_out}{Character string specifying output directory (will be created;
nothing will be overwritten).}

\item{svc_ofile}{Output: Name of file containing properties of \code{svc}s. 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.}

\item{eha_thres}{Integer specifying threshold for delineation of \emph{EHA} in cells;
parameter for GRASS function \emph{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 \code{thresh_sub} of function \code{\link[lumpR]{calc_subbas}} is usually
a good choice.}

\item{sizefilter}{Integer specifying the minimum size of EHAs in hectares.
Smaller EHAs (possibly artefacts) will be removed. Parameter for
GRASS function \emph{r.reclass.area}. If set to \code{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!).}

\item{growrad}{Integer specifying growing radius (in raster cells) to remove
holes in the EHA raster resulting from cleaning of artefacts; parameter for
GRASS function \emph{r.grow}. If set to \code{NULL} (default), it will be
automatically set to 25 (should be but less than 100 due to long computation times!).}

\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}.}

\item{addon_path}{Character string giving the path to your locally installed
GRASS add-ons. Must only be given if necessary, see \code{Note}.}

\item{things2do}{\code{c("eha","river","svc")}. Enables the specification of sub-tasks only. \code{"eha"}: do EHA generation, 
\code{"river"}: calculate river network and morphological parameters, \code{"svc"}: generate SVC map}
}
\value{
Function returns nothing. Output raster files as specified in arguments
     (see above) are written into GRASS location.
}
\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.
}
\note{
Prepare GRASS location and necessary raster files in advance and start
     GRASS session in R using \code{\link[rgrass7]{initGRASS}}.

     Make sure that the GRASS functions \emph{r.stream.distance} and \emph{r.stream.order}
     are available to your GRASS installation. If not, consider \emph{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 \code{g.extension -a}, \code{echo $GRASS_ADDON_BASE} and \code{which r.stream.distance} / \code{where r.stream.distance}, and specify the
     absolute path to add-ons via argument \code{addon_path}. In Windows, replace backslahes for slashes. For more information, see also
     \url{http://grasswiki.osgeo.org/wiki/AddOns/GRASS_7}.
     
     See GRASS documentation for further information on GRASS functions and
     parameters.
}
\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
}
\author{
Tobias Pilz \email{tpilz@uni-potsdam.de}
}
