Sync residual_draws and predicted_draws with tidybayes 3.0 API

[mjskay]

Hi! tidytreatment looks like a great package; it's really awesome to see people building on the tidybayes API :)

Some slightly unfortunate news: I am about to submit a new version of tidybayes to CRAN that changes some parts of the tidybayes API that will cause some test failures on the existing version of tidytreatment on CRAN. The good news is this PR will fix those failures.

The changes in tidybayes that are relevant here are:

• The first argument for all the XXX_draws() functions (fitted, predicted, etc) is now object instead of model, as these typically call down to posterior_predict / posterior_epred / posterior_linpred, and those functions also use object. In some corner cases this was causing problems (specifically, rstanarm's posterior_predict has an m argument that could not be passed to it via add_predicted_draws() due to partial argument matching thinking the user was specifying model). This PR renames model to object in your implementations of residual_draws and predicted_draws. It does not change fitted_draws for reasons outlined below.
• The arguments that name the output column of the various functions (e.g. value = ".value", residual = ".residual", prediction = ".prediction") are now all called value (the default column name is still the same for each function though --- e.g. the default is value = ".residual" for residual_draws). In retrospect having this argument have a different name for each function was confusing. This PR renames the relevant columns to value in your implementations of residual_draws and predicted_draws. You shouldn't have to worry if you have existing users using the old column names; the tidybayes generic for those functions automatically passes through the desired column name to the value argument and gives the user a deprecation warning if they use the old argument name.
• The n argument is renamed to ndraws. This is not a huge change since you don't implement it. This makes it more consistent with naming schemes in the new posterior package, and also prevents corner cases where n is partially matched to the newdata argument (really, partial argument matching is just a terrible feature in R).

Your test suite passes under this PR if either the CRAN version of tidybayes or the github version is installed.

There's another big change I did not try to address in this PR as it does not currently cause any test failures and I'm not sure how you'd want to handle it: as of the next version, tidybayes::fitted_draws() will be deprecated. At least, the default implementation is --- after much experience teaching folks how to use the package, I've come to the realization that "fitted" is a terrible name for the function that only serves to confuse students. Users are now directed to use either epred_draws() (which gives draws from the expected value of the posterior predictive; after rstantools::posterior_epred()) or linpred_draws() (which gives draws from the linear predictor; after rstantools::posterior_linpred()). I'd suggest a similar change here, but of course you're welcome to ignore my advice :). Tidybayes will continue to export the fitted_draws() generic and the deprecation warning is only hit in fitted_draws.default(), so if you choose to keep using the fitted_draws name everything should continue to work and your users should not see a deprecation warning.

I will be making a submission to CRAN soon (probably later this week). If you're able to submit a new version before I do that would be awesome --- it should save you an angry email from CRAN telling you to update the package due to test failures. Sorry to be the bearer of such news, but I hope having a PR attach to the request will make it easier to deal with :). Happy to try to help / answer questions as needed.

[bonStats]

Thanks for the PR and thorough explanation of changes @mjskay ! Very much appreciated!! I should be able to submit to CRAN before the end of the week (I'll try ASAP)

[mjskay]

Awesome, thanks!

Also, looks like I forgot to update the docs after these changes, so I did that :)

[bonStats]

@mjskay still some documentation issues, are you able to correct?

[mjskay]

Ah yup, that's what I get for not running check locally, should be fixed now :).

[bonStats]

@mjskay submitted to CRAN just now. Thank you for being so helpful with the PR. I'll update you when it's accepted.

Regarding fitted_draws() I'll wait until the next update to decide. I really see the value in delineating with epred_draws() and linpred_draws() but my current collaborators will prefer fitted_draws()... at least at first. I will probably end up supporting both.

Thanks again!

[mjskay]

thanks so much!

[bonStats]

@mjskay on its way to CRAN, thanks again :smiley:

[mjskay]

wonderful, thank you!