Merge pull request #34 from nhejazi/joss_revise

.Rbuildignore

@@ -16,3 +16,4 @@
 ^sandbox$
 ^paper$
 ^docs$
+^LICENSE\.md$

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: medoutcon
-Title: Efficient Causal Mediation Analysis with the Natural and Interventional Effects
-Version: 0.1.5
+Title: Efficient Natural and Interventional Causal Mediation Analysis
+Version: 0.1.6
 Authors@R: c(
     person("Nima", "Hejazi", email = "[email protected]",
            role = c("aut", "cre", "cph"),
@@ -37,17 +37,17 @@ Imports:
     scales,
     stringr,
     origami (>= 1.0.3),
-    sl3 (>= 1.4.3)
+    sl3 (>= 1.4.3),
+    hal9001 (>= 0.4.1),
+    speedglm
 Suggests:
     testthat,
     knitr,
     rmarkdown,
     covr,
     Rsolnp,
     nnls,
-    hal9001 (>= 0.4.1),
     SuperLearner,
-    speedglm,
     glmnet,
     xgboost,
     ranger,

LICENSE

@@ -1,2 +1,2 @@
-YEAR: 2020-2021
+YEAR: 2020-2022
 COPYRIGHT HOLDER: Nima S. Hejazi

LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2020-2022 Nima S. Hejazi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

NAMESPACE

@@ -3,8 +3,6 @@
 S3method(confint,medoutcon)
 S3method(print,medoutcon)
 S3method(summary,medoutcon)
-export(est_onestep)
-export(est_tml)
 export(medoutcon)
 importFrom(assertthat,assert_that)
 importFrom(data.table,":=")

R/estimators.R

@@ -315,7 +315,7 @@ cv_eif <- function(fold,
 #' @importFrom stats var weighted.mean
 #' @importFrom origami make_folds cross_validate folds_vfold
 #'
-#' @export
+#' @keywords internal
 est_onestep <- function(data,
                         contrast,
                         g_learners,
@@ -466,7 +466,7 @@ est_onestep <- function(data,
 #'  weighted.mean
 #' @importFrom origami make_folds cross_validate folds_vfold
 #'
-#' @export
+#' @keywords internal
 est_tml <- function(data,
                     contrast,
                     g_learners,

R/medoutcon.R

@@ -69,6 +69,39 @@
 #' @importFrom stats var
 #'
 #' @export
+#'
+#' @examples
+#' # here, we show one-step and TML estimates of the interventional direct
+#' # effect; the indirect effect can be evaluated by a straightforward change
+#' # to the penultimate argument. the natural direct and indirect effects can
+#' # be evaluated by omitting the argument Z (inappropriate in this example).
+#' # create data: covariates W, exposure A, post-exposure-confounder Z,
+#' #              mediator M, outcome Y
+#' n_obs <- 200
+#' w_1 <- rbinom(n_obs, 1, prob = 0.6)
+#' w_2 <- rbinom(n_obs, 1, prob = 0.3)
+#' w <- as.data.frame(cbind(w_1, w_2))
+#' a <- as.numeric(rbinom(n_obs, 1, plogis(rowSums(w) - 2)))
+#' z <- rbinom(n_obs, 1, plogis(rowMeans(-log(2) + w - a) + 0.2))
+#' m_1 <- rbinom(n_obs, 1, plogis(rowSums(log(3) * w + a - z)))
+#' m_2 <- rbinom(n_obs, 1, plogis(rowSums(w - a - z)))
+#' m <- as.data.frame(cbind(m_1, m_2))
+#' y <- rbinom(n_obs, 1, plogis(1 / (rowSums(w) - z + a + rowSums(m))))
+#'
+#' # one-step estimate of the interventional direct effect
+#' os_de <- medoutcon(
+#'   W = w, A = a, Z = z, M = m, Y = y,
+#'   effect = "direct",
+#'   estimator = "onestep"
+#' )
+#'
+#' # TML estimate of the interventional direct effect
+#' # NOTE: improved variance estimate and de-biasing from targeting procedure
+#' tmle_de <- medoutcon(
+#'   W = w, A = a, Z = z, M = m, Y = y,
+#'   effect = "direct",
+#'   estimator = "tmle"
+#' )
 medoutcon <- function(W,
                       A,
                       Z,

README.Rmd

@@ -168,33 +168,33 @@ After using the `medoutcon` R package, please cite the following:
           url = {https://arxiv.org/abs/1912.09936},
           doi = {10.1093/biomet/asaa085},
           journal={Biometrika},
-          volume={},
-          number={},
-          pages={},
+          volume = {108},
+          number = {3},
+          pages = {627--641},
           publisher={Oxford University Press}
         }
 
         @software{hejazi2021medoutcon,
           author={Hejazi, Nima S and D{\'\i}az, Iv{\'a}n and Rudolph, Kara E},
-          title = {{medoutcon}: Efficient causal mediation analysis for the
-            natural and interventional effects},
+          title = {{medoutcon}: Efficient natural and interventional causal
+            mediation analysis},
           year  = {2021},
           url = {https://github.com/nhejazi/medoutcon},
-          note = {R package version 0.1.5}
+          note = {R package version 0.1.6}
         }
 
 ---
 
 ## License
 
-© 2020-2021 [Nima S. Hejazi](https://nimahejazi.org)
+© 2020-2022 [Nima S. Hejazi](https://nimahejazi.org)
 
 The contents of this repository are distributed under the MIT license. See below
 for details:
 ```
 MIT License
 
-Copyright (c) 2020-2021 Nima S. Hejazi
+Copyright (c) 2020-2022 Nima S. Hejazi
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -33,17 +33,18 @@ by the treatment \(A\), these correspond to the *interventional*
 (in)direct effects described by Dı́az et al. (2020), though similar (yet
 less general) effect definitions and/or estimation strategies have
 appeared in VanderWeele, Vansteelandt, and Robins (2014), Rudolph et al.
-(2017), Zheng and van der Laan (2017), and Benkeser (2020). When no
-intermediate confounders are present, these effect definitions simplify
-to the well-studied *natural* (in)direct effects, and our estimators are
-analogs of those formulated by Zheng and van der Laan (2012). Both an
-efficient one-step bias-corrected estimator with cross-fitting (Pfanzagl
-and Wefelmeyer 1985; Zheng and van der Laan 2011; Chernozhukov et al.
-2018) and a cross-validated targeted minimum loss estimator (TMLE) (van
-der Laan and Rose 2011; Zheng and van der Laan 2011) are made available.
-`medoutcon` integrates with the [`sl3` R
-package](https://github.com/tlverse/sl3) (Coyle et al. 2020) to leverage
-statistical machine learning in the estimation procedure.
+(2017), Zheng and van der Laan (2017), and Benkeser and Ran (2021). When
+no intermediate confounders are present, these effect definitions
+simplify to the well-studied *natural* (in)direct effects, and our
+estimators are analogs of those formulated by Zheng and van der Laan
+(2012). Both an efficient one-step bias-corrected estimator with
+cross-fitting (Pfanzagl and Wefelmeyer 1985; Zheng and van der Laan
+2011; Chernozhukov et al. 2018) and a cross-validated targeted minimum
+loss estimator (TMLE) (van der Laan and Rose 2011; Zheng and van der
+Laan 2011) are made available. `medoutcon` integrates with the [`sl3` R
+package](https://github.com/tlverse/sl3)
+(<span class="citeproc-not-found" data-reference-id="coyle2020sl3">**???**</span>)
+to leverage statistical machine learning in the estimation procedure.
 
 -----
 
@@ -70,9 +71,9 @@ library(data.table)
 library(tidyverse)
 #> ── Attaching packages ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── tidyverse 1.3.1 ──
 #> ✔ ggplot2 3.3.5     ✔ purrr   0.3.4
-#> ✔ tibble  3.1.5     ✔ dplyr   1.0.7
+#> ✔ tibble  3.1.6     ✔ dplyr   1.0.7
 #> ✔ tidyr   1.1.4     ✔ stringr 1.4.0
-#> ✔ readr   2.0.2     ✔ forcats 0.5.1
+#> ✔ readr   2.1.1     ✔ forcats 0.5.1
 #> ── Conflicts ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── tidyverse_conflicts() ──
 #> ✖ dplyr::between()   masks data.table::between()
 #> ✖ dplyr::filter()    masks stats::filter()
@@ -195,34 +196,34 @@ After using the `medoutcon` R package, please cite the following:
       url = {https://arxiv.org/abs/1912.09936},
       doi = {10.1093/biomet/asaa085},
       journal={Biometrika},
-      volume={},
-      number={},
-      pages={},
+      volume = {108},
+      number = {3},
+      pages = {627--641},
       publisher={Oxford University Press}
     }
 
     @software{hejazi2021medoutcon,
       author={Hejazi, Nima S and D{\'\i}az, Iv{\'a}n and Rudolph, Kara E},
-      title = {{medoutcon}: Efficient causal mediation analysis for the
-        natural and interventional effects},
+      title = {{medoutcon}: Efficient natural and interventional causal
+        mediation analysis},
       year  = {2021},
       url = {https://github.com/nhejazi/medoutcon},
-      note = {R package version 0.1.5}
+      note = {R package version 0.1.6}
     }
 ```
 
 -----
 
 ## License
 
-© 2020-2021 [Nima S. Hejazi](https://nimahejazi.org)
+© 2020-2022 [Nima S. Hejazi](https://nimahejazi.org)
 
 The contents of this repository are distributed under the MIT license.
 See below for details:
 
     MIT License
 
-    Copyright (c) 2020-2021 Nima S. Hejazi
+    Copyright (c) 2020-2022 Nima S. Hejazi
 
     Permission is hereby granted, free of charge, to any person obtaining a copy
     of this software and associated documentation files (the "Software"), to deal
@@ -250,8 +251,9 @@ See below for details:
 
 <div id="ref-benkeser2020nonparametric">
 
-Benkeser, David. 2020. “Nonparametric Inference for Interventional
-Effects with Multiple Mediators.” *arXiv Preprint arXiv:2001.06027*.
+Benkeser, David, and Jialu Ran. 2021. “Nonparametric Inference for
+Interventional Effects with Multiple Mediators.” *Journal of Causal
+Inference*. <https://doi.org/10.1515/jci-2020-0018>.
 
 </div>
 
@@ -265,28 +267,20 @@ Parameters.” *The Econometrics Journal* 21 (1).
 
 </div>
 
-<div id="ref-coyle2020sl3">
-
-Coyle, Jeremy R, Nima S Hejazi, Ivana Malenica, and Oleg Sofrygin. 2020.
-“`sl3`: Modern Pipelines for Machine Learning and Super Learning.”
-<https://github.com/tlverse/sl3>.
-<https://doi.org/10.5281/zenodo.1342293>.
-
-</div>
-
 <div id="ref-diaz2020nonparametric">
 
 Dı́az, Iván, Nima S Hejazi, Kara E Rudolph, and Mark J van der Laan.
 2020. “Non-Parametric Efficient Causal Mediation with Intermediate
-Confounders.” *Biometrika*. <https://doi.org/10.1093/biomet/asaa085>.
+Confounders.” *Biometrika* 108 (3): 627–41.
+<https://doi.org/10.1093/biomet/asaa085>.
 
 </div>
 
 <div id="ref-pfanzagl1985contributions">
 
 Pfanzagl, J, and W Wefelmeyer. 1985. “Contributions to a General
 Asymptotic Statistical Theory.” *Statistics & Risk Modeling* 3 (3-4):
-379–88.
+379–88. <https://doi.org/10.1007/978-1-4612-5769-1>.
 
 </div>
 
@@ -295,7 +289,7 @@ Asymptotic Statistical Theory.” *Statistics & Risk Modeling* 3 (3-4):
 Rudolph, Kara E, Oleg Sofrygin, Wenjing Zheng, and Mark J van der Laan.
 2017. “Robust and Flexible Estimation of Stochastic Mediation Effects: A
 Proposed Method and Example in a Randomized Trial Setting.”
-*Epidemiologic Methods* 7 (1).
+*Epidemiologic Methods* 7 (1). <https://doi.org/10.1515/em-2017-0007>.
 
 </div>
 
@@ -312,15 +306,15 @@ Business Media.
 VanderWeele, Tyler J, Stijn Vansteelandt, and James M Robins. 2014.
 “Effect Decomposition in the Presence of an Exposure-Induced
 Mediator-Outcome Confounder.” *Epidemiology (Cambridge, Mass.)* 25 (2):
-300.
+300. <https://doi.org/10.1097/ede.0000000000000034>.
 
 </div>
 
 <div id="ref-zheng2011cross">
 
 Zheng, Wenjing, and Mark J van der Laan. 2011. “Cross-Validated Targeted
 Minimum-Loss-Based Estimation.” In *Targeted Learning*, 459–74.
-Springer.
+Springer. <https://doi.org/10.1007/978-1-4419-9782-1_27>.
 
 </div>
 
@@ -336,7 +330,7 @@ Effects.” *International Journal of Biostatistics* 8 (1).
 
 ———. 2017. “Longitudinal Mediation Analysis with Time-Varying Mediators
 and Exposures, with Application to Survival Outcomes.” *Journal of
-Causal Inference* 5 (2).
+Causal Inference* 5 (2). <https://doi.org/10.1515/jci-2016-0006>.
 
 </div>
 

inst/REFERENCES.bib

@@ -22,9 +22,9 @@ @article{diaz2020nonparametric
   url = {https://arxiv.org/abs/1912.09936},
   doi = {10.1093/biomet/asaa085},
   journal={Biometrika},
-  volume={},
-  number={},
-  pages={},
+  volume = {108},
+  number = {3},
+  pages = {627--641},
   publisher={Oxford University Press}
 }