From 59c80d448ad10306776ee3b49d20f351bdfeebef Mon Sep 17 00:00:00 2001
From: Zelos Zhu <zelos.zhu@atorusresearch.com>
Date: Thu, 22 Feb 2024 20:12:36 +0000
Subject: [PATCH] feat: #10 basic vif draft up

---
 DESCRIPTION    |  3 +-
 NAMESPACE      |  1 +
 R/ard_vif.R    | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++
 man/ard_vif.Rd | 27 ++++++++++++++++
 4 files changed, 114 insertions(+), 1 deletion(-)
 create mode 100644 R/ard_vif.R
 create mode 100644 man/ard_vif.Rd

diff --git a/DESCRIPTION b/DESCRIPTION
index 765b97d3b..86b4f399a 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -23,7 +23,8 @@ Suggests:
     broom.helpers (>= 1.13.0),
     spelling,
     testthat (>= 3.2.0),
-    withr
+    withr,
+    car
 Remotes: 
     insightsengineering/cards
 Config/Needs/website: insightsengineering/nesttemplate
diff --git a/NAMESPACE b/NAMESPACE
index d58df76b4..f6c4f3875 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -12,6 +12,7 @@ export(ard_paired_wilcoxtest)
 export(ard_proportion_ci)
 export(ard_regression)
 export(ard_ttest)
+export(ard_vif)
 export(ard_wilcoxtest)
 export(contains)
 export(ends_with)
diff --git a/R/ard_vif.R b/R/ard_vif.R
new file mode 100644
index 000000000..3d39b8730
--- /dev/null
+++ b/R/ard_vif.R
@@ -0,0 +1,84 @@
+#' Regression VIF ARD
+#'
+#' Function takes a regression model object and converts it to a ARD
+#' structure using the `broom.helpers` package.
+#'
+#' @param x regression model object
+#' @param statistic "VIF" (variance inflation factors, for models with no categorical terms)
+#' or one of/combination of "GVIF" (generalized variance inflation factors),
+#' "aGVIF" 'adjusted GVIF, i.e. GVIF^[1/(2*df)] and/or "df" (degrees of freedom).
+#' See car::vif() for details
+#'
+#' @return data frame
+#' @name ard_vif
+#' @rdname ard_vif
+#' @export
+#'
+#' @examples
+#' lm(AGE ~ ARM + SEX, data = cards::ADSL) |>
+#'   ard_vif()
+ard_vif <- function(x, statistic) {
+  # check installed packages ---------------------------------------------------
+  cards::check_pkg_installed("broom.helpers", reference_pkg = "cards")
+
+  # check inputs ---------------------------------------------------------------
+  check_not_missing(x, "model")
+
+  .vif_to_tibble(x) |>
+    tidyr::pivot_longer(cols = -c(variable, row_type), names_to = "stat_name", values_to = "statistic") |>
+    dplyr::mutate(
+      .after = "variable",
+      context = "vif"
+    ) |>
+    dplyr::mutate(
+      .after = "stat_name",
+      stat_label = ifelse(
+        stat_name == "aGVIF",
+        "Adjusted GVIF",
+        stat_name
+      )
+    )
+}
+
+
+# put VIF results in data frame
+.vif_to_tibble <- function(x) {
+  vif <- tryCatch(
+    car::vif(x),
+    error = function(e) {
+      paste(
+        "The {.code add_vif()} uses {.code car::vif()} to",
+        "calculate the VIF, and the function returned an error (see below)."
+      ) %>%
+        stringr::str_wrap() %>%
+        cli::cli_alert_danger()
+      stop(e)
+    }
+  )
+
+  # if VIF is returned
+  if (!is.matrix(vif)) {
+    result <-
+      vif %>%
+      tibble::enframe("variable", "VIF")
+  } # if Generalized VIF is returned
+  else {
+    result <-
+      vif %>%
+      as.data.frame() %>%
+      tibble::rownames_to_column(var = "variable") %>%
+      tibble::as_tibble() %>%
+      dplyr::rename(
+        aGVIF = "GVIF^(1/(2*Df))",
+        df = "Df"
+      )
+  }
+
+  result <-
+    result %>%
+    dplyr::mutate(
+      variable = broom.helpers::.clean_backticks(.data$variable),
+      row_type = "label"
+    )
+  return(result)
+}
diff --git a/man/ard_vif.Rd b/man/ard_vif.Rd
new file mode 100644
index 000000000..ad2f7ed40
--- /dev/null
+++ b/man/ard_vif.Rd
@@ -0,0 +1,27 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/ard_vif.R
+\name{ard_vif}
+\alias{ard_vif}
+\title{Regression VIF ARD}
+\usage{
+ard_vif(x, statistic)
+}
+\arguments{
+\item{x}{regression model object}
+
+\item{statistic}{"VIF" (variance inflation factors, for models with no categorical terms)
+or one of/combination of "GVIF" (generalized variance inflation factors),
+"aGVIF" 'adjusted GVIF, i.e. GVIF^\link{1/(2*df)} and/or "df" (degrees of freedom).
+See car::vif() for details}
+}
+\value{
+data frame
+}
+\description{
+Function takes a regression model object and converts it to a ARD
+structure using the \code{broom.helpers} package.
+}
+\examples{
+lm(AGE ~ ARM + SEX, data = cards::ADSL) |>
+  ard_vif()
+}