From bc47ac08e0a2afd76e9695edb0ed865295cbad49 Mon Sep 17 00:00:00 2001
From: Daniel <mail@danielluedecke.de>
Date: Wed, 26 Jul 2023 14:46:55 +0200
Subject: [PATCH 1/9] Draft `report_s()`

---
 DESCRIPTION     |  3 ++-
 NEWS.md         |  5 +++++
 R/report_s.R    | 29 +++++++++++++++++++++++++++++
 man/report_s.Rd | 20 ++++++++++++++++++++
 4 files changed, 56 insertions(+), 1 deletion(-)
 create mode 100644 R/report_s.R
 create mode 100644 man/report_s.Rd

diff --git a/DESCRIPTION b/DESCRIPTION
index 20891322..e5b74f05 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -1,7 +1,7 @@
 Type: Package
 Package: report
 Title: Automated Reporting of Results and Statistical Models
-Version: 0.5.7.10
+Version: 0.5.7.11
 Authors@R:
     c(person(given = "Dominique",
              family = "Makowski",
@@ -136,6 +136,7 @@ Collate:
     'report_performance.R'
     'report_priors.R'
     'report_random.R'
+    'report_s.R'
     'report_sample.R'
     'report_statistics.R'
     'report_table.R'
diff --git a/NEWS.md b/NEWS.md
index dafbc243..80526d58 100644
--- a/NEWS.md
+++ b/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.
+
 Minor changes 
 
 * `report` now supports variables of class `Date`, treating them like factors.
diff --git a/R/report_s.R b/R/report_s.R
new file mode 100644
index 00000000..214d4e7e
--- /dev/null
+++ b/R/report_s.R
@@ -0,0 +1,29 @@
+#' 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.
+#' @examples
+#' report_s(s = 1.5)
+#' report_s(p = 0.05)
+report_s <- function(s = NULL, p = NULL) {
+  # sanity check arguments
+  if ((is.null(s) && is.null(p)) || (is.na(s) && is.na(p))) {
+    insight::format_error("You must provide either `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 and entire model (all 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)
+}
diff --git a/man/report_s.Rd b/man/report_s.Rd
new file mode 100644
index 00000000..99010879
--- /dev/null
+++ b/man/report_s.Rd
@@ -0,0 +1,20 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/report_s.R
+\name{report_s}
+\alias{report_s}
+\title{Report S- and p-values in easy language.}
+\usage{
+report_s(s = NULL, p = NULL)
+}
+\arguments{
+\item{s}{An S-value. Either \code{s} or \code{p} must be provided.}
+
+\item{p}{A p-value. Either \code{s} or \code{p} must be provided.}
+}
+\description{
+Reports interpretation of S- and p-values in easy language.
+}
+\examples{
+report_s(s = 1.5)
+report_s(p = 0.05)
+}

From 9fa9709ac09d2ce97af3a97dd01ed0de7f42b96c Mon Sep 17 00:00:00 2001
From: Daniel <mail@danielluedecke.de>
Date: Wed, 26 Jul 2023 14:51:15 +0200
Subject: [PATCH 2/9] test, fix

---
 NAMESPACE                                 |  1 +
 R/report_s.R                              |  4 ++++
 man/report_s.Rd                           |  3 +++
 tests/testthat/_snaps/windows/report_s.md | 20 ++++++++++++++++++++
 tests/testthat/test-report_s.R            |  4 ++++
 5 files changed, 32 insertions(+)
 create mode 100644 tests/testthat/_snaps/windows/report_s.md
 create mode 100644 tests/testthat/test-report_s.R

diff --git a/NAMESPACE b/NAMESPACE
index 6b7174c1..a3cb2ff5 100644
--- a/NAMESPACE
+++ b/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)
diff --git a/R/report_s.R b/R/report_s.R
index 214d4e7e..57c3b9e9 100644
--- a/R/report_s.R
+++ b/R/report_s.R
@@ -4,9 +4,13 @@
 #'
 #' @param s An S-value. Either `s` or `p` must be provided.
 #' @param p A p-value. Either `s` or `p` must be provided.
+#'
+#' @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) {
   # sanity check arguments
   if ((is.null(s) && is.null(p)) || (is.na(s) && is.na(p))) {
diff --git a/man/report_s.Rd b/man/report_s.Rd
index 99010879..af6e4b26 100644
--- a/man/report_s.Rd
+++ b/man/report_s.Rd
@@ -11,6 +11,9 @@ report_s(s = NULL, p = NULL)
 
 \item{p}{A p-value. Either \code{s} or \code{p} must be provided.}
 }
+\value{
+A string with the interpretation of the S- or p-value.
+}
 \description{
 Reports interpretation of S- and p-values in easy language.
 }
diff --git a/tests/testthat/_snaps/windows/report_s.md b/tests/testthat/_snaps/windows/report_s.md
new file mode 100644
index 00000000..2e470dcd
--- /dev/null
+++ b/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 and entire model (all 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 and entire model (all 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.
+
diff --git a/tests/testthat/test-report_s.R b/tests/testthat/test-report_s.R
new file mode 100644
index 00000000..115fb8a6
--- /dev/null
+++ b/tests/testthat/test-report_s.R
@@ -0,0 +1,4 @@
+test_that("report_s", {
+  expect_snapshot(report_s(s = 4.2), variant = "windows")
+  expect_snapshot(report_s(p = 0.06), variant = "windows")
+})

From 67a7f921a424ec755f13381ab9492159b548f0a1 Mon Sep 17 00:00:00 2001
From: Daniel <mail@danielluedecke.de>
Date: Wed, 26 Jul 2023 14:53:30 +0200
Subject: [PATCH 3/9] pkgdown

---
 _pkgdown.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/_pkgdown.yml b/_pkgdown.yml
index c13dea49..e8dc6725 100644
--- a/_pkgdown.yml
+++ b/_pkgdown.yml
@@ -59,6 +59,7 @@ reference:
       - report_performance
       - report_priors
       - report_random
+      - report_s
       - report_sample
       - report_statistics
 

From 0f4c160e6b89b0eef749caacc00fd2f3f1437828 Mon Sep 17 00:00:00 2001
From: Daniel <mail@danielluedecke.de>
Date: Wed, 26 Jul 2023 14:54:24 +0200
Subject: [PATCH 4/9] check args

---
 R/report_s.R | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/R/report_s.R b/R/report_s.R
index 57c3b9e9..711b2c06 100644
--- a/R/report_s.R
+++ b/R/report_s.R
@@ -16,6 +16,9 @@ report_s <- function(s = NULL, p = NULL) {
   if ((is.null(s) && is.null(p)) || (is.na(s) && 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)

From c8735de7817dd4ebd6f2416ddf96243e50a2278e Mon Sep 17 00:00:00 2001
From: Daniel <mail@danielluedecke.de>
Date: Wed, 26 Jul 2023 14:55:23 +0200
Subject: [PATCH 5/9] tests

---
 tests/testthat/test-report_s.R | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/tests/testthat/test-report_s.R b/tests/testthat/test-report_s.R
index 115fb8a6..032ed42c 100644
--- a/tests/testthat/test-report_s.R
+++ b/tests/testthat/test-report_s.R
@@ -2,3 +2,8 @@ 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")
+})

From 59f75476d78c00ec50886e0e3109439d230f4591 Mon Sep 17 00:00:00 2001
From: Daniel <mail@danielluedecke.de>
Date: Thu, 27 Jul 2023 09:27:07 +0200
Subject: [PATCH 6/9] Update R/report_s.R

Co-authored-by: Brenton M. Wiernik <bwiernik@users.noreply.github.com>
---
 R/report_s.R | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/R/report_s.R b/R/report_s.R
index 711b2c06..39e05ee6 100644
--- a/R/report_s.R
+++ b/R/report_s.R
@@ -13,7 +13,7 @@
 #' @export
 report_s <- function(s = NULL, p = NULL) {
   # sanity check arguments
-  if ((is.null(s) && is.null(p)) || (is.na(s) && is.na(p))) {
+  if ((is.null(s) || is.na(s)) && (is.null(p) || is.na(p))) {
     insight::format_error("You must provide either `s` or `p`.")
   }
   if (length(s) > 1 || length(p) > 1) {

From 37ad554f6d05ebc22a320f2995551cbd54c99595 Mon Sep 17 00:00:00 2001
From: Daniel <mail@danielluedecke.de>
Date: Thu, 27 Jul 2023 09:28:03 +0200
Subject: [PATCH 7/9] Update R/report_s.R

Co-authored-by: Brenton M. Wiernik <bwiernik@users.noreply.github.com>
---
 R/report_s.R | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/R/report_s.R b/R/report_s.R
index 39e05ee6..7a95828f 100644
--- a/R/report_s.R
+++ b/R/report_s.R
@@ -28,7 +28,7 @@ report_s <- function(s = NULL, p = NULL) {
   all_heads <- round(s)
   chance <- sprintf("%.2g", 100 * p)
   msg <- paste0(
-    "If the test hypothesis and entire model (all assumptions) were true, ",
+    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."
   )

From b7a10a5bf87a70b9236b1a27191964e7187c954b Mon Sep 17 00:00:00 2001
From: Daniel <mail@danielluedecke.de>
Date: Thu, 27 Jul 2023 09:28:10 +0200
Subject: [PATCH 8/9] Update R/report_s.R

Co-authored-by: Brenton M. Wiernik <bwiernik@users.noreply.github.com>
---
 R/report_s.R | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/R/report_s.R b/R/report_s.R
index 7a95828f..d9fe95ac 100644
--- a/R/report_s.R
+++ b/R/report_s.R
@@ -11,7 +11,7 @@
 #' report_s(s = 1.5)
 #' report_s(p = 0.05)
 #' @export
-report_s <- function(s = NULL, p = NULL) {
+report_s <- function(s = NULL, p = NULL, test_value = 0, test_parameter = "parameter") {
   # sanity check arguments
   if ((is.null(s) || is.na(s)) && (is.null(p) || is.na(p))) {
     insight::format_error("You must provide either `s` or `p`.")

From 0a96f19fd0b9d8307f728a17ac161ebf32cd7109 Mon Sep 17 00:00:00 2001
From: Daniel <mail@danielluedecke.de>
Date: Thu, 27 Jul 2023 09:35:16 +0200
Subject: [PATCH 9/9] fix

---
 R/report_s.R                              |  6 ++++--
 man/report_s.Rd                           |  6 +++++-
 tests/testthat/_snaps/windows/report_s.md | 14 +++++++-------
 3 files changed, 16 insertions(+), 10 deletions(-)

diff --git a/R/report_s.R b/R/report_s.R
index d9fe95ac..95654f38 100644
--- a/R/report_s.R
+++ b/R/report_s.R
@@ -4,6 +4,8 @@
 #'
 #' @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.
 #'
@@ -13,7 +15,7 @@
 #' @export
 report_s <- function(s = NULL, p = NULL, test_value = 0, test_parameter = "parameter") {
   # sanity check arguments
-  if ((is.null(s) || is.na(s)) && (is.null(p) || is.na(p))) {
+  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) {
@@ -28,7 +30,7 @@ report_s <- function(s = NULL, p = NULL, test_value = 0, test_parameter = "param
   all_heads <- round(s)
   chance <- sprintf("%.2g", 100 * p)
   msg <- paste0(
-    paste0("If the test hypothesis (", test_parameter, " = ", test_value) " and all model assumptions were true, ",
+    "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."
   )
diff --git a/man/report_s.Rd b/man/report_s.Rd
index af6e4b26..f90ccaa0 100644
--- a/man/report_s.Rd
+++ b/man/report_s.Rd
@@ -4,12 +4,16 @@
 \alias{report_s}
 \title{Report S- and p-values in easy language.}
 \usage{
-report_s(s = NULL, p = NULL)
+report_s(s = NULL, p = NULL, test_value = 0, test_parameter = "parameter")
 }
 \arguments{
 \item{s}{An S-value. Either \code{s} or \code{p} must be provided.}
 
 \item{p}{A p-value. Either \code{s} or \code{p} must be provided.}
+
+\item{test_value}{The value of the test parameter under the null hypothesis.}
+
+\item{test_parameter}{The name of the test parameter under the null hypothesis.}
 }
 \value{
 A string with the interpretation of the S- or p-value.
diff --git a/tests/testthat/_snaps/windows/report_s.md b/tests/testthat/_snaps/windows/report_s.md
index 2e470dcd..e60f51a3 100644
--- a/tests/testthat/_snaps/windows/report_s.md
+++ b/tests/testthat/_snaps/windows/report_s.md
@@ -3,18 +3,18 @@
     Code
       report_s(s = 4.2)
     Message <simpleMessage>
-      If the test hypothesis and entire model (all 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.
+      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 and entire model (all 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
+      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.