Dependence aware tests for ppc*ecdf

[florence-bockting]

Description

The current approach in ppc_loo_pit_ecdf and ppc_pit_ecdf assumes independence of LOO-PIT values which is not valid (Marhunenda et al., 2005). The corresponding graphical test yields an envelope that is too wide, reducing the test's ability to reveal model miscalibration.
Tesso & Vehtari (2026, see preprint) propose three testing procedures that can handle any dependent uniform values and provide an updated graphical representation that uses color coding to indicate influential regions or most influential points of the ECDF. This PR implements the new development, by adding the updated approach (method = "correlated") additionally to the previous approach (method = "independent").

TODOs

• updated ppc_loo_pit_ecdf() function in ppc-loo.R
• updated ppc_pit_ecdf() and ppc_pit_ecdf_grouped() function in ppc-distributions.R
• add unittests and visual regression tests
• update documentation
• deprecation suggestion of old method
  • P1: old method (default) and new method available via method argument
  • P2: new method (default) and old method available via method argument
  • P3: old method is removed

[florence-bockting]

As mentioned in the PR introduction text, the idea would be migration in multiple stages.
First stage is non-breaking behavior: That is users can simply use "original" code but are informed that this behavior will change in future. Future changes consider changing the default method and thus are breaking.

Informing the user in the first stage is currently implemented as follows:

# using the "original" code provides a message about the change
> ppc_loo_pit_ecdf(y, yrep, lw)
ℹ In the next major release, the default `method` will change to 'correlated'.
• To silence this message, explicitly set `method = 'independent'` or `method = 'correlated'`.

# explicit use of "independent" method provides information that this method is superseded
> ppc_loo_pit_ecdf(y, yrep, lw, method = "independent")
The 'independent' method is superseded by the 'correlated' method.

[jgabry]

Here are a few comments and questions. So far I've only looked at some of the code, so I may have more, but I thought I would give you these now so we could start discussing.

[jgabry]

I think R will parse this as

(pareto_pit %||% is.null(pit)) && (test %in% c("POT", "PIET"))

and not as

pareto_pit %||% (is.null(pit) && test %in% c("POT", "PIET"))

So if we have

pareto_pit = TRUE
pit = NULL
test = "PRIT"

then I think this will parse as TRUE && FALSE -> FALSE.

Do we not want this instead?

pareto_pit <- pareto_pit %||% (is.null(pit) && test %in% c("POT", "PIET"))

This is a bit confusing for me, so I could definitely be wrong!

[florence-bockting]

Thank you for catching this behavior! I fixed the notation and created corresponding unittests.
Furthermore, I noticed that I need to catch the situation where a user provides both pareto_pit = TRUE and pit = pit (thus, pit is not NULL). I added an error with the user message:

`pareto_pit = TRUE` cannot be used together with a non-`NULL` `pit` value. Set either `pareto_pit = FALSE` or `pit = NULL`.

[jgabry]

@florence-bockting The changes look good, but I think there are the same issues (with the gamma doc and the pareto_pit issue) in the ppc-distributions.R file too, right? Also, how much of the doc in the two R files now overlaps? Could we write some of it once and share it? (If it's only a small amount of overlap then maybe not worth it).

[florence-bockting]

@jgabry
Thanks for the comments. I was planning to do the refactoring for reducing duplicate code between the ppc-ecdf functions at a later stage as this was already in the original version the case. But given your comment I realized that I should probably do it just now. Thus:

I have refactored the code such that it removes duplicate code and documentation by creating new helper functions or template files.
Furthermore, I increased the helper-text size but also added now the factor for controlling size as an additional argument. When we improve the theme, we can probably get rid of it again. @avehtari

[jgabry]

@florence-bockting please also officially add yourself to the DESCRIPTION file as part of this PR!