Draft report_s() (#384)

* Draft `report_s()`

* test, fix

* pkgdown

* check args

* tests

* Update R/report_s.R

Co-authored-by: Brenton M. Wiernik <[email protected]>

* Update R/report_s.R

Co-authored-by: Brenton M. Wiernik <[email protected]>

* Update R/report_s.R

Co-authored-by: Brenton M. Wiernik <[email protected]>

* fix

---------

Co-authored-by: Brenton M. Wiernik <[email protected]>
Co-authored-by: Rémi Thériault <[email protected]>

DESCRIPTION

@@ -139,6 +139,7 @@ Collate:
     'report_performance.R'
     'report_priors.R'
     'report_random.R'
+    'report_s.R'
     'report_sample.R'
     'report_statistics.R'
     'report_table.R'

NAMESPACE

@@ -297,6 +297,7 @@ export(report_participants)
 export(report_performance)
 export(report_priors)
 export(report_random)
+export(report_s)
 export(report_sample)
 export(report_statistics)
 export(report_story)

NEWS.md

@@ -1,5 +1,10 @@
 # report 0.5.8
 
+New features
+
+* `report_s()` to report the interpretation of S- and p-values in an easy-to-understand
+  language.
+
 Major Changes
 
 * This release changes the licensing model of `{report}` to an MIT license. 

R/report_s.R

@@ -0,0 +1,38 @@
+#' Report S- and p-values in easy language.
+#'
+#' Reports interpretation of S- and p-values in easy language.
+#'
+#' @param s An S-value. Either `s` or `p` must be provided.
+#' @param p A p-value. Either `s` or `p` must be provided.
+#' @param test_value The value of the test parameter under the null hypothesis.
+#' @param test_parameter The name of the test parameter under the null hypothesis.
+#'
+#' @return A string with the interpretation of the S- or p-value.
+#'
+#' @examples
+#' report_s(s = 1.5)
+#' report_s(p = 0.05)
+#' @export
+report_s <- function(s = NULL, p = NULL, test_value = 0, test_parameter = "parameter") {
+  # sanity check arguments
+  if ((is.null(s) || all(is.na(s))) && (is.null(p) || all(is.na(p)))) {
+    insight::format_error("You must provide either `s` or `p`.")
+  }
+  if (length(s) > 1 || length(p) > 1) {
+    insight::format_error("You must provide a single value for `s` or `p`.")
+  }
+  # make sure we have both s and p
+  if (!is.null(p) && !is.na(p)) {
+    s <- -log2(p)
+  } else {
+    p <- 2^(-s)
+  }
+  all_heads <- round(s)
+  chance <- sprintf("%.2g", 100 * p)
+  msg <- paste0(
+    "If the test hypothesis (", test_parameter, " = ", test_value, ") and all model assumptions were true, ",
+    "there is a ", chance, "% chance of observing this outcome. How weird is that? ",
+    "It's hardly more surprising than getting ", all_heads, " heads in a row with fair coin tosses."
+  )
+  insight::format_alert(msg)
+}

_pkgdown.yml

@@ -59,6 +59,7 @@ reference:
       - report_performance
       - report_priors
       - report_random
+      - report_s
       - report_sample
       - report_statistics
 

tests/testthat/_snaps/windows/report_s.md

@@ -0,0 +1,20 @@
+# report_s
+
+    Code
+      report_s(s = 4.2)
+    Message <simpleMessage>
+      If the test hypothesis (parameter = 0) and all model assumptions were
+        true, there is a 5.4% chance of observing this outcome. How weird is
+        that? It's hardly more surprising than getting 4 heads in a row with
+        fair coin tosses.
+
+---
+
+    Code
+      report_s(p = 0.06)
+    Message <simpleMessage>
+      If the test hypothesis (parameter = 0) and all model assumptions were
+        true, there is a 6% chance of observing this outcome. How weird is that?
+        It's hardly more surprising than getting 4 heads in a row with fair coin
+        tosses.
+

tests/testthat/test-report_s.R

@@ -0,0 +1,9 @@
+test_that("report_s", {
+  expect_snapshot(report_s(s = 4.2), variant = "windows")
+  expect_snapshot(report_s(p = 0.06), variant = "windows")
+})
+
+test_that("report_s, arguments", {
+  expect_error(report_s())
+  expect_error(report_s(s = 1:2), "single value")
+})