Load Middle Earth example

The small Middle Earth example dataset used here contains four objects which are loaded by load_middle_earth_ex():

1. lotr_vcf - a vcfR object containing the genetic data

2. lotr_coords - a dataframe object containing sample coordinates

3. lotr_lyr - a raster object of the landscape (higher values indicate greater connectivity/carrying capacity)

4. lotr_range - a polygon outlining the “range” of the simulated species

load_middle_earth_ex()
#> 
#> -------------- middle earth example --------------
#> 
#> Objects loaded:
#> lotr_vcf: vcfR object (100 variants x 100 samples)
#> lotr_coords: dataframe with x and y coordinates
#> lotr_lyr: middle earth RasterLayer (100 x 100)
#> lotr_range: sf polygon of the species range
#> 
#> --------------------------------------------------

# Genetic data
lotr_vcf
#> Loading required namespace: vcfR
#> ***** Object of Class vcfR *****
#> 100 samples
#> 1 CHROMs
#> 100 variants
#> Object size: 0.1 Mb
#> 0 percent missing data
#> *****        *****         *****

# Coordinates
head(lotr_coords)
#>             x         y
#> 538  88.73547 -66.61610
#> 1397 78.50479 -23.24048
#> 1200 14.32163 -25.99363
#> 952  89.86373 -65.49860
#> 1177 45.42427 -23.13054
#> 383  98.89395 -13.88943

# Raster data
lotr_lyr
#> class      : RasterLayer 
#> dimensions : 100, 100, 10000  (nrow, ncol, ncell)
#> resolution : 1, 1  (x, y)
#> extent     : 0, 100, -100, 0  (xmin, xmax, ymin, ymax)
#> crs        : NA 
#> source     : memory
#> names      : lyr 
#> values     : 0, 1  (min, max)

# Map of data
plot(lotr_lyr, col = magma(100), axes = FALSE, box = FALSE)
points(lotr_coords, col = mako(1, begin = 0.8), pch = 3, cex = 0.5)

If users don’t have a raster layer of their landscape, they can generate one using their sample coordinates with the coords_to_raster() function. The resolution of this raster can be tuned either with the agg (to aggregate) or disagg (to disaggregate) arguments, or defined using the res argument. The res argument can either be a single value (e.g., 0.00833) or a vector of two values with the x and y resolutions. The buffer argument can be used to add an edge to the raster (i.e., buffer away from the coordinates).

ex_raster1 <- coords_to_raster(lotr_coords, buffer = 1, plot = TRUE)

ex_raster2 <- coords_to_raster(lotr_coords, buffer = 1, agg = 2, plot = TRUE)

ex_raster3 <- coords_to_raster(lotr_coords, buffer = 1, disagg = 4, plot = TRUE)

ex_raster4 <- coords_to_raster(lotr_coords, buffer = 1, res = 10, plot = TRUE)

Run moving window calculations with window_gd()

To create a moving window map with a rectangular window, use window_gd(). The main additional arguments to window_gd() are:

1. wdim - Used to create the neighborhood matrix for the moving window based on the dimensions provided. This argument can either be set to one value (e.g., 3) which will create a square window (e.g., 3 x 3), or two values, which will create a rectangular window (e.g., 3 x 5). We encourage users to experiment with different values of wdim to determine the sensitivity of their results to this parameter. Ideally, wdim would be set with some knowledge of the study system in mind (e.g., the dispersal patterns and/or neighborhood size of the study organism). A preview of the window size relative to the landscape can be obtained using the preview_gd() function.

2. crop_edges - Whether to crop out the cells along the edge of the raster that are not surrounded by a full window. Users may want to do so to avoid “edge effects” caused by incomplete windows along the borders of the raster. As wingen is relatively insensitive to sample size, edge effects are not likely to have a very strong effect on diversity estimates, so by default crop_edges = FALSE.

