IDbyDistanceRawData: Spatially provenance a specimen from raw trait data

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

Spatially provenance a specimen from raw trait data

Description

This function takes the raw variables of an unknown specimen and reference specimens and uses euclidean distances to calculate a likely spatial provenance. Note that this procedure can only be applied to one unknown specimen at a time. Shape variables can be specified and if so Procrustes distances can be calculated. It 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 IDbyDistanceRawDataCCV function which does this automatically in a leave-one-out process. However, if a cross-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

IDbyDistanceRawData(
  LatLongs,
  TargetData,
  RefData,
  ShapeData = TRUE,
  ShapeDim = 2,
  DistMethod = c("Euc", "Proc"),
  LongRange = c(0, 0),
  LatRange = c(0, 0),
  RangeSamp = 10,
  Verbose = TRUE,
  PrintProg = FALSE,
  Validate = FALSE,
  ValidLatLongs,
  PlotRes = TRUE,
  HeatHue = c(0.15, 1),
  TileSize = 2,
  PlotProv = FALSE,
  PlotValCor,
  Method = c("Spearman", "Pearson"),
  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.
TargetData	is a vector of unknown specimen data. If it is geometric morphometric data is should be a vector of superimposed coordinated in the format X1, Y1, X2, Y2... etc. (or a vector of other standardised variables that can appropriately have euclidean distances calculated between it and reference variables). NB if applied to a reference collection specimen be sure to remove it from the RefData dataset.
RefData	is a matrix of Reference specimen data where the rows are the individual reference specimens and the columns are the variables in the same order as the TargetData vector.
ShapeData	logical indicating whether the data is geometric morphometric shape data that requires superimposition. Default set to TRUE
ShapeDim	integer either 2 or 3 to indicate the dimensions of landmark coordinates if the data is geometric morphometric data.
DistMethod	determines what kind of distance calculation should be used, either Euclidean "Euc" or Procrustes "Proc". If the user wishes to use another distance or dissimilarity please use the IDbyDistanceDistInput function.
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

When used for shape data and for Procrustes distances this function makes use of the procGPA and procdist functions from the shapes package. When Euclidean distances are employed the dist function of the base stats package is used. 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

Ian L. Dryden (2016). shapes: Statistical Shape Analysis. R package version 1.1-13. https://CRAN.R-project.org/package=shapes

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

Author(s)

Ardern Hulme-Beaman

Examples

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))

RpraetorDataMat <- Array2Mat(Rpraetor$LMs)

rThres <- IDbyDistanceRawDataCCV(LatLongs = Rpraetor$Lat.Long,
              RefData = RpraetorDataMat,
              ShapeData=TRUE,
              ShapeDim=2,
              DistMethod= "Proc",
              Verbose = TRUE,
              ProvConfidence = .95,
              PrintProg = FALSE,
              Method = 'Spearman')

R.Samp <- c(12, 42)

IDbyDistanceRawData(LatLongs = Rpraetor$Lat.Long[-1,],
                 TargetData = RpraetorDataMat[1,],
                 RefData = RpraetorDataMat[-1,],
                 ShapeData = TRUE,
                 ShapeDim = 2,
                 DistMethod = "Proc",
                 LongRange = Long.Range,
                 LatRange = Lat.Range,
                 RangeSamp = R.Samp,
                 Verbose = FALSE,
                 Validate = FALSE,
                 PlotValCor = rThres$`Provenancing.Correlation.95%.Confidence`,
                 PlotProv = TRUE,
                 Method = 'Spearman')

points(x = Rpraetor$Lat.Long$Long[1], y=Rpraetor$Lat.Long$Lat[1], col='blue', pch=16)

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