-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathREADME.Rmd
276 lines (224 loc) · 14.9 KB
/
README.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
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
---
output: github_document
---
```{r, message = FALSE, tidy = FALSE, echo = F}
## knitr configuration: http://yihui.name/knitr/options#chunk_options
library(knitr)
showMessage <- FALSE
showWarning <- TRUE
set_alias(w = "fig.width", h = "fig.height", res = "results")
opts_chunk$set(comment = "##", error= TRUE, warning = showWarning, message = showMessage,
tidy = FALSE, cache = FALSE, echo = TRUE,
fig.width = 7, fig.height = 7,
fig.path = "man/figures")
## for rgl
## knit_hooks$set(rgl = hook_rgl, webgl = hook_webgl)
## for animation
opts_knit$set(animation.fun = hook_ffmpeg_html)
## R configuration
options(width = 116, scipen = 5)
```
# regmedint <img src="man/figures/hex.png" align="right" height="140"/>
[](https://github.com/kaz-yos/regmedint/actions)
[](http://www.r-pkg.org/pkg/regmedint)
[](http://www.r-pkg.org/pkg/regmedint)
This is an extension of the regression-based causal mediation analysis first proposed by Valeri and VanderWeele (2013) and Valeri and VanderWeele (2015). The current version supports including effect measure modification by covariates (treatment-covariate and mediator-covariate product terms in mediator and outcome regression models). It also accommodates the original 'SAS' macro (can be found at Dr. VanderWeele's [Tools and Tutorials](https://www.hsph.harvard.edu/tyler-vanderweele/tools-and-tutorials/)) and PROC CAUSALMED procedure in 'SAS' when there is no effect measure modification. Linear and logistic models are supported for the mediator model. Linear, logistic, loglinear, Poisson, negative binomial, Cox, and accelerated failure time (exponential and Weibull) models are supported for the outcome model.
To cite this software, please cite Li et al (2023) <doi:10.1097/EDE.0000000000001643>
<!-- cite the r package: https://easystats.github.io/report/articles/cite_packages.html -->
# Implemented models
The following grid of models are implemented. `yreg` refers to the outcome model and `mreg` refers to the mediator model.
<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
| yreg \\\\ mreg | linear | logistic |
|:----------------|:---------------:|:---------------:|
| linear | :heavy_check_mark: | :heavy_check_mark: |
| logistic$^1$ | :heavy_check_mark: | :heavy_check_mark: |
| loglinear | :heavy_check_mark:$^2$ | :heavy_check_mark:$^2$ |
| poisson | :heavy_check_mark: | :heavy_check_mark: |
| negbin | :heavy_check_mark: | :heavy_check_mark: |
| survCox$^1$ | :heavy_check_mark: | :heavy_check_mark: |
| survAFT exp | :heavy_check_mark: | :heavy_check_mark: |
| survAFT weibull | :heavy_check_mark: | :heavy_check_mark: |
$^1$ Approximation depends on the rare event assumptions.
$^2$ Implemented as a modified Poisson model (log link with robust variance) as in Z2004.
See the corresponding vignettes (Articles on the package website) for how to perform bootstrapping and multiple imputation.
# Installation
For the developmental version on Github, use the following commands to install the package.
```{r}
# install.packages("devtools") # If you do not have devtools already.
devtools::install_github("kaz-yos/regmedint")
```
The CRAN version can be installed as follows.
```{r, eval = FALSE}
install.packages("regmedint")
```
# Data Example
We use `VV2015` dataset for demonstration.
```{r, eval = TRUE}
library(regmedint)
data(vv2015)
```
## `regmedint()` to fit models
The `regmedint` function is the user interface for constructing a result object of class `regmedint`. The interface is similar to the original SAS macro. For survival outcomes, the indicator variable is an event indicator (1 for event, 0 for censoring). `c_cond` vector is required be specified. This vector is the vector of covariate values at which the conditional effects are evaluated at.
1. When there is no effect measure modification by covariates, `emm_ac_mreg = NULL`, `emm_ac_yreg = NULL`, `emm_mc_yreg = NULL`.
```{r}
regmedint_obj1 <- regmedint(data = vv2015,
## Variables
yvar = "y",
avar = "x",
mvar = "m",
cvar = c("c"),
eventvar = "event",
## Values at which effects are evaluated
a0 = 0,
a1 = 1,
m_cde = 1,
c_cond = 3,
## Model types
mreg = "logistic",
yreg = "survAFT_weibull",
## Additional specification
interaction = TRUE,
casecontrol = FALSE)
summary(regmedint_obj1)
```
2. When there is effect measure modification by covariates, `emm_ac_mreg`, `emm_ac_yreg` and `emm_mc_yreg` can take a sub-vector of covariates in `cvar`.
```{r}
regmedint_obj2 <- regmedint(data = vv2015,
## Variables
yvar = "y",
avar = "x",
mvar = "m",
cvar = c("c"),
emm_ac_mreg = c("c"),
emm_ac_yreg = c("c"),
emm_mc_yreg = c("c"),
eventvar = "event",
## Values at which effects are evaluated
a0 = 0,
a1 = 1,
m_cde = 1,
c_cond = 3,
## Model types
mreg = "logistic",
yreg = "survAFT_weibull",
## Additional specification
interaction = TRUE,
casecontrol = FALSE)
summary(regmedint_obj2)
```
<!-- ## `print()` to examine simplified results -->
<!-- Implicit printing prints `mreg`, `yreg`, and mediation analysis point estimates. All effect estimates are on the scale of the link function. -->
## `summary()` to examine extended results
The `summary` method gives the summary for `mreg`, `yreg`, and mediation analysis results. The `exponentiate` option will add the exponentiated estimate and confidence limits if the outcome model is not a linear model. The pure natural direct effect (`pnde`) is what is typically called the natural direct effect (NDE). The total natural indirect effect (`tnie`) is the corresponding natural indirect effect (NIE).
```{r}
summary(regmedint_obj2, exponentiate = TRUE)
```
Use `coef` to extract the mediation analysis results only.
```{r}
coef(summary(regmedint_obj2, exponentiate = TRUE))
```
Note that the estimates can be re-evaluated at different `m_cde` and `c_cond` without re-fitting the underlyng models.
```{r}
coef(summary(regmedint_obj2, exponentiate = TRUE, m_cde = 0, c_cond = 5))
```
# Formulas
See [here](https://osf.io/d4brv/) for the following formulas.
## Effect formulas in the supplementary document
| yreg \\\\ mreg | linear | logistic |
|-----------------|--------------------------------------|--------------------------------------|
| linear | Formulas (1) - (5) | Formulas (11) - (15) |
| | | |
| logistic | Formulas (21) - (25) | Formulas (31) - (35) |
| loglinear | Formulas (21) - (25) | Formulas (31) - (35) |
| poisson | Formulas (21) - (25) | Formulas (31) - (35) |
| negbin | Formulas (21) - (25) | Formulas (31) - (35) |
| | | |
| survCox | Formulas (21) - (25) | Formulas (31) - (35) |
| survAFT exp | Formulas (21) - (25) | Formulas (31) - (35) |
| survAFT weibull | Formulas (21) - (25) | Formulas (31) - (35) |
## Standard error formulas in the supplementary document
| yreg \\\\ mreg | linear | logistic |
|-----------------|--------------------------------|--------------------------------|
| linear | Formulas (6) - (10) | Formulas (16) - (20) |
| | | |
| logistic | Formulas (26) - (30) | Formulas (36) - (40) |
| loglinear | Formulas (26) - (30) | Formulas (36) - (40) |
| poisson | Formulas (26) - (30) | Formulas (36) - (40) |
| negbin | Formulas (26) - (30) | Formulas (36) - (40) |
| | | |
| survCox | Formulas (26) - (30) | Formulas (36) - (40) |
| survAFT exp | Formulas (26) - (30) | Formulas (36) - (40) |
| survAFT weibull | Formulas (26) - (30) | Formulas (36) - (40) |
Note: The point estimate and standard error formulas (multivariate delta method) were derived based on the following references.
- V2015: VanderWeele (2015) Explanation in Causal Inference.
- VV2013A: Valeri & VanderWeele (2013) Appendix
- VV2015A: Valeri & VanderWeele (2015) Appendix
## Effect formulas are based on the following propositions
| yreg \\\\ mreg | linear | logistic |
|-----------------|--------------------------------------|--------------------------------------|
| linear | V2015 p466 Proposition 2.3 | V2015 p471 Proposition 2.5 |
| | | |
| logistic | V2015 p468 Proposition 2.4 | V2015 p473 Proposition 2.6 |
| loglinear | VV2013A p8 Use Proposition 2.4 | VV2013A p8 Use Proposition 2.6 |
| poisson | VV2013A p8 Use Proposition 2.4 | VV2013A p8 Use Proposition 2.6 |
| negbin | VV2013A p8 Use Proposition 2.4 | VV2013A p8 Use Proposition 2.6 |
| | | |
| survCox | V2015 p496 Proposition 4.4 (Use 2.4) | V2015 p499 Proposition 4.6 (Use 2.6) |
| survAFT exp | V2015 p494 Proposition 4.1 (Use 2.4) | V2015 p495 Proposition 4.3 (Use 2.6) |
| survAFT weibull | V2015 p494 Proposition 4.1 (Use 2.4) | V2015 p495 Proposition 4.3 (Use 2.6) |
## Standard error formulas are based on the following propositions
| yreg \\\\ mreg | linear | logistic |
|-----------------|--------------------------------|--------------------------------|
| linear | V2015 p466 Proposition 2.3 | V2015 p471 Proposition 2.5 |
| | | |
| logistic | V2015 p468 Proposition 2.4 | V2015 p473 Proposition 2.6 |
| loglinear | VV2013A p8 Use Proposition 2.4 | VV2013A p8 Use Proposition 2.6 |
| poisson | VV2013A p8 Use Proposition 2.4 | VV2013A p8 Use Proposition 2.6 |
| negbin | VV2013A p8 Use Proposition 2.4 | VV2013A p8 Use Proposition 2.6 |
| | | |
| survCox | V2015 p496 Use Proposition 2.4 | V2015 p499 Use Proposition 2.6 |
| survAFT exp | V2015 p494 Use Proposition 2.4 | V2015 p495 Use Proposition 2.6 |
| survAFT weibull | V2015 p494 Use Proposition 2.4 | V2015 p495 Use Proposition 2.6 |
<!-- # Design -->
<!-- The software design is outlined here for those who may be interested. -->
<!-- - Call structure -->
<!-- - regmedint UI function -->
<!-- - new_regmedint internal constructor -->
<!-- - fit_mreg -->
<!-- - fit_yreg -->
<!-- - calc_myreg calls a specialized worker function, which return two functions, one for point estimates and the other for standard error estimate. -->
<!-- - calc_myreg_mreg_linear_yreg_linear -->
<!-- - calc_myreg_mreg_linear_yreg_logistic -->
<!-- - calc_myreg_mreg_logistic_yreg_linear -->
<!-- - calc_myreg_mreg_logistic_yreg_logistic -->
<!-- - regmedint object structure -->
<!-- - mreg_fit mediator regression model object as is -->
<!-- - yreg_fit outcome regression model object as is -->
<!-- - myreg_funs list -->
<!-- - est_fun: (a0,a1,m_cde,c_cond) → (cde,pnde,tnie,tnde,pnie,te,pm) -->
<!-- - se_fun: (a0,a1,m_cde,c_cond) → se for (cde,pnde,tnie,tnde,pnie,te,pm) -->
<!-- - args preserves arguments given to the UI -->
<!-- - User methods for the regmedint object -->
<!-- - print.regmedint: prints coefficients for mreg, yreg, and mediation analysis -->
<!-- - summary.regmedint: regmedint → summary_regmedint -->
<!-- - print.summary_regmedint: prints summary objects for mreg, yreg, and mediation analysis -->
<!-- - coef.summary_regmedint: -->
<!-- - coef.regmedint: regmedint → vector (cde,pnde,tnie,tnde,pnie,te,pm) -->
<!-- - vcov.regmedint: regmedint → matrix (cde,pnde,tnie,tnde,pnie,te,pm). Off-diagonals are NA. -->
<!-- - confint.regmedint: regmedint → matrix of (lower,upper) -->
# Similar or related projects for counterfactual-based causal mediation analysis
## R
- mediation (simulation-based): https://CRAN.R-project.org/package=mediation
- medflex (natural effect model): https://CRAN.R-project.org/package=medflex
- intmed (interventional analogue): https://CRAN.R-project.org/package=intmed
- CMAverse (regression-based approach, weighting-based approach, inverse odd-ratio weighting, natural effect model, marginal structural model, g-formula approach): https://bs1125.github.io/CMAverse/
- mediator (regression-based): https://github.com/GerkeLab/mediator
- causalMediation (regression-based): https://github.com/harvard-P01/causalMediation
## Other statistical environment
- SAS macro (original regression-based) https://www.hsph.harvard.edu/tyler-vanderweele/tools-and-tutorials/
- SAS PROC CAUSALMED (regression-based) https://support.sas.com/rnd/app/stat/procedures/causalmed.html
# References
- V2015: VanderWeele (2015) Explanation in Causal Inference.
- VV2013: Valeri & VanderWeele (2013) Psych Method. 18:137.
- VV2015: Valeri & VanderWeele (2015) Epidemiology. 26:e23.
- Z2004: Zou (2004) Am J Epidemiol 159:702.