Analyze the range size differences between projections of species distribution models

This function allows to calculate the absolute number of locations (pixels) lost, stable and gained, as well as the corresponding relative proportions, between two (or more) binary projections of (ensemble) species distribution models (which can represent new time scales or environmental scenarios for example).

BIOMOD_RangeSize(
  proj.current,
  proj.future,
  models.chosen = "all",
  metric.binary = NULL
)

Arguments

proj.current

a BIOMOD.projection.out object containing the initial projection(s) of the (ensemble) species distribution model(s)

proj.future

a BIOMOD.projection.out object containing the final binary projection(s) of the (ensemble) species distribution model(s)

models.chosen

a vector containing model names to be kept, must be either all or a sub-selection of model names that can be obtained with the get_projected_models function

metric.binary

(optional, default NULL)
A vector containing evaluation metric selected to transform predictions into binary values, must be among POD, FAR, POFD, SR, ACCURACY, BIAS, ROC, TSS, KAPPA, OR, ORSS, CSI, ETS, BOYCE, MPA

Value

A BIOMOD.rangesize.out containing principaly two objects :

Compt.By.Species

a data.frame containing the summary of range change for each comparison

• Loss : number of pixels predicted to be lost

• Stable_Abs : number of pixels not currently occupied and not predicted to be

• Stable_Pres : number of pixels currently occupied and predicted to remain occupied

• Gain : number of pixels predicted to be gained

• PercLoss : percentage of pixels currently occupied and predicted to be lost (Loss / (Loss + Stable_Pres))

• PercGain : percentage of pixels predicted to be gained compare to the number of pixels currently occupied (Gain / (Loss + Stable_Pres))

• SpeciesRangeChange : percentage of pixels predicted to change (loss or gain) compare to the number of pixels currently occupied (PercGain - PercLoss)

• CurrentRangeSize : number of pixels currently occupied

• FutureRangeSize0Disp : number of pixels predicted to be occupied, assuming no migration

• FutureRangeSize1Disp : number of pixels predicted to be occupied, assuming migration

loss.gain

an object in the same form than the input data (proj.current and proj.future) and containing a value for each point/pixel of each comparison among :

• -2 : predicted to be lost

• -1 : predicted to remain occupied

• 0 : predicted to remain unoccupied

• 1 : predicted to be gained

Diff.By.Pixel

an object in the same form than the input data (proj.current and proj.future) and containing a value for each point/pixel of each comparison obtain with :

• Future - 2* Current for binary data

• Future - Current for nonbinary after rescaling Future and Current from 0 to 1.

See also

BIOMOD_Projection, BIOMOD_EnsembleForecasting, bm_PlotRangeSize

Other Main functions: BIOMOD_EnsembleForecasting(), BIOMOD_EnsembleModeling(), BIOMOD_FormatingData(), BIOMOD_LoadModels(), BIOMOD_Modeling(), BIOMOD_Projection()

Author

Maya Guéguen, Hélène Blancheteau

Examples

library(terra)

# Load species occurrences (6 species available)
data(DataSpecies)
head(DataSpecies)

# Select the name of the studied species
myRespName <- 'GuloGulo'

# Get corresponding presence/absence data
myResp <- as.numeric(DataSpecies[, myRespName])

# Get corresponding XY coordinates
myRespXY <- DataSpecies[, c('X_WGS84', 'Y_WGS84')]

# Load environmental variables extracted from BIOCLIM (bio_3, bio_4, bio_7, bio_11 & bio_12)
data(bioclim_current)
myExpl <- terra::rast(bioclim_current)

DONTSHOW({
myExtent <- terra::ext(0,30,45,70)
myExpl <- terra::crop(myExpl, myExtent)
})

# --------------------------------------------------------------- #
file.out <- paste0(myRespName, "/", myRespName, ".AllModels.models.out")
if (file.exists(file.out)) {
  myBiomodModelOut <- get(load(file.out))
} else {

  # Format Data with true absences
  myBiomodData <- BIOMOD_FormatingData(resp.name = myRespName,
                                       resp.var = myResp,
                                       resp.xy = myRespXY,
                                       expl.var = myExpl)

  # Model single models
  myBiomodModelOut <- BIOMOD_Modeling(bm.format = myBiomodData,
                                      modeling.id = 'AllModels',
                                      models = c('RF', 'GLM'),
                                      CV.strategy = 'random',
                                      CV.nb.rep = 2,
                                      CV.perc = 0.8,
                                      OPT.strategy = 'bigboss',
                                      metric.eval = c('TSS', 'ROC'),
                                      var.import = 3,
                                      seed.val = 42)
}

models.proj <- get_built_models(myBiomodModelOut, algo = "RF")
  # Project single models
  myBiomodProj <- BIOMOD_Projection(bm.mod = myBiomodModelOut,
                                    proj.name = 'CurrentRangeSize',
                                    new.env = myExpl,
                                    models.chosen = models.proj,
                                    metric.binary = 'all',
                                    build.clamping.mask = TRUE)


# --------------------------------------------------------------- #
# Load environmental variables extracted from BIOCLIM (bio_3, bio_4, bio_7, bio_11 & bio_12)
data(bioclim_future)
myExplFuture <- terra::rast(bioclim_future)
DONTSHOW({
myExtent <- terra::ext(0,30,45,70)
myExplFuture <- terra::crop(myExplFuture, myExtent)
})
# Project onto future conditions
myBiomodProjectionFuture <- BIOMOD_Projection(bm.mod = myBiomodModelOut,
                                              proj.name = 'FutureRangeSize',
                                              new.env = myExplFuture,
                                              models.chosen = models.proj,
                                              metric.binary = 'TSS')
                                              
# Compute differences
myBiomodRangeSize <- BIOMOD_RangeSize(proj.current = myBiomodProj,
                                      proj.future = myBiomodProjectionFuture,
                                      metric.binary = "TSS")


# Represent main results
bm_PlotRangeSize(bm.range = myBiomodRangeSize)