Before running window_gd(), users can preview the moving window and the counts within each cell of the raster to get a sense of how big the window is and what the density of counts looks like across their landscape. Here, we provide the raster layer (lotr_lyr), the coordinates (lotr_coords), the window dimensions (7 x 7), the aggregation factor (3), and the minimum sample number (min_n). min_n will be used to mask the sample count layer to show how much of the landscape will be excluded due to low sample count. We specify method = window for a preview of window_gd(), we will discuss other methods (i.e., circle and resist later).

preview_gd(lotr_lyr,
  lotr_coords,
  method = "window",
  wdim = 7,
  fact = 3,
  sample_count = TRUE,
  min_n = 2
)

#> class       : SpatRaster 
#> size        : 34, 34, 1  (nrow, ncol, nlyr)
#> resolution  : 3, 3  (x, y)
#> extent      : 0, 102, -102, 0  (xmin, xmax, ymin, ymax)
#> coord. ref. :  
#> source(s)   : memory
#> name        : sample_count 
#> min value   :            2 
#> max value   :           11

Next, we run the moving window function with our vcf, coordinates, and raster layer. Here, we set the parameters to calculate pi, using a window size of 7 x 7, an aggregation factor of 3, and rarefaction with a rarefaction size of 2 (i.e., minimum sample size of 2), and 5 iterations.

We then plot the genetic diversity layer (the first layer of the produced raster stack) and the sample counts layer (the second layer).

Note: you will get a warning that no CRS is found for the provided coordinates or raster and to check that the CRS for these objects match. This is because these simulated data don’t have a CRS, but we know they match, so we can ignore this warning.

wgd <- window_gd(lotr_vcf,
  lotr_coords,
  lotr_lyr,
  stat = "pi",
  wdim = 7,
  fact = 3,
  rarify = TRUE,
  rarify_n = 2,
  rarify_nit = 5,
  L = 100
)
#> Warning in crs_check_window(lyr, coords): No CRS found for the provided coordinates. Make sure the coordinates and the raster have the same projection (see function details or wingen vignette)
#> Warning in crs_check_window(lyr, coords): No CRS found for the provided raster. Make sure the coordinates and the raster have the same projection (see function details or wingen vignette)
# The ggplot_gd function plots the genetic diversity layer
ggplot_gd(wgd, bkg = lotr_range) +
  ggtitle("Moving window pi") +
  # Add sampling coordinates
  geom_point(data = lotr_coords, aes(x = x, y = y), pch = 16)

# The plot_count function plots the sample count layer
ggplot_count(wgd) +
  ggtitle("Moving window sample counts")

You can also create base R plots of your results using plot_gd() and plot_count():

plot_gd(wgd, bkg = lotr_range, main = "Moving window pi")

plot_count(wgd, main = "Moving window sample counts")

Run moving window calculations with circle_gd()

To create a moving window map with a circular window, we can use circle_gd(). The main additional arguments to circle_gd() are:

1. maxdist - maximum geographic distance used to define the neighborhood; any samples farther than this distance will not be included (this can be thought of as the neighborhood radius). Can be provided as either (1) a single numeric value or (2) a SpatRaster where each pixel is the maximum distance to be used for that cell on the landscape (must be the same spatial scale as lyr). As with wdim, we encourage users to experiment with different values of maxdist to determine the sensitivity of their results to this parameter and ideally set it with some knowledge of the study system in mind (e.g., the dispersal patterns and/or neighborhood size of the study organism).

2. distmat - optional distance matrix output from get_geodist(); if not provided, circle_gd() will automatically use the get_geodist() function to calculate the distance matrix instead.

Like before, we can use the preview_gd() function to preview parameter settings. This time we specify method = "circle" and need to provide maxdist. Before doing so, we can calculate the distance matrix using get_geodist() which we can then use in both preview_gd() and circle_gd() to save time.

get_geodist() produces a distance matrix where the rows represent the cells of the raster and the columns are the individuals. The values are the geographic distance between each cell and each individual. Note that the input layer for get_geodist() must have the same resolution as the input layer for preview_gd() and circle_gd(). For example, if you want to run circle_gd() with fact = 3 and lyr = lotr_lyr, the input layer to get_geodist() must be aggregate(lotr_lyr, 3). Alternatively, you can first create a new aggregated raster to be used for all functions, as we have done below.

