*! version 1.0.0 10may2019

Title

svalue -- Computes and graphically displays S-values against their respective P-values

Syntax

svalue
#P-value
,
[
figure[(twoway_options)]
saving(filename, replace)
]

#P-value must be between 0.0001 and 1.0, with no more than 4 digits to the right of the decimal

figure[(twoway_options)] produces a plot of S-values against their respective P-values. Specifying figure
without options (or not specifying figure at all) uses the default graph settings

saving(filename, replace) save results to filename. The suboption "replace" is allowed

Description

svalue computes S-values corresponding to all P-values ranging from 0.0001 to 1.0, and generates a plot with the specific S-value highlighted.
An S-value (Greenland 2018, 2019), also referred to as a self-information or surprisal information measure (Shannon 1948; MacKay 2003; Fraundorf 2019),
is a negative base-2 log transformation of the P-value (or any probability value in the [0,1] range), such that S = -log(p)/log(2).

Greenland (Greenland 2017, 2018, 2019) advocates for the use of S-values to assist in the interpretation of P-values. The S-value is zero (unsurprising) when P = 1.0,
increases exponentially as P approaches zero, and can be intuitively yet correctly understood via a simple coin-tossing experiment.

As Fraundorf (2019) explains, a bit of surprisal is what you feel after "calling heads" on a coin toss, when the coin lands with heads up! Surprisal is two bits when
you throw heads on two of two coins at once. Three bits of surprisal (heads up on three of three coins) is starting to feel respectable. Twenty-four bits of surprisal,
on the other hand, is closer to what you experience when winning the lottery. Thus surprisal reduces the probability of an extremely rare event to a quantity
of more manageable size.

In the context of P-values, larger S-values correspond to more evidence against the null hypothesis. For example, the corresponding S-value for a P-value of 0.05
is 4.32 bits of information against the null hypothesis (b = 0), which is only slightly more surprising than seeing 4 heads on the first toss of 4 coins (Greenland 2019).
Similarly a P-value of 0.0001 has a corresponding S-value of 13.3 bits of information against the null hypothesis (b = 0), which is as surprising as seeing 13 heads
in the first toss of 13 coins.

svalue is an immediate command, see immed.

Options

figure[(twoway_options)] produces
a line graph in which S-values are plotted against their respective P-value within the range of 0.0001 and 1.0 (which is equal to an S-value of 0). Specifying figure without options (or simply not specifying figure) uses the
default graph settings.

saving(filename, replace) specifies the filename where the S-value and P-value variables generated by svalue will be saved. replace, used with
saving, specifies that filename can be replaced if it already exists.

Examples

We specify a P-value of 0.05. The resulting S-value of 4.3 bits of information against the null hypothesis (b = 0) is only slightly more surprising than seeing 4 heads on the first toss
of 4 coins.

. svalue 0.05

Here we specify a P-value of 0.50. The resulting S-value of 1 bit of information against the null hypothesis (b = 0) is no more surprising than seeing a head on a single toss of a coin.

. svalue 0.50

Here we specify a P-value of 0.0001. We also modify the figure by setting the scheme to scheme_scientific (downloadable from SSC). The resulting S-value
of 13.3 bits of information against the null hypothesis (b = 0) is as surprising as seeing 13 heads in the first toss of 13 coins.

. svalue 0.0001, fig(scheme(scientific))

Acknowledgments

I thank John Moran for advocating that I write this package.

References

Fraundorf, P. 2019. Examples of Surprisal.
Available at http://www.umsl.edu/~fraundorfp/egsurpri.html

Greenland, S. 2017. Invited Commentary: The Need for Cognitive Science in Methodology.
American Journal of Epidemiology 186(6): 639-645.

Greenland, S. 2018.
The Unconditional Information in P-values, and Its Refutational Interpretation via S-values. Unpublished manuscript.

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.

MacKay, D. J. C. 2003. Information Theory, Inference, and Learning Algorithms
Cambridge, Cambridge University Press

Shannon, C. E. 1948. A Mathematical Theory of Communication.
Bell System Technical Journal 27: 379–423, 623–656.

Citation of svalue

svalue is not an official Stata command. It is a free contribution
to the research community, like a paper. Please cite it as such:

Linden A. (2019). SVALUE: Stata module for computing and graphically displaying S-values against their respective P-values.
Statistical Software Components, Boston College Department of Economics.

Author

Ariel Linden

President, Linden Consulting Group, LLC

alinden@lindenconsulting.org

Also see

Online: cifunction (if installed), getregstats (if installed), scheme_scientific (if installed)