compute_extrapolation: Quantify extrapolation in multivariate environmental space

In densitymodelling/dsmextra: A Toolkit for Extrapolation Assessments in Density Surface Models

Description

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.

Usage

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.

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.

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).

Author(s)

Phil J. Bouchet

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)

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

library(dsmextra)
library(raster)
library(sp)
library(magrittr)

# 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))

# Make a map
map_extrapolation(map.type = "extrapolation", extrapolation.object = bioclim.ex)

densitymodelling/dsmextra documentation built on Feb. 12, 2022, 4:40 a.m.