adespatial: Moran’s Eigenvector Maps and related methods for the spatial multiscale analysis of ecological communities

Stéphane Dray

2019-02-26

The package adespatial contains functions for the multiscale analysis of spatial multivariate data. It implements some new functions and reimplements existing functions that were available in packages of the sedaR project hosted on R-Forge (spacemakeR, packfor, AEM, etc.). It can be seen as a bridge between packages dealing with mutltivariate data (e.g., ade4, S. Dray and Dufour (2007)) and packages that deals with spatial data (sp, spdep). In adespatial, many methods consider the spatial information as a spatial weighting matrix (SWM), object of class listw provided by the spdep package (Figure 1). The SWM is defined as the Hadamard product (element‐wise product) of a connectivity matrix by a weighting matrix. The binary connectivity matrix (spatial neighborhood, object of class nb) defines the pairs of connected and unconnected samples, while the weighting matrix allows weighting the connections, for instance to define that the strength of the connection between two samples decreases with the geographic distance.

Once SWM is defined, it can be used to build Moran’s Eigenvector Maps (MEM, S. Dray, Legendre, and Peres-Neto (2006)) that are orthogonal vectors maximizing the spatial autocorrelation (measured by Moran’s index of autocorrelation). These spatial predictors can be used in multivariate statistical methods to provide spatially-explicit multiscale tools (S. Dray et al. 2012). This document provides a description of the main functionalities of the package.


Figure 1: Schematic representation of the functioning of the adespatial package. Classes are represented in pink frames and functions in blue frames. Classes and functions provided by adespatial are in bold.


To run the different analysis described, several packages are required and are loaded:

library(adespatial)
library(ade4)
## 
## Attaching package: 'ade4'
## The following object is masked from 'package:adespatial':
## 
##     multispati
library(adegraphics)
## 
## Attaching package: 'adegraphics'
## The following objects are masked from 'package:ade4':
## 
##     kplotsepan.coa, s.arrow, s.class, s.corcircle, s.distri,
##     s.image, s.label, s.logo, s.match, s.traject, s.value,
##     table.value, triangle.class
library(spdep)
## Loading required package: sp
## Loading required package: Matrix
## Loading required package: spData
## To access larger datasets in this package, install the spDataLarge
## package with: `install.packages('spDataLarge',
## repos='https://nowosad.github.io/drat/', type='source')`
## Loading required package: sf
## Linking to GEOS 3.6.2, GDAL 2.2.3, PROJ 4.9.3
## 
## Attaching package: 'spdep'
## The following object is masked from 'package:ade4':
## 
##     mstree
library(maptools)
## Checking rgeos availability: TRUE

1 Building spatial neighborhood

Spatial neighborhoods are managed in spdep as objects of class nb. It corresponds to the notion of connectivity matrices discussed in S. Dray, Legendre, and Peres-Neto (2006) and can be represented by an unweighted graph. Various functions are devoted to create nb objects from geographic coordinates of sites. We present different alternatives according to the design of the sampling scheme.

1.1 Surface data

The function poly2nb allows to define neighborhood when the sampling sites are polygons and not points (two regions are neighbors if they share a common boundary). The resulting object can be plotted on a geographical map using the s.Spatial function of the adegraphics package (Siberchicot et al. 2017).

data(mafragh)
class(mafragh$Spatial)
## [1] "SpatialPolygons"
## attr(,"package")
## [1] "sp"
nb.maf <- poly2nb(mafragh$Spatial)
s.Spatial(mafragh$Spatial, nb = nb.maf, plabel.cex = 0, pnb.edge.col = 'red')

1.2 Regular grid and transect

If the sampling scheme is based on regular sampling (e.g., grid of 10 rows and 8 columns), spatial coordinates can be easily generated:

xygrid <- expand.grid(x = 1:10, y = 1:8)
s.label(xygrid, plabel.cex = 0)

For a regular grid, spatial neighborhood can be created with the function cell2nb. Two types of neighborhood can be defined. The queen specification considered horizontal, vertical and diagonal edges whereas the rook specification considered only horizontal and vertical edges:

nb2.q <- cell2nb(10, 8, type = "queen")
nb2.r <- cell2nb(10, 8, type = "rook")
s.label(xygrid, nb = nb2.q, plabel.cex = 0, main = "Queen neighborhood")

s.label(xygrid, nb = nb2.r, plabel.cex = 0, main = "Rook neighborhood")

The function cell2nb is the easiest way to deal with transects by considering a grid with only one row:

xytransect <- expand.grid(1:20, 1)
nb3 <- cell2nb(20, 1)

