IDbyDistanceDistInput: Spatially provenance a specimen from distance data

In ArdernHB/GeoOrigins: Spatial exploration of trait boundaries and provenance

Spatially provenance a specimen from distance data

Description

This function takes the distances from an unknown specimen to all reference specimens and uses these distances to calculate a likely spatial provenance. Note that this procedured can only be applied to one unknown specimen at a time. This distance input function allows the user to input any dissimilarity or distance desired and as appropriate for the data. The function has two applications either: calculating a specimens' provenance, or alternatively it can be used to calculate the minimum correlation coefficient needed to correctly identify a known specimen at its true collection location. The second application of this function can work as a correct cross-validation process if looped, but see IDbyDistanceDistInputCCV function which does this automatically in a leave-one-out process. However, if a corss-validation process that removed more than one specimen from the reference dataset at a time is required then it is advised that this be applied using this function.

Usage

IDbyDistanceDistInput(
  LatLongs,
  DistDataVec,
  LongRange,
  LatRange,
  RangeSamp = 10,
  Verbose = TRUE,
  PrintProg = FALSE,
  Validate = FALSE,
  ValidLatLongs,
  PlotRes = TRUE,
  HeatHue = c(0.15, 1),
  TileSize = 2,
  PlotProv = FALSE,
  PlotValCor,
  Method = c("Pearson", "Spearman"),
  PacificCent = FALSE
)

Arguments

LatLongs	a matrix of n rows by 2 columns where n is the number of reference specimens in your dataset and the columns are Latitude and Longitude values in that order. These latitude-longitude coordinates should be of the locations of the reference specimens.
DistDataVec	is a vector of distances from each reference specimen to the specimen of interest (either a specimen with unknown provenance or another reference specimen that the user is interested in validating the provenance of)
LongRange	is a vector of 2 elements defining the maximum and minimum Longitude values that the provenancing method should explore. This will also define the mapping range in the final plotted output.
LatRange	is a vector of 2 elements defining the maximum and minimum Latitude values that the provenancing method should explore. This will also define the mapping range in the final plotted output.
RangeSamp	is an integer vector of 1 or 2 elements that defines the resolution of spatial sampling. If one element is provided then both the latitude and longitude ranges are equally and evenly sampled using this value. If 2 elements are provided they should be in the order of latitude longitude and each range will be evenly sampled with its respective value.
Verbose	logical whether or not a matrix of spatial correlation values is returned or not. Default is set to TRUE.
PrintProg	logical whether or not to print a progress bar. Default set to FALSE.
Validate	logical whether or not to run a correct cross-validation analysis to find the lowest required correlation value for correct identification.
ValidLatLongs	if the process is carried out on a specimen of known location '(e.g. Validate=TRUE)', then the latitude longitude coordinates for that location should be provided here in that order.
PlotRes	logical whether or not to plot the provenancing map with heat values of most likely spatial origin.
HeatHue	numeric vector of 2 elements each between 0 and 1. The first should be the hue value on the HSV scale; the second value should be the level of transparency of the colour used.
TileSize	numeric to dictate the pixel size of the heat mapping colour values.
PlotProv	logical if the map should be printed with a polygon demarking a contour at a user defined correlation value.
PlotValCor	numeric correlation value that is used to determine the most likely origin of the specimen. This value can be calculated by using the correct cross-validation method and identifying the correlation value that will correctly identify a desired percentage of specimens (e.g. 95%).
Method	determines what kind of correlation coefficient should be used, either "Spearman" or "Pearson". Spearman's ranked correlation coefficient does not assume a linear relationship between geographic and trait distances, whereas Pearson's coefficient does.
PacificCent	logical determines whether the plotted map and analyses should be centred on the Pacific. Default set to FALSE.

Details

This method also makes use of the cor.test function from the stats package. When the PrintProg is set to TRUE, the progress function of the svMisc package is used. The map plotting of this function makes use of the functions of the maps package.

Value

If Verbose is TRUE then a dataframe of all values for every sampled grid reference is returned. If Verbose is FALSE then only those grid references with the highest correlation values are returned.

Citations

Original S code by Richard A. Becker, Allan R. Wilks. R version by Ray Brownrigg. Enhancements by Thomas P Minka and Alex Deckmyn. (2017). maps: Draw Geographical Maps. R package version 3.2.0. https://CRAN.R-project.org/package=maps

Grosjean, Ph. (2016). svMisc: SciViews-R. UMONS, Mons, Belgium. http://www.sciviews.org/SciViews-R.

Author(s)

Ardern Hulme-Beaman

Examples

RatDistMat <- ProcDistanceTable(Rpraetor$LMs)
Range.Exp <- .5
Long.Range <- c(floor(min(Rpraetor$Lat.Long$Long))
              -Range.Exp,ceiling(max(Rpraetor$Lat.Long$Long)+Range.Exp))
Lat.Range <- c(floor(min(Rpraetor$Lat.Long$Lat))
              -Range.Exp,ceiling(max(Rpraetor$Lat.Long$Lat)+Range.Exp))
rThres <- IDbyDistanceDistInputCCV(LatLongs = Rpraetor$Lat.Long,
              DistDataMat = RatDistMat,
              Verbose = TRUE,
              ProvConfidence = .95,
              PrintProg = FALSE,
              Method = 'Spearman')


R.Samp <- c(12, 42)
IDbyDistanceDistInput(LatLongs = Rpraetor$Lat.Long[-1,],
                   DistDataVec = RatDistMat[-1,1],
                   LongRange = Long.Range,
                   LatRange = Lat.Range,
                   RangeSamp = R.Samp,
                   Verbose = FALSE,
                   Validate = FALSE,
                   PlotValCor = rThres$`Provenancing.Correlation.95%.Confidence`,
                   PlotProv = TRUE,
                   Method = 'Spearman')

ArdernHB/GeoOrigins documentation built on Nov. 19, 2022, 10:21 a.m.