mapi (version 1.0.5)

mapi: MAPI, general presentation

Description

MAPI is an exploratory method providing graphical representations of the spatial variation of pairwise metrics (eg. distance, similarity coefficient, ...) computed between georeferenced samples.

Principle

As schematically illustrated Figure 1, MAPI relies on spatial joins between a hexagonal grid and a network of georeferenced samples connected by ellipses, i.e. polygons with 32 segments approaching an elliptical shape.

The shape of the ellipses can be controlled through the eccentricity value and the sample locations can be "blurred" by applying an error circle of a given radius on the geographic coordinates. Each elliptical polygon is associated to 1) the value of the pairwise metric computed between the samples it connects and 2) a weight corresponding to the inverse of its area (i.e. larger ellipses have lower weights).

Each cell of the grid receives the weighted mean of the pairwise metric values associated to the ellipses intersecting the cell.

Figure 1: Schematic principle of the MAPI method from Piry et al. 2016.

Input data

The analysis requires two tables (data.frame or data.table):

1. Information on samples: table with three mandatory columns and column names: 'ind' (sample name), 'x' and 'y' (projected coordinates). An optional column 'errRad' (radius of error circle on sample coordinates) can be provided.

MAPI requires cartesian coordinates (ie. projected, such as UTM or Lambert) NOT (yet?) angular coordinates (eg. latitude/longitude). The package sf provides the st_transform function for coordinates transformation and projection. GIS software such as QGis can also help with datum transformation.

Example of 'samples' data:

	ind	x	y	errRad
1	2_42	12000	5000	10
2	2_47	17000	5000	10
3	1_82	2000	9000	10
4	2_100	20000	10000	10
5	2_87	17000	9000	10
6	1_11	1000	2000	10
...	...	...	...	...

1. Values of the pairwise metric computed between samples provided, either, as a complete matrix with the same number of columns and rows (column and row names must match the sample names provided in the 'samples' data) or as a table with three mandatory columns and column names: 'ind1', 'ind2' (sample names) and 'value' (pairwise metric values).

Example of 'metric' data:

	ind1	ind2	value
1	1_1	1_2	0.055556
2	1_1	1_3	0.020833
3	1_1	1_4	0.125000
4	1_1	1_5	0.125000
5	1_1	1_6	0.020833
6	1_1	1_7	0.090278
...	...	...	...

Try it

Using the test dataset ('samples' and 'metric') included in the package, let's run an (almost) automatic MAPI analysis

Test data result from population genetic simulations in which two panmictic populations are separated by a barrier to dispersal. As we use dummy coordinates, there is no appropriate crs, so we just use 'crs=3857' (a pseudo-mercator projection). Of course, in this case, sample position on earth is meaningless. For a real dataset, 'crs' must be the EPSG code of the projection of your cartesian coordinates.

 # Load the package
 library(mapi)
 
 # Load 'samples' data
 data("samples")
 
 # Load 'metric' data. For our simulated data set the parwise metric 
 # computed between samples is the individual genetic distance â of Rousset (2000).
 data("metric")
 
 # Run MAPI the lazy way (automatic) with 1000 permutations 
 # for detection of significant (dis)continuous areas.
 # As crs must be set, we go with crs=3857 even if we use dummy coordinates.
 # Of course, this have no geographical meaning.
 # As we have a regular sampling, we use beta=0.5
 my.results <- MAPI_RunAuto(samples, metric, crs=3857, beta=0.5, nbPermuts=1000)
 
 # Get significant areas with a FDR control at alpha=0.05 (5%, by default)
 my.tails <- MAPI_Tails(my.results, alpha=0.05)
 
 # Look at the result Figure 2.
 MAPI_Plot2(my.results, tails=my.tails)
 

Spatial variation of the genetic distance is represented with a color scale from dark brown (lowest values) to dark blue (higher value). The central blue area identified as a significant area of discontinuity corresponds to the position of the simulated barrier. Note that due to the permutation procedure, delineation of the significant areas may vary slightly among runs.

Figure 2: MAPI graphical Output produced using the MAPI_Plot2 function.

To go deeper

MAPI_RunAuto is a wrapper which calls three other functions: MAPI_CheckData, MAPI_GridAuto and MAPI_RunOnGrid.

MAPI_GridAuto is itself another wrapper around MAPI_EstimateHalfwidth and MAPI_GridHexagonal.

Typically, a "manual" MAPI analysis will involve the following ordered steps:

