add_epred_rvars {tidybayes} | R Documentation |
Add rvar
s for the linear predictor, posterior expectation, posterior predictive, or residuals of a model to a data frame
Description
Given a data frame and a model, adds rvar
s of draws from the linear/link-level predictor,
the expectation of the posterior predictive, or the posterior predictive to
the data frame.
Usage
add_epred_rvars(
newdata,
object,
...,
value = ".epred",
ndraws = NULL,
seed = NULL,
re_formula = NULL,
dpar = NULL,
columns_to = NULL
)
epred_rvars(
object,
newdata,
...,
value = ".epred",
ndraws = NULL,
seed = NULL,
re_formula = NULL,
dpar = NULL,
columns_to = NULL
)
## Default S3 method:
epred_rvars(
object,
newdata,
...,
value = ".epred",
seed = NULL,
dpar = NULL,
columns_to = NULL
)
## S3 method for class 'stanreg'
epred_rvars(
object,
newdata,
...,
value = ".epred",
ndraws = NULL,
seed = NULL,
re_formula = NULL,
dpar = NULL,
columns_to = NULL
)
## S3 method for class 'brmsfit'
epred_rvars(
object,
newdata,
...,
value = ".epred",
ndraws = NULL,
seed = NULL,
re_formula = NULL,
dpar = NULL,
columns_to = NULL
)
add_linpred_rvars(
newdata,
object,
...,
value = ".linpred",
ndraws = NULL,
seed = NULL,
re_formula = NULL,
dpar = NULL,
columns_to = NULL
)
linpred_rvars(
object,
newdata,
...,
value = ".linpred",
ndraws = NULL,
seed = NULL,
re_formula = NULL,
dpar = NULL,
columns_to = NULL
)
## Default S3 method:
linpred_rvars(
object,
newdata,
...,
value = ".linpred",
seed = NULL,
dpar = NULL,
columns_to = NULL
)
## S3 method for class 'stanreg'
linpred_rvars(
object,
newdata,
...,
value = ".linpred",
ndraws = NULL,
seed = NULL,
re_formula = NULL,
dpar = NULL,
columns_to = NULL
)
## S3 method for class 'brmsfit'
linpred_rvars(
object,
newdata,
...,
value = ".linpred",
ndraws = NULL,
seed = NULL,
re_formula = NULL,
dpar = NULL,
columns_to = NULL
)
add_predicted_rvars(
newdata,
object,
...,
value = ".prediction",
ndraws = NULL,
seed = NULL,
re_formula = NULL,
columns_to = NULL
)
predicted_rvars(
object,
newdata,
...,
value = ".prediction",
ndraws = NULL,
seed = NULL,
re_formula = NULL,
columns_to = NULL
)
## Default S3 method:
predicted_rvars(
object,
newdata,
...,
value = ".prediction",
seed = NULL,
columns_to = NULL
)
## S3 method for class 'stanreg'
predicted_rvars(
object,
newdata,
...,
value = ".prediction",
ndraws = NULL,
seed = NULL,
re_formula = NULL,
columns_to = NULL
)
## S3 method for class 'brmsfit'
predicted_rvars(
object,
newdata,
...,
value = ".prediction",
ndraws = NULL,
seed = NULL,
re_formula = NULL,
columns_to = NULL
)
Arguments
newdata |
Data frame to generate predictions from. |
object |
A supported Bayesian model fit that can provide fits and predictions. Supported models
are listed in the second section of tidybayes-models: Models Supporting Prediction. While other
functions in this package (like |
... |
Additional arguments passed to the underlying prediction method for the type of model given. |
value |
The name of the output column:
|
ndraws |
The number of draws to return, or |
seed |
A seed to use when subsampling draws (i.e. when |
re_formula |
formula containing group-level effects to be considered in the prediction.
If |
dpar |
For |
columns_to |
For some models, such as ordinal, multinomial, and multivariate models (notably, |
Details
Consider a model like:
This model has:
an outcome variable,
a response distribution,
, having parameters
(with link function
) and
(with link function
)
a single predictor,
coefficients
,
,
, and
We fit this model to some observed data, , and predictors,
. Given new values of predictors,
,
supplied in the data frame
newdata
, the functions for posterior draws are
defined as follows:
-
add_predicted_rvars()
addsrvar
s containing draws from the posterior predictive distribution,, to the data. It corresponds to
rstanarm::posterior_predict()
orbrms::posterior_predict()
. -
add_epred_rvars()
addsrvar
s containing draws from the expectation of the posterior predictive distribution, aka the conditional expectation,, to the data. It corresponds to
rstanarm::posterior_epred()
orbrms::posterior_epred()
. Not all models support this function. -
add_linpred_rvars()
addsrvar
s containing draws from the posterior linear predictors to the data. It corresponds torstanarm::posterior_linpred()
orbrms::posterior_linpred()
. Depending on the model type and additional parameters passed, this may be:The untransformed linear predictor, e.g.
=
. This is returned by
add_linpred_rvars(transform = FALSE)
for brms and rstanarm models. It is analogous totype = "link"
inpredict.glm()
.The inverse-link transformed linear predictor, e.g.
=
. This is returned by
add_linpred_rvars(transform = TRUE)
for brms and rstanarm models. It is analogous totype = "response"
inpredict.glm()
.
NOTE:
add_linpred_rvars(transform = TRUE)
andadd_epred_rvars()
may be equivalent but are not guaranteed to be. They are equivalent when the expectation of the response distribution is equal to its first parameter, i.e. when. Many distributions have this property (e.g. Normal distributions, Bernoulli distributions), but not all. If you want the expectation of the posterior predictive, it is best to use
add_epred_rvars()
if available, and if not available, verify this property holds prior to usingadd_linpred_rvars()
.
The corresponding functions without add_
as a prefix are alternate spellings
with the opposite order of the first two arguments: e.g. add_predicted_rvars(newdata, object)
versus predicted_rvars(object, newdata)
. This facilitates use in data
processing pipelines that start either with a data frame or a model.
Given equal choice between the two, the spellings prefixed with add_
are preferred.
Value
A data frame (actually, a tibble) equal to the input newdata
with
additional columns added containing rvar
s representing the requested predictions or fits.
Author(s)
Matthew Kay
See Also
add_predicted_draws()
for the analogous functions that use a long-data-frame-of-draws
format instead of a data-frame-of-rvar
s format. See spread_rvars()
for manipulating posteriors directly.
Examples
## Not run:
library(ggplot2)
library(dplyr)
library(posterior)
library(brms)
library(modelr)
theme_set(theme_light())
m_mpg = brm(mpg ~ hp * cyl, data = mtcars, family = lognormal(),
# 1 chain / few iterations just so example runs quickly
# do not use in practice
chains = 1, iter = 500)
# Look at mean predictions for some cars (epred) and compare to
# the exponeniated mu parameter of the lognormal distribution (linpred).
# Notice how they are NOT the same. This is because exp(mu) for a
# lognormal distribution is equal to its median, not its mean.
mtcars %>%
select(hp, cyl, mpg) %>%
add_epred_rvars(m_mpg) %>%
add_linpred_rvars(m_mpg, value = "mu") %>%
mutate(expmu = exp(mu), .epred - expmu)
# plot intervals around conditional means (epred_rvars)
mtcars %>%
group_by(cyl) %>%
data_grid(hp = seq_range(hp, n = 101)) %>%
add_epred_rvars(m_mpg) %>%
ggplot(aes(x = hp, color = ordered(cyl), fill = ordered(cyl))) +
stat_lineribbon(aes(dist = .epred), .width = c(.95, .8, .5), alpha = 1/3) +
geom_point(aes(y = mpg), data = mtcars) +
scale_color_brewer(palette = "Dark2") +
scale_fill_brewer(palette = "Set2")
# plot posterior predictive intervals (predicted_rvars)
mtcars %>%
group_by(cyl) %>%
data_grid(hp = seq_range(hp, n = 101)) %>%
add_predicted_rvars(m_mpg) %>%
ggplot(aes(x = hp, color = ordered(cyl), fill = ordered(cyl))) +
stat_lineribbon(aes(dist = .prediction), .width = c(.95, .8, .5), alpha = 1/3) +
geom_point(aes(y = mpg), data = mtcars) +
scale_color_brewer(palette = "Dark2") +
scale_fill_brewer(palette = "Set2")
## End(Not run)