sgpv (version 1.1.0)

plotman: Second-Generation p-Value Plotting

Description

This function displays a modified Manhattan-style plot colored according to second-generation p-value status. There are several variations of this plot that can be made depending upon user input for type as well as the set.order and x.show options. These plots allow the user to visualize the overall result of a large-scale analysis succintly and to visually assess the differences in the results using second-generation p-value techniques as opposed to classical p-value techniques.

Usage

plotman(
  est.lo,
  est.hi,
  null.lo,
  null.hi,
  set.order = NA,
  x.show = NA,
  type = "delta-gap",
  p.values = NA,
  ref.lines = NA,
  null.pt = NA,
  int.col = c("cornflowerblue", "firebrick3", "darkslateblue"),
  int.pch = 16,
  int.cex = 0.4,
  title.lab = NA,
  x.lab = "Position (by set.order)",
  y.lab = "Outcome label",
  legend.on = TRUE
)

Arguments

est.lo

A numeric vector of lower bounds of interval estimates. Must be of same length as est.hi.

est.hi

A numeric vector of upper bounds of interval estimates. Must be of same length as est.lo.

null.lo

A scalar representing the lower bound of the null interval hypothesis (indifference zone). Value must be finite.

null.hi

A scalar representing the upper bound of the null interval hypothesis (indifference zone). Value must be finite.

set.order

A numeric vector giving the desired order along the x-axis. Alternatively, if set.order is set to "sgpv", the second-generation p-value ranking is used. The default option is NA, which uses the original input ordering.

x.show

A numeric scalar representing the maximum ranking on the x-axis that is displayed. Default is to display all rankings.

type

A string specifying the desired Manhattan-style plot to be graphed. This argument specifies the variable on the y-axis. If type = "delta-gap", the delta-gaps are ranked. If type = "p-value", the classic p-values are ranked. If type = "comparison", the classic p-values are ranked by SGPV. Default is type = "delta-gap".

p.values

A numeric vector giving the classic p-values. This is required when type = "p-value" or type = "comparison", and is not required when type = "delta-gap". The p.values input may be any desired transformation of the p-values. For example, if the desired transformation is \(-log10(p-value)\) as in a traditional Manhattan plot, the \(-log10(p-values)\) should be provided for p.values. The corresponding x or y axis label(s) should be updated to reflect any transformations.

ref.lines

A numeric scalar or vector giving the points on the y-axis at which to add a horizontal reference line. For example, if p.values is set to \(-log10(p-values)\) and the type of plot selected shows the (transformed) p-values on the y-axis, possible locations for the reference lines could be at the \(-log10(0.05)\), \(-log10(Bonferroni)\) and \(-log10(FDR)\) significance levels.

null.pt

An optional numeric scalar representing a point null hypothesis. Default is NA.

int.col

Vector of length three specifing the colors of the points according to SGPV result. The first color option corresponds to the \(SGPV = 0\) results, the second color option corresponds to the \(0 < SGPV < 1\) results, and the third color option corresponds to the \(SGPV = 1\) results. Default is int.col = c("cornflowerblue","firebrick3","darkslateblue").

int.pch

Plotting symbol for points. Default is 16 for small points.

int.cex

Size of plotting symbol for points. Default is 0.4.

title.lab

Title text.

x.lab

A title for the x-axis. Default is the generic "Position (by set.order)".

y.lab

A title for the y-axis. Default is the generic "Outcome label".

legend.on

Toggle for plotting the legend. Default is TRUE.

Details

Use set.order to provide the classical p-value ranking. For example, if pvalue.vector is a vector of classical p-values, then set set.order=order(pvalue.vector) to sort the x-axis according to p-value rank.

Use type and p.values to provide the \(-log10(p-values)\) for the y-axis. For example, if pvalue.vector is a vector of classical p-values, then set type="p-value" (or type="comparison") and p.values=-log10(pvalue.vector) to set the y-axis. Then, set the y-axis title to something like y.lab="-log10(p)".

References

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

Blume JD, D<U+2019>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

See Also

sgpvalue, plotsgpv, sgpower, plotsgpower

Examples

# NOT RUN {

#  Use leukstats data
data(leukstats)

# ID number on the x-axis, delta-gap on the y-axis, using an interval null hypothesis of
# (-0.3, 0.3) for the log mean difference in expression levels (fold change).
plotman(est.lo=leukstats$ci.lo, est.hi=leukstats$ci.hi,
       null.lo=-0.3, null.hi=0.3,
       set.order=NA,
       type="delta-gap",
       ref.lines=NA,
       int.pch=16, int.cex=0.4,
       title.lab="Leukemia Example",
       y.lab="Delta-gap",
       x.lab="Position (ID)",
       legend.on=TRUE)

# ID number on the x-axis, -log10(classical p-value) on the y-axis, using an interval
# null hypothesis of (-0.3, 0.3) for the log mean difference in expression levels
# (fold change).
plotman(est.lo=leukstats$ci.lo, est.hi=leukstats$ci.hi,
       null.lo=-0.3, null.hi=0.3,
       set.order=NA,
       type="p-value",
       p.values=-log10(leukstats$p.value),
       ref.lines=-log10(0.05),
       int.pch=16, int.cex=0.4,
       title.lab="Leukemia Example",
       y.lab=expression("-log"[10]*"(p-value)"),
       x.lab="Position (ID)",
       legend.on=TRUE)

# Second-generation p-value (SGPV) on the x-axis, -log10(classical p-value) on the
# y-axis, using an interval null hypothesis of (-0.3, 0.3) for the log mean difference
# in expression levels (fold change).
plotman(est.lo=leukstats$ci.lo, est.hi=leukstats$ci.hi,
       null.lo=-0.3, null.hi=0.3,
       set.order="sgpv",
       type="comparison",
       p.values=-log10(leukstats$p.value),
       ref.lines=c(-log10(0.05), -log10(0.001)),
       int.pch=16, int.cex=0.4,
       title.lab="Leukemia Example",
       y.lab=expression("-log"[10]*"(p-value)"),
       x.lab="Second-generation p-value ranking",
       legend.on=TRUE)

# }