Climate velocity trajectory classification

Function for the spatial classification of cells based on VoCC trajectories after Burrows et al. (2014). The function performs a hierarchical sequential classification based on length of trajectories, geographical features, and the relative abundance of trajectories ending in, starting from and flowing through each cell. Essentially, cells are first classified as non-moving, slow-moving and fast-moving relative to the distance a trajectory will cover over the projection period based on local climate velocities. Two types of climate sinks are then identified among the fast-moving cells: (i) boundary (e.g., coastal) cells disconnected from cooler (warmer) neighbouring cells under a locally warming (cooling) climate, and (ii) locations with endorheic spatial gradients where the velocity angles of neighbouring cells converge towards their central point of intersection. Finally, the remaining cells are classified by reference to the total number of trajectories per cell based on the proportions of the number of trajectories starting from (Nst), ending in (Nend), and flowing through (NFT) a cell over the period. Based on these proportions, cells are classified into five classes: (1) climate sources, when no trajectories end in a cell (Nend = 0); (2) relative climate sinks, when the relative number of trajectories ending in a cell is high and the proportion of starting trajectories is low; (3) corridors as cells with a high proportion of trajectories passing through; and (4) divergence and (5) convergence cells identified from the remaining cells as those where fewer/more trajectories ended than started in that cell, respectively.

Usage

trajClas(
  traj,
  vel,
  ang,
  mn,
  trajSt,
  tyr,
  nmL,
  smL,
  Nend,
  Nst,
  NFT,
  DateLine = FALSE
)

Arguments

traj: data.frame as retuned by voccTraj containing the coordinates and identification number for each trajectory.
vel: SpatRaster with the magnitude of gradient-based climate velocity.
ang: SpatRaster with velocity angles.
mn: SpatRaster with mean climatic values for the study period.
trajSt: integer number of trajectories starting from each cell or spatial unit.
tyr: integer number of years comprising the projected period.
nmL: numeric upper threshold (distance units as per vel object) up to which a trajectory is considered to have traveled a negligible distance over the study period (non-moving).
smL: numeric upper threshold up to which a trajectory is considered to have traveled a small distance over the study period (slow-moving).
Nend: numeric the percentage of trajectories ending to be used as threshold in the classification.
Nst: numeric the percentage of trajectories starting to be used as threshold in the classification.
NFT: numeric the percentage of trajectories flowing through to be used as threshold in the classification.
DateLine: logical does the raster extent cross the international date line? (default "FALSE").

Value

A SpatRaster containing the trajectory classification ("TrajClas"), as well as those based on trajectory length ("ClassL"; 1 non-moving, 2 slow-moving, 3 fast-moving cells), boundrary ("BounS") and internal sinks ("IntS"), and the proportion of trajectories ending("PropEnd"), flowing through ("PropFT") and starting ("PropSt"). The trajectory classes ("TrajClas") are (1) non-moving, (2) slow-moving, (3) internal sinks, (4) boundary sinks, (5) sources, (6) relative sinks, (7) corridors, (8) divergence and (9) convergence.

References

Burrows et al. 2014. Geographical limits to species-range shifts are suggested by climate velocity. Nature, 507, 492-495.

Author

Jorge Garcia Molinos

Examples

if (FALSE) { # \dontrun{
HSST <- VoCC_get_data("HSST.tif")

# input raster layers
yrSST <- sumSeries(HSST,
  p = "1960-01/2009-12", yr0 = "1955-01-01", l = terra::nlyr(HSST),
  fun = function(x) colMeans(x, na.rm = TRUE), freqin = "months", freqout = "years"
)

mn <- terra::mean(yrSST, na.rm = TRUE)
tr <- tempTrend(yrSST, th = 10)
sg <- spatGrad(yrSST, th = 0.0001, projected = FALSE)
v <- gVoCC(tr, sg)
vel <- v[[1]]
ang <- v[[2]]

# Get the set of starting cells for the trajectories and calculate trajectories
# at 1/4-deg resolution (16 trajectories per 1-deg cell)
mnd <- terra::disagg(mn, 4)
veld <- terra::disagg(vel, 4)
angd <- terra::disagg(ang, 4)
lonlat <- stats::na.omit(data.frame(
  terra::xyFromCell(veld, 1:terra::ncell(veld)),
  terra::values(veld), terra::values(angd), terra::values(mnd)
))[, 1:2]

traj <- voccTraj(lonlat, vel, ang, mn, tyr = 50, correct = TRUE)

# Generate the trajectory-based classification
clas <- trajClas(traj, vel, ang, mn,
  trajSt = 16, tyr = 50, nmL = 20, smL = 100,
  Nend = 45, Nst = 15, NFT = 70, DateLine = FALSE
)

# Define first the colour palette for the full set of categories
my_col <- c(
  "gainsboro", "darkseagreen1", "coral4", "firebrick2", "mediumblue", "darkorange1",
  "magenta1", "cadetblue1", "yellow1"
)
# Keep only the categories present in our raster
my_col <- my_col[sort(unique(terra::values(clas[[7]])))]

# Classify raster / build attribute table
clasr <- terra::as.factor(clas[[7]])
rat_r <- data.frame(ID = sort(unique(terra::values(clas[[7]]))),
                    trajcat = c("N-M", "S-M", "IS", "BS", "Srce",
                               "RS", "Cor", "Div", "Con")[sort(unique(terra::values(clas[[7]])))])
terra::cats(clasr) <- rat_r
# Produce the plot using the rasterVis levelplot function
rasterVis::levelplot(clasr,
  col.regions = my_col,
  xlab = NULL, ylab = NULL, scales = list(draw = FALSE)
)
} # }