diff --git a/DESCRIPTION b/DESCRIPTION index a4129c71..b52506ec 100644 --- a/DESCRIPTION +++ b/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' 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/NEWS.md b/NEWS.md index d6d33206..4a52b5b5 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. + Major Changes * This release changes the licensing model of `{report}` to an MIT license. diff --git a/R/report_s.R b/R/report_s.R new file mode 100644 index 00000000..95654f38 --- /dev/null +++ b/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) +} 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 diff --git a/man/report_s.Rd b/man/report_s.Rd new file mode 100644 index 00000000..f90ccaa0 --- /dev/null +++ b/man/report_s.Rd @@ -0,0 +1,27 @@ +% 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, 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. +} +\description{ +Reports interpretation of S- and p-values in easy language. +} +\examples{ +report_s(s = 1.5) +report_s(p = 0.05) +} diff --git a/tests/testthat/_snaps/windows/report_s.md b/tests/testthat/_snaps/windows/report_s.md new file mode 100644 index 00000000..e60f51a3 --- /dev/null +++ b/tests/testthat/_snaps/windows/report_s.md @@ -0,0 +1,20 @@ +# report_s + + Code + report_s(s = 4.2) + Message + 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 + 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. + diff --git a/tests/testthat/test-report_s.R b/tests/testthat/test-report_s.R new file mode 100644 index 00000000..032ed42c --- /dev/null +++ b/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") +})