NEWS.md
New features:
draw_indices parameter in spread_draws() and gather_draws(). (#323)Bug fixes:
nest_rvars() and unnest_rvars(). (#316)spread_draws() on R >= 4.5.Deprecations:
recover_types() with character vectors is now deprecated, as the expected order of the levels of the variable is ambiguous, leading to hard-to-spot errors where indices and names do not line up correctly. A warning message has been added suggesting the use of factors instead. (#312)Bug fixes:
residual_draws() more robust (due to change in default value of the method argument to brms::residuals()). (#313)Bug fixes:
summarise_draws.grouped_df() due to changes in how posterior::summarise_draws() handles the num_args argument.epred, linpred, and predicted in add_XXX_rvars().dplyr and tidyr.fitted_draws() deprecation warning (#288).epred_draws() on rethinking models.posterior::as_draws_df() instead of As.mcmc.list() for rstan objects.stat_... and stat_dist_...)@examplesIf for conditional examples (#294)compose_data() are overwritten by generated names (#295)Breaking changes and deprecations:
[add_]XXX_draws() (predicted_draws(), add_predicted_draws(), etc) functions have been substantially restructured:
add_fitted_draws() and fitted_draws() are now deprecated, along with the scale argument. Several years’ teaching experience has demonstrated that “fitted” is a very confusing name for students. Use the more-specific [add_]linpred_draws() if you want draws from the linear predictor or the new [add_]epred_draws() if you want draws from the expectation of the posterior predictive (which is what fitted_draws() was most typically used for).value, but retain function-specific default column names. E.g. the prediction argument for predicted_draws() is now spelled value but has a default of ".prediction". One breaking change is that the default output column for linpred_draws() is now ".linpred" instead of ".value". This should make it easier to combine outputs across multiple functions while also making it easier to remember the name of the argument that changes the output column name.n argument is now spelled ndraws to be more consistent with terminology in the posterior package and to prevent partial argument name matching bugs with newdata.object instead of model, in order to match with argument names in posterior_predict(), etc. This was necessary to prevent partial argument name matching bugs with certain model types in rstanarm that have an m argument to their prediction functions.New features:
posterior package:
_rvars counterparts to the _draws family of functions, including spread_rvars(), gather_rvars(), epred_rvars(), linpred_rvars(), and predicted_rvars(), which add columns of posterior::rvar() objects to data frames instead of long-format columns of draws. These can be easier to read and take up less memory than the long-format data frames of draws. See vignette("tidy-posterior") for examples.nest_rvars() and unnest_rvars() functions for converting between data frames of rvars and long format data frames of draws.tidy_draws() has been rebuilt on top of posterior::as_draws_df(), which means it should support even more model types and benefit from efficiency improvements in posterior. This means that cmdstanr is now supported, for example.posterior::summarise_draws() for grouped data frames of draws: summarise_draws.grouped_df()
compare_levels() now supports data frames of posterior::rvar()s.epred_draws(), linpred_draws(), and predicted_draws() functions should now support any models that implement posterior_epred(), posterior_linpred(), and posterior_predict() so long as they take a newdata argument.forcats, plyr, and purrr.seed when subsampling to several functions (#276).New documentation:
vignette("tidy-posterior") describing the use of tidybayes with posterior, and particularly the posterior::rvar() data type. This vignette also includes an updated version of the ordinal regression example from vignette("tidy-brms"), now with an illustration of the relationship between the latent linear predictor and the category-level probabilities.Bug fixes:
tidy_draws() if retrieving them results in an error (#244)compare_levels() (#272)emmeans package to be used with compare_levels() via the new emmeans_comparison() function (#272)tidybayes into tidybayes and ggdist (#250). ggdist now contains all stats/geoms from tidybayes (except deprecated ones), all support functions for stats/geoms (such as point_interval()), vignette("slabinterval"), and vignette("freq-uncertainty-vis"). tidybayes retains all other functions, and re-exports all ggdist functions for now.ggplot2. If needed, this can be overridden using the existing orientation parameter.
h-suffix geoms are now deprecated. The h-suffix geoms have been left in tidybayes and give a deprecation warning when used; they cannot be used from ggdist directly.h-suffix point_interval() functions are also deprecated, since they are not needed in tidybayes nor in ggplot2::stat_summary().geom_interval(), geom_pointinterval(), and geom_lineribbon() no longer automatically set the ymin and ymax aesthetics if .lower or .upper are present in the data. This allows them to work better with automatic orientation detection (and was a bad feature to have existed in the first place anyway). The deprecated tidybayes::geom_intervalh() and tidybayes::geom_pointintervalh() still automatically set those aesthetics, since they are deprecated anyway (so supporting the old behavior is fine in these functions).geom_lineribbon()/stat_lineribbon() now supports a step argument for creating stepped lineribbons (#249). H/T to Solomon Kurz for the suggestion.ggdist now has its own implementation of the scaled and shifted Student’s t distribution (dstudent_t(), qstudent_t(), etc), since it is very useful for visualizing confidence distributions. That is re-exported in tidybayes as well`.Various minor forward and backward compatibility fixes:
stringsAsFactors issues for R 4[[<- for R 4parse() instead of str2lang() for compatibility with R <= 3.6geom_slabinterval() and stat_slabinterval() “meta-geom” (#84). This has enabled a bunch of new geoms to be created (see vignette("slabinterval") and fixed a number of outstanding issues:
position = "dodge" correctly (#180)geom_dots() and geom_dotsinterval() (#210). These include a quantiles parameter on the stats to make it easy to create quantile dotplots.stat_dist_... family of geoms for both the geom_slabinterval() family and geom_lineribbon() (see stat_dist_slabinterval() and stat_dist_lineribbon()).parse_dist(), which parses distribution specifications (like normal(0,1)) into tidy columns, can be combined with the stat_dist_... family of geoms to easily to visualize priors (e.g. from brms).dlkjcorr_marginal() and company), combined with parse_dist() and the stat_dist_... family make it easy to visualize the marginal LKJ prior on a cell in a correlation matrix. (#191 #192)vignette("freq-uncertainty-vis"), also made possible by the new stat_dist_... family of geoms (#188)tidy_draws() can now be applied to already-tidied data frames, allowing dependent functions (like spread_draws() and gather_draws()) to also be applied to data frames directly (#82). This can be a useful optimization in workflows where the initial tidying is slow but spreading/gathering is fast (see discussion in #144)stat_dist_slabh(). An example of this usage is in vignette("tidy-brms").hdi() now uses trimmed densities by default to avoid odd behavior with bounded distributions (#165).compare_levels(comparison = ) now uses a modern tidy approach to dealing with unevaluated expressions, so rlang::exprs() can be used in place of plyr::.() (#174, #175)geom_lineribbon() now works with ggnewscale (#178)fitted_draws()/predicted_draws() give more helpful error messages on unsupported models (#177)New features and documentation:
Bug fixes:
New features and documentation:
Minor changes:
predicted_draws(), closes #134emm_list in gather_emmeans_draws(), closes #126geom_lineribbon() color black, closes #153gather_pairs method for creating custom scatterplot matrices (and more!)NA values are now better supported in point_interval, and it has an na.rm argument (#123)Suggests