## Multi-Scale Pattern Analysis

### Description

The multi-scale pattern analysis (MSPA, Jombart et al 2009) investigates the main scales of spatial variation in a multivariate dataset. This implementation allows one to perform a MSPA using any multivariate analysis (stored as a `dudi` object), and a list of spatial weights (class `listw`) or an object of class `orthobasisSp`.

### Usage

```mspa(
dudi,
lwORorthobasisSp,
nblocks,
scannf = TRUE,
nf = 2,
centring = c("param", "sim"),
nperm = 999
)

## S3 method for class 'mspa'
scatter(
x,
xax = 1,
yax = 2,
posieig = "topleft",
bary = TRUE,
plot = TRUE,
storeData = TRUE,
pos = -1,
...
)

## S3 method for class 'mspa'
print(x, ...)
```

### Arguments

 `dudi` a duality diagram (i.e. a reduced space ordination) obtained by a `dudi` function (for instance `dudi.pca`). `lwORorthobasisSp` either a list of weights (class `listw`) that san be obtained easily using the function `chooseCN` or an object of class `orthobasisSp` `nblocks` an integer indicating the number of blocks to divide MEMs. `scannf` logical, indicating whether the screeplot should be displayed to choose the number or retained factors. `nf` the number of retained factors `centring` a character string indicating if parametric ("param") or non-parametric ("sim") centring should be used `nperm` an integer giving the number of permutations used to compute the theoretical coefficients of determination (999 by default); used if centring="sim". `x` a mspa object. `xax` an integer indicating the x axis to be displayed. `yax` an integer indicating the y axis to be displayed. `posieig` a character indicating the position of the screeplot (any of the four combination between "top", "bottom", "left" and "right"). `bary` a logical indicating whether the barycenter of the variables should be displayed. `plot` a logical indicating if the graphics is displayed `storeData` a logical indicating if the data should be stored in the returned object. If `FALSE`, only the names of the data arguments are stored `pos` an integer indicating the position of the environment where the data are stored, relative to the environment where the function is called. Useful only if `storeData` is `FALSE` `...` additional graphical parameters (see `adegpar` and `trellis.par.get`)

### Details

The `scatter` method is used for plotting the results. Compared to the original version of the method, this new implementation allows to specify a number of blocks (`nblocks`). In this case, the multiscale decomposition is performed by dividing MEMs into several blocks and summing R2 values. This could facilitate the interpretation of results.

### Value

An object having the classes `mspa` and `dudi`: `mspa` objects are `dudi` objects with the following extra slots:
- ls: principal components of the MSPA. These are the coordinates of variables onto principal axes, to be used for plotting. Correspond to matrix B in Appendix A of Jombart et al (2009).
- R2: matrix of R2 between variables and MEMs. Corresponds to S in Jombart et al (2009).
- meanPoint: coordinates of the 'mean variable' onto principal axes. The 'mean variable' is an hypothetic variable whose scale profile is the average of those of all variables of the analysed dataset.
- varweights: the weights of variables. Corresponds to d in Jombart et al. (2009).

### Author(s)

Thibaut Jombart t.jombart@imperial.ac.uk

### References

Jombart T, Dray S, and Dufour, A-B. (2009) Finding essential scales of spatial variation in ecological data: a multivariate approach. Ecography 32: 161-168.

`chooseCN` to obtain a list of spatial weights.

### Examples

```

####################################
### using oribatib mites dataset ###
####################################

data(oribatid)

## get the list of spatial weights
cn <- chooseCN(oribatid\$xy, res = "listw", ask = FALSE, type = 1)

## Hellinger transformation
hellTrans <- function(X){
if (!( is.matrix(X) | is.data.frame(X) )) stop("Object is not a matrix.")
if (any(is.na(X))) stop("na entries in table.")

sumRow <- apply(X,1,sum)
Y <- X/sumRow
Y <- sqrt(Y)

return(Y)
}

## ENVIRONMENTAL VARIABLES ##
## Hill and Smith analysis for environmental variables
## (for a mixture of quantitative / qualitative variables)
hsEnv <- dudi.hillsmith(oribatid\$envir,scannf=FALSE)

## detrending of the analysis (residuals of regression onto xy coordinates)
hsEnv.detr <- pcaivortho(hsEnv,oribatid\$xy,scannf=FALSE)

## MSPA of the detrended analysis
mspaEnv <- mspa(hsEnv.detr,cn,scannf=FALSE,nf=2)
scatter(mspaEnv)

## SPECIES DATA ##
## PCA of species abundances, after Hellinger transformation
pcaFau <- dudi.pca(hellTrans(oribatid\$fau),scale=FALSE,scannf=FALSE)

## detrending of this PCA
pcaFau.detr <- pcaivortho(pcaFau,oribatid\$xy,scannf=FALSE)

# MSPA of the detrended analysis
mspaFau <- mspa(pcaFau.detr,cn,scannf=FALSE,nf=2)
scatter(mspaFau)

## CANONICAL MSPA ##
## RDA species ~ envir
## (species abundances predicted by environment)
## note: RDA = 'PCAIV' (PCA with Instrumental Variables)
rda1 <- pcaiv(dudi=pcaFau.detr, df=oribatid\$envir,scannf=FALSE,nf=2)

## canonical MSPA (species predicted by environment)
mspaCan1 <- mspa(dudi=rda1, lw=cn, scannf=FALSE, nf=2)
scatter(mspaCan1)

## same analysis, using a non-parametric centring
mspaCan1NP <- mspa(dudi=rda1, lw=cn, scannf=FALSE, nf=2,cent="sim",nper=999)
scatter(mspaCan1NP) # basically no change

## PARTIAL CANONICAL MSPA ##
## partial RDA species ~ envir
## (species abundances not predicted by environment)
rda2 <- pcaivortho(dudi=pcaFau.detr,df=oribatid\$envir,scannf=FALSE,nf=2)

## partial canonical MSPA
mspaCan2 <- mspa(dudi=rda2, lw=cn, scannf=FALSE, nf=2)
scatter(mspaCan2) # nothing left
}
```