1. MAPI_CheckData

2. MAPI_EstimateHalfwidth

3. MAPI_GridHexagonal

4. MAPI_RunOnGrid

5. MAPI_Tails

6. MAPI_Plot2

Within this general framework, you may, for example:

• set your own value for 'halfwidth' (ignore step 2)

• use your own grid, or reuse one from another run (ignore steps 2 & 3)

• tweak some MAPI parameters (such as dMin or dMax for filtering on geographic distances between samples)

• discard poorly supported cells prior detecting significant areas of (dis)continuity (parameter minQ) and/or change significance level (parameter alpha in MAPI_Tails)

• build your MAPI maps with a GIS software (ignore step 6). See 'Export results' section below

Export results

Output tables (weighted mean of the pairwise metric within cell and polygons delineating significant areas of (dis)continuity) are spatial objects built using the package sf. Refer to sf documentation to export MAPI results in various format. Below is an example of how MAPI results can be exported as ESRI Shapefiles:

library(sf)
# Export results for our test dataset
st_write(my.results, dsn=".", layer="myFirstMapiResult", 
   driver="ESRI Shapefile", append=FALSE, delete_layer=TRUE)
st_write(my.tails, dsn=".", layer="myFirstMapiResultTails", 
   driver="ESRI Shapefile", append=FALSE, delete_layer=TRUE)

Alternatively, exporting layers in a geopackage is more convenient (only one file):

library(sf)
# Export results for our test dataset
st_write(my.results, dsn="myFirstMapi.gpkg", layer="Result", 
   driver="GPKG", append=FALSE, delete_layer=TRUE)
st_write(my.tails, dsn="myFirstMapi.gpkg", layer="Tails", 
   driver="GPKG", append=FALSE, delete_layer=TRUE)

You may now open these files myFirstMapiResult.shp and myFirstMapiResultTails.shp or myFirstMapi.gpkg in a GIS software such as QGis and customize the layout.

NOTE: recent versions of sf/gdal packages does not allow to export the 'permuts' column. As it was never used, MAPI >=1.0.4 releases does not returns anymore this column. If you still use older MAPI versions, you can remove this column before exporting using the following command:

my.results$permuts <- NULL

NOTE: If the area of significant zones is very large, the measure may not fit in Shapefiles fields. It is then possible to convert the area measure in km² by dividing the value by 1,000,000:

my.tails$area <- as.numeric(my.tails$area) / 1e6

Overlaying MAPI results with landscape layouts can help in analyzing the relationship between environmental features and spatial genetic patterns (eg. Piry & al., 2016; Piry & al., 2018).

References

Description of the MAPI method

Piry S., Chapuis M.-P., Gauffre B., Papaïx J., Cruaud A. and Berthier K. (2016). Mapping Averaged Pairwise Information (MAPI): a new exploratory tool to uncover spatial structure. Methods in Ecology and Evolution 7:(12), 1463–1475. tools:::Rd_expr_doi("10.1111/2041-210X.12616")

Applications of MAPI in Landscape Genetics

• Larson S., Gagne RB et al. 2021 Translocations maintain genetic diversity and increase connectivity in sea otters, Enhydra lutris Marine Mammal Science tools:::Rd_expr_doi("10.1111/mms.12841")

• Stragier C., Piry S., et al. 2020. Interplay between historical and current features of the cityscape in shaping the genetic structure of the house mouse (Mus musculus domesticus) in Dakar (Senegal, West Africa) bioRxiv ; Version 4 of this preprint has been peer-reviewed and is recommended by Peer Community In Ecology (DOI:10.24072/pci.ecology.100044) tools:::Rd_expr_doi("10.1101/557066")

• Piry S., Berthier K., Streiff R., Cros-Arteil S., Tatin L., Foucart A., Bröder L., Hochkirch A., and Chapuis M.-P. (2018). Fine-scale interactions between habitat quality and genetic variation suggest an impact of grazing on the critically endangered Crau Plain grasshopper (Pamphagidae: Prionotropis rhodanica). Journal of Orthoptera Research 27, 61–73. tools:::Rd_expr_doi("10.3897/jor.27.15036")

• Dellicour S, Prunier JG, Piry S, et al. (2019) Landscape genetic analyses of Cervus elaphus and Sus scrofa: comparative study and analytical developments. Heredity. tools:::Rd_expr_doi("10.1038/s41437-019-0183-5")