summary(nb3)
## Neighbour list object:
## Number of regions: 20 
## Number of nonzero links: 38 
## Percentage nonzero weights: 9.5 
## Average number of links: 1.9 
## Link number distribution:
## 
##  1  2 
##  2 18 
## 2 least connected regions:
## 1:1 1:20 with 1 link
## 18 most connected regions:
## 1:2 1:3 1:4 1:5 1:6 1:7 1:8 1:9 1:10 1:11 1:12 1:13 1:14 1:15 1:16 1:17 1:18 1:19 with 2 links

All sites have two neighbors except the first and the last one.

1.3 Irregular sampling

There are many ways to define neighborhood in the case of irregular samplings. We consider a random sampling with 20 sites:

set.seed(3)
xyir <- matrix(runif(40), 20, 2)
s.label(xyir, main = "Irregular sampling with 10 sites")

The most intuitive way is to consider that sites are neighbors (or not) according to the distances between them. This definition is provided by the dnearneigh function:

nbnear1 <- dnearneigh(xyir, 0, 0.2)
nbnear2 <- dnearneigh(xyir, 0, 1.5)

g1 <- s.label(xyir, nb = nbnear1, pnb.edge.col = "red", main = "neighbors if 0<d<0.2", plot = FALSE)
g2 <- s.label(xyir, nb = nbnear2, pnb.edge.col = "red", main = "neighbors if 0<d<1.5", plot = FALSE)
cbindADEg(g1, g2, plot = TRUE)

Using a distance-based criteria could lead to unbalanced graphs. For instance, if the maximum distance is too low, some points have no neighbors:

nbnear1
## Neighbour list object:
## Number of regions: 20 
## Number of nonzero links: 40 
## Percentage nonzero weights: 10 
## Average number of links: 2 
## 3 regions with no links:
## 2 7 19

On the other hand, if the maximum distance is to high, all sites could connected to the 9 others:

nbnear2
## Neighbour list object:
## Number of regions: 20 
## Number of nonzero links: 380 
## Percentage nonzero weights: 95 
## Average number of links: 19

It is also possible to possible to define neighborhood by a criteria based on nearest neighbors. However, this option can lead to non-symmetric neighborhood: if site A is the nearest neighbor of site B, it does not mean that site B is the nearest neighbor of site A.

The function knearneigh creates an object of class knn. It can be transformed into a nb object with the function knn2nb. This function has an argument sym which can be set to TRUE to force the output neighborhood to symmetry.

knn1 <- knearneigh(xyir, k = 1)
nbknn1 <- knn2nb(knn1, sym = TRUE)
knn2 <- knearneigh(xyir, k = 2)
nbknn2 <- knn2nb(knn2, sym = TRUE)

g1 <- s.label(xyir, nb = nbknn1, pnb.edge.col = "red", main = "Nearest neighbors (k=1)", plot = FALSE)
g2 <- s.label(xyir, nb = nbknn2, pnb.edge.col = "red", main = "Nearest neighbors (k=2)", plot = FALSE)
cbindADEg(g1, g2, plot = TRUE)

This definition of neighborhood can lead to unconnected subgraphs. The function n.comp.nb finds the number of disjoint connected subgraphs:

n.comp.nb(nbknn1)
## $nc
## [1] 7
## 
## $comp.id
##  [1] 1 2 3 3 2 4 5 5 6 4 6 6 2 6 7 7 5 2 7 1

More elaborate procedures are available to define neighborhood. For instance, Delaunay triangulation is obtained with the function tri2nb. It requires the package deldir. Other graph-based procedures are also available:

nbtri <- tri2nb(xyir)
## 
##      PLEASE NOTE:  The components "delsgs" and "summary" of the
##  object returned by deldir() are now DATA FRAMES rather than
##  matrices (as they were prior to release 0.0-18).
##  See help("deldir").
##  
##      PLEASE NOTE: The process that deldir() uses for determining
##  duplicated points has changed from that used in version
##  0.0-9 of this package (and previously). See help("deldir").
nbgab <- graph2nb(gabrielneigh(xyir), sym = TRUE)
nbrel <- graph2nb(relativeneigh(xyir), sym = TRUE)
nbsoi <- graph2nb(soi.graph(nbtri, xyir), sym = TRUE)

g1 <- s.label(xyir, nb = nbtri, pnb.edge.col = "red", main = "Delaunay", plot = FALSE)
g2 <- s.label(xyir, nb = nbgab, pnb.edge.col = "red", main = "Gabriel", plot = FALSE)
g3 <- s.label(xyir, nb = nbrel, pnb.edge.col = "red", main = "Relative", plot = FALSE)
g4 <- s.label(xyir, nb = nbsoi, pnb.edge.col = "red", main = "Sphere of influence", plot = FALSE)

