add quantile dot plot functions

[behramulukir]

As I mentioned at #354 I have been working on adding quantile dot plots. It was more complicated than I was expecting, so I wanted to make sure about the direction of this.

Current Progress

So far, I have implemented two functions, ppc_qdotplot which under the hood utilises geom_dotplot and ppc_qdotplot_ggdist which utilises stat_dots from ggdist.

qdotplot

This function utilises geom_dotplot, which gives a very simple way to build dot plots. geom_dotplot function has two main deficiencies:

1. Very often, the number of dots exceeds the space that the graphic has, and since geom_dotplot doesn't have a proper auto-sizing for dots, the visual is getting clipped and not presenting the full picture.
2. It doesn't have functionality to plot according to quantiles.

To minimise the first problem, I implemented a simple auto-sizing algorithm which performs well when the bin width is not specified or very reasonably specified; however, when it is even a little unsuitable, it is likely to run into issues. Here are some example uses of ppc_qdotplot:

color_scheme_set("brightblue")
y <- example_y_data()
yrep <- example_yrep_draws()
group <- example_group_data()
ppc_qdotplot(y, yrep[1:8, ])

ppc_qdotplot(y, yrep[1:8, ], binwidth = 5)

ppc_qdotplot(y, yrep[1:8, ], binwidth = 3)

ppc_qdotplot(y, yrep[1:8, ], binwidth = 10)

As you can see, for certain bin widths, dots are over-compressed or exceed the limit of the graphic.

qdotplot_ggdist

The second alternative relies on stat_dots from ggdist. It is slightly more successful overall in handling edge cases and has a warning system; however, it also brings additional dependency to the package, making me unsure if we want to go that route. The advantages of this over qdotplot are:

1. When dots are unfit for the graph size, it gives a warning to the user
2. It can plot based on quantiles

ppc_qdotplot_ggdist(y, yrep[1:8, ])

ppc_qdotplot_ggdist(y, yrep[1:8, ], binwidth = 3)

ppc_qdotplot_ggdist(y, yrep[1:8, ], binwidth = 5)

ppc_qdotplot_ggdist(y, yrep[1:8, ], binwidth = 10)

In the previous three graphics where the dots do not fit into the visual, the following error is thrown at the console:

Warning messages:
1: The provided binwidth will cause dots to overflow the boundaries of the geometry.
→ Set `binwidth = NA` to automatically determine a binwidth that ensures dots fit within the bounds,
→ OR set `overflow = "compress"` to automatically reduce the spacing between dots to ensure the dots fit within the bounds,
→ OR set `overflow = "keep"` to allow dots to overflow the bounds of the geometry without producing a warning.

ppc_qdotplot_ggdist can be used with quantiles as follows:

ppc_qdotplot_ggdist(y, yrep[1:8, ], quantile = 25)

Future

To move forward, I think we need to decide on which function we want to keep and whether we want to add ggdist dependency. After that, I can remove the unnecessary function and continue with the rest of the implementation.

• implement geom_dotplot version
• implement stat_dots
• decide on which function to keep
• implement the ppd version
• update the documentation
• implement tests

[jgabry]

I didn't realize there would be this sort of difficulty with the dot plots. I think handling those edge cases and having appropriate warnings is probably enough of a benefit to add ggdist dependency and maybe we can also use ggdist for other plots in the future. For now we could just add it to Suggests (instead of Imports) and then use our internal suggested_package() function to make sure it's installed if someone wants to make the dot plots. If we end up using ggdist for a bunch of other plots in the future we can move it to Imports so that it gets automatically installed. @avehtari @TeemuSailynoja what do you think?

[behramulukir]

This solution makes sense to me. If @TeemuSailynoja or @avehtari don't have any objection, I can work on this.

[avehtari]

I like ggdist, so I'm fine using it more

[TeemuSailynoja]

I think adding ggdist as a suggested package is very good for this.

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.62%. Comparing base (da5c707) to head (cd9f63f).
Report is 9 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #357      +/-   ##
==========================================
- Coverage   98.64%   98.62%   -0.03%     
==========================================
  Files          35       35              
  Lines        5550     5600      +50     
==========================================
+ Hits         5475     5523      +48     
- Misses         75       77       +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jgabry]

Thanks for this! I still need to actually play around with the functions and try using them to make some plots (I will try to do that soon), but the code is looking good. I made a few small review comments and, in addition to those, two other things:

1. It looks like several tests are failing. Can you look into why they're failing?

2. Can you regenerate the documentation using devtools::document(). That will regenerate the user manual pages (the .Rd files in the man directory) based on the documentation you put in the R files.

3. Thinking about the name for this function, maybe we should just call it ppc_dots(). Does anyone have a strong preference?

[behramulukir]

Thanks, I'll look into all of these and update the code

[jgabry]

Thanks @behramulukir. Just two things:

1. Can you run devtools::document() to regenerate the .Rd files and the NAMESPACE file? Right now you have the documentation written in the .R file, which looks good, but it doesn't actually get added to the user manual until the .Rd file is updated from the R file. And the function won't be exported for users until it's listed in the NAMESPACE file. Running devtools::document() will do both of those things for you.

2. Do you know why the visual tests comparing the SVGs are failing? We should get those to pass before merging this. You may need to use testthat::snapshot_review().

Otherwise this looks good!

[jgabry]

Thanks @behramulukir! I'm going to merge this now.