Add a message that prints during fitting if terms are aliased

[gavinsimpson]

Many users wonder why they have fewer constrained axes than constraints they include in their model. We currently include a note in the output when printing the model, but seemingly users either miss this or do not understand it.

Instead, print a message about the aliasing when fitting the model/ordination, in addition to the existing note in the printed output.

See discussion in #671, in which @jarioksa suggests:

• [x] ordConstrain should issue a message() of aliased variables (and preferably in plain English: the current one of aliasing sounds complicated).
• [x] ordConstrained should have a message() instead of current warning() of overfitted models and missing residual component.
• [x] print.cca should print a text of missing residual component (and overfitted) model in addition to the current text of aliased redundant constraints and/or conditions.

[gavinsimpson]

@jarioksa One infelicity of printing a message() (or just printing something to the console) is that functions that fit a model repeatedly generate messages:

> drop1(mcca,  test = "permutation", permutations = per)

Some constraints or conditions were aliased because they were redundant. This can
happen if terms are linearly dependent (collinear): ‘Manure^4’

Some constraints or conditions were aliased because they were redundant. This can
happen if terms are linearly dependent (collinear): ‘Manure^4’
                      Df  AIC    F Pr(>F)  
<none>                   87.9              
Condition(Management)  2 87.9              
Manure                 3 86.5 1.03   0.86  
A1                     1 89.0 2.00   0.04 *
---
Signif. codes:  0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1

We'll need to wrap some calls in some functions like drop1.cca in suppressMessages().

Right now I know the following which need attention:

• [x] add1.cca()
• [x] drop1.cca()
• [x] anovaCCAbymargin()
• [x] anovaCCAbyaxis()

[gavinsimpson]

I think using suppressMessages() in add1 and drop1 methods is OK because adding terms should never get into a situation where you add a linearly dependent term and dropping terms won't create a problem unless the model the user fitted already had aliased terms and thus will already have seen the message.

[gavinsimpson]

@jarioksa

OK, I think I have something ready for your input:

message emitted when fitting model

> mod <- cca(dune ~ . + Condition(Manure), dune.env)

Some constraints or conditions were aliased because they were redundant. This can
happen if terms are linearly dependent (collinear): ‘ManagementNM’, ‘Manure.L’,
‘Manure.Q’, ‘Manure.C’, ‘Manure^4’

output when printing the model

> mod
Call: cca(formula = dune ~ A1 + Moisture + Management + Use + Manure +
Condition(Manure), data = dune.env)

-- Model Summary --

              Inertia Proportion Rank
Total          2.1153     1.0000     
Conditional    0.6116     0.2891    4
Constrained    0.8916     0.4215    8
Unconstrained  0.6121     0.2894    7

Inertia is scaled Chi-square

-- Note --

Some constraints or conditions were aliased because they were redundant. This
can happen if terms are linearly dependent (collinear): ‘ManagementNM’,
‘Manure.L’, ‘Manure.Q’, ‘Manure.C’, ‘Manure^4’

-- Eigenvalues --

Eigenvalues for constrained axes:
  CCA1   CCA2   CCA3   CCA4   CCA5   CCA6   CCA7   CCA8 
0.3318 0.1585 0.1095 0.1004 0.0832 0.0557 0.0286 0.0240 

Eigenvalues for unconstrained axes:
    CA1     CA2     CA3     CA4     CA5     CA6     CA7 
0.27237 0.10876 0.08975 0.06305 0.03489 0.02529 0.01798 

Note that I have made more significant changes to print.cca to facilitate printing a more informative notification. When I added the aliasing note the important results disappeared, especially if there were more notes to print (e.g. deleted samples/species). So I decided to add a heading for the sections to highlight the results. I'm not wedded to -- Heading -- notation - suggestions for alternatives welcome.

I have fixed the methods mentioned above that would refit a model and thus cause more messages to be printed. So we just need to agree / OK the text and then I can finalise this.

[jarioksa]

This was more complicated than I expected (but I should have learnt to expect complications). At the first look this looks good, but I'll run more extensive tests tomorrow.

[gavinsimpson]

@jarioksa OK; I'll push this to a branch so you can check when you get time.

[gavinsimpson]

@jarioksa I have pushed the changes shown above to the issue-682 branch

[jarioksa]

Gav,

I’ll have a look at these changes “asap” – but have you heare the Danish word “hygge”? For me this means that the “asap” could be Monday. I could imagine some potential complicataions. For insance, you may have aliased partial terms (Condition). Thet are aliased, but you won’t see none of them – aliiased nor non-aliased. What would happen with overfitted model with matrix arguments, such as having pcnm matix as Conditon or constraints – or how rda(y, x, z) without formula would be handled. These are the things I would look at aong normal tests. But perhaps first on Monday…

Cheers, J

On 16 Aug 2024, at 21:20, Gavin Simpson @.***> wrote:

@jarioksa https://github.com/jarioksa I have pushed the changes shown above to the issue-682 https://github.com/vegandevs/vegan/tree/issue-682 branch

— Reply to this email directly, view it on GitHub https://github.com/vegandevs/vegan/issues/682#issuecomment-2293956091, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAK52ZPXPTXCOUYCTROE3U3ZRY7HTAVCNFSM6AAAAABMT4ZDTOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEOJTHE2TMMBZGE. You are receiving this because you were mentioned.

[jarioksa]

Gav,

I have played with vegan and tried different cases. All seem to work well. I think this can be merged to master, and I think it could go to cran-2.6-6.

Cheers, Jari

On 16 Aug 2024, at 21:20, Gavin Simpson @.***> wrote:

@jarioksa https://github.com/jarioksa I have pushed the changes shown above to the issue-682 https://github.com/vegandevs/vegan/tree/issue-682 branch

— Reply to this email directly, view it on GitHub https://github.com/vegandevs/vegan/issues/682#issuecomment-2293956091, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAK52ZPXPTXCOUYCTROE3U3ZRY7HTAVCNFSM6AAAAABMT4ZDTOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEOJTHE2TMMBZGE. You are receiving this because you were mentioned.

[jarioksa]

Gav, I pushed one more commit to issue-682 branch (db5cfc2f0): man/plot.cca.Rd builds automatically an entry in the manual, and this printed a confusing looking message when building vegan (or when generating man page with R CMD Rd2txt man/plot.cca.Rd).

If you decide to push these changes to cran-2.6-6, do not cherry-pick this change. man/plot.cca.Rd files have diverged so widely between master and cran-2.6-6 that cherry-picking would fail – and this change is not needed in cran-2.6-6.