Backwards compatibility of adonis2() with adonis()...?

[gavinsimpson]

Although not documented, adonis() can be used to perform univariate permutational ANOVA:

library("vegan")
data(dune, dune.env)
tmp <- cbind.data.frame(Poatriv = dune$Poatriv, dune.env)
adonis(Poatriv ~ Management * A1, data = tmp, permutations = 99, method = "euclidean")

but this fails with adonis2()

> adonis2(Poatriv ~ Management * A1, data = tmp, permutations = 99, method = "euclidean")
Error in eval(expr, envir, enclos) : object 'Poatriv' not found

partly because adonis0() doesn't expect this kind of set-up and evaluates the lhs of the formula in the global environment, and not data. (as an aside, if we eval() the lhs in the global environment, then isn't the envir argument me specify in adonis0() not needed?)

Now, that the above works at all in adonis() is because vegdist() doesn't need to do any matrix operations on the lhs because we explicitly set method = "euclidean" - the adonis() call fails with the default method = "bray" for example.

Questions:

1. Do we want to retain this backwards compatibility for an undocumented "feature"?

   I can see a case for keeping it for method = "euclidean" only, for pedagogic reasons - it's nice to be able to show how the PERMANOVA relates to ANOVA in the univariate case.

   Assuming answer to Q1 is Yes, then we need to catch problems before they get anywhere near vegdist() and throw an error if the lhs is not a matrix/data frame and method != "euclidean" (or the alternate spelling of that dissimilarity).

2. If we don't want this, we need to catch univariate responses and issue a suitable error as soon as possible.

Thoughts?

[jarioksa]

The deeply nested design brings along scoping issues (for instance, see 7ff1443). I rather like to see them solved. Got to see if it is possible for this issue with this design.

[jarioksa]

At closer look, this is not only undocumented, but it is against documentation. Moreover, dbrda, capscale and rda all can handle univariate response, but not in the data. We specifically prevent that by using delete.response when evaluating terms in the formula. Documentation for rda (and cca) and for capscale & dbrda says that data should contain variables in the RHS, and documentation for (old) adonis says the same but with different words. I cannot see any reason to maintain this contra-documented feature in vegan (and the analysis, although doable, really is insane: if you want to have univariate permutational tests, you can use rda instead of having PCoA of Euclidean distances of one variable to get back the original variable).

However, the current implementation of adonis2 still fails where it should work. The documented way of having univariate response would be:

> with(dune, adonis2(Poatriv ~ Management*A1, data=dune.env, method="eucl"))
Error in eval(expr, envir, enclos) : object 'Poatriv' not found

This works with adonis, dbrda, capscale and rda which all give the same result.

[jarioksa]

Your commit 0989c0c revealed that adonis2 could not pass on method. It was hardwired to "bray" and this worked. After your commit, adonis2 failed. I also fixed the with(dune, adonis2(Poatriv... issue of my previous message. The old adonis way of finding LHS from data still fails, but now we are consistent with constrained ordination methods and can find univariate LHS from the global environment or in the with() environment.

[jarioksa]

The following analyses give equal results -- and with the same RNG seed they should even give the same permutations, point to point:

with(dune, anova(rda(Poatriv ~ Management*A1, data=dune.env), by="term"))
with(dune, anova(dbrda(Poatriv ~ Management*A1, data=dune.env), by="term")) # vegan 2.4-0
with(dune, anova(capscale(Poatriv ~ Management*A1, data=dune.env), by="term"))
with(dune, adonis(Poatriv ~ Management*A1, data=dune.env, method="euclid"))
with(dune, adonis2(Poatriv ~ Management*A1, data=dune.env, method="euclid")) # vegan 2.4-0

Among these, current adonis is unique in being able to find the univariate LHS in data=. This is undocumented, and most dissimilarity measures will fail, including default "bray". The other four functions only seek the RHS terms in data= and assume LHS is an independent multivariate object somewhere else, and we seek in the environment(formula) and .GlobalEnv (but the default distance = "euclidean" will work in dbrda and capscale, and rda will work with univariate response). Do you suggest we change all these to seek for univariate LHS in data?

[jarioksa]

I decided to release adonis2 in vegan 2.4-0 without backward compatibility to adonis in this issue. The feature was never documented, and we do still have adonis for those who wish to have the complete compatibility mode.