From f4666422bc2e98c6a64ae5febed21f28965280bc Mon Sep 17 00:00:00 2001
From: Daniel <mail@danielluedecke.de>
Date: Wed, 18 Dec 2024 10:08:13 +0100
Subject: [PATCH] docs

---
 R/rescale_weights.R    | 66 ++++++++++++++++++++++++++++--------------
 man/rescale_weights.Rd | 66 +++++++++++++++++++++++++++++-------------
 2 files changed, 91 insertions(+), 41 deletions(-)

diff --git a/R/rescale_weights.R b/R/rescale_weights.R
index 7bf320a0e..bc10ca249 100644
--- a/R/rescale_weights.R
+++ b/R/rescale_weights.R
@@ -76,31 +76,55 @@
 #'
 #'   - Kish, L. (1965) Survey Sampling. London: Wiley.
 #'
-#' @examples
-#' if (require("lme4")) {
-#'   data(nhanes_sample)
-#'   head(rescale_weights(nhanes_sample, "SDMVSTRA", "WTINT2YR"))
+#' @examplesIf all(insight::check_if_installed(c("lme4", "parameters"), quietly = TRUE))
+#' data(nhanes_sample)
+#' head(rescale_weights(nhanes_sample, "SDMVSTRA", "WTINT2YR"))
 #'
-#'   # also works with multiple group-variables
-#'   head(rescale_weights(nhanes_sample, c("SDMVSTRA", "SDMVPSU"), "WTINT2YR"))
+#' # also works with multiple group-variables
+#' head(rescale_weights(nhanes_sample, c("SDMVSTRA", "SDMVPSU"), "WTINT2YR"))
 #'
-#'   # or nested structures.
-#'   x <- rescale_weights(
-#'     data = nhanes_sample,
-#'     by = c("SDMVSTRA", "SDMVPSU"),
-#'     probability_weights = "WTINT2YR",
-#'     nest = TRUE
-#'   )
-#'   head(x)
+#' # or nested structures.
+#' x <- rescale_weights(
+#'   data = nhanes_sample,
+#'   by = c("SDMVSTRA", "SDMVPSU"),
+#'   probability_weights = "WTINT2YR",
+#'   nest = TRUE
+#' )
+#' head(x)
 #'
-#'   nhanes_sample <- rescale_weights(nhanes_sample, "SDMVSTRA", "WTINT2YR")
+#' \donttest{
+#' # compare different methods, using multilevel-Poisson regression
 #'
-#'   glmer(
-#'     total ~ factor(RIAGENDR) * (log(age) + factor(RIDRETH1)) + (1 | SDMVPSU),
-#'     family = poisson(),
-#'     data = nhanes_sample,
-#'     weights = pweights_a
-#'   )
+#' d <- rescale_weights(nhanes_sample, "SDMVSTRA", "WTINT2YR")
+#' result1 <- lme4::glmer(
+#'   total ~ factor(RIAGENDR) + log(age) + factor(RIDRETH1) + (1 | SDMVPSU),
+#'   family = poisson(),
+#'   data = d,
+#'   weights = pweights_a
+#' )
+#' result2 <- lme4::glmer(
+#'   total ~ factor(RIAGENDR) + log(age) + factor(RIDRETH1) + (1 | SDMVPSU),
+#'   family = poisson(),
+#'   data = d,
+#'   weights = pweights_b
+#' )
+#'
+#' d <- rescale_weights(
+#'   nhanes_sample,
+#'   probability_weights = "WTINT2YR",
+#'   method = "kish"
+#' )
+#' result3 <- lme4::glmer(
+#'   total ~ factor(RIAGENDR) + log(age) + factor(RIDRETH1) + (1 | SDMVPSU),
+#'   family = poisson(),
+#'   data = d,
+#'   weights = pweights
+#' )
+#' parameters::compare_parameters(
+#'   list(result1, result2, result3),
+#'   exponentiate = TRUE,
+#'   column_names = c("Carle (A)", "Carle (B)", "Kish")
+#' )
 #' }
 #' @export
 rescale_weights <- function(data,
diff --git a/man/rescale_weights.Rd b/man/rescale_weights.Rd
index 25d5a8958..45dd460b1 100644
--- a/man/rescale_weights.Rd
+++ b/man/rescale_weights.Rd
@@ -86,31 +86,57 @@ then divided by the design effect.
 }
 }
 \examples{
-if (require("lme4")) {
-  data(nhanes_sample)
-  head(rescale_weights(nhanes_sample, "SDMVSTRA", "WTINT2YR"))
+\dontshow{if (all(insight::check_if_installed(c("lme4", "parameters"), quietly = TRUE))) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
+data(nhanes_sample)
+head(rescale_weights(nhanes_sample, "SDMVSTRA", "WTINT2YR"))
 
-  # also works with multiple group-variables
-  head(rescale_weights(nhanes_sample, c("SDMVSTRA", "SDMVPSU"), "WTINT2YR"))
+# also works with multiple group-variables
+head(rescale_weights(nhanes_sample, c("SDMVSTRA", "SDMVPSU"), "WTINT2YR"))
 
-  # or nested structures.
-  x <- rescale_weights(
-    data = nhanes_sample,
-    by = c("SDMVSTRA", "SDMVPSU"),
-    probability_weights = "WTINT2YR",
-    nest = TRUE
-  )
-  head(x)
+# or nested structures.
+x <- rescale_weights(
+  data = nhanes_sample,
+  by = c("SDMVSTRA", "SDMVPSU"),
+  probability_weights = "WTINT2YR",
+  nest = TRUE
+)
+head(x)
+
+\donttest{
+# compare different methods, using multilevel-Poisson regression
 
-  nhanes_sample <- rescale_weights(nhanes_sample, "SDMVSTRA", "WTINT2YR")
+d <- rescale_weights(nhanes_sample, "SDMVSTRA", "WTINT2YR")
+result1 <- lme4::glmer(
+  total ~ factor(RIAGENDR) + log(age) + factor(RIDRETH1) + (1 | SDMVPSU),
+  family = poisson(),
+  data = d,
+  weights = pweights_a
+)
+result2 <- lme4::glmer(
+  total ~ factor(RIAGENDR) + log(age) + factor(RIDRETH1) + (1 | SDMVPSU),
+  family = poisson(),
+  data = d,
+  weights = pweights_b
+)
 
-  glmer(
-    total ~ factor(RIAGENDR) * (log(age) + factor(RIDRETH1)) + (1 | SDMVPSU),
-    family = poisson(),
-    data = nhanes_sample,
-    weights = pweights_a
-  )
+d <- rescale_weights(
+  nhanes_sample,
+  probability_weights = "WTINT2YR",
+  method = "kish"
+)
+result3 <- lme4::glmer(
+  total ~ factor(RIAGENDR) + log(age) + factor(RIDRETH1) + (1 | SDMVPSU),
+  family = poisson(),
+  data = d,
+  weights = pweights
+)
+parameters::compare_parameters(
+  list(result1, result2, result3),
+  exponentiate = TRUE,
+  column_names = c("Carle (A)", "Carle (B)", "Kish")
+)
 }
+\dontshow{\}) # examplesIf}
 }
 \references{
 \itemize{