new pareto_pit function

[avehtari]

Summary

This PR adds

• new pgeneralized_pareto() distribution function for the generalized Pareto distribution, needed by pareto_pit()
• adds tests also for the old qgeneralized_pareto() function
• adds support for weights in gpdfit(), needed by pareto_pit()
• new pareto_pit() function that behaves as pit() expect that in tails instead of using ECDF, uses CDF computed from fitted generalized Pareto distribution. This reduces variability and provides non-0 and non-1 PIT values also outside of the range of reference draws.

pareto_pit() is useful for stabilizing PIT uniformity checking, as current pit() can produce big variation whether there is single 0 or 1 or not.

The following figure illustrates how PIT values that are 0 or 1 from pit() function are replaced with a PIT value estimated with GPD fitted to the tail. Left plot is lower tail and right plot is upper tail. Log scale is used to better show the range of PIT values in tails, The dot with red circle has PIT value 0 from pit() and in log scale that is -Inf, but ggplot plots it next to the axis (and gives a warning).

EDIT: added dashed lines showing PIT values if 1, 2, or 3 draws are further in tail than y. In the left plot one pit() result matches 3. In right plot the predicted tail probability is much smaller than 1/4000.

The function is specifically useful when the draws x distribution is unbounded and has nicely behaving tails, which is common for many observation families. The function is useful if we happen to have only draws from the posterior predictive distribution, but in general it would be better to compute PIT values using the known parametric observation distribution CDF.

Copyright and Licensing

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 1b96d28 is merged into master:

• ✔️as_draws_array: 136ms -> 136ms [-1.06%, +1.88%]
• ✔️as_draws_df: 71.5ms -> 72.6ms [-0.4%, +3.33%]
• ✔️as_draws_list: 159ms -> 159ms [-1.19%, +1.6%]
• ✔️as_draws_matrix: 31.2ms -> 30.8ms [-2.94%, +0.45%]
• ✔️as_draws_rvars: 79.3ms -> 79.4ms [-0.97%, +1.11%]
• ✔️summarise_draws_100_variables: 745ms -> 743ms [-0.66%, +0.18%]
• ✔️summarise_draws_10_variables: 86ms -> 86.3ms [-0.13%, +0.7%]
  Further explanation regarding interpretation and methodology can be found in the documentation.

[florence-bockting]

I think roxygen2::roxygenise() wasn't running and therefore pareto_pit.Rd and pgeneralized_pareto.Rd are missing in the man folder (causing issues in the GitHub Actions).

Might actually be a good candidate for including this call in the GitHub Action Workflow?

[github-actions]

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

• ✔️as_draws_array: 132ms -> 132ms [-1.46%, +0.84%]
• ✔️as_draws_df: 74.9ms -> 75.6ms [-0.85%, +2.71%]
• ✔️as_draws_list: 169ms -> 168ms [-2.55%, +0.34%]
• ✔️as_draws_matrix: 28.9ms -> 28.8ms [-1.19%, +0.58%]
• ✔️as_draws_rvars: 80ms -> 80.8ms [-0.18%, +2.14%]
• ✔️summarise_draws_100_variables: 725ms -> 724ms [-0.48%, +0.21%]
• ✔️summarise_draws_10_variables: 85.9ms -> 85.5ms [-1.46%, +0.44%]
  Further explanation regarding interpretation and methodology can be found in the documentation.

[github-actions]

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

• ✔️as_draws_array: 130ms -> 130ms [-0.47%, +1.6%]
• ✔️as_draws_df: 67.9ms -> 67.9ms [-1.29%, +1.32%]
• ✔️as_draws_list: 155ms -> 156ms [-0.29%, +1.47%]
• ✔️as_draws_matrix: 28.1ms -> 28.1ms [-1.2%, +1.28%]
• ✔️as_draws_rvars: 78.4ms -> 78.3ms [-1.11%, +0.92%]
• ✔️summarise_draws_100_variables: 729ms -> 728ms [-0.52%, +0.13%]
• ✔️summarise_draws_10_variables: 84.9ms -> 84.3ms [-1.71%, +0.29%]
  Further explanation regarding interpretation and methodology can be found in the documentation.

[github-actions]

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

• ✔️as_draws_array: 129ms -> 128ms [-2.12%, +0.03%]
• ✔️as_draws_df: 67.3ms -> 67ms [-2.1%, +1.12%]
• ✔️as_draws_list: 150ms -> 151ms [-0.11%, +1.13%]
• ✔️as_draws_matrix: 28.2ms -> 28.6ms [-1.23%, +4.19%]
• ❗🐌as_draws_rvars: 76.5ms -> 114ms [+47.9%, +50.64%]
• ✔️summarise_draws_100_variables: 720ms -> 722ms [-0.03%, +0.53%]
• ✔️summarise_draws_10_variables: 85.3ms -> 85.3ms [-0.62%, +0.63%]
  Further explanation regarding interpretation and methodology can be found in the documentation.