Distill a raster stack into a set of distribution metrics

Source: R/metrics.R

This function is used to summarize several distributional features of interest across a series of distributions. Distributional information in the original raster stack is "distilled" for subsequent visualization.

metrics_distill(x)

Arguments

x

RasterStack of distributions. Layers typically contain information about the distribution of a single individual or species at multiple points in time. Alternatively, layers may contain information about the distributions of multiple individuals or species within a single time period. Other conceptualizations are possible.

Value

A RasterStack with four layers:

  • intensity: the maximum intensity value across all layers.

  • layer_id: an integer identifying layer containing the maximum intensity value.

  • specificity: the degree to which intensity values are unevenly distributed across layers (see Details).

  • n_layers: the number of layers with non-NA values (see Details).

The maximum cell value in the stack is stored as the "maximum" attribute. The link between the layer_id and the layer names from the underlying raster is stored as a data frame in the layer_names attribute.

Details

Specificity values range from 0 to 100. Values of 0 indicate intensity values are identical in all layers. Values of 100 indicate intensity values are restricted to a single layer. Interpretation of specificity values depends on the layers provided. If layers describe the distribution of a species at different times of the year, specificity can be interpreted as a measure of seasonality (i.e., 0 = stable year-round occurrence in a cell, 100 = highly seasonal occurrence). If layers describe space use by multiple individuals, specificity can be interpreted as a measure of exclusivity (i.e., 0 = equal use of a cell by all individuals, 100 = exclusive use by one individual).

The number of layers with non-NA values is recorded to aid interpretation of distributions. Ideally, n_layers values are identical in every cell, indicating that users have knowledge of distributions over the same area in every layer of their raster stack. When n_layers values are unequal, it indicates that users have unequal knowledge of distributions in their raster stack. Distributions are more likely to be misrepresented and misinterpreted if cells do not contain intensity values in every layer.

See also

Other metrics: metrics_pull()

Examples

# load elephant data
data("elephant_ud")

# distill
r <- metrics_distill(elephant_ud)
print(r)

#> class      : RasterStack 
#> dimensions : 208, 193, 40144, 4  (nrow, ncol, ncell, nlayers)
#> resolution : 500, 500  (x, y)
#> extent     : -58642.18, 37857.82, -2376938, -2272938  (xmin, xmax, ymin, ymax)
#> crs        : +proj=moll +lon_0=15.8231920275931 +x_0=0 +y_0=0 +ellps=WGS84 +units=m +no_defs 
#> names      : intensity, layer_id, specificity, n_layers 
#> min values :         0,        1,           0,        2 
#> max values :         1,        2,         100,        2 
#> 

# maximum value across all layers stored as an attribute
attr(r, "maximum")

#> [1] 0.002409927
# link between layer id and name stored as an attribute
attr(r, "layer_names")

#>   layer_id layer_name
#> 1        1       LA11
#> 2        2       LA14