Note: if you want to get only the distances between your sample coordinates, set coords_only = TRUE.

# First, create a new aggregated raster
lotr_lyr5 <- aggregate(lotr_lyr, 5)

# Then calculate the distance matrix
distmat <- get_geodist(coords = lotr_coords, lyr = lotr_lyr5)

preview_gd(lotr_lyr5,
  lotr_coords,
  method = "circle",
  maxdist = 10,
  distmat = distmat,
  sample_count = TRUE,
  min_n = 2
)

#> class       : SpatRaster 
#> size        : 20, 20, 1  (nrow, ncol, nlyr)
#> resolution  : 5, 5  (x, y)
#> extent      : 0, 100, -100, 0  (xmin, xmax, ymin, ymax)
#> coord. ref. :  
#> source(s)   : memory
#> name        : sample_count 
#> min value   :            2 
#> max value   :            9

Then, we can run circle_gd():

cgd <- circle_gd(lotr_vcf,
  lotr_coords,
  lotr_lyr5,
  stat = "pi",
  maxdist = 10,
  distmat = distmat,
  rarify = FALSE,
  L = 100
)

ggplot_gd(cgd, bkg = lotr_range) +
  ggtitle("Circle moving window pi")

For circle_gd() (and resist_gd()), you can also define maxdist with a raster to set the maximum distance (i.e., the radius) for each cell. In this case, we can use the carrying capacity/conductance map (lotr_lyr5) and multiply it by 100 so that the radius will range from 0 to 100 based on the value of the raster.

vcgd <- circle_gd(
  lotr_vcf,
  lotr_coords,
  lotr_lyr5,
  stat = "pi",
  maxdist = lotr_lyr5 * 100,
  distmat = distmat,
  rarify = FALSE,
  L = 100
)

ggplot_gd(vcgd, bkg = lotr_range) +
  ggtitle("Circle moving window pi")

Run moving window calculations with resist_gd()

To create a moving window map with resistance distances, use resist_gd(). The main additional arguments to resist_gd() are:

1. maxdist - maximum cost distance used to define the neighborhood; any samples further than this cost distance will not be included (this can be thought of as the neighborhood radius, but in terms of cost distance). Can be provided as either (1) a single numeric value or (2) a SpatRaster where each pixel is the maximum distance to be used for that cell on the landscape (must be the same spatial scale as lyr). As stated before, we encourage users to experiment with different values of maxdist to determine the sensitivity of their results to this parameter.

2. lyr - in addition to being the raster layer the window moves across, this will also serve as the conductivity layer used to calculate resistance distances (higher values should mean greater conductivity).

3. distmat - optional distance matrix output from get_resdist(); if not provided, resist_gd() will automatically use the get_resdist() function to calculate the distance matrix instead.

resist_gd() takes a longer time to run and we recommend taking advantage of parallelization, in particular for the calculation of the distance matrix using get_resdist(). We also recommend first calculating the distance matrix with get_resdist() and then providing it to resist_gd() using the distmat argument as this allows for resist_gd() to be run quickly multiple times (i.e., to test different parameters) by avoiding repeating the costly distance calculations. Note that lyr in both get_resdist() and in resist_gd() must have the same spatial scale (e.g., the same resolution and extent).

As with get_geodist(), get_resdist() produces a distance matrix where the rows represent the cells of the raster and the columns are the individuals. The values are the resistance distance between each cell and each individual. If you want to get only the distances between your sample coordinates, set coords_only = TRUE.

Again, we can use the preview_gd() function to preview parameter settings. Here, we specify method = "resist" and provide maxdist.

lotr_distmat <- get_resdist(coords = lotr_coords, lyr = lotr_lyr5)

preview_gd(lotr_lyr5,
  lotr_coords,
  method = "resist",
  maxdist = 60,
  distmat = lotr_distmat,
  sample_count = TRUE,
  min_n = 2
)

