BoundaryFinder: Returns geographic boundaries identified from trait distances

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

Returns geographic boundaries identified from trait distances

Description

This function takes the distances among all reference specimens and uses a process similar to leave-one-out correct cross-validation to identify likely spatial trait boundaries. This method only allows for the inclusion of specimens with specific known locations (i.e. specific latitude-longitude coordinates). This functions requires a distance input, which allows the user to input any desired dissimilarity or distance metrics as appropriate for the data.

Usage

BoundaryFinder(
  LatLongs,
  RefDistMat = matrix(),
  LongRange,
  LatRange,
  RangeSamp = 10,
  PrintProg = TRUE,
  PlotValCor,
  ExpandMap = c(0, 0),
  DataDump = TRUE,
  DataDumpPath = NA,
  StartPoint = 1,
  RefIDs = NULL,
  IgnorePrompts = FALSE,
  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.
RefDistMat	is a square matrix of pairwise distances among all reference specimens.
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.
PrintProg	logical whether or not to print a progress bar. Default set to FALSE.
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%).
ExpandMap	is a vector of 2 elements for expanding the plotting region of the map. The first element expands the latitudinal area and the second element expands the longitudinal area.
DataDump	determines whether a datadump is used, which is recommended for large datasets that may take time to computeand when the user might want to interupt the process mid way. The default is set to TRUE. If it's set to FALSE then the results are output as an array where rows and columns reflect latitude longitude and the third dimension are individual specimens in the reference dataset.
DataDumpPath	is a directory path indicating where the data for constructing the boundaries can be dumped.
StartPoint	is an iteger that denotes the specimen to start the process on. As the method needs to cycle through all known specimens in the database, this can take some time. If the process is stopped for whatever reason the process can be picked up again by adjusting the StartPoint to the specimen number that it had previously finished on.
RefIDs	is a vector of the unique identifiers for each of the reference specimens in the reference dataset. These values will be used for naming the files in the datadump folder and also for matching up with the returned summary results. Default is set to NULL and if this is not populated then reference data is worked through consecutively, naming the datadump files in consecutive order.
IgnorePrompts	default is set to FALSE, but if set to TRUE queries such as those confirming the location of the datadump will be suppressed.
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

The map plotting of this function makes use of the functions of the maps package. Spatial polygons were constructed using functions from the sp package and calculations of polygon intersects and areas were carried out using functions from the raster package. When the PrintProg is set to TRUE, the progress function of the svMisc package is used.

Value

If Verbose is TRUE then an array 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.

Pebesma, E.J., R.S. Bivand, 2005. sp: Classes and methods for spatial data in R. R News 5 (2) http://cran.r-project.org/doc/Rnews/.

Robert J. Hijmans (2016). raster: Geographic Data Analysis and Modeling. R package version 2.5-8. https://CRAN.R-project.org/package=raster

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

LowResRsamp.Rp <- c(7,20)
Boundaryfinding <- BoundaryFinder(LatLongs = Rpraetor$Lat.Long,
                               RefDistMat = RatDistMat,
                               LongRange = Long.Range,
                               LatRange = Lat.Range,
                               RangeSamp = LowResRsamp.Rp,
                               PlotValCor = rThres$`Provenancing.Correlation.95%.Confidence`,
                               ExpandMap = c(0,0),
                               RefIDs = rownames(Rpraetor$Lat.Long),
                               DataDump = FALSE,
                               IgnorePrompts = TRUE,
                               Method = 'Spearman')

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