Allow finer control of which eigenvalues (constrained or unconstrained) are returned by eigenvals()

[gavinsimpson]

Consider

data(varespec, varechem)
vare.cca <- cca(varespec ~ Al + P*(K + Baresoil), data=varechem)

How do I extract only the unconstrained eigenvalues? With eigenvals(), as currently implemented, this is not possible:

> eigenvals(vare.cca, constrained = TRUE)
     CCA1      CCA2      CCA3      CCA4      CCA5      CCA6 
0.3756307 0.2341897 0.1406696 0.1322908 0.1067518 0.0561409 
> eigenvals(vare.cca, constrained = FALSE)
     CCA1      CCA2      CCA3      CCA4      CCA5      CCA6       CA1       CA2 
0.3756307 0.2341897 0.1406696 0.1322908 0.1067518 0.0561409 0.2757692 0.1541055 
      CA3       CA4       CA5       CA6       CA7       CA8       CA9      CA10 
0.1353625 0.1180342 0.0888713 0.0551092 0.0491937 0.0378095 0.0357212 0.0277773 
     CA11      CA12      CA13      CA14      CA15      CA16      CA17 
0.0212446 0.0136233 0.0092818 0.0059037 0.0045662 0.0030977 0.0020541

I propose modifying the current behaviour of eigenvals() such that

• constrained only controls whether or not constrained eigenvalues are returned
• new argument unconstrained controls whether or not the unconstrained eigenvalues are returned.

Thoughts?

[jarioksa]

@gavinsimpson , this was based on my idea how eigenvals are used. I assumed people want to get all eigenvalues or only constrained eigenvalues. I didn't occur to me that people would only want to have ("need to have") residual unconstrained eigenvalues. Personally I don't want to get any of these, and my ability to empathy failed.

[gavinsimpson]

Ha!

It would make it internally easier to extract and separate up the types of eigenvalues. So, unless I hear any objections, I'll go implement this change for use in #203

[jarioksa]

fitted, predict and goodness use argument model which could be model = c("all", "CCA", "CA"). An alternative in some other methods is to use k or rank for the number of axes. Typically k can go across models (CCA/CA border), but rank takes a subset within a model.

[gavinsimpson]

I've never liked that these are CCA and CA for a-non-CCA ordination model. Perhaps for v 3.0-x we can change these to "partial", "constrained", "unconstrained"? ;-)

At the user level we don't need to stick to these names even if the internal object still uses them (but see joking above).

I'd probably suggest model = c("constrained", "unconstrained"). If we went that way is likely to break more things, although subtly changing the meaning of constrained = TRUE may mean bugs go unnoticed beyond vegan?

I think it really depends how much you'd like to see standardised across these functions and at which point we introduce broader standardisation? With a lot of these recent suggested changes we are really talking about changing some older, established functions and possibly underlying representations. If we do plan to do some real standardisation that has the potential to break code, we may want to think about a road map for 2.4-x, 2.5-x, (and any other 2.y-x) and 3.0-x, assigning changes to each release so we can think more strategically.

[jarioksa]

@gavinsimpson , about model = c("constrained", "unconstrained") -- that depends how much you want to break things. Now it would be about breaking the user interface. The reason why I used model = c("pCCA", "CCA", "CA") is that I can use object[[model]]$item within the code (and indeed, you cannot have "all" or more than one model with this idiom). You can call this elegant or lazy depending on your point of view. The reason for the models being called pCCA, CCA and CA is that this is how they were called in 2002 when I had no intention to ever implement RDA that I regarded as useless weaker alternative to CCA (but I have become softer with age and now I tolerate RDA, and I think the difference is much smaller than I used to think earlier, and smaller than between CA and the abominable PCA).

[jarioksa]

@gavinsimpson : I'm preparing for the 2.5-0 release, and this issue seems to be still open. Something to do for the release, or is this OK?

[gavinsimpson]

@jarioksa I'll deal with this using argument model = c("all", "unconstrained", "constrained") but preserve the old behaviour and allow constrained as an argument which we can deprecate this version for future removal.