#> class       : SpatRaster 
#> size        : 20, 20, 1  (nrow, ncol, nlyr)
#> resolution  : 5, 5  (x, y)
#> extent      : 0, 100, -100, 0  (xmin, xmax, ymin, ymax)
#> coord. ref. :  
#> source(s)   : memory
#> name        : sample_count 
#> min value   :            2 
#> max value   :           20

rgd <- resist_gd(lotr_vcf,
  lotr_coords,
  lotr_lyr5,
  distmat = lotr_distmat,
  stat = "pi",
  maxdist = 60,
  rarify = FALSE,
  L = 100
)

ggplot_gd(rgd, bkg = lotr_range) +
  ggtitle("Resistance moving window pi")

In addition to using continuous rasters of connectivity, you can also use rasters to designate passable and impassable areas. This can be useful for designating boundaries you don’t want windows to extend across (e.g., mountain ranges) or extend between (e.g., rivers).

# create layer
resist_lyr <- rast(aggregate(lotr_lyr, 5))

# create an impassable area down the middle coded as NA
resist_lyr[] <- 1
resist_lyr[ext(40, 60, -100, 0)] <- NA

# get resistance distances
distmat <- get_resdist(coords = lotr_coords, lyr = resist_lyr)

# plot preview
preview_gd(resist_lyr, lotr_coords, method = "resist", distmat = distmat, maxdist = 10)

#> class       : SpatRaster 
#> size        : 20, 20, 1  (nrow, ncol, nlyr)
#> resolution  : 5, 5  (x, y)
#> extent      : 0, 100, -100, 0  (xmin, xmax, ymin, ymax)
#> coord. ref. :  
#> source(s)   : memory
#> name        : sample_count 
#> min value   :            0 
#> max value   :           10

# create moving window map
resist_gd <- resist_gd(
  lotr_vcf,
  lotr_coords,
  resist_lyr,
  maxdist = 10,
  distmat = distmat
)

ggplot_gd(resist_gd)

Krige results

To produce smoother maps of genetic diversity, we provide the function wkrig_gd() which creates a spatially interpolated raster from the moving window raster produced by the moving window functions. This function uses the gstat package to fit different variogram models and select the best one to perform kriging.

Kriging is performed by first transforming the moving window layer into a set of coordinates with corresponding genetic diversity (or sample count) values and then interpolating using these coordinates across the grid provided. Because of this, it is important to keep in mind how the coordinates from the moving window raster and the grid align. If the resolution of the moving window raster is much lower than that of the grid, there are fewer points for interpolation which can result in grid-like artifacts during kriging.

To deal with this issue, users can either (1) resample their moving window raster layers and grid layers to the same resolution using the resample argument, or (2) manually disaggregate or aggregate either the moving window or grid layers using the terra aggregate() or disagg() functions. Generally, if users want a smoother resulting surface, a higher resolution grid layer should be used. Keep in mind that increasing the resolution of the moving window layer (either by resampling or disaggregating) can increase computational time as this increases the number of coordinates being used for kriging. This is also the case for increasing the resolution of the grid layer, though to a lesser extent.

To run this function, we provide the moving window raster layer and a raster layer to interpolate across. If no raster layer for interpolation is provided, the moving window layer will be used (i.e., the output kriged layer will have the same resolution and extent of the input window layer). If a stack of rasters is provided, only the first layer will be used. The output of this function is a kriged raster layer. Optionally, users can supply the moving window sample counts layer with the weight_r argument to set weights for variogram fitting and kriging, giving higher influence to cells with more samples. Users may also want to test different values for nmax, which is the maximum number of points to use for kriging; here, we use nmax = 30 to balance speed and accuracy.

# First, let's make a layer to krige across
# Let's say I want to krige to twice the resolution of the moving window layer
# I can use the disagg() function to disaggregate the moving window layer
grd <- disagg(wgd, 2)

# Then, I can use this layer as the grid to krige across
kgd <- wkrig_gd(wgd[["pi"]], grd = grd, weight_r = wgd[["sample_count"]], nmax = 30)
#> [using ordinary kriging]

