wDist {assignR}

Probability weighted distances and bearings

Description

Calculate the distance and bearing of migration for one or more samples, weighted by probabilities from a pdRaster analysis.

Usage

wDist(pdR, sites, maxpts = 1e5, bw = "sj")

Arguments

pdR

SpatRaster of n probability density maps, e.g., as produced by pdRaster.

sites

SpatVector object containing the collection locations for the n samples represented in pdR.

maxpts

numeric. Maximum number of grid cells at which to calculate bearing and distance.

bw

character or numeric. Smoothing bandwidth to be used in kernel density estimation. See bandwidth.

Details

pdR and sites must be of equal length and corresponding order, or if length(sites) == 1 & nlyr(pdR) > 1 then the location in sites is recycled with a message. Names in the output object are taken from the names of the layers in pdR.

Distances and bearings are calculated on the WGS84 geoid using functions from the terra and geosphere package. These calculations can take a long time for large rasters. If maxpts is less than the number of grid cells in each pdR layer, calculations are carried out for maxpts randomly selected cells.

Bearing values correspond to the initial bearing from source to collection location, and are reported on a scale of -180 to +180 degrees. The statistical metrics are rectified so that values for distributions spanning due south are reported correctly. Both weighted bearing and distance distributions are often multimodal, and it is recommended to review the distribution densities to assess the representativeness of the statistics (e.g., using plot.wDist).

When algorithmic bandwidth selection is used weights are ignored for this step and warnings to this effect are suppressed.

Value

Returns an object of class “wDist”, a list of length n. Each item contains three named objects:

stats

named number. Statistics for the distance (dist, meters) and bearing (bear, degrees) between source and collection locations, including the weighted mean (wMean) and quantile (wXX) values.

d.dens

density. Weighted kernel density for the distance between source and collection locations (meters). See density.

b.dens

density. Weighted kernel density for the bearing between source and collection locations (degrees). See density.

Examples

# load hydrogen isotope data for human hair in North America
d = subOrigData(group = "Modern human", mask = naMap, genplot = FALSE)

# rescale from environmental isoscape to tissue isoscape
r = calRaster(d, d2h_lrNA, naMap, genplot = FALSE)

# four unknown-origin examples
id = c("A", "B", "C", "D")
d2H = c(-110, -90, -105, -102)
un = data.frame(id, d2H)

# posterior probabilities
pp = pdRaster(r, un, mask = naMap, genplot = FALSE)

# random collection locations
sites = d$data[sample(seq(length(d$data)), 4),]

# generate a wDist object
wd = wDist(pp, sites)

# structure of the wDist object
str(wd, 2)