brms (version 1.3.1)

marginal_effects.brmsfit: Display marginal effects of predictors

Description

Display marginal effects of one or more numeric and/or categorical predictors including two-way interaction effects.

Usage

"marginal_effects"(x, effects = NULL, conditions = NULL, re_formula = NA, robust = TRUE, probs = c(0.025, 0.975), method = c("fitted", "predict"), contour = FALSE, resolution = 100, ...)
marginal_effects(x, ...)
"plot"(x, ncol = NULL, points = FALSE, rug = FALSE, theme = bayesplot::theme_default(), ask = TRUE, plot = TRUE, ...)

Arguments

x

An object usually of class brmsfit.

effects

An optional character vector naming effects (main effects or interactions) for which to compute marginal plots. Interactions are specified by a : between variable names. If NULL (the default), plots are generated for all main effects and two-way interactions estimated in the model. When specifying effects manually, all two-way interactions may be plotted even if not orginally modeled.

conditions

An optional data.frame containing variable values to marginalize on. Each effect defined in effects will be plotted separately for each row of data. The row names of data will be treated as titles of the subplots. It is recommended to only define a few rows in order to keep the plots clear. If NULL (the default), numeric variables will be marginalized by using their means and factors will get their reference level assigned.

re_formula

A formula containing random effects to be considered in the marginal predictions. If NULL, include all random effects; if NA (default), include no random effects.

robust

If TRUE (the default) the median is used as the measure of central tendency. If FALSE the mean is used instead.

probs

The quantiles to be used in the computation of credible intervals (defaults to 2.5 and 97.5 percent quantiles)

method

Either "fitted" or "predict". If "fitted", plot marginal predictions of the regression curve. If "predict", plot marginal predictions of the responses.

contour

Logical; Indicates whether interactions should be visualized with a contour plot. Defaults to FALSE.

resolution

Number of support points used to generate the plots. Higher resolution leads to smoother plots. Defaults to 100. If contour is TRUE, this implies 10000 support points for interaction terms, so it might be necessary to reduce resolution when only few RAM is available.

...

Currently ignored.

ncol

Number of plots to display per column for each effect. If NULL (default), ncol is computed internally based on the number of rows of data.

points

Logical; indicating whether the original data points should be added via geom_point. Default is FALSE. Note that only those data points will be added that match the specified conditions defined in conditions.

rug

Logical; indicating whether a rug representation of predictor values should be added via geom_rug. Default is FALSE.

theme

A theme object modifying the appearance of the plots. For some basic themes see ggtheme and theme_default. Can be defined globally for the current session, via theme_set.

ask

logical; indicates if the user is prompted before a new page is plotted. Only used if plot is TRUE.

plot

logical; indicates if plots should be plotted directly in the active graphic device. Defaults to TRUE.

Value

An object of class brmsMarginalEffects, which is a named list with one data.frame per effect containing all information required to generate marginal 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.

Details

NA values within factors in conditions, are interpreted as if all dummy variables of this factor are zero. This allows, for instance, to make predictions of the grand mean when using sum coding.

Examples

## Not run: 
# fit <- brm(count ~ log_Age_c + log_Base4_c * Trt_c + (1 | patient),
#            data = epilepsy, family = poisson()) 
#            
# ## plot all marginal effects
# plot(marginal_effects(fit), ask = FALSE)
# 
# ## only plot the marginal interaction effect of 'log_Base4_c:Trt_c'
# ## for different values for 'log_Age_c'
# conditions <- data.frame(log_Age_c = c(-0.3, 0, 0.3))
# plot(marginal_effects(fit, effects = "log_Base4_c:Trt_c", 
#                       conditions = conditions))
#                       
# ## also incorporate random effects variance over patients
# ## also add data points and a rug representation of predictor values
# plot(marginal_effects(fit, effects = "log_Base4_c:Trt_c", 
#                       conditions = conditions, re_formula = NULL), 
#      points = TRUE, rug = TRUE)
#      
# ## fit a model to illustrate how to plot 3-way interactions
# fit3way <- brm(count ~ log_Age_c * log_Base4_c * Trt_c, data = epilepsy)
# conditions <- data.frame(log_Age_c = c(-0.3, 0, 0.3))
# rownames(conditions) <- paste("log_Age_c =", conditions$log_Age_c)
# plot(marginal_effects(fit3way, "log_Base4_c:Trt_c",
#                       conditions = conditions))
# ## End(Not run)