R: Function MAPI_RunAuto

MAPI_RunAuto {mapi} | R Documentation

## Function MAPI_RunAuto

### Description

This function is a wrapper allowing to run a complete MAPI analysis.

### Usage

    MAPI_RunAuto(
      samples,
      metric,
      crs,
      isMatrix = all(class(metric) == "matrix", nrow(metric) == ncol(metric)),
      beta = 0.25,
      ecc = 0.975,
      buf = 0,
      errRad = 10,
      nbPermuts = 0,
      dMin = 0,
      dMax = Inf,
      nbCores = ifelse(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.
`crs` | coordinate reference system: integer with the EPSG code, or character with proj4string. When using dummy coordinates (eg. simulation output) you may use EPSG:3857 for example. This allows computation but, of course, has no geographical meaning.
`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.
`beta` | A value depending on spatial regularity of sampling: 0.5 for regular sampling, 0.25 for random sampling (Hengl, 2006).
`ecc` | ellipse eccentricity value (0.975 by default).
`buf` | optional. This parameter allows to expand or shrink the grid by a number of units in the same reference system as the sample geographical coordinates (0 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

Following functions are called by `MAPI_RunAuto` in following order:

- `MAPI_CheckData` cleans the dataset;

- `MAPI_GridAuto` generates a grid of hexagons by calling `MAPI_EstimateHalfwidth` then `MAPI_GridHexagonal`;

- `MAPI_RunOnGrid` performs the MAPI analysis.

NOTE: The call to `MAPI_Tails` is not included. It should be done afterwards on the object returned by `MAPI_RunAuto`.

### 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. & 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")
    # Run a MAPI analysis without permutation
    my.results <- MAPI_RunAuto(samples, metric, crs=3857, beta=0.5, nbPermuts=0)

    # eg. Export results to shapefile "myFirstMapiResult" in current directory
    # to further visualize and customize the MAPI plot in SIG software.
    library(sf)
    st_write(my.results, dsn=".", layer="myFirstMapiResult", driver="ESRI Shapefile")

    ## End(Not run)

[Package mapi version 1.0.5 Index]