Dr. Brenton Wiernik pointed me to this thread after seeing me splash my confusion all over Twitter about what it is exactly that posterior_epred() does in comparison to posterior_predict() and why the rstanarm documentation states (indirectly) that posterior_epred() should be used sparingly.
In case the questions I posted earlier today on this same forum may prove helpful to you in improving the brms and rstanarm documentation, I am linking to them here:
Confusion on difference between posterior_epred() and posterior_predict() in a mixed effects modelling context - Modeling - The Stan Forums (mc-stan.org)
People like myself, coming from a predominantly Frequentist background, tend to struggle with the nuances of language and interpretation in the Bayesian R packages help files. At the end of the day, we may not be able to understand all the tricky nuances, but what we do want is to know (at least broadly) which function to apply in which practical setting.
If you have a chance to look at my questions, you will see that I created a table of potential use cases for a relatively simple mixed effects models and took a stab at guessing whether posterior_epred() or posterior_predict() should be applied to each of those cases. I am not sure whether I am on the right track with that, but having a package vignette or commented examples in the help files for brms or rstanarm along those lines would be invaluable. That would at least give people a good starting point and then, if they want to tease out the deeper nuances, they could do so later on. (I do some teaching on top of my consulting and I know that being able to build on a solid foundation will make learning something new a lot easier than building it on shaky ground.)
Here is the table in case you won’t have a chance to read the questions I linked to:
Though I am probably not the best person to help with any documentation updates (a genuine Bayesian would be a much better fit), I would be happy to help in any small way I can, such as suggesting examples to be included in the documentation/vignette (along the lines devised above), taking a tentative stab at the R syntax and having a more experienced person confirm what looks right and what looks wrong, etc.
I would love it if there was a place for tables like the one above somewhere in the documentation not just for this model but for other, more complex models (e.g., ordbetareg, which interests me directly).
Thank you!
Isabella