R/conditional_effects.R
conditional_effects.brmsfit.Rd
Display conditional effects of one or more numeric and/or categorical predictors including twoway interaction effects.
# S3 method for brmsfit conditional_effects( x, effects = NULL, conditions = NULL, int_conditions = NULL, re_formula = NA, prob = 0.95, robust = TRUE, method = "posterior_epred", spaghetti = FALSE, surface = FALSE, categorical = FALSE, ordinal = FALSE, transform = NULL, resolution = 100, select_points = 0, too_far = 0, probs = NULL, ... ) conditional_effects(x, ...) # S3 method for brms_conditional_effects plot( x, ncol = NULL, points = FALSE, rug = FALSE, mean = TRUE, jitter_width = 0, stype = c("contour", "raster"), line_args = list(), cat_args = list(), errorbar_args = list(), surface_args = list(), spaghetti_args = list(), point_args = list(), rug_args = list(), facet_args = list(), theme = NULL, ask = TRUE, plot = TRUE, ... )
x  An object of class 

effects  An optional character vector naming effects (main effects or
interactions) for which to compute conditional plots. Interactions are
specified by a 
conditions  An optional 
int_conditions  An optional named 
re_formula  A formula containing grouplevel effects to be considered
in the conditional predictions. If 
prob  A value between 0 and 1 indicating the desired probability to be covered by the uncertainty intervals. The default is 0.95. 
robust  If 
method  Method used to obtain predictions. Can be set to

spaghetti  Logical. Indicates if predictions should
be visualized via spaghetti plots. Only applied for numeric
predictors. If 
surface  Logical. Indicates if interactions or
twodimensional smooths should be visualized as a surface.
Defaults to 
categorical  Logical. Indicates if effects of categorical
or ordinal models should be shown in terms of probabilities
of response categories. Defaults to 
ordinal  (Deprecated) Please use argument 
transform  A function or a character string naming
a function to be applied on the predicted responses
before summary statistics are computed. Only allowed
if 
resolution  Number of support points used to generate
the plots. Higher resolution leads to smoother plots.
Defaults to 
select_points  Positive number.
Only relevant if 
too_far  Positive number.
For surface plots only: Grid points that are too
far away from the actual data points can be excluded from the plot.

probs  (Deprecated) The quantiles to be used in the computation of
uncertainty intervals. Please use argument 
...  Further arguments such as 
ncol  Number of plots to display per column for each effect.
If 
points  Logical. Indicates if the original data points
should be added via 
rug  Logical. Indicates if a rug representation of predictor
values should be added via 
mean  Logical. Only relevant for spaghetti plots.
If 
jitter_width  Only used if 
stype  Indicates how surface plots should be displayed.
Either 
line_args  Only used in plots of continuous predictors:
A named list of arguments passed to

cat_args  Only used in plots of categorical predictors:
A named list of arguments passed to

errorbar_args  Only used in plots of categorical predictors:
A named list of arguments passed to

surface_args  Only used in surface plots:
A named list of arguments passed to

spaghetti_args  Only used in spaghetti plots:
A named list of arguments passed to

point_args  Only used if 
rug_args  Only used if 
facet_args  Only used if if multiple condtions are provided:
A named list of arguments passed to

theme  A 
ask  Logical; indicates if the user is prompted
before a new page is plotted.
Only used if 
plot  Logical; indicates if plots should be
plotted directly in the active graphic device.
Defaults to 
An object of class 'brms_conditional_effects'
which is a
named list with one data.frame per effect containing all information
required to generate conditional effects plots. Among others, these
data.frames contain some special variables, namely estimate__
(predicted values of the response), se__
(standard error of the
predicted response), lower__
and upper__
(lower and upper
bounds of the uncertainty interval of the response), as well as
cond__
(used in faceting when conditions
contains multiple
rows).
The corresponding plot
method returns a named
list of ggplot
objects, which can be further
customized using the ggplot2 package.
When creating conditional_effects
for a particular predictor
(or interaction of two predictors), one has to choose the values of all
other predictors to condition on. By default, the mean is used for
continuous variables and the reference category is used for factors, but
you may change these values via argument conditions
. This also has
an implication for the points
argument: In the created plots, only
those points will be shown that correspond to the factor levels actually
used in the conditioning, in order not to create the false impression of
bad model fit, where it is just due to conditioning on certain factor
levels.
To fully change colors of the created plots, one has to amend both
scale_colour
and scale_fill
. See
scale_colour_grey
or scale_colour_gradient
for
more details.
if (FALSE) { fit < brm(count ~ zAge + zBase * Trt + (1  patient), data = epilepsy, family = poisson()) ## plot all conditional effects plot(conditional_effects(fit), ask = FALSE) ## change colours to grey scale library(ggplot2) me < conditional_effects(fit, "zBase:Trt") plot(me, plot = FALSE)[[1]] + scale_color_grey() + scale_fill_grey() ## only plot the conditional interaction effect of 'zBase:Trt' ## for different values for 'zAge' conditions < data.frame(zAge = c(1, 0, 1)) plot(conditional_effects(fit, effects = "zBase:Trt", conditions = conditions)) ## also incorporate grouplevel effects variance over patients ## also add data points and a rug representation of predictor values plot(conditional_effects(fit, effects = "zBase:Trt", conditions = conditions, re_formula = NULL), points = TRUE, rug = TRUE) ## change handling of twoway interactions int_conditions < list( zBase = setNames(c(2, 1, 0), c("b", "c", "a")) ) conditional_effects(fit, effects = "Trt:zBase", int_conditions = int_conditions) conditional_effects(fit, effects = "Trt:zBase", int_conditions = list(zBase = quantile)) ## fit a model to illustrate how to plot 3way interactions fit3way < brm(count ~ zAge * zBase * Trt, data = epilepsy) conditions < make_conditions(fit3way, "zAge") conditional_effects(fit3way, "zBase:Trt", conditions = conditions) ## only include points close to the specified values of zAge me < conditional_effects( fit3way, "zBase:Trt", conditions = conditions, select_points = 0.1 ) plot(me, points = TRUE) }