MAPI_RunOnGrid: Function MAPI_RunOnGrid
In mapi: Mapping Averaged Pairwise Information

Description Usage Arguments Details Value References Examples

View source: R/MAPI_RunOnGrid.R

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

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
)

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

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

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

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

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