localSpatialCorrForValues: Local characteristic distance of spatial autocorrelation for...

In adamlilith/enmSdm: Tools for Modeling Niches and Distributions of Species

Local characteristic distance of spatial autocorrelation for variables

Description

This function calculates the range of spatial autocorrelation for a set of predictors at a set of sites. The output is determined by the type of input:

• If the input is raster or raster stack, the output is a raster stack, one layer per layer of input, with cell values equal to the characteristic distance of spatial autocorrelation for each cell.

• If input is a raster and a matrix, data frame, SpatialPoints, or SpatialPointsDataFrame object, the output will be a matrix, data frame, or SpatialPointsDataFrame with the characteristic distance of spatial autocorrelation for each layer in the raster set at each point.

• If input is just a single matrix, data frame, or SpatialPointsDataFrame, output will reflect the scale of autocorrelation using data at just the sites represented by the input. The output format be the same as the input format.

See Details for information on how the characteristic scale of spatial autocorrelation is estimated. This function is related to spatialCorrForPoints which calculates spatial autocorrelation for distances between points. However, this function calculates spatial autocorrelation for numeric-valued measurements taken at points (or raster cell centers).

Usage

localSpatialCorrForValues(
  x,
  focals = NULL,
  vars = NULL,
  breaks = 20,
  limitDist = FALSE,
  returnMax = TRUE,
  iters = 100,
  perc = 95,
  verbose = TRUE,
  ...
)

Arguments

x	Either a raster, raster stack/brick, matrix with column names, data frame, or SpatialPointsDataFrame. If you use a matrix or data frame then the first two columns will be assumed to represent longitude and latitude, in that order, and their coordinate reference system will be assumed to be WGS84 (unprojected).
focals	This has various uses depending on the type of object specified for x: If x is a raster or raster stack/brick and focals is NULL (default), then spatial autocorrelation will be calculated across all non-NA cells in x. If x is a SpatialPointsDataFrame and focals is NULL (default), then spatial autocorrelation will be calculated across all non-NA points represented by x. If x is a raster or raster stack/brick and x is a matrix with column names, data frame, SpatialPoints, or SpatialPointsDataFrame object, then autocorrelation will be calculated focals all sites in focals. If you use a matrix or data frame then the first two columns will be assumed to represent longitude and latitude, in that order, and their coordinate reference system will be assumed to be the same as the raster or raster stack/brick.
vars	Character vector or NULL (default). If x is a SpatialPointsDataFrame, by default the variables on which to calculate spatial autocorrelation will be taken from the column names of x. However, you can use vars to specify the column names in x to use. This is ignored if x is not a SpatialPointsDataFrame.
breaks	Either: A single integer, three numeric values, or a matrix or data frame with at least two columns: A positive integer: Number of overlapping bins to use. The minimum bin distance will be >0 and maximum <= the maximum inter-point distance. Three numeric values: The first two values are smallest and largest distances (in units used in coordinate reference system of rast, typically meters) across which to tabulate distance frequencies. The third value is the number of bins. Matrix or data frame with at least two columns. Each row corresponds to a different bin. The first column represents the minimum distance in each bin (in units used in coordinate reference system of rast, typically meters) and the second column the maximum distance. Subsequent columns are ignored. Note that by using this option arbitrary bins can be used–they need not overlap or even be continuous in coverage.
limitDist	Logical, if TRUE, consider only inter-point distances less than the maximum distance indicated by breaks (if breaks is a matrix, data frame, or a 3-element numeric vector). If FALSE (default), consider all inter-point distances even if they fall beyond the maximum distance defined by breaks. Note that if limitDist is TRUE, then there is the possibility that a particular cell/point will have no or very few "neighbors". If there are none, the value assigned to the neighbor-less point will be NA, and if there are few neighbors, then statistical power will be diminished and it will be likely that the maximum distance will be assigned to the cell/point.
returnMax	Logical, if TRUE (default) and the local characteristic distance of spatial autocorrelation is greater than the maximum distance under consideration, then return the maximum distance (i.e., the upper limit of the last distance bin generated from breaks). If FALSE then return NA in this case.
iters	Positive integer, number of times to permute the randomization test. Default is NULL.
perc	Numeric value in the range [0, 100], indicates the upper quantile of randomized distance frequencies above which observed distance frequencies are considered significant. Default is 95.
verbose	Logical, if TRUE (default) show progress.
...	Other arguments (not used).

