docs, add tests

Author: strengejacke

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: performance
 Title: Assessment of Regression Models Performance
-Version: 0.12.2.10
+Version: 0.12.2.11
 Authors@R:
     c(person(given = "Daniel",
              family = "Lüdecke",

R/check_dag.R

@@ -6,13 +6,16 @@
 #' model is correctly adjusted for identifying specific relationships of
 #' variables, especially directed (maybe also "causal") effects for given
 #' exposures on an outcome. In case of incorrect adjustments, the function
-#' suggest the minimal required variables that should be adjusted for (sometimes
-#' also called "controlled for"), i.e. that need to be included in the model.
-#'  It returns a **dagitty** object that can be visualized with `plot()`.
+#' suggests the minimal required variables that should be adjusted for (sometimes
+#' also called "controlled for"), i.e. variables that *at least* need to be
+#' included in the model. Depending on the goal of the analysis, it is still
+#' possible to add more variables to the model than just the minimally required
+#' adjustment sets.
 #'
 #' `check_dag()` is a convenient wrapper around `ggdag::dagify()`,
 #' `dagitty::adjustmentSets()` and `dagitty::adjustedNodes()` to check correct
-#' adjustment sets. `as.dag()` is a small convenient function to return the
+#' adjustment sets. It returns a **dagitty** object that can be visualized with
+#' `plot()`. `as.dag()` is a small convenient function to return the
 #' dagitty-string, which can be used for the online-tool from the
 #' dagitty-website.
 #'
@@ -59,7 +62,7 @@
 #' The function checks if the model is correctly adjusted for identifying the
 #' direct and total effects of the exposure on the outcome. If the model is
 #' correctly specified, no adjustment is needed to estimate the direct effect.
-#' If the model is not correctly specified, the function suggests the minimal
+#' If the model is not correctly specified, the function suggests the minimally
 #' required variables that should be adjusted for. The function distinguishes
 #' between direct and total effects, and checks if the model is correctly
 #' adjusted for both. If the model is cyclic, the function stops and suggests

man/check_dag.Rd

@@ -131,3 +131,90 @@
       All minimal sufficient adjustments to estimate the direct and total effect were done.
       
 
+# check_dag, different adjustements for total and direct
+
+    Code
+      print(dag)
+    Output
+      # Check for correct adjustment sets
+      - Outcome: outcome
+      - Exposure: exposure
+      
+      Identification of direct effects
+      
+      Incorrectly adjusted!
+      To estimate the direct effect, at least adjust for `x1` and `x2`.
+      Currently, the model does not adjust for any variables.
+      
+      Identification of total effects
+      
+      Incorrectly adjusted!
+      To estimate the total effect, at least adjust for `x1`.
+      Currently, the model does not adjust for any variables.
+      
+
+---
+
+    Code
+      print(dag)
+    Output
+      # Check for correct adjustment sets
+      - Outcome: outcome
+      - Exposure: exposure
+      - Adjustment: x1
+      
+      Identification of direct effects
+      
+      Incorrectly adjusted!
+      To estimate the direct effect, at least adjust for `x1` and `x2`.
+      Currently, the model only adjusts for `x1`.
+      
+      Identification of total effects
+      
+      Model is correctly specified.
+      All minimal sufficient adjustments to estimate the total effect were done.
+      
+
+---
+
+    Code
+      print(dag)
+    Output
+      # Check for correct adjustment sets
+      - Outcome: outcome
+      - Exposure: exposure
+      - Adjustment: x2
+      
+      Identification of direct effects
+      
+      Incorrectly adjusted!
+      To estimate the direct effect, at least adjust for `x1` and `x2`.
+      Currently, the model only adjusts for `x2`.
+      
+      Identification of total effects
+      
+      Incorrectly adjusted!
+      To estimate the total effect, do not adjust for `x2`.
+      
+
+---
+
+    Code
+      print(dag)
+    Output
+      # Check for correct adjustment sets
+      - Outcome: outcome
+      - Exposure: exposure
+      - Adjustments: x1 and x2
+      
+      Identification of direct effects
+      
+      Model is correctly specified.
+      All minimal sufficient adjustments to estimate the direct effect were done.
+      
+      Identification of total effects
+      
+      Incorrectly adjusted!
+      To estimate the total effect, do not adjust for `x1` and `x2`.
+      
+

tests/testthat/_snaps/check_dag.md

@@ -91,3 +91,45 @@ test_that("check_dag, multiple adjustment sets", {
   )
   expect_snapshot(print(dag))
 })
+
+
+test_that("check_dag, different adjustements for total and direct", {
+  dag <- check_dag(
+    outcome ~ exposure + x1 + x2,
+    x2 ~ exposure,
+    exposure ~ x1,
+    outcome = "outcome",
+    exposure = "exposure"
+  )
+  expect_snapshot(print(dag))
+
+  dag <- check_dag(
+    outcome ~ exposure + x1 + x2,
+    x2 ~ exposure,
+    exposure ~ x1,
+    adjusted = "x1",
+    outcome = "outcome",
+    exposure = "exposure"
+  )
+  expect_snapshot(print(dag))
+
+  dag <- check_dag(
+    outcome ~ exposure + x1 + x2,
+    x2 ~ exposure,
+    exposure ~ x1,
+    adjusted = "x2",
+    outcome = "outcome",
+    exposure = "exposure"
+  )
+  expect_snapshot(print(dag))
+
+  dag <- check_dag(
+    outcome ~ exposure + x1 + x2,
+    x2 ~ exposure,
+    exposure ~ x1,
+    adjusted = c("x1", "x2"),
+    outcome = "outcome",
+    exposure = "exposure"
+  )
+  expect_snapshot(print(dag))
+})