ADEgS(list(g1, g2, g3, g4))

The adespatial functions chooseCN and listw.candidates provides simple ways to build spatial neighborhoods. They are wrappers of many of the spdep functions presented above. The function listw.explore discussed in section XX is an interactive graphical interface that allows to generate R code to build neighborhood objects.

1.4 Manipulation of nb objects

A nb object is not stored as a matrix. It is a list of neighbors. The neighbors of the first site are in the first element of the list:

nbgab[[1]]
## [1]  7 20

Various tools are provided by spdep to deal with these objects. For instance, it is possible to identify differences between two neighborhoods:

diffnb(nbsoi, nbrel)
## Neighbour list object:
## Number of regions: 20 
## Number of nonzero links: 24 
## Percentage nonzero weights: 6 
## Average number of links: 1.2 
## 4 regions with no links:
## 1 4 11 17

Usually, it can be useful to remove some connections due to edge effects. In this case, the function edit.nb provides an interactive tool to add or delete connections.

The function include.self allows to include a site in its own list of neighbors (self-loops). The spdep package provides many other tools to manipulate nb objects:

intersect.nb(nb.obj1, nb.obj2)
union.nb(nb.obj1, nb.obj2)
setdiff.nb(nb.obj1, nb.obj2)
complement.nb(nb.obj)
droplinks(nb, drop, sym = TRUE)
nblag(neighbours, maxlag)

2 Defining spatial weighting matrices

A spatial weighting matrices (SWM) is computed by a transformation of a spatial neighborhood. In R, they are not stored as matrices but as objects of the class listw. This format is more efficient than a matrix representation to manage large data sets. An object of class listw can be easily created from an object of class nb with the function nb2listw.

Different objects listw can be obtained from a nb object. The argument style allows to define a transformation of the matrix such as standardization by row sum, by total sum or binary coding, etc. General spatial weights can be introduced by the argument glist. This allows to introduce, for instance, a weighting relative to the distances between the points. For this task, the function nbdists is very useful as it computes Euclidean distance between neighbor sites defined by an nb object.

To obtain a simple row-standardization, the function is simply called by:

nb2listw(nbgab)
## Characteristics of weights list object:
## Neighbour list object:
## Number of regions: 20 
## Number of nonzero links: 58 
## Percentage nonzero weights: 14.5 
## Average number of links: 2.9 
## 
## Weights style: W 
## Weights constants summary:
##    n  nn S0       S1       S2
## W 20 400 20 14.38889 82.06944

More sophisticated forms of spatial weighting matrices can be defined. For instance, it is possible to weight edges between neighbors as functions of geographic distances. In a fist step, distances between neighbors are obtained by the function :

distgab <- nbdists(nbgab, xyir)
nbgab[[1]]
## [1]  7 20
distgab[[1]]
## [1] 0.3740569 0.1135694

Then, spatial weights are defined as a function of distance (e.g. \(1-d_{ij}/max(d_{ij})\)):

fdist <- lapply(distgab, function(x) 1 - x/max(dist(xyir)))

And the spatial weighting matrix is then created:

listwgab <- nb2listw(nbgab, glist = fdist, style = "B")
listwgab
## Characteristics of weights list object:
## Neighbour list object:
## Number of regions: 20 
## Number of nonzero links: 58 
## Percentage nonzero weights: 14.5 
## Average number of links: 2.9 
## 
## Weights style: B 
## Weights constants summary:
##    n  nn       S0       S1       S2
## B 20 400 47.49881 79.02568 484.6624
names(listwgab)
## [1] "style"      "neighbours" "weights"
listwgab$neighbours[[1]]
## [1]  7 20
listwgab$weights[[1]]
## [1] 0.6652764 0.8983728

The matrix representation of a listw object can also be obtained:

print(listw2mat(listwgab)[1:10, 1:10], digits = 3)
##     [,1] [,2] [,3] [,4] [,5]  [,6]  [,7]  [,8]  [,9] [,10]
## 1  0.000    0 0.00 0.00    0 0.000 0.665 0.000 0.000 0.000
## 2  0.000    0 0.00 0.00    0 0.000 0.000 0.000 0.000 0.000
## 3  0.000    0 0.00 0.94    0 0.000 0.000 0.000 0.000 0.000
## 4  0.000    0 0.94 0.00    0 0.000 0.000 0.000 0.000 0.000
## 5  0.000    0 0.00 0.00    0 0.000 0.000 0.000 0.000 0.000
## 6  0.000    0 0.00 0.00    0 0.000 0.000 0.703 0.000 0.960
## 7  0.665    0 0.00 0.00    0 0.000 0.000 0.000 0.593 0.000
## 8  0.000    0 0.00 0.00    0 0.703 0.000 0.000 0.000 0.000
## 9  0.000    0 0.00 0.00    0 0.000 0.593 0.000 0.000 0.819
## 10 0.000    0 0.00 0.00    0 0.960 0.000 0.000 0.819 0.000

