plot.frag.study.all {fragility}

Plot Method for "frag.study.all" Objects

Description

Visualizes the fragility of an individual study with a binary outcome.

Usage

## S3 method for class 'frag.study.all'
plot(x, method, modify0, modify1, trun,
     xlab, ylab, xlim, ylim, cex.pts, cex.legend.pval, cex.legend.title,
     col.ori, col.ori.hl, col.f.hl, col.sig, lty.ori, lwd.ori,
     pch, pch.ori, pch.ori.hl, pch.f, pch.f.hl, pch.trun,
     adjust.legend, adjust.seg, legend.pvals, ...)

Arguments

x

an object of class "frag.study.all". It is produced by the function frag.study with its argument all = TRUE.

method

a character string ("Fisher", "chisq", "OR", "RR", or "RD") indicating the method used to calculate the p-value. It must be an element of x$methods; the default is the first method in x$methods.

modify0

a logical value indicating whether event status is modified in group 0 for plotting. The default is TRUE if the range of event status modifications stored in the object x (x$f0.range) is not 0; otherwise, the default is FALSE.

modify1

a logical value indicating whether event status is modified in group 1 for plotting. The default is TRUE if the range of event status modifications stored in the object x (x$f1.range) is not 0; otherwise, the default is FALSE.

trun

a positive numeric value indicating truncation of p-value (on a base-10 logarithmic scale); p-values smaller than this threshold (10^-trun) are truncated. The default is 10.

xlab

a label for the x axis.

ylab

a label for the y axis.

xlim

the x limits c(x1, x2) of the plot.

ylim

the y limits c(y1, y2) of the plot.

cex.pts

the size of points in the plot (the default is 0.5).

cex.legend.pval

the text size of p-values in the legend (the default is 0.6). It is only used when both arguments modify0 and modify1 are TRUE.

cex.legend.title

the size of the legend title (the default is 1). It is only used when both arguments modify0 and modify1 are TRUE.

col.ori

the color of the line(s) depicting the original data (without event status modifications). The default is "gray50".

col.ori.hl

the color of the point depicting the original data (without event status modifications). The default is "black". It is only used when both arguments modify0 and modify1 are TRUE.

col.f.hl

the color of the point(s) for highlighting the minimal event status modifications for altering statistical significance or non-significance. The default is "black". It is only used when both arguments modify0 and modify1 are TRUE.

col.sig

a vector of two colors for non-significant and significant results, accordingly. The default includes "forestgreen" (for non-significant results) and "firebrick" (for significant results). When both arguments modify0 and modify1 are TRUE, they serve as colors of points representing p-values based on different event status modifications, with opacity automatically adjusted for depicting the p-value magnitudes (based on the function adjustcolor with different opacity levels for its argument alpha.f). When only one of the arguments modify0 and modify1 is TRUE, they serve as the background colors for distinguishing non-significance and significance, with the default opacity alpha.f = 0.1 in adjustcolor.

lty.ori

the type of the line(s) depicting the original data (without event status modifications). The default is 2 (dashed).

lwd.ori

the width of the line(s) depicting the original data (without event status modifications). The default is 1.

pch

the symbol of the points in the plot. The default is 16 (filled circle) when both arguments modify0 and modify1 are TRUE, and is 1 (circle) when only one of the arguments modify0 and modify1 is TRUE.

pch.ori

the symbol of the point depicting the original data (without event status modifications). The default is 15 (filled square).

pch.ori.hl

the symbol of the point for highlighting the original data (without event status modifications). The default is 0 (square). It is only used when both arguments modify0 and modify1 are TRUE.

pch.f

the symbol of the point depicting the original data (without event status modifications). The default is 15 (filled square).

pch.f.hl

the symbol of the point(s) for highlighting the minimal event status modifications for altering statistical significance or non-significance. The default is 2 (triangle point up). It is only used when both arguments modify0 and modify1 are TRUE.

pch.trun

the symbol of the point(s) depicting truncated p-values. The default is 3 (plus). It is only used when only one of the arguments modify0 and modify1 is TRUE.

adjust.legend

a positive numeric value for adjusting the width of the legend of p-values. The default is 1.

adjust.seg

a positive integer for adjusting the number of segments in the legend of p-values. The default is 10.

legend.pvals

a numeric value or a vector of numeric values that give additional p-values (e.g., 0.005 and 0.1) to be shown in the legend. The default is NULL.

...

other arguments that can be passed to plot.default.

Details

When both arguments modify0 and modify1 are TRUE, the generated plot presents p-values (with different colors representing their magnitudes) based on all possible event status modifications. The modifications in group 0 are presented on the x axis, and those in group 1 are presented on the y axis. When only one of the arguments modify0 and modify1 is TRUE, a scatter plot is generated, which presents p-values (on a base-10 logarithmic scale) on the y axis against event status modifications in group 0 (if modify0 = TRUE) or group 1 (if modify1 = TRUE) on the x axis.

Value

None.

References

Lin L (2021). "Factors that impact fragility index and their visualizations." Journal of Evaluation in Clinical Practice, 27(2), 356–64. <doi: 10.1111/jep.13428>

Lin L, Chu H (2022). "Assessing and visualizing fragility of clinical results with binary outcomes in R using the fragility package." PLOS ONE, 17(6), e0268754. <doi: 10.1371/journal.pone.0268754>

See Also

frag.study