svalue: Surprisal Value

In extras: Helper Functions for Bayesian Analyses

Surprisal Value

Description

The surprisal value (Greenland 2019) is a probability expressed in terms of how many consecutive heads would have to be thrown on a fair coin in a single attempt to achieve the same probability: -\log_2(p), where p is the p-value of interest. See the details section for some examples.

Usage

svalue(x, ..., side = "both", threshold = 0, skeptical = TRUE, na_rm = FALSE)

p2svalue(p)

Arguments

x	A numeric object of MCMC values.
...	Unused.
side	A character indicating whether to calculate s-values using p-values for the left tail ("left"), right tail ("right"), or both tails ("both"; default).
threshold	A number of the threshold value.
skeptical	A flag specifying whether or not to add one sample to the empty side of the threshold when 100% of samples are on one side. Avoids zero p-values and infinite s-values, and also imposes stronger bounds on directional information than [-n, n], which assume the MCMC samples are independent and representative.
na_rm	A flag specifying whether to remove missing values.
p	A numeric vector of probabilities.

Details

A near-certain event has an s-value near 0 because it is similar to getting 0 successful coin flips out of 0 tosses, which is certain and unsurprising.

An event with a probability of 0.5 is as surprising as getting a successful coin toss.

A near-impossible event has a very large s-value because its occurrence would be extremely surprising, like observing many consecutive successes on a fair coin.

When skeptical = TRUE (default), a ceiling of \log_2(n + 1) is applied to the s-value to avoid s-values of Inf when all samples are on one side of the threshold. When skeptical = FALSE, s-values of Inf are allowed.

Value

A non-negative number. If x has NA values but na_rm is FALSE, returns NA_real.

Functions

• svalue(): Calculate an s-value from a posterior distribution.

• p2svalue(): Calculate an s-value from a vector of probabilities.

References

Greenland, S. 2019. Valid P-Values Behave Exactly as They Should: Some Misleading Criticisms of P-Values and Their Resolution With S-Values. The American Statistician 73(sup1): 106–114. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1080/00031305.2018.1529625")}.

See Also

Other summary: direction(), directional_information(), kurtosis(), lower(), probability_direction(), pvalue(), pzeros(), skewness(), upper(), variance(), xtr_mean(), xtr_median(), xtr_sd(), zeros(), zscore()

Examples

svalue(as.numeric(0:100))
svalue(as.numeric(0:100), side = "left")
svalue(as.numeric(0:100), side = "right")
svalue(rnorm(1e4, mean = 1), side = "left")
svalue(rnorm(1e4, mean = 1), side = "right")
svalue(rep(1, 10)) # skeptical = TRUE (default) avoids Inf
svalue(rep(1, 10), skeptical = FALSE) # skeptical = FALSE allows Inf

p2svalue(seq(0, 1, by = 0.1))

extras documentation built on July 16, 2026, 1:07 a.m.