capscale: deprecate, downgrade or upgrade?

[jarioksa]

I'm re-implementing constrained ordination methods using common underlying code ordConstrained() in branch rda-2.0. I have already implemented and merged to master cca, rda and capscale and I'm ready to start finishing dbrda. The dbrda re-implementation will break some support functions (permutest and hence anova, fitted and hence residuals, stressplot), and fixing those will break capscale at least for permutest and anova. There are at least two alternative ways of fixing the capscale breakage: upgrade to have special handling of capscale to give similar results as in vegan release 2.4-0 (released Jun 15, 2016), or downgrade to have similar results as in older releases (2.3-5 and older).

What happened in release 2.4-0 was that we added dbrda as a new function for distance-based RDA. This function directly handles dissimilarities and also handles negative eigenvalues. The old capscale (since vegan 1.6-0 of 2003) only analysed the real components and only gave information of the magnitude of non-analysed imaginary components (sum of negative eigenvalues). When we added dbrda we also made capscale to evaluate the magnitudes of partial, constrained and residual components with these negative eigenvalues although the actual ordination was only based on real components with positive eigenvalues. In this way, anova etc of capscale gave identical results to dbrda, although the ordination (plots) only used real components. I have no intention of implementing this behaviour in the new unified ordConstrained infrastructure, but currently capscale function adds the necessary components to its result, and current dbrda uses capscale-like internal structure. The new code will change dbrda to use similar structure as cca and rda, and I will remove the special code for distance-based methods in the support functions like permutests.cca (hence the breakage). Now the question is whether I still should keep that code only for capscale (i.e., upgrade), or remove the special handling from the support functions and parallel analysis from capscale (i.e., to downgrade).

Finally, the big question is do we really need capscale any longer? It has been in vegan for thirteen years, but it is superseded by dbrda. We could deprecate capscale in release 2.4-2 and make defunct in 2.6-0 (i.e., not yet in 2.5-0 where it would be deprecated). Should it be downgraded before that? Or should we keep downgraded capscale only handling real dimensions & positive eigenvalues?

[EDiLD]

My 2cts:
Let capscale go and keep dbrda with support functions...

[jarioksa]

I have now downgraded capscale to its pre-2.4-0 shape before introducing dbrda. The function is not deprecated yet, though, and the changes are not yet merged to the main rda-2.0 branch. Probably some more testing will be needed.

[jarioksa]

Downgraded capscale is now merged to the rda-2.0 branch (commit 05080f8) and once rda-2.0 is merged to master, the downgraded version will be there. This merge will happen after making dbrda to build upon ordConstrained.

There is no deprecation message yet, and I haven't made my mind of deprecating capscale, although I probably will do so finally.