Repository navigation
Expanding the bayesplot vignette library #436
Description
Summary
While bayesplot currently offers a few introductory vignettes, the user experience could be improved by more targeted documentation. In the following three suggestions:
Suggested Vignettes
1. "Which plot should I use?"
This problem-oriented vignette would provide a structured overview (e.g., a lookup table) mapping specific diagnostic questions to their corresponding plot functions.
| Diagnostic Question | Recommended Function(s) |
|---|---|
| Did my MCMC chains mix? | mcmc_trace(), mcmc_rank_overlay() |
| Is my R-hat acceptable? | mcmc_rhat(), mcmc_rhat_hist() |
| ... | ... |
2. "Bayesplot and the Bayesian Workflow"
A workflow-oriented vignette that walks users through a complete modeling cycle using a single running example. It would demonstrate the appropriate plots for each stage.
3. "Customizing Bayesplot Outputs"
Since bayesplot returns standard ggplot objects, they can be modified using standard ggplot2 functions. However, it might be that some users are unaware of this extensibility. This vignette would guide users on how to benefit from this composability, covering topics such as: Adding layers or changing labels using the + operator, utilizing built-in color schemes and themes, customizing plot appearance via ggplot2 theme elements.
Relation to other issues
This issue is related to Issue#144 (Extend and Update vignettes) and Issue#142 (Vignette/template demonstrating how to contribute a new plotting function to bayesplot).
Activity
Add three new vignettes for expanded documentation (stan-dev#436)
jgabry commentedon Mar 10, 2026
I agree these would be good additions
ishaan-arora-1 commentedon Mar 14, 2026
Hey @florence-bockting
I did my research and looked at how arviz organised their docs, to get a better idea of how i should go about with this.
I've been thinking about the questions from #440, which vignettes, what content, how they relate, long vs. focused.
Curently the three exitsing vignettes are organized by function families. They work good as reference docs, but don't help a user with quesitons like what should they check after they fit a model?
What i think is that on each vignette:
Coming to the structure : I'd lean toward separate focused vignettes taht are consistent with the existing pattern. Starting with the workflow vignette seems best as it has the clearest scope and least overlap.
I would be happy to draft an outline (not code) for the workflow vignette as a next step if this sounds reasonable.