In polak51/WitOMI: Within Outlying Mean Indexes: Refining the OMI Analysis

subniche is an open-source R (R Core Team, 2017) package that implements functions useful for the calculation of the Within Outlying Mean Indexes (WitOMI) and their respective statistical tests [@karasiewicz2017; @subniche2017]. It consists of complementary calculations to the Outlying Mean Index analysis (OMI) [@Doledec2000]. OMI analysis can be implemented with the niche function from the ade4 package [@dray2007]. WitOMI analysis enables to explore niche shift in a community and environmental constraints within an Euclidean space, with graphical displays. The method allows to divide the realized niche, estimated from the niche function into subniches defined by a factor (time, space), which creates the subsets of habitat conditions.

How to get started

Install and load the R package from CRAN using the following commands on the R console:

install.packages("subniche")
library(subniche)

## Loading required package: ade4

` To install the most recent version from GitHub:

install.packages("devtools")
devtools::install_github("KarasiewiczStephane/WitOMI")
library(subniche)
install.packages("knitr")
library(knitr)

Generate the data required to run this example

Get the data set “drome” from the subniche package [@karasiewicz2017]. This data set includes, fish species occurence along with environmental variables.

data(drome)

Performing the OMI analysis

The first step consists of performing a PCA on the environmental table.

dudi1 <- dudi.pca(drome$env[,-1], scale = TRUE, scan = FALSE, nf = 3)
scatter(dudi1)

The graph display the correlation between the different environmental variables. Next the OMI analysis uses the standardized environmental table from the PCA in combination with the faunistic data to performed the OMI analysis. The standardized environmental table can be extracted from the dudi1 with $tab as follow:

kable(dudi1$tab)

The next step is to perform the OMI analysis from @Doledec2000 by implementing the function niche from the ade4 package [@dray2007].

nic1 <- niche(dudi1, drome$fish, scann = FALSE)
nic1

plot(nic1)

The graph display the results of the OMI analysis within a two-dimensional Euclidean space. Its display the species niche position (labels in Samples and Species, top-right) and breadth (ellipses in Niches, bottom-right graph), within the environmental gradients (summarized by Variables). The species niche parameter (Inertia, OMI, Tol and Rtol) are calculated with the niche.parameter function from the ade4 package [@dray2007]. More details on the niche parameters calculation in @Doledec2000.

kable(niche.param(nic1))

The test for statistical significance can now be implemented, which correspond to the comparison between the observe species' marginality and the simulated values, hereafter 100 random permutations, under the null hypothesis that the species is indifferent to its environment [@Doledec2000].

rtest(nic1,100)

Subsets creation

Herein, for the sake of the example, we will create two subsets. A factor needs to be made, in order to divide the data in two subsets. We used the functions cutree and hclust to create a cluster, k=2, following the ward.D method. The function create the subsets based on a dissimilarity matrix created by dist, with the SUs of nic1. It divided the sampling domain into two subset along the first OMI axis. Blue corresponds to downstream habitat conditions, and the red to the upstream conditions.

# Creation of the factor
fact <- as.factor(as.numeric(cutree(hclust(dist(nic1$ls, "euclidean"), "ward.D"),k=2)))
# plotting the two subsets
s.class(nic1$ls, fact, col=c("red", "blue"),cellipse=0, cpoint=2, pch=3)
s.chull(nic1$ls, fact, col=c("red", "blue"),optchull = 1, add.plot = T)
#According to the previous graph,(Variable in plot(nic1)), group 1 and 2 corresponds to upstream and downstream conditions respectively.
levels(fact)<- c("up", "down")

Now that we have the factor for dividing the niche, the subniche function can be implemented as follow:

subnic1 <- subniche(nic1, fact)
subnic1

The subniche function only adds itemsto the niche list, which are $factor, $G_k and $sub. The function does not change the previous results obtained with the OMI analysis from the niche function. The following functions, plot, refparam and rtest, are used to display the same results as in the ade4 package:

plot(subnic1)

The niche parameters from the OMI analysis can still be extracted with its respective significant test with refparam. The test for significance can also be applied, with rtest function.

kable(refparam(subnic1))

rtest(subnic1)

Calculation of the WitOMI (Spatial example)

The result of the test on marginality from the OMI analysis are important for the relevance of the WitOMI calculation. The following functions will still calculate the WitOMI even if the OMI are not significant. For the WitOMI to be use for interpretation, the OMI should first be significant. Then, the probability for the WitOMI to be significant within the subset G~K~ correspond to the $witomigtest$SubniPvalue wihtin the rtestrefor function for WitOMIG. And the equivalent for the WitOMIG~K~ is $witomig_ktest$SubniPvalue in the rtestsubor.

margvectdisplays the marginality vector of the suborigins,G~K~ ,within the overall available habitat conditions (black polygon), the available resource under each subset habitat condition (red polygons), and the species subniche (species label).

margvect(subnic1)

subplot displays the subset's constraint of habitat conditions (red polygons), found within the overall available habitat condition (black polygons), and the corresponding species subniche positions. The arrows representing the marginality vectors from the sub-orgins G~K~ (red dots), corresponds to the graphical representation of the WitOMIG~K~.

subplot(subnic1)

subparam.refor calculates the species marginality (WitOMIG), tolerance (Tol) and residual tolerance (Rtol) to the average habitat condition (G). For details on the parameters calculation see @karasiewicz2017.

kable(subparam.refor(subnic1))

rtestrefor calculates the subniches' parameters from G with the respective significant test. The output of the rtestrefor function is an object of class list, which includes the results of the WitOMIG significant test, under each subset defined by the $factor.

refor <- rtestrefor(subnic1,100)

First,for each of the two subsets, the subset statictical significance is tested with the following null hypothesis that G~K~ is not different from the overall average habitat conditions, represented by G. The subsets P value is equal to the product of equiprobabilities to find the same mean value for each variables [@karasiewicz2017].

refor[[1]]$Subsettest

refor[[2]]$Subsettest

Second the species marginality is tested for statistical significance following the null hypothesis that the species within each of the subsets is uninfluenced by its overall average habitat conditions (ubiquitous), for WitOMIG [@karasiewicz2017].

refor[[1]]$witomigtest

refor[[2]]$witomigtest

subparam.subor calculates the species marginality (WitOMIG~K~), tolerance (Tol) and residual tolerance (Rtol) to the subset average habitat condition (G~K~). For details on the parameters calculation see @karasiewicz2017.

kable(subparam.subor(subnic1))

In a similar fashion, rtestsubor calculates the subniches' parameters from G~K~ with the respective significance test. The output of the rtestsubor function is an object of class list, which includes the results of the WitOMIG~K~ significance test, under each of the two subsets defined by the $factor.

subor <- rtestsubor(subnic1,100)

As previously, the subsets are tested.

subor[[1]]$Subsettest

subor[[2]]$Subsettest

Second the species marginality is tested for significance following the null hypothesis that the species within a subset is uninfluenced by its subset average habitat conditions (ubiquitous), for WitOMIG~K~ [@karasiewicz2017].

subor[[1]]$witomig_ktest

subor[[2]]$witomig_ktest

Exercise (temporal example)

Now, try to the same work but the data ardecheinv. Herein, the invertebrates' abundances need to be log(x+1) transform prior the analysis, and the first column of the $env data are the seasons use to divide the dataset. Therefore, the creation of the required factor is done by the following line:

fact <- factor(archecheinv$env[,1])

Replace spring and autumn by numbers for the subniche function to work correctly. After OMI analysis, and WitOMI calculations, you should find the following:

data(ardecheinv)
dudi1 <- dudi.pca(ardecheinv$env[,-1], scale = TRUE, scan = FALSE, nf = 3)
scatter(dudi1)
nic1 <- niche(dudi1, log(ardecheinv$Invertebrates+1), scann = FALSE)
plot(nic1)
fact <- factor(ardecheinv$env[,1])
s.class(nic1$ls, fact, col=c("red", "blue"),cellipse=0, cpoint=2, pch=3)
s.chull(nic1$ls, fact, col=c("red", "blue"),optchull = 1, add.plot = T)
subnic1 <- subniche(nic1, fact)
plot(subnic1)
margvect(subnic1)
subplot(subnic1)

kable(refparam(subnic1))
rtest(subnic1,100)

kable(subparam.refor(subnic1))
rtestrefor(subnic1,100)

kable(subparam.subor(subnic1))
rtestsubor(subnic1,100)