To facilitate the building of spatial neighborhoods (nb object) and associated spatial weighting matrices (listw object), the package adespatial provides several tools. An interactive graphical interface is launched by the call listw.explore() assuming that spatial coordinates are still stored in an object of the R session (Figure 2).


Figure 2: The interactive interface provided by the function listw.explore.


3 Creating spatial predictors

The package adespatial provide different tools to build spatial predictors that can be incorporated in multivariate analysis. They are orthogonal vectors stored in a object of class orthobasisSp. Orthogonal polynomials of geographic coordinates can be computed by the function orthobasis.poly whereas traditional principal coordinates of neighbour matrices (PCNM, Borcard and Legendre (2002)) are obtained by the function dbmem. The more flexible Moran’s Eigenvectors Maps (MEMs) of a spatial weighting matrix are computed by the functions scores.listw or mem of the adespatial package. These two functions are exactly identical and return an object of class orthobasisSp.

mem.gab <- mem(listwgab)
mem.gab
## Orthobasis with 20 rows and 19 columns
## Only 6 rows and 4 columns are shown
##          MEM1        MEM2        MEM3       MEM4
## 1 -0.90672748 -0.06565448 -0.04776682 -0.2371804
## 2  1.00027097  1.13232055  0.44830373 -0.4506747
## 3 -1.60466714  0.77623659  1.18177121  1.0279127
## 4 -1.43085124  0.54646370  1.10065325  1.0434462
## 5 -0.03992758  1.16673599 -0.92313755 -0.7243739
## 6  0.15116014 -1.13831331  1.18996867 -0.9394357

This object contains MEMs, stored as a data.frame and other attributes:

str(mem.gab)
## Classes 'orthobasisSp', 'orthobasis' and 'data.frame':   20 obs. of  19 variables:
##  $ MEM1 : num  -0.9067 1.0003 -1.6047 -1.4309 -0.0399 ...
##  $ MEM2 : num  -0.0657 1.1323 0.7762 0.5465 1.1667 ...
##  $ MEM3 : num  -0.0478 0.4483 1.1818 1.1007 -0.9231 ...
##  $ MEM4 : num  -0.237 -0.451 1.028 1.043 -0.724 ...
##  $ MEM5 : num  -1.61 -0.597 0.434 -0.479 2.175 ...
##  $ MEM6 : num  1.48899 0.00604 -0.58245 -0.80351 1.09241 ...
##  $ MEM7 : num  0.6065 0.7788 -1.0025 -0.0579 -0.0817 ...
##  $ MEM8 : num  -0.329 2.48 0.499 0.188 -0.563 ...
##  $ MEM9 : num  2.687 -0.631 -0.268 -1.389 0.127 ...
##  $ MEM10: num  -0.254 -0.824 -0.854 1.464 1.617 ...
##  $ MEM11: num  -0.991 -1.722 0.604 0.664 -0.344 ...
##  $ MEM12: num  -0.864 -0.203 0.171 -1.297 -0.142 ...
##  $ MEM13: num  0.0305 -1.0147 0.0403 -1.0781 0.1025 ...
##  $ MEM14: num  -0.944 0.95 1.627 -2.137 -0.691 ...
##  $ MEM15: num  0.403 -1.46 1.732 -0.836 -0.67 ...
##  $ MEM16: num  -0.101 -0.598 0.366 -0.497 0.655 ...
##  $ MEM17: num  -0.863 -0.334 -2.095 0.396 -1.697 ...
##  $ MEM18: num  -1.215 -0.418 -0.465 -0.397 0.311 ...
##  $ MEM19: num  -0.727 0.637 0.021 -0.502 1.703 ...
##  - attr(*, "values")= num  0.1133 0.1005 0.0723 0.0671 0.0551 ...
##  - attr(*, "weights")= num  0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 ...
##  - attr(*, "call")= language mem(listw = listwgab)

The eigenvalues associated to MEMs are stored in the attribute called values:

    barplot(attr(mem.gab, "values"), 
        main = "Eigenvalues of the spatial weighting matrix", cex.main = 0.7)

A plot method is provided to represent MEMs. By default, eigenvectors are represented as a table (sites as rows, MEMs as columns):

plot(mem.gab)

