diff --git a/DESCRIPTION b/DESCRIPTION index 801a0514d..9158e5179 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Type: Package Package: performance Title: Assessment of Regression Models Performance -Version: 0.12.2.4 +Version: 0.12.2.5 Authors@R: c(person(given = "Daniel", family = "Lüdecke", diff --git a/R/check_dag.R b/R/check_dag.R index 5b11ec7f3..842508f10 100644 --- a/R/check_dag.R +++ b/R/check_dag.R @@ -12,7 +12,8 @@ #' #' @param ... One or more formulas, which are converted into **dagitty** syntax. #' First element may also be model object. If a model objects is provided, its -#' formula is used as first formula. See 'Details'. +#' formula is used as first formula, and all independent variables will be used +#' for the `adjusted` argument. See 'Details' and 'Examples'. #' @param outcome Name of the dependent variable (outcome), as character string. #' Must be a valid name from the formulas. If not set, the first dependent #' variable from the formulas is used. @@ -21,7 +22,8 @@ #' Must be a valid name from the formulas. If not set, the first independent #' variable from the formulas is used. #' @param adjusted A character vector with names of variables that are adjusted -#' for in the model. +#' for in the model. If a model object is provided in `...`, any values in +#' `adjusted` will be overwritten by the model's independent variables. #' @param latent A character vector with names of latent variables in the model. #' @param effect Character string, indicating which effect to check. Can be #' `"all"` (default), `"total"`, or `"direct"`. @@ -74,6 +76,18 @@ #' #' # Objects returned by `check_dag()` can be used with "ggdag" or "dagitty" #' ggdag::ggdag_status(dag) +#' +#' # Using a model object to extract information about outcome, +#' # exposure and adjusted variables +#' data(mtcars) +#' m <- lm(mpg ~ wt + gear + disp + cyl, data = mtcars) +#' dag <- check_dag( +#' m, +#' wt ~ disp + cyl, +#' wt ~ am +#' ) +#' dag +#' plot(dag) #' @export check_dag <- function(..., outcome = NULL, @@ -124,6 +138,11 @@ check_dag.default <- function(..., formulas[[1]] <- stats::as.formula( paste(vars$response, "~", paste(vars$conditional, collapse = "+")) ) + # if we have a model, we *always* overwrite adjusted + if (!is.null(adjusted)) { + insight::format_alert("The `adjusted` argument will be overwritten by all independent variables from the model.") # nolint + } + adjusted <- vars$conditional } # if outcome is not set, use first dependent variable @@ -230,6 +249,16 @@ print.check_dag <- function(x, ...) { ": ", datawizard::text_concatenate(attributes(x)$exposure) ) + # add information on adjustments + if (!is.null(out$current_adjustments)) { + exposure_outcome_text <- paste0( + exposure_outcome_text, + "\n- Adjustment", + ifelse(length(out$current_adjustments) > 1, "s", ""), + ": ", datawizard::text_concatenate(out$current_adjustments) + ) + } + # build message with check results for effects ----------------------- if (isTRUE(out$adjustment_not_needed)) { diff --git a/man/check_dag.Rd b/man/check_dag.Rd index b0039a142..281a62ef9 100644 --- a/man/check_dag.Rd +++ b/man/check_dag.Rd @@ -19,7 +19,8 @@ as.dag(x, ...) \arguments{ \item{...}{One or more formulas, which are converted into \strong{dagitty} syntax. First element may also be model object. If a model objects is provided, its -formula is used as first formula. See 'Details'.} +formula is used as first formula, and all independent variables will be used +for the \code{adjusted} argument. See 'Details' and 'Examples'.} \item{outcome}{Name of the dependent variable (outcome), as character string. Must be a valid name from the formulas. If not set, the first dependent @@ -31,7 +32,8 @@ Must be a valid name from the formulas. If not set, the first independent variable from the formulas is used.} \item{adjusted}{A character vector with names of variables that are adjusted -for in the model.} +for in the model. If a model object is provided in \code{...}, any values in +\code{adjusted} will be overwritten by the model's independent variables.} \item{latent}{A character vector with names of latent variables in the model.} @@ -99,5 +101,17 @@ dag # Objects returned by `check_dag()` can be used with "ggdag" or "dagitty" ggdag::ggdag_status(dag) + +# Using a model object to extract information about outcome, +# exposure and adjusted variables +data(mtcars) +m <- lm(mpg ~ wt + gear + disp + cyl, data = mtcars) +dag <- check_dag( + m, + wt ~ disp + cyl, + wt ~ am +) +dag +plot(dag) \dontshow{\}) # examplesIf} } diff --git a/tests/testthat/_snaps/check_dag.md b/tests/testthat/_snaps/check_dag.md index e28c825c3..16432d033 100644 --- a/tests/testthat/_snaps/check_dag.md +++ b/tests/testthat/_snaps/check_dag.md @@ -30,6 +30,7 @@ Model is correctly specified. - Outcome: y - Exposure: x + - Adjustment: b All minimal sufficient adjustments to estimate the direct effect were done. @@ -38,6 +39,7 @@ Model is correctly specified. - Outcome: y - Exposure: x + - Adjustment: b All minimal sufficient adjustments to estimate the total effect were done. @@ -76,6 +78,7 @@ Incorrectly adjusted! - Outcome: y - Exposure: x + - Adjustment: c To estimate the direct effect, also adjust for `b` and `c`. Currently, the model currently only adjusts for `c`. @@ -85,8 +88,33 @@ Incorrectly adjusted! - Outcome: y - Exposure: x + - Adjustment: c To estimate the total effect, also adjust for `b` and `c`. Currently, the model currently only adjusts for `c`. +--- + + Code + print(dag) + Output + # Correct adjustments for identifying direct effects + + Model is correctly specified. + - Outcome: mpg + - Exposure: wt + - Adjustments: cyl, disp and gear + + All minimal sufficient adjustments to estimate the direct effect were done. + + # Correct adjustments for identifying total effects + + Model is correctly specified. + - Outcome: mpg + - Exposure: wt + - Adjustments: cyl, disp and gear + + All minimal sufficient adjustments to estimate the total effect were done. + + diff --git a/tests/testthat/test-check_dag.R b/tests/testthat/test-check_dag.R index 458226251..efc7c95bf 100644 --- a/tests/testthat/test-check_dag.R +++ b/tests/testthat/test-check_dag.R @@ -31,6 +31,15 @@ test_that("check_dag", { adjusted = "c" ) expect_snapshot(print(dag)) + data(mtcars) + m <- lm(mpg ~ wt + gear + disp + cyl, data = mtcars) + dag <- check_dag( + m, + wt ~ disp + cyl, + wt ~ am + ) + dag + expect_snapshot(print(dag)) }) test_that("check_dag, cylic error", {