[florence-bockting]

Summary

Closes #446.

ps_tail_length() now depends on ndraws only: floor(3 * sqrt(ndraws)) if ndraws > 225, and floor(ndraws / 5) otherwise.

r_eff stays in the signatures of ps_tail_length(), pareto_khat(), pareto_diags(), and pareto_smooth(), so existing calls do not break. A value other than NULL gives a warning of class posterior_warning_pareto_r_eff_ignored.

Changes:

• A call that passes r_eff now gives a warning.
• The rvar methods give the warning once, not once for each element.
• pareto_pit() used r_eff = 1 before, so its results do not change.
• New tests: r_eff does not change khat, a non-NULL value warns (also with ndraws_tail), the rvar methods warn once, and ps_tail_length() values for ndraws above and below 225.
• I removed r_eff from 3 older test calls.
• The ps_tail_length() docs give the formula and say that it differs from Appendix H.
• man-roxygen/args-pareto.R now links ndraws_tail to ps_tail_length(). This also removes the old text, which said ceiling but the code uses floor.
• The new warning class is in the list of warning classes in ?posterior.

AI assistance: I used LLMs in this PR.

Copyright and Licensing

Copyright holder: Aalto University

By submitting this pull request, the copyright holder is agreeing to
license the submitted work under the following licenses:

• Code: BSD 3-clause (https://opensource.org/licenses/BSD-3-Clause)
• Documentation: CC-BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

[github-actions]

This is how benchmark results would change (along with a 95% confidence interval in relative change) if 6831294 is merged into master:

• ✔️as_draws_array: 88.7ms -> 89ms [-0.06%, +0.69%]
• ✔️as_draws_df: 28.5ms -> 28.5ms [-0.27%, +0.43%]
• ✔️as_draws_list: 142ms -> 143ms [-0.36%, +2.06%]
• ✔️as_draws_matrix: 22.9ms -> 22.9ms [-0.6%, +0.23%]
• ✔️as_draws_rvars: 68.1ms -> 67.8ms [-1.18%, +0.25%]
• ✔️summarise_draws_100_variables: 582ms -> 583ms [-0.1%, +0.48%]
• ✔️summarise_draws_10_variables: 64.3ms -> 64.3ms [-0.23%, +0.24%]
  Further explanation regarding interpretation and methodology can be found in the documentation.

[avehtari]

A value other than NULL gives a warning of class posterior_warning_pareto_r_eff_ignored.

I assume this means there will be only one warning line (possibly with a count) in case of repeated calls?

[paul-buerkner]

I don't really have time to review this right now. Would @avehtari 's review be sufficient?

[florence-bockting]

I assume this means there will be only one warning line (possibly with a count) in case of repeated calls?

Without count. Its not collecting warnings, but rather catches early when r_eff is not Null and sets it then to Null, such that downstream functions do not warn anymore.

[avehtari]

but rather catches early when r_eff is not Null and sets it then to Null,

I see the warnings, but I don't see where it is set to NULL

[florence-bockting]

A value other than NULL gives a warning of class posterior_warning_pareto_r_eff_ignored.

I assume this means there will be only one warning line (possibly with a count) in case of repeated calls?

The rvar methods take r_eff as a named argument. They warn once, then call the default method for each element without r_eff. However, when you call the methods multiple times this will give you multiple warnings.

[avehtari]

Is it possible that some other package calls this or some posterior function repeatedly with non-null r_eff?