Details

The characteristic scale of spatial autocorrelation for a variable for a specific "focals" site relative to a set of "reference" sites is estimated through a multi-step process. The nature of the focals and reference sites depends on the values of x and focals. If x is supplied but focals is not, then all sites (or cells) in x will be assumed to be the reference and focals sites. If x and focals are supplied, then sites in focals are the focals sites and sites (or cells) in x are the reference sites.

1. For each distance bin, calculate the observed upper quantile of the distribution of absolute difference between the value of the variable at the the focals site and all other "reference" sites supplied in argument x. Here, the upper quantile is given by 100 - 0.5 * (100 - perc). So if perc = 95 (default), this is the 97.5th quantile of the observed absolute difference for values associated with all reference points in each distance bin.

2. Apply a permutation test by scrambling the absolute differences associated with each pairwise distance between the focals site at reference sites. For each distance bin generate a null expectation from the randomized absolute differences by calculating the value of the 100 - percth quantile (so if perc = 95 this is the 5th quantile of the distribution). Repeat iters times and for each bin calculate the mean of the 100 - percth quantile.

Note that this measure of spatial autocorrelation assumes anisotropy, meaning that from a given focals site the characteristic distance of spatial autocorrelation is the same in all directions.

Value

A raster, raster stack/brick, or SpatialPointsDataFrame, depending on the input. If the output is a raster, raster stack, or raster brick, then values represent the minimum distance at which spatial autocorrelation is not significantly different from random expectation (i.e., the "left" side of the distance bin at which this occurs). If the output is a SpatialPointsDataFrame, then columns will be named "sacDistMin_XYZ", "sacDistMid_XYZ" and "sacDistMax_XYZ", where "XYZ" refers to the variable name and "Min", "Mid", and "Max" refer to the minimum, middle, and maximum distance of spatial autocorrelation for each site in the output (i.e., the left, middle, and right side of teh distance bin at which spatial autocorrelation for the site is not different from random expectation).

See Also

spatialCorrForPoints

Examples

## Not run: 
# get rasters for mean annual temperature and total precipitation
worldClim <- raster::getData('worldclim', var='bio', res=10)
worldClim <- raster::subset(worldClim, c(1, 12))

# crop to Madagascar
data(mad0)
madClim <- raster::crop(worldClim, mad0)

# remove non-Malagasy islands
madRast <- raster::rasterize(mad0, madClim)
madClim <- madClim * madRast
names(madClim) <- c('bio1', 'bio12')
madClim[['bio1']] <- madClim[['bio1']] / 10 # to deg C

### spatial autocorrelation for raster (can take a long time!)
sacRast <- localSpatialCorrForValues(x=madClim, focals=NULL)
sacRast <- sacRast / 1000 # convert to km

# plot
par(mfrow=c(2, 2))
raster::plot(madClim[['bio1']], main='BIO 01\n(10 * deg C)')
raster::plot(madClim[['bio12']], main='BIO 12\n(mm)')
raster::plot(sacRast[['bio1']], main='BIO 01\nDistance (km)')
raster::plot(sacRast[['bio12']], main='BIO 12\nDistance (km)')

### spatial autocorrelation for spatial points
# faster than rasters, but still takes a while
set.seed(123)
x <- dismo::randomPoints(madClim, 200)
env <- raster::extract(madClim, x)
x <- cbind(x, env)
breaks <- c(0, 100000, 10)
sacPoints <- localSpatialCorrForValues(x=x, breaks=breaks)

# plot: code point color by characteristic distance of spatial autocorrelation
maxSacBio1 <- max(sacPoints$sacDistMid_bio1, na.rm=TRUE)
maxSacBio12 <- max(sacPoints$sacDistMid_bio12, na.rm=TRUE)
sacBio1 <- 4 * sacPoints$sacDistMid_bio1 / maxSacBio1
sacBio12 <- 4 * sacPoints$sacDistMid_bio12 / maxSacBio12

