R/rasterTools-package.R

In EhrmannS/rasterTools: Obtain and process earth observation data

#' rasterTools: obtain and process earth observation data
#'
#'
#' also mention https://en.wikipedia.org/wiki/Domain-specific_language
#' 
#' The \code{rasterTools} package is based on the three core-functions
#' \code{\link{obtain}}, \code{\link{modify}} and \code{\link{measure}}.
#'
#' Each of the core functions processes an \emph{algorithm} based on which the
#' specific task at hand shall be carried out. An algorithm is a list of scope
#' specific functions and their arguments (which are together called
#' \emph{operators}) that carry out a specific (spatial) operation (see Examples
#' below). Algorithms are an easy to share and transparent "recipe" of a certain
#' (sequence of) spatial operation.
#'
#' You might find \code{rasterTools} useful when you want to
#' \code{\link{obtain}} spatial (gridded) datasets and \code{\link{modify}}
#' them, which may be required to identify objects about which you want to
#' inquire. You would then \code{\link{measure}} the potentially modified data
#' with the help of a modular system of generic and derived metrics that allows
#' you to use nearly all landscape metrics or even develop your own.
#'
#' @section Rationale: All functions that come with this package can be used in
#'   a tidy way. However, based on the tidy paradigm, an algorithm is always a
#'   pipeline of functions that are evaluated on the fly. This can lead to
#'   excessive flooding of a script with those pipelines/algorithms, when one
#'   wants to send many objects through pipelines. Often the various pipelines
#'   do a very similar thing to a range of objects and even if several objects
#'   have to be sent through the same pipeline, a pipelne for each object has to
#'   be written down explicitly.
#'
#'   \code{rasterTools} has been conceptualised so that the core functions are
#'   modular. The core functions manage all the code-logic that is common for
#'   the class of tasks, such as "obtaining/loading spatial datasets". Code that
#'   manages a particular task of that class, such as "loading the MODIS
#'   dataset", is outsourced to a separate function (the \code{\link{oMODIS}}
#'   operator). The algorithm provided to a core function is comparable to the
#'   pipeline of the tidy paradigm. However, it is not evaluated on the fly as
#'   it is a mere list. This allows for separating the grammar of a spatial
#'   operation (the \emph{how}), from the object(s) that shall be processed (the
#'   \emph{what}) and is thus a consequential evolution of the tidy paradigm.
#'
#'   In the scope of spatial raster operations there are only two distinct types
#'   of input data, rasters with categorical and rasters with continuous values.
#'   A particular algorithm that has been deviced once can be used to process
#'   all objects of the data type it has been defined for. Therefore, when
#'   processing a large range of objects with the same or similar algorithm, an
#'   even tidier and more concise script results. This increases readability
#'   (for non-experts) and therefore transparency and reproducability of the
#'   spatial operations.
#'
#' @section Contribute: If you want to contribute, please study the
#'   \href{https://ehrmanns.github.io/rasterTools/articles/contribute.html}{Contribution
#'    Guidelines} or create an issue on
#'   \href{https://github.com/EhrmannS/rasterTools/issues}{github}.
#' @examples
#' \dontrun{
#'
#' require(magrittr)
#'
#' # define an algorithm
#' myDatasets <- list(list(operator = "oGFC", years = 2006)),
#'                    list(operator = "oCLC", years = 2006),
#'                    list(operator = "oMODIS", product = "mod17a3",
#'                         period = 2006, layer = 2))
#'
#' load a mask from some file,
#' myMask <- loadData(files = "locations.csv",
#'                    localPath = system.file("csv", package="rasterTools")) %>%
#'   gt_group(distance = 10000) %>%
#'   gs_rectangle()
#'
#' # grab the data
#' myData <- obtain(data = myDatasets, mask = myMask)
#' }
#' @docType package
#' @name rasterTools
NULL