export helper functions

[n-kall]

Summary

As discussed in #358, some internal functions could be useful for other packages (including loo and projpred).

This PR adds documentation to, and exports, the following functions under a new family "helper-functions":

• ps_khat_threshold
• ps_min_ss
• ps_tail_length
• ps_convergence_rate
• gpdfit (not exported)

It also updates the PSIS paper reference.

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 9de9857 is merged into master:

• ✔️as_draws_array: 143ms -> 144ms [-0.17%, +1.61%]
• 🚀as_draws_df: 70.4ms -> 68.4ms [-4.17%, -1.45%]
• 🚀as_draws_list: 165ms -> 161ms [-3.05%, -1.6%]
• ❗🐌as_draws_matrix: 64.7ms -> 65.8ms [+0.46%, +2.91%]
• ✔️as_draws_rvars: 84.6ms -> 84.7ms [-1.01%, +1.3%]
• ✔️summarise_draws_100_variables: 719ms -> 719ms [-0.27%, +0.36%]
• ✔️summarise_draws_10_variables: 112ms -> 112ms [-0.68%, +0.88%]
  Further explanation regarding interpretation and methodology can be found in the documentation.

[mjskay]

Since these are being exported, would it be good to make the names of functions and arguments follow the same variable naming rules as other public functions? (eg gpdfit -> fit_gp or fit_generalized_pareto; at a first glance parameter names wip and S also stand out).

[n-kall]

S has been replaced with ndraws, and the gpdfit is no longer exported at this time. It is currently exported by loo, so we will think further before exporting it too.

[github-actions]

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

• ✔️as_draws_array: 143ms -> 143ms [-0.97%, +1.12%]
• 🚀as_draws_df: 69.5ms -> 68.3ms [-2.79%, -0.66%]
• ✔️as_draws_list: 165ms -> 165ms [-0.21%, +0.85%]
• 🚀as_draws_matrix: 65.5ms -> 63.7ms [-3.72%, -1.8%]
• ✔️as_draws_rvars: 84.2ms -> 84.1ms [-1.26%, +0.98%]
• ✔️summarise_draws_100_variables: 714ms -> 716ms [-0.22%, +0.81%]
• ❗🐌summarise_draws_10_variables: 112ms -> 113ms [+0.03%, +1.28%]
  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 609028d is merged into master:

• ✔️as_draws_array: 143ms -> 142ms [-1.16%, +0.65%]
• 🚀as_draws_df: 70.8ms -> 69.6ms [-3.01%, -0.48%]
• ✔️as_draws_list: 169ms -> 170ms [-0.75%, +0.96%]
• 🚀as_draws_matrix: 64ms -> 62.6ms [-3.53%, -0.67%]
• ✔️as_draws_rvars: 83.7ms -> 83.9ms [-1.02%, +1.54%]
• ✔️summarise_draws_100_variables: 721ms -> 720ms [-0.58%, +0.49%]
• ✔️summarise_draws_10_variables: 112ms -> 112ms [-1.32%, +0.86%]
  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 419a1a3 is merged into master:

• ✔️as_draws_array: 135ms -> 135ms [-0.72%, +0.29%]
• ❗🐌as_draws_df: 63.8ms -> 65.2ms [+0.82%, +3.45%]
• ✔️as_draws_list: 155ms -> 155ms [-0.38%, +0.4%]
• ✔️as_draws_matrix: 60.4ms -> 60.1ms [-1.34%, +0.51%]
• ✔️as_draws_rvars: 79.8ms -> 80ms [-0.58%, +1.05%]
• ✔️summarise_draws_100_variables: 689ms -> 691ms [-0.02%, +0.63%]
• ✔️summarise_draws_10_variables: 107ms -> 108ms [-0.38%, +0.87%]
  Further explanation regarding interpretation and methodology can be found in the documentation.

[paul-buerkner]

Looks good to me. Any changes you want to make before we merge?

[n-kall]

I think it should be good now

[paul-buerkner]

great! merging now