ggplot_gd(kgd) +
  ggtitle("Kriged pi")

Users can optionally get the full model output by setting model_output = TRUE in which case wkrig_gd() returns a list where the first element (“raster”) is the kriged raster, the second element (“variogram”) is the variogram, and the third element (“model”) is the best-fit variogram model.

Note: Kriging can produce values that fall outside the range of possible values (e.g., genetic diversity values less than 0 or greater than the possible maximum). By default, in order to ensure that the values are bounded within the range of possible values, wkrig_gd() converts all values greater than the maximum of the input raster to that maximum (upper_bound = TRUE), and all values less than the minimum of the input raster to that minimum (lower_bound = TRUE). Users can turn off this functionality by setting lower_bound and upper_bound to FALSE. Users can also set their own custom lower_bound and upper_bound values (e.g., for heterozygosity or pi, you may want to set lower_bound = 0 and upper_bound = 1).

Legacy method: krig_gd() Users should note that wkrig_gd() superseded krig_gd(). This legacy function used the autoKrige() function from the R package automap to perform kriging using an automatically generated variogram. We have found that wkrig_gd() provides improved performance for interpolation of the moving window raster and we recommend using it instead of krig_gd().

Mask results

Next, we mask the resulting kriged layers. Masking can be performed using a variety of methods.

Method 1: Mask using the carrying capacity layer to exclude any areas where the carrying capacity is lower than 0.1. Alternatively, one could use a species distribution model or habitat suitability model to exclude areas where the probability of presence is very low:

# Aggregate the lotr_lyr to make it the same resolution as kgd before masking
# Note: lotr_lyr is a RasterLayer, so we convert it to a SpatRaster
mask_lyr <- resample(rast(lotr_lyr), kgd)
mgd <- mask_gd(kgd, mask_lyr, minval = 0.1)

ggplot_gd(mgd) +
  ggtitle("Kriged & carrying capacity masked pi")

Method 2: Mask the layer using a species range map (in this case, an sf polygon) to exclude areas falling outside the species range.

mgd <- mask_gd(kgd, lotr_range)

ggplot_gd(mgd) +
  ggtitle("Kriged & range masked pi")

Method 3: Mask the layer using a spatial Kernel Density Estimation (KDE) of sample density to exclude areas with low sampling density using the SpatialKDE package:

# First, install and load the SpatialKDE package
if (!require("SpatialKDE", quietly = TRUE)) install.packages("SpatialKDE")
library(SpatialKDE)

# Note: this code is not evaluated when building the vignette as it requires the SpatialKDE package

# Spatial KDE requires an sf data.frame containing only POINTS that is in a projected coordinate system
# The simulated coordinates are not projected, but for the purposes of this example, we'll pretend they are projected under the Goode Homolosine projection
# This kind of arbitrary setting of crs should not be done for real data (see above example for how to properly project coordinates)
lotr_sf <- st_as_sf(lotr_coords, coords = c("x", "y")) %>% st_set_crs("+proj=goode")

# The grid layer must also be a RasterLayer for SpatialKDE
# Here, we use the kriged raster as our grid to get a KDE layer of the same spatial extent and resolution
grid <- raster(kgd)

# See the SpatialKDE package for more options and details about using KDE
kde_lyr <- kde(
  lotr_sf,
  kernel = "quartic",
  band_width = 15,
  decay = 1,
  grid = grid,
)

# Visualize KDE layer
ggplot_count(kde_lyr) +
  ggtitle("KDE")

# Mask with mask_gd
mgd <- mask_gd(kgd, kde_lyr, minval = 1)

ggplot_gd(mgd) +
  ggtitle("Kriged & sample density masked pi")

Another nice visualization option is to add a “background” to your plots in the form of a raster or other sp or sf object (e.g., a country or range boundary) which can help provide geographic context:

ggplot_gd(mgd, bkg = lotr_range) +
  ggtitle("Kriged & masked pi")