# plot: notice points along transitional zones
# have smaller distances, as expected
par(mfrow=c(1, 2))
leg <- '\n(small: short dist, large: long dist)'
sp::plot(mad0, main=paste0('BIO 01', leg))
raster::plot(madClim[['bio1']], add=TRUE)
points(sacPoints, pch=1, cex=sacBio1, col='red')
sp::plot(mad0, main=paste0('BIO 12', leg))
raster::plot(madClim[['bio12']], add=TRUE)
points(sacPoints, pch=1, cex=sacBio12, col='blue')
#'
par(mfrow=c(1, 1))
maxDist <- max(c(sacPoints$sacDistMid_bio1, sacPoints$sacDistMid_bio12),
na.rm=TRUE)
yMax <- max(
hist(sacPoints$sacDistMid_bio1, breaks=10, plot=FALSE)$counts,
	hist(sacPoints$sacDistMid_bio12, breaks=10, plot=FALSE)$counts
)

hist(sacPoints$sacDistMid_bio1, col='red', xlim=c(0, maxDist),
ylim=c(0, yMax), breaks=10, xlab='Distance (m)')
hist(sacPoints$sacDistMid_bio12, border='blue', breaks=10, density=10,
add=TRUE)
legend('topleft', inset=0.01, legend=c('BIO1', 'BIO12'), fill=c('red', NA),
density=c(NA, 15), border=c('black', 'blue'))
	

### spatial autocorrelation for spatial points using raster as reference
data(lemurs)
lemur <- lemurs[lemurs$species == 'Eulemur rufifrons',
c('longitude', 'latitude')]
	
# remove record in water
lemurBio1 <- raster::extract(madClim[['bio1']], lemur)
nas <- which(is.na(lemurBio1))
lemur <- lemur[-nas, ]

sacLemur <- localSpatialCorrForValues(x=madClim, focals=lemur, breaks=10)

# plot: code point color by characteristic distance of spatial autocorrelation
bio1SacScaled <- 
round(100 * omnibus::stretchMinMax(sacLemur$sacDistMid_bio1))
bio12SacScaled <-
round(100 * omnibus::stretchMinMax(sacLemur$sacDistMid_bio12))

grayBio1 <- paste0('gray', bio1SacScaled)
grayBio12 <- paste0('gray', bio12SacScaled)

par(mfrow=c(1, 2))
leg <- '\n(dark: short dist, light: long dist)'
raster::plot(madClim[['bio1']], cex=1.2, main=paste0('BIO 01', leg))
points(lemur, pch=21, bg=grayBio1)
raster::plot(madClim[['bio12']], cex=1.2, main=paste0('BIO 12', leg))
points(lemur, pch=21, bg=grayBio12)

# plot buffers showing characteristic distance of spatial autocorrelation
# around each point
sacLemurEa <- sp::spTransform(sacLemur, getCRS('mollweide', TRUE))
buffsBio1Ea <- rgeos::gBuffer(sacLemurEa, byid=TRUE,
width=sacLemurEa$sacDistMid_bio1)
buffsBio12Ea <- rgeos::gBuffer(sacLemurEa, byid=TRUE,
width=sacLemurEa$sacDistMid_bio12)
buffsBio1 <- sp::spTransform(buffsBio1Ea, getCRS('wgs84', TRUE))
buffsBio12 <- sp::spTransform(buffsBio1Ea, getCRS('wgs84', TRUE))
par(mfrow=c(1, 2))
raster::plot(madClim[['bio1']], main=paste0('BIO 01', leg))
sp::plot(buffsBio1, add=TRUE)
points(lemur, pch=21, bg=grayBio1)
raster::plot(madClim[['bio12']], main=paste0('BIO 12', leg))
sp::plot(buffsBio12, add=TRUE)
points(lemur, pch=21, bg=grayBio12)


## End(Not run)

adamlilith/enmSdm documentation built on Jan. 6, 2023, 11 a.m.