HeatMappingPerm: Heat mapping function to identify region of highest value...

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

Heat mapping function to identify region of highest value with significance

Description

This function takes a metric for spatial specimens or populations with defined locations and calculates the region of highest values. This can be used with population variance scores to identify regions of highest variance. A permutation test accompanies this to identify regions where the correlation between the metric and geographic distance is significant to the user determined level. This function runs permutations in parallel.

Usage

HeatMappingPerm(
  LatLongs,
  VarData,
  LongRange = c(0, 0),
  LatRange = c(0, 0),
  RangeSamp = 10,
  Verbose = TRUE,
  PlotRes = TRUE,
  HeatHue = c(0.15, 1),
  TileSize = 2,
  Method = c("Spearman", "Pearson"),
  PacificCent = FALSE,
  Perm = 100,
  SigLevel = 0.05
)

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.
VarData	a numeric vector of values (e.g. variance metrics) in corresponding order with the LatLongs.
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.
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.
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.
Perm	an integer of the number of permutations the function is to run.
SigLevel	a numeric value between 1 and 0 to set the required significance level for plotting a significant ploygon. Default is set to 0.05.

Details

The map plotting of this function makes use of the functions of the maps package. 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.

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

Range.Exp <- .5

Long.Range <- c(80, -100)
#Lat.Range <- c(floor(min(RatVarData$Lat))-Range.Exp,ceiling(max(RatVarData$Lat)+Range.Exp))

#R.Samp <- c(30, 50)


#VarianceOrigin(LatLongs = cbind(RatVarData$Lat, RatVarData$Long),
 #              VarData = RatVarData$mean.of.sq.prodist.var,
  #             LongRange = Long.Range,
   #            LatRange = Lat.Range,
    #           RangeSamp = R.Samp,
     #          Method = 'Pearson',
      #         PacificCent = TRUE)

#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.