*! version 1.04 05 Jul 2020

Title

plotsgpv -- Plotting Second-Generation P-Values

Syntax

plotsgpv
[if]
[in],
estlo(name) esthi(name) nulllo(boundlist) nullhi(boundlist)
[options]

Main
estlo(name) lower bound of interval estimate.

eshi(name) upper bound of interval estimate.

nulllo(boundlist) lower bound of null interval.

nullhi(boundlist) upper bound of null interval.

Colors
nullcol(colorstyle:color) coloring of the null interval (indifference zone).

intcol1(colorstyle:color) color of the interval according to SGPV ranking for SGPV = 0.

intcol2(colorstyle:color) color of the interval according to SGPV ranking for 0 < SGPV < 1.

intcol3(colorstyle:color) color of the interval according to SGPV ranking for SGPV = 1.

Titles
title(string) title of the plot.

xtitle(string) label of the x-axis.

ytitle(string) label of the y-axis.

Further options
noplotx_axis deactive showing the x-axis.

noploty_axis deactive showing the y-axis.

nolegend deactivate plotting the legend.

nooutlinezone deactivate drawing a slim white outline around the null zone.

setorder(string) a variable giving the desired order along the x-axis.

xshow(#) a number representing the maximum ranking on the x-axis that is displayed.

nullpt(#) a number representing a point null hypothesis.

nomata do not use Mata for calculating the SGPVs.

replace replace existing variables in case the nomata-option was used.

twoway_opt(twoway_options:options) any additional options for the plotting go here.

Description

Plot the second-generation p-value (SGPV), as introduced in Blume et al. (2018), for user supplied interval estimates (support intervals, confidence intervals, credible intervals, etc.) according to its associated second-generation p-value ranking.
This command and its companions commands (sgpvalue, sgpower, fdrisk) are based on the R-code for the sgpv-package from https://github.com/weltybiostat/sgpv.
A dialog box for easier usage is available.
The command works best if a dataset is used which contains the estimation or test results similar to the example leukstats-dataset.

Options

Main

estlo(name) lower bound of interval estimate.
Typically the lower bound of a confidence interval can be used. A variable or matrix containing the lower bound can be also used, but then a variable/matrix containing the upper bounds must be also used for option esthi.

esthi(name) upper bound of interval estimate.
Typically the upper bound of a confidence interval can be used. A variable or matrix containing the upper bound can be also used but then a variable/matrix containing the lower bounds must be also used for option estlo.

nulllo(boundlist) lower bound of null interval.

nulllo(boundlist) upper bound of null interval.

A boundlist is:
# [# ...]
exp [exp ...]

Colors

nullcol(colorstyle:color) coloring of the null interval (indifference zone). Default is the R-color "Hawkes Blue". You can see the color before plotting via
palette color 208 216 232.
You can set the color to any other available color in Stata. See colorstyle for more information.

Interval colors

The coloring of the intervals according to SGPV ranking. Default are the R-colors ("cornflowerblue","firebrick3","darkslateblue") for SGPVs of 0, in (0,1), and 1 respectively.
You can see the default color(s) before plotting via:

palette color 205 38 38 firebrick3 for SGPV = 0

palette color 100 149 237 cornflowerblue for 0 < SGPV < 1

palette color 72 61 139 darkslateblue for SGPV = 1

You can set the colors to any other available color in Stata. See colorstyle for more information.

intcol1(colorstyle:color) color of the interval with the R-color "firebrick3" as the default for SGPV = 0

intcol2(colorstyle:color) color of the interval with the R-color "cornflowerblue" as the default for 0 < SGPV < 1

intcol3(colorstyle:color) color of the interval with the R-color "firebrick3" as the default for SGPV = 1

Title options

title(string) title of the plot.

xtitle(string) label of the x-axis. Default is "Ranking according to <order>" where <order> can refer to the value of the option setorder() or the original sorting of the input.

ytitle(string) label of the y-axis.

Further options

noplotx_axis deactivate showing the x-axis.

noploty_axis deactivate showing the y-axis.

nooutlinezone deactivate drawing a slim white outline around the null zone. Helpful visual aid when plotting many intervals. Default is on.

nolegend deactivate plotting the legend.

setorder(string) a variable giving the desired order along the x-axis.
If setorder is set to "sgpv", the second-generation p-value ranking is used.
If setorder is empty, the original input ordering is used.

xshow(#) a number representing the maximum ranking on the x-axis that is displayed.
Default is to display all intervals.

nullpt(#) a number representing a point null hypothesis.
If set, the command will draw a horizontal dashed red line at this location.

nomata deactivate the usage of Mata for calculating the SGPVs with matrices larger than c(matsize) or variables.
If this option is set, an approach based on variables is used.
Using variables instead of Mata will be faster, but new variables containing the results are created.
If you don't want to create new variables and time is not an issue then don't set this option.
Stata might become unresponsive when using Mata because it takes time to return a large matrix.

replace replace existing variables in case the nomata-option was used.

twoway_opt(twoway_opt:options) any additional options for the plotting go here.
Options set here may override the values set in other options before.

Examples

Replicate the example plot from the R-code with the example dataset provided with this command:
(If you did not already install the example dataset,
then you can download it here together with the file plotsgpv-leukemia-example.do which helps you run the example in Stata.)
Run following the lines with the help of do plotsgpv-leukemia-example.do

. sysuse leukstats ,clear

. plotsgpv, esthi(ci_hi) estlo(ci_lo) nulllo(-0.3) nullhi(0.3)
title("Leukemia Example") xtitle("Classical p-value ranking") ytitle("Fold Change (base 10)")
setorder(p_value) xshow(7000) nullpt(0) nomata replace
twoway_opt(ylabel(`=log10(1/1000)' "1/1000" `=log10(1/100)' "1/100" `=log10(1/10)' "1/10"
`=log10(1/2)' "1/2" `=log10(2)' "2" `=log10(10)' "10" `=log10(100)' "100" `=log10(1000)' "1000"))

The last option in twoway_opt(...) changes the labeling of the y-axis (See axis_label_options for more information).

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, sgpvalue, sgpower, sgpv