Quantify extrapolation in multivariate environmental space — compute

Assesses univariate (Type I) and combinatorial (Type II) extrapolation in spatial ecological models such as density surface models of line transect data. Models are built in a reference (calibration) system and projected into one or more target (prediction) system(s). The function is based on original code from the ecospat package (Broennimann et al. 2016). Although the required inputs mirror those of the dsm package (Miller et al. 2015), the function is not restricted to line/strip-transect data and can be applied to other survey types and predictive modelling scenarios. See the 'Examples' section and Bouchet et al. (2019) for more information.

compute_extrapolation(
  samples,
  segments,
  covariate.names,
  prediction.grid,
  coordinate.system,
  resolution = NULL,
  verbose = TRUE
)

Arguments

samples	Sample (reference) dataset used for model building and calibration. This corresponds to the `segment.data` used when building density surface models in `dsm`. It must contain one column for each of the covariates in `covariate.names`.
covariate.names	Character string. Names of the covariates of interest.
prediction.grid	Prediction data.frame. This contains both geographic coordinates (`x`, `y`) and covariate values associated with the target locations for which predictions are desired. Typically, these locations are taken as the centroids of the grid cells in a spatial prediction grid/raster. See `predict.dsm`.
coordinate.system	Projected coordinate system relevant to the study location. Can be either a character string or an object of class `CRS`.
resolution	Resolution of the output raster (in units relevant to `coordinate.system`). Only required if `prediction.grid` is irregular, and thus needs to be rasterised. Defaults to `NULL`.
verbose	Logical. Show or hide possible warnings and messages.

Value

A list object containing extrapolation values in both data.frame and raster format. Also included are a summary object of class extrapolation_results_summary and a copy of function inputs (i.e, coordinate.system, covariate.names, and prediction.grid).

Details

The function calculates values of the ExDet (EXtrapolation DETection) metric as originally proposed by Mesgaran et al. (2014). ExDet takes on strictly negative values during univariate extrapolation (i.e. when predictions are made outside the range of individual covariates), is strictly >1 during combinatorial extrapolation (i.e. when predictions are made within the range of individual covariates, but for combinations of environmental conditions not encountered in the sample), and lies within the range 0-1 when predictions are made in conditions analogous to those found in the reference system. The function also determines which covariates make the largest contribution to each type of extrapolation; this is the most influential covariate (MIC). See Mesgaran et al. (2014) for details.

Note that compute_extrapolation returns results in both numerical and raster format. The latter is used to support mapping functions and requires the locations in prediction.grid to be evenly spaced. If this is not the case, dsmextra will attempt to automatically generate a raster with a resolution given by the resolution argument (and expressed in the units of coordinate.system). An error may be returned if no resolution is specified.

The data list captures ExDet values at prediction locations (i.e. cells in prediction.grid) and is organised into multiple data.frame objects, as follows:

`all`	All prediction locations
`univariate`	Prediction locations subject to univariate extrapolation (only)
`combinatorial`	Prediction locations subject to combinatorial extrapolation (only)
`analogue`	Prediction locations where conditions are analogous to sampled conditions (only)

Each data.frame contains four columns:

`ExDet`	ExDet values
`mic_univariate`	Integer identifying the univariate MIC
`mic_combinatorial`	Integer identifying the combinatorial MIC
`mic`	Integer identifying the MIC

The rasters list comprises two elements, named ExDet and mic. Each contains individual rasters mapping ExDet and MIC values, respectively.

References

Bouchet PJ, Miller DL, Roberts JJ, Mannocci L, Harris CM and Thomas L (2019). From here and now to there and then: Practical recommendations for extrapolating cetacean density surface models to novel conditions. CREEM Technical Report 2019-01, 59 p. https://research-repository.st-andrews.ac.uk/handle/10023/18509

Broennimann O, Di Cola V, Guisan A (2016). ecospat: Spatial Ecology Miscellaneous Methods. R package version 2.1.1. https://CRAN.R-project.org/package=ecospat

Mesgaran MB, Cousens RD, Webber BL (2014). Here be dragons: a tool for quantifying novelty due to covariate range and correlation change when projecting species distribution models. Diversity & Distributions, 20: 1147-115. DOI: 10.1111/ddi.12209

Miller DL, Rexstad E, Burt L, Bravington MV, Hedley S (2015). dsm: Density Surface Modelling of Distance Sampling Data. R package version 2.2.9. https://CRAN.R-project.org/package=dsm

Examples

library(dsmextra)

#  --- EXAMPLE 1: Line transect surveys of sperm whales ---

# Load the Mid-Atlantic sperm whale data (see ?spermwhales)
data(spermwhales)

# Extract the data
segs <- spermwhales$segs
predgrid <- spermwhales$predgrid

# Define relevant coordinate system
my_crs <- sp::CRS("+proj=aea +lat_1=38 +lat_2=30 +lat_0=34 +lon_0=-73 +x_0=0
 +y_0=0 +datum=WGS84 +units=m +no_defs +ellps=WGS84 +towgs84=0,0,0")

# Define covariates of interest
my_cov <- c("Depth", "DistToCAS", "SST", "EKE", "NPP")

# Assess extrapolation in the multivariate space defined by five covariates
spermw.extrapolation <- compute_extrapolation(samples = segs,
      covariate.names = my_cov,
      prediction.grid = predgrid,
      coordinate.system = my_crs)
#> Computing ...
#> Done!

#  --- EXAMPLE 2: Crowdsourced records of Acacia cyclops (see Mesgaran et al. 2014)  ---

library(dsmextra)
library(raster)
library(sp)
library(magrittr)
#> 
#> Attaching package: ‘magrittr’
#> The following object is masked from ‘package:raster’:
#> 
#>     extract

# Native and introduced range
data(acacia)

# Download BioClim data
r <- raster::getData(name = "worldclim", var = "bio", res = 10)

# Define variables of interest
bioclim.variables <- c("bio1", "bio5", "bio6", "bio12", "bio13", "bio14")

# Reference system (South Australia)
ref <- raster::crop(x = r[[bioclim.variables]], y = acacia$south_australia) %>%
raster::mask(x = ., mask = acacia$south_australia) %>%
raster::as.data.frame(x = ., xy = TRUE, na.rm = TRUE)

# Target system (South Africa)
target <- raster::crop(x = r[[bioclim.variables]], y = acacia$south_africa) %>%
raster::mask(x = ., mask = acacia$south_africa) %>%
raster::as.data.frame(., xy = TRUE, na.rm = TRUE)

# Assess extrapolation
bioclim.ex <- compute_extrapolation(samples = ref,
                                    covariate.names = bioclim.variables,
                                    prediction.grid = target,
                                    coordinate.system = sp::proj4string(r))
#> Error in supressWarnings(coordinate.system <- sp::CRS(coordinate.system)): could not find function "supressWarnings"

# Make a map
map_extrapolation(map.type = "extrapolation", extrapolation.object = bioclim.ex)
#> Error in map_extrapolation(map.type = "extrapolation", extrapolation.object = bioclim.ex): object 'bioclim.ex' not found