The previous representation is not really informative and MEMs can be represented in the geographical space as maps if the argument SpORcoords is documented:

plot(mem.gab, SpORcoords = xyir, nb = nbgab)

Moran’s I can be computed and tested for each eigenvector with the moran.randtest function:

moranI <- moran.randtest(mem.gab, listwgab, 99)
moranI
## class: krandtest lightkrandtest 
## Monte-Carlo tests
## Call: moran.randtest(x = mem.gab, listw = listwgab, nrepet = 99)
## 
## Number of tests:   19 
## 
## Adjustment method for multiple comparisons:   none 
## Permutation number:   99 
##     Test           Obs    Std.Obs   Alter Pvalue
## 1   MEM1  9.545478e-01  5.4108146 greater   0.01
## 2   MEM2  8.463497e-01  5.6654531 greater   0.01
## 3   MEM3  6.087820e-01  3.6902332 greater   0.01
## 4   MEM4  5.651718e-01  3.4503635 greater   0.01
## 5   MEM5  4.642564e-01  3.4428901 greater   0.01
## 6   MEM6  3.114056e-01  2.3805633 greater   0.03
## 7   MEM7  2.503420e-01  1.6708987 greater   0.08
## 8   MEM8  6.873937e-02  0.5738166 greater   0.25
## 9   MEM9  1.108535e-05  0.2289309 greater   0.40
## 10 MEM10 -1.388302e-01 -0.4663896 greater   0.69
## 11 MEM11 -1.923089e-01 -0.8612371 greater   0.81
## 12 MEM12 -3.357687e-01 -1.6790234 greater   0.97
## 13 MEM13 -4.001950e-01 -2.0684406 greater   0.98
## 14 MEM14 -4.445105e-01 -2.4745258 greater   1.00
## 15 MEM15 -4.873813e-01 -2.4327556 greater   0.99
## 16 MEM16 -6.563053e-01 -3.9997778 greater   1.00
## 17 MEM17 -6.947406e-01 -3.9824080 greater   1.00
## 18 MEM18 -8.170207e-01 -4.7431342 greater   1.00
## 19 MEM19 -9.025446e-01 -4.7662544 greater   1.00

By default, the function moran.randtest tests against the alternative hypothesis of positive autocorrelation (alter = "greater") but this can be modified by setting the argument alter to "less" or "two-sided". The function is not only devoted to MEMs and can be used to compute spatial autocorrelations for all kind of variables.

As demonstrated in S. Dray, Legendre, and Peres-Neto (2006), eigenvalues and Moran’s I are equal (post-multiply by a constant):

attr(mem.gab, "values") / moranI$obs
##  MEM1.statistic  MEM2.statistic  MEM3.statistic  MEM4.statistic 
##        0.118747        0.118747        0.118747        0.118747 
##  MEM5.statistic  MEM6.statistic  MEM7.statistic  MEM8.statistic 
##        0.118747        0.118747        0.118747        0.118747 
##  MEM9.statistic MEM10.statistic MEM11.statistic MEM12.statistic 
##        0.118747        0.118747        0.118747        0.118747 
## MEM13.statistic MEM14.statistic MEM15.statistic MEM16.statistic 
##        0.118747        0.118747        0.118747        0.118747 
## MEM17.statistic MEM18.statistic MEM19.statistic 
##        0.118747        0.118747        0.118747

Then, it is possible to map only positive significant eigenvectors (i.e., MEMs with significant positive spatial autocorrelation):

signi <- which(moranI$pvalue < 0.05)
signi
## [1] 1 2 3 4 5 6
plot(mem.gab[,signi], SpORcoords = xyir, nb = nbgab)

References

Borcard, D, and P Legendre. 2002. “All-scale spatial analysis of ecological data by means of principal coordinates of neighbour matrices.” Ecological Modelling 153: 51–68.

Dray, S, and A B Dufour. 2007. “The ade4 package: implementing the duality diagram for ecologists.” Journal of Statistical Software 22 (4): 1–20.

Dray, S, P Legendre, and P R Peres-Neto. 2006. “Spatial modeling: a comprehensive framework for principal coordinate analysis of neighbor matrices (PCNM).” Ecological Modelling 196: 483–93.

Dray, S, R Pélissier, P Couteron, M J Fortin, P Legendre, P R Peres-Neto, E Bellier, et al. 2012. “Community ecology in the age of multivariate multiscale spatial analysis.” Ecological Monographs 82 (3): 257–75.

Siberchicot, A., A. Julien-Laferrière, A.-B. Dufour, J. Thioulouse, and S. Dray. 2017. “adegraphics: An S4 lattice-based package for the representation of multivariate data.” R Journal 9 (2).