process_surface: Process a Raster* by aggregation and quantify the error...
In edwardlavender/flapper: Routines for the Analysis of Passive Acoustic Telemetry Data

process_surface

R Documentation

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

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.