*! version 1.02 10 Jul 2020

Title

sgpower -- Power functions for Second-Generation P-Values

Syntax

sgpower, true(#) nulllo(#) nullhi(#) level(#) likelihood(#)
[stderr(#) bonus]

Main
true(#) the true value for the parameter of interest at which to calculate power.

nulllo(#) the lower bound of the indifference zone (null interval) upon which the second-generation p-value is based.

nullhi(#) the upper bound for the indifference zone (null interval) upon which the second-generation p-value is based.

level(#) confidence interval with the specified level was used to calculated the SGPV; default is level(95).

likelihood(#) likelihood support interval with level 1/k was used to calculate the SGPV.

Further options
stderr(#) standard error for the distribution of the estimator for the parameter of interest.

bonus display the additional diagnostics for the type I error.

Description

Compute power/type I error for Second-Generation P-Values approach. See here for more information about the Second-Generation P-Values.

An additional GUI makes using this command easier.
To make the GUI available from the User-menubar, you have to run sgpv menu.

The power functions are the following based on the equations (S4), (S6), (S8) and (S9)
from the supplementary material to Blume et al.(2018):

P_θ(p_δ = 0) = ϕ[(θ_0 - δ) /SE - θ/SE + Z_α/2 ] + ϕ[ -(θ_0 + δ) /SE + θ/SE - Z_α/2 ]
P_θ(p_δ = 1) = ϕ[(θ_0 + δ) /SE - θ/SE - Z_α/2 ] - ϕ[ (θ_0 - δ) /SE - θ/SE + Z_α/2 ]
P_θ(0 < p_δ < 1) = 1 - ϕ[ (θ_0 - δ) /SE - θ/SE - Z_α/2 ] + ϕ[ -(θ_0 + δ) /SE + θ/SE - Z_α/2 ]
- ϕ[ (θ_0 + δ) /SE - θ/SE - Z_α/2 ] - ϕ[ (θ_0 - δ) /SE - θ/SE + Z_α/2 ]
when δ > Z_α/2 * SE
P_θ(0 < p_δ < 1) = 1 - ϕ[ (θ_0 - δ) /SE - θ/SE - Z_α/2 ] + ϕ[ -(θ_0 + δ) /SE + θ/SE - Z_α/2 ]
when δ <= Z_α/2 * SE

SE denotes the standard error, (θ_0 - δ) and (θ_0 + δ) denote the lower and upper bound of the null interval.

Options

Main

true(#) the true value for the parameter of interest at which to calculate power.
Note that this is on the absolute scale of the parameter, and not the standard deviation or standard error scale.

nulllo(#) the lower bound of the indifference zone (null interval) upon which the second-generation p-value is based.

nullhi(#) the upper bound for the indifference zone (null interval) upon which the second-generation p-value is based.

level(#) confidence interval with level (1-α)100% was used to calculated the SGPV. The default is level(95) or as set by set level if option likelihood or another confidence level is not set.

likelihood(#) likelihood support interval with level 1/k was used to calculate the SGPV. The level is 1/k (not k).
For technical reasons, a fraction like 1/8 as the level must be converted to a real number like 0.125 first, when used for this option.

Further options

stderr(#) standard error for the distribution of the estimator for the parameter of interest.
Note that this is the standard deviation for the estimator, not the standard deviation parameter for the data itself.
This will be a function of the sample size(s).

bonus display the additional diagnostics for type I error. These are different ways the type I error may be summarized for an interval null hypothesis.

Examples

. sgpower,true(2) nulllo(-1) nullhi(1) stderr(1)

. sgpower,true(0) nulllo(-1) nullhi(1) stderr(1)

Plot the power curve examples: Click here to view the code which is part of the ancillary files of the sgpv-package.
To download the file together with the rest of the examples click here.

. do sgpower-plot-example.do

Stored results

Scalars

r(poweralt) probability of SGPV = 0 calculated assuming the parameter is equal to true. That is, poweralt = P(SGPV = 0 | θ = true).

r(powernull) probability of SGPV = 1 calculated assuming the parameter is equal to true. That is, powernull = P(SGPV = 1 | θ = true).

r(powerinc) probability of 0 < SGPV < 1 calculated assuming the parameter is equal to true. That is, powerinc = P(0 < SGPV < 1 | θ = true).

The next three scalars are only returned if the bonus-option was used.

r(minI) minimum type I error over the range (nulllo, nullhi), which occurs at the midpoint of (nulllo, nullhi).

r(maxI) maximum type I error over the range (nulllo, nullhi), which occurs at the boundaries of the null hypothesis, nulllo and nullhi.

r(avgI) average type I error (unweighted) over the range (nulllo, nullhi).

If 0 is included in the null hypothesis region, then "type I error summaries" also contains "at 0":

r(pow0) type I error assuming the true parameter value θ is equal to 0.

References

Blume JD, D’Agostino McGowan L, Dupont WD, Greevy RA Jr. (2018). Second-generation p-values: Improved rigor, reproducibility, & transparency in statistical analyses. PLoS ONE 13(3): e0188299.
https://doi.org/10.1371/journal.pone.0188299

Blume JD, Greevy RA Jr., Welty VF, Smith JR, Dupont WD (2019). An Introduction to Second-generation p-values. The American Statistician. In press. https://doi.org/10.1080/00031305.2018.1537893

Author

Sven-Kristjan Bormann, School of Economics and Business Administration, University of Tartu.

Bug Reporting

Please submit bugs, comments and suggestions via email to:	sven-kristjan@gmx.de

Further Stata programs and development versions can be found under https://github.com/skbormann/stata-tools

See Also

Related commands:

fdrisk, plotsgpv, sgpvalue, sgpv