{smcl}
{* *! version 1.0.0 10may2019}{...}
{title:Title}

{p2colset 5 15 20 2}{...}
{p2col:{hi:svalue} {hline 2}} Computes and graphically displays S-values against their respective P-values {p_end}
{p2colreset}{...}


{title:Syntax}

{p 8 14 2}
{cmd:svalue}
{it: #P-value}
{cmd:,}
[
{opt fig:ure}[{cmd:(}{it:{help twoway_options:twoway_options}}{cmd:)}]
{opt sav:ing}({it:{help filename:filename}, replace})
]

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


{synoptset 26 tabbed}{...}
{synopthdr}
{synoptline}
{synopt:{opt fig:ure}[{cmd:(}{it:{help twoway_options:twoway_options}}{cmd:)}]}produces a plot of S-values against their respective {it:P}-values. Specifying {cmd:figure} 
without options (or not specifying {cmd:figure} at all) uses the default graph settings {p_end}
{synopt :{help prefix_saving_option:{bf:{ul:sav}ing(}{it:filename}{bf:, replace)}}}save results to {it:filename}. The suboption "replace" is allowed{p_end}
{synoptline}



{title:Description}

{pstd}
{opt svalue} computes S-values corresponding to all {it: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 {it: self-information} or {it:surprisal} information measure (Shannon 1948; MacKay 2003; Fraundorf 2019),
is a negative base-2 log transformation of the {it:P}-value (or any probability value in the [0,1] range), such that S = -log(p)/log(2).  

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

{pstd}
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.

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

{pstd}
{opt svalue} is an immediate command, see {helpb immed}.



{title:Options}

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

{p 4 8 2}
{cmd:{help prefix_saving_option:{bf:{ul:sav}ing(}{it:filename}{bf:, replace)}}} specifies the filename where the S-value and {it:P}-value variables generated by {cmd:svalue} will be saved. {cmd:replace}, used with 
{cmd:saving}, specifies that {it:{help filename}} can be replaced if it already exists.



{title:Examples}

{pmore} We specify a {it:P}-value of 0.05. The resulting S-value of 4.3 bits of information against the null hypothesis ({it:b} = 0) is only slightly more surprising than seeing 4 heads on the first toss 
of 4 coins. {p_end}
{pmore2}{bf:{stata "svalue 0.05": . svalue 0.05}} {p_end}

{pmore} Here we specify a {it:P}-value of 0.50. The resulting S-value of 1 bit of information against the null hypothesis ({it:b} = 0) is no more surprising than seeing a head on a single toss of a coin. {p_end}
{pmore2}{bf:{stata "svalue 0.50": . svalue 0.50}} {p_end}

{pmore} Here we specify a {it:P}-value of 0.0001. We also modify the figure by setting the scheme to {helpb scheme_scientific} (downloadable from SSC). The resulting S-value 
of 13.3 bits of information against the null hypothesis ({it:b} = 0) is as surprising as seeing 13 heads in the first toss of 13 coins.{p_end}
{pmore2}{bf:{stata "svalue 0.0001, fig(scheme(scientific))": . svalue 0.0001, fig(scheme(scientific))}} {p_end}



{title:Acknowledgments}

{p 4 4 2}
I thank John Moran for advocating that I write this package. 



{title:References}

{phang}
Fraundorf, P. 2019. {it: Examples of Surprisal}. 
Available at {browse "http://www.umsl.edu/~fraundorfp/egsurpri.html"}

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

{phang}
Greenland, S. 2018. 
{it: The Unconditional Information in P-values, and Its Refutational Interpretation via S-values}. Unpublished manuscript.

{phang}
Greenland, S. 2019. Valid P-Values Behave Exactly as They Should:
Some Misleading Criticisms of P-Values and Their Resolution With S-Values.
{it: The American Statistician} 73(sup1): 106-114.

{phang}
MacKay, D. J. C. 2003. {it:Information Theory, Inference, and Learning Algorithms}
Cambridge, Cambridge University Press

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



{marker citation}{title:Citation of {cmd:svalue}}

{p 4 8 2}{cmd:svalue} is not an official Stata command. It is a free contribution
to the research community, like a paper. Please cite it as such: {p_end}

{p 4 8 2}
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.



{title:Author}

{p 4 4 2}
Ariel Linden{break}
President, Linden Consulting Group, LLC{break}
alinden@lindenconsulting.org{break}



{title:Also see}

{p 4 8 2} Online: {helpb cifunction} (if installed), {helpb getregstats} (if installed), {helpb scheme_scientific} (if installed) {p_end}