MAPI_RunOnGrid {mapi}

Function MAPI_RunOnGrid

Description

Launch a MAPI analysis for a given grid computed with MAPI_GridAuto or MAPI_GridHexagonal or provided by users.

Usage

MAPI_RunOnGrid(
  samples,
  metric,
  grid,
  isMatrix = FALSE,
  ecc = 0.975,
  errRad = 10,
  nbPermuts = 0,
  dMin = 0,
  dMax = Inf,
  nbCores = ifelse(base::requireNamespace("parallel", quietly = TRUE),
    parallel::detectCores() - 1, 1),
  N = 8
)

Arguments

samples

a data.frame with names and geographical coordinates of samples. Column names must be: 'ind', 'x', 'y'. Optional column 'errRad' with an error radius for sample locations (eg. GPS uncertainty). Coordinates must be projected (not latitude/longitude).

metric

a data.frame or a square matrix with the pairwise metric computed for all pairs of samples. If data.frame, column names must be: 'ind1', 'ind2', 'value'. If matrix, sample names must be the row- and column names.

grid

a spatial object of class 'sf' with the geometry of each cell. When using your own grid, please check that the object structure is the same as returned by MAPI_GridAuto or MAPI_GridHexagonal.

isMatrix

Boolean. Depends on the 'metric' data:
TRUE if 'metric' is a square matrix with column names = row names and standing for sample names.
FALSE if 'metric is a three columns data.frame ('ind1', 'ind2', 'value').
The default value is determined using a "matrix" class detection for metric as well as identity between row and column number.

ecc

ellipse eccentricity value (0.975 by default).

errRad

global error radius for sample locations (same radius for all samples, 10 by default). Units are in the same reference system as the sample geographical coordinates. To use different error radius values for sample locations, add a column 'errRad' in the 'sample' data (see mapi).

nbPermuts

number of permutations of sample locations (0 by default).

dMin

minimum distance between individuals. 0 by default.

dMax

maximal distance between individuals. +Inf by default.

nbCores

number of CPU cores you want to use during parallel computation. The default value is estimated as the number of available cores minus 1, suitable for a personal computer. On a cluster you might have to set it to a reasonable value (eg. 8) in order to keep resources for other tasks.

N

number of points used per quarter of ellipse, 8 by default. Don't change it unless you really know what you are doing.

Details

To test whether the pairwise metric values associated with the ellipses are independent of the sample locations, those are permuted 'nbPermuts' times. At each permutation, new cell values are computed and stored to build a cumulative null distribution for each cell of the grid. Each cell value from the observed data set is then ranked against its null distribution. For each cell, the proportion of permuted values that are smaller or greater than the observed value provides a lower-tailed (ltP) and upper-tailed (utP) test p-value.

A false discovery rate (FDR) procedure (Benjamini and Yekutieli, 2001) is applied to account for multiple testing (number of cells) under positive dependency conditions (spatial autocorrelation). An adjusted p-value is computed for each cell using the function p.adjust from the 'stats' package with the method 'BY'.

Value

a spatial object of class 'sf' providing for each cell:

• gid: Cell ID
  

• x and y coordinates of cell center
  

• nb_ell: number of ellipses used to compute the weighted mean
  

• avg_value: weighted mean of the pairwise metric
  

• sum_wgts: sum of weights of ellipses used to compute the weighted mean
  

• w_stdev: weighted standard deviation of the pairwise metric
  

• swQ: percentile of the sum of weights
  

• geometry
  When permutations are performed:
  

• proba: proportion of the permuted weighted means below the observed weighted mean
  

• ltP: lower-tail p-value adjusted using the FDR procedure of Benjamini and Yekutieli
  

• utP: upper-tail p-value adjusted using the FDR procedure of Benjamini and Yekutieli
  

References

Benjamini, Y. and Yekutieli, D. (2001). The control of the false discovery rate in multiple testing under dependency. Annals of Statistics 29, 1165–1188.

Examples

## Not run: 
data(metric)
data(samples)
my.grid <- MAPI_GridHexagonal(samples, crs=3857, 500) # 500m halfwidth

# Note: 10 permutations is only for test purpose, increase to >=1000 in real life!
my.results <- MAPI_RunOnGrid(samples, metric, grid=my.grid, nbPermuts=10, nbCores=1)

# eg. Export results to shapefile "myFirstMapiResult" in current directory
library(sf)
st_write(my.results, dsn=".", layer="myFirstMapiResult", driver="ESRI Shapefile")

## End(Not run)