dspca {adiv}

Double similarity principal component analysis

Description

The function dspca performs the double similarity principal component analysis (DSPCA) (Pavoine 2019): an ordination approach to analyse functional or phylogenetic similarities between species communities. The function plot.dspca displays factorial maps of dspca.

Usage

dspca(comm, S=NULL, tol=1e-8)

## S3 method for class 'dspca'
plot(x, xaxis = 1, yaxis = 2, labels = TRUE,
    arrows = TRUE, points = FALSE, autolab = TRUE, title = NULL,
    colors = NULL, type = c("X&Y","X","Y"), zoom = TRUE, ...)

Arguments

comm

a data frame or a matrix typically with communities (or sites, plots, etc.) as rows, species as columns and presence/absence (1/0) or an index of abundance as entries.

S

a matrix of functional or phylogenetic similarities between species (species as rows and columns in the same order as in comm).

tol

a numeric tolerance threshold: a value between -tol and tol is considered as zero.

x

an object of class dspca.

xaxis

the number of the DSPCA axis chosen for the x-axis of the 3d plot.

yaxis

the number of the DSPCA axis chosen for the y-axis of the 3d plot.

labels

a logical specifying whether the names of the species and those of the communities must be displayed in the factorial maps.

arrows

a logical specifying whether arrows must be used to indicate the positions of the species and those of the communities.

points

a logical specifying whether points must be used to indicate the positions of the species and those of the communities.

autolab

a logical indicating if a function autoLab extracted from package FactoMineR version 2.6 must be used to display the labels. If there are more than 50 species or more than 50 communities, this option may be time-consuming. If autolab = FALSE, the names of species and those of the communities will be placed quickly but may overlap.

title

a string (if type="X" or type="Y") or a vector of strings (if type="X&Y") giving the title of each graph.

colors

a vector (if type="X" or type="Y") providing the color or the colors to be used for species names, points and arrows (if type="X"), or community names, points and arrows (if type="Y"), OR, if type="X&Y", a list of two vectors, the first one with the colors to be used for species names, points and arrows and the other one for community names, points and arrows.

type

a string that can be "X&Y","X","Y". If type="X", species scores are displayed. If type="Y", community scores are displayed. If "X&Y", both species and community scores are displayed.

zoom

a logical indicating if the graphs must zoom on the positions of the species and those of the communities (defaults to TRUE). If zoom=FALSE then species and communities are positioned in the full circle of unit radius.

...

further arguments passed to or from other methods. These must be common to functions plot, arrows, points, and autoLab or text.

Details

Coordinates can be visualized with graphic tools available in R. Examples are provided below (see section named "examples").

Value

dspca returns a list of the following objects:

eig

Final eigenvalues: positive eigenvalues of the matrix of similarities among communities.

X

final coordinates of the species (\mathbf{X}_{final}): matrix with the coordinates of the species on the principal components associated with the matrix of similarities among communities. The names of the matrix start with "CPC" indicating "communities' principal component".

Y

final coordinates of the communities (\mathbf{Y}_{final}): matrix with the coordinates of the communities on the principal components associated with the matrix of similarities among communities. The names of the matrix start with "CPC" indicating "communities' principal component".

Scom

matrix of similarities among communities (obtained with coefficient SOchiai (Pavoine and Ricotta 2014))

.

Author(s)

Sandrine Pavoine [e-mail]

References

Pavoine, S. (2019) An ordination approach to explore similarities among communities. Journal of Theoretical Biology, 462, 85–96.

Pavoine, S. and Ricotta, C. (2014) Functional and phylogenetic similarity among communities. Methods in Ecology and Evolution, 5, 666–675.

See Also

evoNSCA, evopcachord, evopcahellinger, dsimcom

Examples

## Not run: 
if(require(ade4)){

data(macroloire, package="ade4") 
# Analysis of the feeding habits of macroinvertebrates in the Loire river, France

# The matrix named feed below contains feeding attributes as rows,
# species as columns, and affinities (proportions) as entries.
feed <- macroloire$traits[, -(1:4)]

# Feeding habits comprise seven categories: engulfers, shredders, scrapers,
# deposit-feeders, active filter-feeders, passive filter-feeders and piercers, in this order.

# Functional similarities among species are computed as indicated in Pavoine and Ricotta (2014)
s_species_ochiai_feed <- dsimFun(feed, vartype = "P", method=4)

# To check that this matrix of trait-based similarities 
# among species is positive semidefinite (p.s.d.)
# we have to verify that its eigenvalues are all nonnegative:
all(eigen(s_species_ochiai_feed)$val>-(1e-8))

dspca_feed <- dspca(t(macroloire$fau), s_species_ochiai_feed)

# eigenvalue distribution:
barplot(dspca_feed$eig)
# The eigenvalues show strong similarities in the composition of the sites 
# regarding the feeding habits of the macroinvertebrates.

# In this data set, communities (sites) are named from S1 to S38 from upstream to downstream
rownames(t(macroloire$fau))

# species are coded from E1 to E40
colnames(t(macroloire$fau))

plot(dspca_feed,  autolab=TRUE, 
    colors= list(ifelse(feed[,6]>0.5,"red","black"), 
    hcl.colors(38, "cyan")))

# The graphical display shows that most sites are characterized by the dominance of a few species 
# (which are mostly passive filter-feeders, in red). 
# In a few sites mostly upstream (in blue), the diversity in feeding habits is higher. 
}

## End(Not run)