process_surface: Process a Raster* by aggregation and quantify the error...

In edwardlavender/flapper: Routines for the Analysis of Passive Acoustic Telemetry Data

Process a Raster* by aggregation and quantify the error induced by this process

Description

This function reduces the resolution of a 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 raster (x) must be supplied as well as an aggregation factor (fact) and a named list of functions (stat) used to aggregate the raster. The raster is aggregated using each method (function) and mapped back onto the original resolution for calculation of the differences between the original raster and the aggregated raster(s). The function returns a visual statistical summary of the differences (if plot = TRUE) and a named list comprising the aggregated raster(s) and the re-sampled version(s) of those mapped back onto the original resolution.

Usage

process_surface(
  x,
  fact = 2L,
  stat = list(mean = mean),
  ...,
  plot = TRUE,
  cl = NULL,
  varlist = NULL,
  verbose = TRUE
)

Arguments

x	A raster to be processed. For implementations preceding a call to of one of flapper's particle filtering algorithms, 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 pf).
fact	A positive integer that defines by how much x should be aggregated (see aggregate).
stat	A named list of functions used to aggregate x (see the fun argument of aggregate).
...	Additional arguments passed to aggregate to control aggregation.
plot	A logical input that defines whether or not to plot a summary of the differences between the original raster (x) and the aggregated raster(s). If specified, the minimum, median and maximum difference are shown for each statistic (stat).
cl, varlist	(optional) Parallelisation options. cl is (a) a cluster object from makeCluster or (b) an integer that defines the number of child processes. varlist is a character vector of variables for export (see 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 cl_stop). For further information, see cl_lapply and flapper-tips-parallel.
verbose	A logical input that defines whether or not to print messages to the console to relay function progress.

Details

This function was motivated by the particle filtering algorithms in flapper (e.g., pf). For these algorithms, it is computationally beneficial to reduce 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 raster that minimises the error, with the magnitude of that error propagated via the depth_error parameter.

Value

The function returns a plot of the differences between the original and aggregated raster(s), if plot = TRUE, and a named list of (a) the aggregated raster(s) (‘agg_by_stat’), (b) the aggregated, resampled raster(s) (‘agg_by_stat_rs’) and (c) the summary statistics plotted.

Author(s)

Edward Lavender

See Also

aggregate, resample

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)

edwardlavender/flapper documentation built on Jan. 22, 2025, 2:44 p.m.