process_surface.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/processing.R
\name{process_surface}
\alias{process_surface}
\title{Process a Raster* by aggregation and quantify the error induced by this process}
\usage{
process_surface(
  x,
  fact = 2L,
  stat = list(mean = mean),
  ...,
  plot = TRUE,
  cl = NULL,
  varlist = NULL,
  verbose = TRUE
)
}
\arguments{
\item{x}{A \code{\link[raster]{raster}} to be processed. For implementations preceding a call to of one of \code{\link[flapper]{flapper}}'s particle filtering algorithms, \code{x} should be planar (i.e., Universal Transverse Mercator projection) with equal resolution in the x, y directions and identical units in the x, y and z directions (see \code{\link[flapper]{pf}}).}

\item{fact}{A positive integer that defines by how much \code{x} should be aggregated (see \code{\link[raster]{aggregate}}).}

\item{stat}{A named list of functions used to aggregate \code{x} (see the \code{fun} argument of \code{\link[raster]{aggregate}}).}

\item{...}{Additional arguments passed to \code{\link[raster]{aggregate}} to control aggregation.}

\item{plot}{A logical input that defines whether or not to plot a summary of the differences between the original \code{\link[raster]{raster}} (\code{x}) and the aggregated \code{\link[raster]{raster}}(s). If specified, the minimum, median and maximum difference are shown for each statistic (\code{stat}).}

\item{cl, varlist}{(optional) Parallelisation options. \code{cl} is (a) a cluster object from \code{\link[parallel]{makeCluster}} or (b) an integer that defines the number of child processes. \code{varlist} is a character vector of variables for export (see \code{\link[flapper]{cl_export}}). Exported variables must be located in the global environment. If a cluster is supplied, the connection to the cluster is closed within the function (see \code{\link[flapper]{cl_stop}}). For further information, see \code{\link[flapper]{cl_lapply}} and \code{\link[flapper]{flapper-tips-parallel}}.}

\item{verbose}{A logical input that defines whether or not to print messages to the console to relay function progress.}
}
\value{
The function returns a plot of the differences between the original and aggregated \code{\link[raster]{raster}}(s), if \code{plot = TRUE}, and a named list of (a) the aggregated \code{\link[raster]{raster}}(s) (`agg_by_stat'), (b) the aggregated, resampled \code{\link[raster]{raster}}(s) (`agg_by_stat_rs') and (c) the summary statistics plotted.
}
\description{
This function reduces the resolution of a \code{\link[raster]{raster}} by multiple aggregation methods and then quantifies the relative error induced by each method from the differences between the original values and the aggregated values. To implement the function, a \code{\link[raster]{raster}} (\code{x}) must be supplied as well as an aggregation factor (\code{fact}) and a named list of functions (\code{stat}) used to aggregate the \code{\link[raster]{raster}}. The \code{\link[raster]{raster}} is aggregated using each method (function) and mapped back onto the original resolution for calculation of the differences between the original \code{\link[raster]{raster}} and the aggregated \code{\link[raster]{raster}}(s). The function returns a visual statistical summary of the differences (if \code{plot = TRUE}) and a named list comprising the aggregated \code{\link[raster]{raster}}(s) and the re-sampled version(s) of those mapped back onto the original resolution.
}
\details{
This function was motivated by the particle filtering algorithms in \code{\link[flapper]{flapper}} (e.g., \code{\link[flapper]{pf}}). For these algorithms, it is computationally beneficial to reduce \code{\link[raster]{raster}} resolution, where possible, by aggregation. To facilitate this process, this function quantifies the relative error induced by different aggregation functions. If appropriate, the particle filtering algorithm(s) can then be implemented using the aggregated \code{\link[raster]{raster}} that minimises the error, with the magnitude of that error propagated via the \code{depth_error} parameter.
}
\examples{
# Define the raster for which to implement the function
x <- dat_gebco
blank <- raster::raster(raster::extent(x), crs = raster::crs(x), resolution = 250)
x <- raster::resample(x, blank, method = "bilinear")
# Implement function using a list of statistics
out <- process_surface(x, fact = 2, stat = list(min = min, mean = mean, median = median, max = max))
summary(out)

}
\seealso{
\code{\link[raster]{aggregate}}, \code{\link[raster]{resample}}
}
\author{
Edward Lavender
}