plotman: Second-Generation p-Value Plotting
In weltybiostat/sgpv: Calculate Second-Generation p-Values and Associated Measures

Description Usage Arguments Details References See Also Examples

View source: R/plotman.R

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.

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
)

`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`.

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)".

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’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

sgpvalue, plotsgpv, sgpower, plotsgpower

#  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)