cca support functions: something missing?

[jarioksa]

The constrained ordination methods return a complicated and large result object. We have documented its internal structure in ?cca.object. However, I think we should not have that result object as public API, because the result object can change. If people access the result elements directly (with $), their scripts and functions will fail if we change the result object. The result object has been very stable since it was introduced in 2002, but now the underlying code has been completely refactored and re-written, and may change (see issue #218). I already changed the way the dependent data are stored (issue #227), and this will break at least one CRAN package. I also introduced function ordiYbar() (released in vegan-2.4-3) that can extract the dependent data both with the old and the new structure. @gavinsimpson has expressed his dislike to result component names pCCA, CCA and CA in rda() and distance-based analysis. Changing these names will break a lot of external code, though. If we document the result object, people think that they can safely use these and other names. Therefore I removed the documentation, and instead document the functions that can be used to access the results. When making this change, I found out that some elements cannot be accessed with support functions, or some of these functions are awkward to use:

• top level items inertia and method: these are informative text, and accessor functions are not needed (?)
• item tot.chi can be accessed only via sum(eigenvals(), but that will not include partial term.
• item envcentre (in $pCCA, $CCA)
• item qrank can be accessed only via $QR element, and pCCA$QR has no accessor (CCA$QR can be extracted with qr.cca()).
• item CCA$rank can be accessed only via eigenvals(..., constrained = TRUE)
• item poseig (for the rank of real solution in dbrda) can be accessed only via eigenvals() (and needs detecting positive eigenvalues)
• result scores can be accessed with scores(..., scaling = FALSE), but there is no direct way of getting all scores for a certain component without juggling with eigenvals().
• imaginary scores for negative eigenvalues cannot be accessed in dbrda() and capscale().
• distance-based analysis can add several items to the top-level, but these cannot be accessed: metaMDSdist (data set name), sqrt.dist (logical), ac (additive constant), add (the method used for ac), adjust (adjustment for RDA-like results), vdata (data set names for added species scores).