nearestEnvPoints {enmSdmX} | R Documentation |
Extract "most conservative" environments from points and/or polygons
Description
This function implements the "nearest environmental point" method (Smith et al. 2023) to enable the use of occurrence records geolocated only to a general place (e.g., a country or province), along with occurrences georeferenced with little error. The function returns environments from a set of precisely-geolocated points plus the environment associated with each imprecise record.
Usage
nearestEnvPoints(
rasts,
pts = NULL,
polys = NULL,
centerFrom = "pts",
pca = TRUE,
numPcs = 3,
center = TRUE,
scale = TRUE,
rule = "nearest",
na.rm = TRUE,
out = "both"
)
Arguments
rasts |
A |
pts |
A set of spatial points of class |
polys |
A set of spatial polygons of class |
centerFrom |
Indicates how to locate the "reference" centroid used to identify single points on each polygon. This is only relevant if both
|
pca |
If |
numPcs |
The number of PC axes used to find environmental centroids. This is only used if |
center , scale |
Settings for |
rule |
Determines how to identify the single environmental point to associate with each polygon. Options include:
|
na.rm |
If |
out |
Determines what is returned. Only used if both
|
Details
This function locates a set of points from the environments covered by each polygon using the following procedure, the details of which depend on what arguments are specified:
Only
pts
is specified: Environments are taken directly from the locations ofpts
in environmental space.Only
polys
is specified: Environments are taken from the closest environment of all the environments associated with each each polygon that is closest to the environmental centroid of the environmental centroids of the polygons (that may be confusing, but it is not a typo).-
pts
andpolys
are specified: Environments are taken from the locations ofpts
plus the environment from each polygon closest to the environmental centroid ofpts
. By default, the function uses the environmental centroid of the precise occurrences in step (1), but this can be changed to the environmental centroid of the centroids of the polygons or the environmental centroid of the points defined by the union of precise occurrence points plus the environmental centroids of the polygons.
The function can alternatively return the points on the vertices of the MCP, or points on the input polygons closest to the reference centroid.
Value
A data frame.
References
Smith, A.B., Murphy, S.J., Henderson, D., and Erickson, K.D. 2023. Including imprecisely georeferenced specimens improves accuracy of species distribution models and estimates of niche breadth. Global Ecology and Biogeography In press. Open access pre-print: doi:10.1101/2021.06.10.447988
See Also
nearestGeogPoints
for the "nearest geographic point" method, a related approach for geographic space.
Examples
# This is a contrived example based on red-bellied lemurs in Madagascar.
# Point locations (which are real data) will be assumed to be "precise"
# records. We will designate a set of Faritas ("counties") to represent
# "imprecise" occurrences that can only be georeferenced to a geopolitical
# unit.
library(sf)
library(terra)
# coordinate reference system
wgs84 <- getCRS('WGS84')
# lemur point data
data(lemurs)
precise <- lemurs[lemurs$species == 'Eulemur rubriventer', ]
ll <- c('longitude', 'latitude')
precise <- sf::st_as_sf(precise[ , ll], coords=ll, crs=wgs84)
# *fake* lemur administrative unit-level data
faritras <- c('Vakinankaratra', 'Haute matsiatra', 'Ihorombe',
'Vatovavy Fitovinany', 'Alaotra-Mangoro', 'Analanjirofo', 'Atsinanana',
'Analamanga', 'Itasy')
data(mad1)
imprecise <- mad1[mad1$NAME_2 %in% faritras, ]
# climate predictors
rastFile <- system.file('extdata/madClim.tif', package='enmSdmX')
rasts <- rast(rastFile)
### Plot environment of points and environments of each polygon closest to
### centroid of environments of points. In this example, we use the first two
### principal component axes to characterize the niche.
# apply Nearest Environmental Point method
envPtsPolys <- nearestEnvPoints(rasts, pts = precise, polys = imprecise,
pca = TRUE, numPcs = 2)
envPolys <- nearestEnvPoints(rasts, pts = precise, polys = imprecise, numPcs = 2,
out = 'polys')
envPts <- nearestEnvPoints(rasts, pts = precise, polys = imprecise, numPcs = 2,
out = 'pts')
allPolyEnvs <- extract(rasts, imprecise)
# plot occurrences in environmental space
plot(envPtsPolys$PC1, envPtsPolys$PC2, pch=16, col='black',
xlab='PC1', ylab='PC2')
points(envPolys$PC1, envPolys$PC2, pch=21, bg='orange')
legend(
'bottomleft',
inset = 0.01,
legend = c('precise', 'imprecise (closest)'),
pch = c(16, 21),
col = c('black', 'black'),
pt.bg = c('orange', 'orange')
)
### compare identified environments to all environments across all polygons
###########################################################################
env <- as.data.frame(rasts)
pca <- stats::prcomp(env, center=TRUE, scale.=TRUE)
allPolyEnvs <- extract(rasts, imprecise, ID = FALSE)
allPolyEnvsPcs <- predict(pca, allPolyEnvs)
allPolyEnvs <- cbind(allPolyEnvs, allPolyEnvsPcs)
# plot in environmental space
plot(allPolyEnvs$PC1, allPolyEnvs$PC2, pch=16, col='orange',
xlab='PC1', ylab='PC2')
points(envPts$PC1, envPts$PC2, pch=16)
points(envPolys$PC1, envPolys$PC2, pch=1)
legend(
'bottomleft',
inset = 0.01,
legend = c('precise', 'imprecise (closest)', 'imprecise (all)'),
pch = c(16, 21, 16),
col = c('black', 'black', 'orange'),
pt.bg = c(NA, 'orange')
)
### display niches (minimum convex hulls) estimated
### using just precise or precise + imprecise records
#####################################################
pcs <- c('PC1', 'PC2')
preciseIndices <- chull(envPts[ , pcs])
preciseImpreciseIndices <- chull(envPtsPolys[ , pcs])
preciseIndices <- c(preciseIndices, preciseIndices[1])
preciseImpreciseIndices <- c(preciseImpreciseIndices,
preciseImpreciseIndices[1])
preciseOnlyNiche <- envPts[preciseIndices, pcs]
preciseImpreciseNiche <- envPtsPolys[preciseImpreciseIndices, pcs]
# plot in environmental space
plot(allPolyEnvs$PC1, allPolyEnvs$PC2, pch=16, col='orange',
xlab='PC1', ylab='PC2')
points(envPts$PC1, envPts$PC2, pch=16)
points(envPolys$PC1, envPolys$PC2, pch=1)
lines(preciseImpreciseNiche, col='coral4', lwd=2)
lines(preciseOnlyNiche, lty='dotted')
legend(
'bottomleft',
inset = 0.01,
legend = c('precise', 'imprecise (closest)', 'imprecise (all)',
'MCP imprecise-only', 'MCP precise + imprecise'),
pch = c(16, 21, 16, NA, NA),
col = c('black', 'black', 'orange', 'black', 'coral4'),
pt.bg = c(NA, 'orange', NA, NA, NA),
lwd = c(NA, NA, NA, 1, 2),
lty = c(NA, NA, NA, 'dotted', 'solid')
)