R/deprecated.R
tidybayes-deprecated.RdDeprecated 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).
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
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.
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
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
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).