Calculate the Isolation Metrics — isolation • caribmacro

This function is used to calculate the isolation metrics based on a PCA of the isolation distances for the geographic features of interest. This function requires the package 'FactoMineR'

isolation(
  dist,
  source,
  main,
  geo.rm = NULL,
  min = TRUE,
  sum = TRUE,
  larger = FALSE,
  area = NULL,
  sq.rt = TRUE,
  scale = TRUE,
  stats = TRUE,
  d.main = TRUE,
  export.dist = FALSE
)

Arguments

dist: a distance matrix in a data frame format that has the pairwise distance between all geographic features of interest and the nearby continents. The row names of the data from should be the names of the geographic features and should also be equal to the column names.
source: A character or vector of the column name(s) of the distance to the evolutionary source(s) of the group of species that will be used for the calculation of diversity indexes.
main: A character or vector of the column name(s) of the distance to the nearby continent(s)
geo.rm: Optional. A character or vector of the column name(s) of the distance
min: Logical. If TRUE then the minimum distance to another bank is used in the PCA
sum: Logical. If TRUE then the sum of the all the distances to the other banks is used in the PCA
larger: Logical. If TRUE then the minimum distance to a geographic feature of equal or larger size is used in the PCA
area: Optional. A data frame with two columns. The first has to be the names of the geographic features used in dist and the second the area for those geographic features. This argument is only needed if larger = TRUE
sq.rt: Logical. If TRUE then the distances will be square root transformed before the PCA is ran
scale: Logical. If TRUE then the data will be scaled in the PCA
stats: Logical. If TRUE then the the function will return a list of length 2 with the first element holding the isolation metrics (PC1 - PC4), the second holding the eigenvalues and variance explained by the PCs, and the third holding the loadings for the PCs.
d.main: Logical. If TRUE then the minimum distance to the mainland is used in the PCA
export.dist: Logical. If TRUE then all of the isolation distances are returned as a data frame in the last element of the exported list.

Value

A data frame holding the PC1, PC2, and PC3 scores for each geographic feature of interest calculated from a Principle Components Analysis of the isolation distances. If stats = TRUE then a list of length 3 is returned with the second slot holding the fit statistics of the PCA and the third slot holding the PC loadings for the isolation distances.

Isolation distances are the summed distances between a geographic feature and all others (including the mainland), the distance to nearest neighbor, minimum distance to mainland, and the minimum distance to a source geographic feature.

Examples

if (FALSE) {

library(here)
library(sf)
library(FactoMineR)

cent <- st_read(file.path(here(), 'gis', 'Centroids_Bank_Main_WGS_Merc.shp'))
cent.dist <- st_distance(x = cent, y = cent, by_element = FALSE)

cent.dist <- data.frame(cent.dist)
names(cent.dist) <- gsub(' ', '.', cent$bank)
cent.dist$bank <- cent$bank
cent.dist < -cent.dist[order(cent.dist$bank),
                        c('bank', sort(names(cent.dist)[which(names(cent.dist) != 'bank')]))]

for (i in 2:ncol(cent.dist)) {
  cent.dist[, i] <- as.numeric(cent.dist[, i])
}

main <- c('central.america', 'north.america', 'south.america')
iso <- isolation(dist = cent.dist,
                 source = c('cuba', 'south.america'),
                 main = main)

}