tidybayes-deprecated: Deprecated functions, arguments, and column names in...

In tidybayes: Tidy Data and 'Geoms' for Bayesian Models

Deprecated functions, arguments, and column names in tidybayes

Description

Deprecated functions, arguments, and column names and their alternatives are listed below. Many of the deprecations are due to a naming scheme overhaul in tidybayes version 1.0 (see Deprecated Functions and Deprecated Arguments and Column Names below) or due to the deprecation of horizontal shortcut geoms and stats in tidybayes 2.1 (see Deprecated Horizontal Shortcut Geoms and Stats).

Deprecated Functions

Several deprecated versions of functions use slightly different output formats (e.g., they use names like term and estimate where new functions use .variable and .value; or they set .iteration even when iteration information is not available — new functions always set .draw but may not set .iteration), so be careful when upgrading to new function names. See Deprecated Arguments and Column Names, below, for more information.

Functions deprecated in tidybayes 3.0:

• fitted_draws and add_fitted_draws are deprecated because their names were confusing: it was unclear to many users if these functions returned draws from the posterior predictive, the mean of the posterior predictive, or the linear predictor (and depending on model type it might have been either of the latter). Use epred_draws()/add_epred_draws() if you want the expectation of the posterior predictive and use linpred_draws()/add_linpred_draws() if you want the linear predictor.

Functions deprecated in tidybayes 1.0:

• spread_samples, extract_samples, and tidy_samples are deprecated names for spread_draws(). The spread/gather terminology better distinguishes the resulting data frame format, and draws is more correct terminology than samples for describing multiple realizations from a posterior distribution.

• gather_samples is a deprecated name for gather_draws(), reflecting a package-wide move to using draws instead of samples for describing multiple realizations from a distribution.

• unspread_samples is a deprecated name for unspread_draws(), reflecting a package-wide move to using draws instead of samples for describing multiple realizations from a distribution.

• ungather_samples is a deprecated name for ungather_draws(), reflecting a package-wide move to using draws instead of samples for describing multiple realizations from a distribution.

• fitted_samples / add_fitted_samples are deprecated names for fitted_draws / add_fitted_draws, reflecting a package-wide move to using draws instead of samples for describing multiple realizations from a distribution. (though see the note above about the deprecation of fitted_draws in favor of epred_draws() and linpred_draws()).

• predicted_samples / add_predicted_samples are deprecated names for predicted_draws() / add_predicted_draws(), reflecting a package-wide move to using draws instead of samples for describing multiple realizations from a distribution.

• gather_lsmeans_samples and gather_emmeans_samples are deprecated aliases for gather_emmeans_draws(). The new name (estimated marginal means) is more appropriate for Bayesian models than the old name (least-squares means), and reflects the naming of the newer emmeans package. It also reflects a package-wide move to using draws instead of samples for describing multiple realizations from a distribution.

• as_sample_tibble and as_sample_data_frame are deprecated aliases for tidy_draws(). The original intent of as_sample_tibble was to be used primarily internally (hence its less user-friendly name); however, increasingly I have come across use cases of tidy_draws that warrant a more user-friendly name. It also reflects a package-wide move to using draws instead of samples for describing multiple realizations from a distribution.

• ggeye is deprecated: for a package whose goal is flexible and customizable visualization, monolithic functions are inflexible and do not sufficiently capitalize on users' existing knowledge of ggplot; instead, I think it is more flexible to design geoms and stats that can used within a complete ggplot workflow. stat_eye() offers a horizontal eye plot geom that can be used instead of ggeye.

• See the sections below for additional deprecated functions, including horizontal geoms, stats, and point_intervals

Deprecated Eye Geom Spellings

geom_eye, geom_eyeh, and geom_halfeyeh are deprecated spellings of stat_eye() and stat_halfeye() from before name standardization of stats and geoms. Use those functions instead.

Deprecated Horizontal Shortcut Geoms and Stats

Due to the introduction of automatic orientation detection in tidybayes 2.1, shortcut geoms and stats (which end in h) are no longer necessary, and are deprecated. In most cases, these can simply be replaced with the same geom without the h suffix and they will remain horizontal; e.g. stat_halfeyeh(...) can simply be replaced with stat_halfeye(...). If automatic orientation detection fails, override it with the orientation parameter; e.g. stat_halfeye(orientation = "horizontal").

These deprecated stats and geoms include:

• stat_eyeh / stat_dist_eyeh

• stat_halfeyeh / stat_dist_halfeyeh

• geom_slabh / stat_slabh / stat_dist_slabh

• geom_intervalh / stat_intervalh / stat_dist_intervalh

• geom_pointintervalh / stat_pointintervalh / stat_dist_pointintervalh

• stat_gradientintervalh / stat_dist_gradientintervalh

• stat_cdfintervalh / stat_dist_cdfintervalh

• stat_ccdfintervalh / stat_dist_ccdfintervalh

• geom_dotsh / stat_dotsh / stat_dist_dotsh

• geom_dotsintervalh / stat_intervalh / stat_dist_intervalh

• stat_histintervalh

Deprecated Horizontal Point/Interval Functions

These functions ending in h (e.g., point_intervalh, median_qih) used to be needed for use with ggstance::stat_summaryh, but are no longer necessary because ggplot2::stat_summary() supports automatic orientation detection, so they have been deprecated. They behave identically to the corresponding function without the h, except that when passed a vector, they return a data frame with x/xmin/xmax instead of y/ymin/ymax.

• point_intervalh

• mean_qih / median_qih / mode_qih

• mean_hdih / median_hdih / mode_hdih

• mean_hdcih / median_hdcih / mode_hdcih

Deprecated Arguments and Column Names

Arguments deprecated in tidybayes 3.0 are:

• The n argument is now called ndraws in predicted_draws(), linpred_draws(), etc. This prevents some bugs due to partial matching of argument names where n might be mistaken for newdata.

• The value argument in linpred_draws() is now spelled linpred and defaults to ".linpred" in the same way that the predicted_draws() and epred_draws() functions work.

• The scale argument in linpred_draws() is no longer allowed (use transform instead) as this naming scheme only made sense when linpred_draws() was an alias for fitted_draws(), which it no longer is (see note above about the deprecation of fitted_draws()).

Versions of tidybayes before version 1.0 used a different naming scheme for several arguments and output columns.

Arguments and column names deprecated in tidybayes 1.0 are:

• term is now .variable

• estimate is now .value

• pred is now .prediction

• conf.low is now .lower

• conf.high is now .upper

• .prob is now .width

• The .draw column was added, and should be used instead of .chain and .iteration to uniquely identify draws when you do not care about chains. (.chain and .iteration are still provided for identifying draws within chains, if desired).

To translate to/from the old naming scheme in output, use to_broom_names() and from_broom_names().

Many of these names were updated in version 1.0 in order to make terminology more consistent and in order to satisfy these criteria:

• Ignore compatibility with broom names on the assumption an adapter function can be created.

• Use names that could be compatible with frequentist approaches (hence .width instead of .prob).

• Always precede with "." to avoid collisions with variable names in models.

• No abbreviations (remembering if something is abbreviated or not can be a pain).

• No two-word names (multi-word names can always be standardized on and used in documentation, but I think data frame output should be succinct).

• Names should be nouns (I made an exception for lower/upper because they are common).

Author(s)

Matthew Kay

tidybayes documentation built on Aug. 13, 2023, 1:06 a.m.