-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathmarginal_effects.brmsfit.Rmd
171 lines (151 loc) · 11.1 KB
/
marginal_effects.brmsfit.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
---
title: "``brms::marginal_effects.brmsfit``"
output: html_document
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
library(brms)
```
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
<pre><code>
## S3 method for class 'brmsfit'
marginal_effects(x, effects = NULL, conditions = NULL, int_conditions = NULL, re_formula = NA, robust = TRUE, probs = c(0.025, 0.975), method = c("fitted", "predict"), spaghetti = FALSE, surface = FALSE, categorical = FALSE,
ordinal = FALSE, transform = NULL, resolution = 100, select_points = 0, too_far = 0, ...) marginal_effects(x, ...)
## S3 method for class 'brmsMarginalEffects'
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(),
theme = NULL, ask = TRUE, plot = TRUE, ...)
</code></pre>
#### Arguments
* ``x``: An R 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 originally modeled.
* ``conditions``: An optional data.frame containing variable values to condition on. Each effect
defined in effects will be plotted separately for each row of conditions. values in the cond__ column will be used as titles of the subplots. If ``cond__`` is not given, the row names will be used for this purpose instead. It is recommended to only define a few rows in order to keep the plots clear. See make_conditions
for an easy way to define conditions. If NULL (the default), numeric variables will be marginalized by using their means and factors will get their reference level assigned.
* ``int_conditions``: An optional named list whose elements are numeric vectors of values of the second variables in two-way interactions. At these values, predictions are evaluated. The names of int_conditions have to match the variable names exactly.
Additionally, the elements of the numeric vectors may be named themselves, in which case their names appear as labels for the conditions in the plots. Instead of vectors, functions returning vectors may be passed and are applied on the original values of the corresponding variable. If NULL (the default), predictions are evaluated at the mean and at mean + = sd.
* ``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.
* ``spaghetti``: Logical. Indicates if predictions should be visualized via spaghetti plots. Only applied for numeric predictors. If TRUE, it is recommended to set argument nsamples to a relatively small value (e.g. 100) in order to reduce computation
time.
* ``surface``: Logical. Indicates if interactions or two-dimensional smooths should be visualized
as a surface. Defaults to FALSE. The surface type can be controlled via
argument stype of the related plotting method.
* ``categorical``: Logical. Indicates if effects of categorical or ordinal models should be shown in terms of probabilities of response categories. Defaults to FALSE.
* ordinal Deprecated! Please use argument categorical. Logical. Indicates if effects in ordinal models should be visualized as a raster with the response categories on the y-axis. Defaults to FALSE.
* ``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 method = "predict".
* ``resolution``: Number of support points used to generate the plots. Higher resolution leads to smoother plots. Defaults to 100. If surface is TRUE, this implies 10000 support points for interaction terms, so it might be necessary to reduce resolution
when only few RAM is available.
* ``select_points:``: Positive number. Only relevant if points or rug are set to TRUE: Actual data points of numeric variables that are too far away from the values specified in conditions can be excluded from the plot. Values are scaled into the unit interval and then points more than select_points from the values in conditions are excluded. By default, all points are used.
* ``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. ``too_far`` determines what is too far. The grid is scaled into the unit square and then grid points more than
too_far from the predictor variables are excluded. By default, all grid points are used. Ignored for non-surface plots.
* ``...``: Further arguments such as subset or nsamples passed to predict or fitted.
* ``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 conditions.
* ``points``: Logical; indicating whether the original data points should be added via geom_jitter.
Default is FALSE. Note that only those data points will be added that match the specified conditions defined in conditions. For categorical predictors, the conditions have to match exactly. For numeric predictors, argument select_points
is used to determine, which points do match a condition.
* rug Logical; indicating whether a rug representation of predictor values should be added via geom_rug. Default is FALSE. Depends on select_points in the same way as points does.
* ``mean``: Logical; only relevant for spaghetti plots. If TRUE (the default), display the mean regression line on top of the regression lines for each sample.
* ``jitter_width``: Only used if points = TRUE: Amount of horizontal jittering of the data points. Mainly useful for ordinal models. Defaults to 0 that is no jittering.
* stype Indicates how surface plots should be displayed. Either "contour" or "raster".
* ``line_args``: Only used in plots of continuous predictors: A named list of arguments passed
to geom_smooth.
* ``cat_args``: Only used in plots of categorical predictors: A named list of arguments
passed to geom_point.
* ``errorbar_args``: Only used in plots of categorical predictors: A named list of arguments passed to geom_errorbar.
* ``surface_args``: Only used in surface plots: A named list of arguments passed to geom_contour
or geom_raster (depending on argument stype).
spaghetti_args Only used in spaghetti plots: A named list of arguments passed to geom_smooth.
point_args Only used if points = TRUE: A named list of arguments passed to geom_jitter.
rug_args Only used if rug = TRUE: A named list of arguments passed to geom_rug.
100 marginal_effects.brmsfit
theme A theme object modifying the appearance of the plots. For some basic themes
see ggtheme and theme_default.
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.
### Examples
```{r}
## Not run:
fit <- brm(count ~ log_Age_c + log_Base4_c * Trt + (1 | patient),
data = epilepsy, family = poisson())
## plot all marginal effects
plot(marginal_effects(fit), ask = FALSE)
## change colours to grey scale
me <- marginal_effects(fit, "log_Base4_c:Trt")
plot(me, plot = FALSE)[[1]] +
scale_color_grey() +
scale_fill_grey()
```
```{r}
## only plot the marginal interaction effect of 'log_Base4_c:Trt'
marginal_smooths.brmsfit 101
## 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",
conditions = conditions))
```
```{r}
## 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",
conditions = conditions, re_formula = NULL),
points = TRUE, rug = TRUE)
```
```{r}
## change handling of two-way interactions
int_conditions <- list(
log_Base4_c = setNames(c(-2, 1, 0), c("b", "c", "a"))
)
```
```{r}
marginal_effects(fit, effects = "Trt:log_Base4_c",
int_conditions = int_conditions)
marginal_effects(fit, effects = "Trt:log_Base4_c",
int_conditions = list(log_Base4_c = quantile))
```
```{r}
## fit a model to illustrate how to plot 3-way interactions
fit3way <- brm(count ~ log_Age_c * log_Base4_c * Trt, data = epilepsy)
conditions <- make_conditions(fit3way, "log_Age_c")
marginal_effects(
fit3way, "log_Base4_c:Trt", conditions = conditions
)
```
```{r}
## only include points close to the specified #### Values of log_Age_c
me <- marginal_effects(
fit3way, "log_Base4_c:Trt", conditions = conditions,
select_points = 0.1
)
plot(me, points = TRUE)
## End(Not run)
```{r}
#### 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
When creating marginal_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. Since we condition on rather than actually marginalizing
variables, the name marginal_effects is possibly not ideally chosen in retrospect.
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.
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.