Draw interactive boxplots or violin plots using plotly
Usage
draw_box(
x,
time = NULL,
time_bin = c("year", "quarter", "month", "day"),
type = c("box", "violin"),
group = NULL,
x_transform = c("none", "scale", "minmax"),
main = NULL,
xlab = "",
ylab = NULL,
col = NULL,
alpha = 0.6,
bg = NULL,
plot_bg = NULL,
theme = rtemis_theme,
palette = rtemis_palette,
boxpoints = "outliers",
quartilemethod = "linear",
xlim = NULL,
ylim = NULL,
violin_box = TRUE,
orientation = "v",
annotate_n = FALSE,
annotate_n_y = 1,
annotate_mean = FALSE,
annotate_meansd = FALSE,
annotate_meansd_y = 1,
annotate_col = theme[["labs_col"]],
xnames = NULL,
group_lines = FALSE,
group_lines_dash = "dot",
group_lines_col = NULL,
group_lines_alpha = 0.5,
labelify = TRUE,
order_by_fn = NULL,
font_size = 16,
ylab_standoff = 18,
legend = NULL,
legend_col = NULL,
legend_xy = NULL,
legend_orientation = "v",
legend_xanchor = "auto",
legend_yanchor = "auto",
xaxis_type = "category",
cataxis_tickangle = "auto",
margin = list(b = 65, l = 65, t = 50, r = 12, pad = 0),
automargin_x = TRUE,
automargin_y = TRUE,
boxgroupgap = NULL,
hovertext = NULL,
show_n = FALSE,
pvals = NULL,
htest = "none",
htest_compare = 0,
htest_y = NULL,
htest_annotate = TRUE,
htest_annotate_x = 0,
htest_annotate_y = -0.065,
htest_star_col = theme[["labs_col"]],
htest_bracket_col = theme[["labs_col"]],
starbracket_pad = c(0.04, 0.05, 0.09),
use_plotly_group = FALSE,
width = NULL,
height = NULL,
displayModeBar = TRUE,
modeBar_file_format = "svg",
filename = NULL,
file_width = 500,
file_height = 500,
file_scale = 1,
...
)Arguments
- x
Vector or List of vectors: Input
- time
Date or date-time vector
- time_bin
Character: "year", "quarter", "month", or "day". Period to bin by
- type
Character: "box" or "violin"
- group
Factor to group by
- x_transform
Character: "none", "scale", or "minmax" to use raw values, scaled and centered values or min-max normalized to 0-1, respectively. Transform is applied to each variable before grouping, so that groups are comparable
- main
Character: Plot title.
- xlab
Character: x-axis label.
- ylab
Character: y-axis label.
- col
Color, vector: Color for boxes. If NULL, which will draw colors from
palette- alpha
Float (0, 1]: Transparency for box colors.
- bg
Color: Background color.
- plot_bg
Color: Background color for plot area.
- theme
Character: Theme to use: Run
themes()for available themes- palette
Character: Name of rtemis palette to use. Only used if
col = NULL.- boxpoints
Character or FALSE: "all", "suspectedoutliers", "outliers" See https://plotly.com/r/box-plots/#choosing-the-algorithm-for-computing-quartiles
- quartilemethod
Character: "linear", "exclusive", "inclusive"
- xlim
Numeric vector: x-axis limits
- ylim
Numeric vector: y-axis limits
- violin_box
Logical: If TRUE and type is "violin" show box within violin plot
- orientation
Character: "v" or "h" for vertical, horizontal
- annotate_n
Logical: If TRUE, annotate with N in each box
- annotate_n_y
Numeric: y position for
annotate_n- annotate_mean
Logical: If TRUE, annotate with mean of each box
- annotate_meansd
Logical: If TRUE, annotate with mean (SD) of each box
- annotate_meansd_y
Numeric: y position for
annotate_meansd- annotate_col
Color for annotations
- xnames
Character, vector, length = NROW(x): x-axis names. Default = NULL, which tries to set names automatically.
- group_lines
Logical: If TRUE, add separating lines between groups of boxplots
- group_lines_dash
Character: "solid", "dot", "dash", "longdash", "dashdot", or "longdashdot"
- group_lines_col
Color for
group_lines- group_lines_alpha
Numeric: transparency for
group_lines_col- labelify
Logical: If TRUE, labelify x names
- order_by_fn
Function: If defined, order boxes by increasing value of this function (e.g. median).
- font_size
Float: Font size for all labels.
- ylab_standoff
Numeric: Standoff for y-axis label
- legend
Logical: If TRUE, draw legend.
- legend_col
Color: Legend text color. Default = NULL, determined by the theme.
- legend_xy
Float, vector, length 2: Relative x, y position for legend.
- legend_orientation
"v" or "h" for vertical, horizontal
- legend_xanchor
Character: Legend's x anchor: "left", "center", "right", "auto"
- legend_yanchor
Character: Legend's y anchor: "top", "middle", "bottom", "auto"
- xaxis_type
Character: "linear", "log", "date", "category", "multicategory"
- cataxis_tickangle
Numeric: Angle for categorical axis tick labels
- margin
Named list: plot margins.
- automargin_x
Logical: If TRUE, automatically set x-axis amrgins
- automargin_y
Logical: If TRUE, automatically set y-axis amrgins
- boxgroupgap
Numeric: Sets the gap (in plot fraction) between boxes of the same location coordinate
- hovertext
Character vector: Text to show on hover for each data point
- show_n
Logical: If TRUE, show N in each box
- pvals
Numeric vector: Precomputed p-values. Should correspond to each box. Bypasses
htestandhtest_compare. Requiresgroupto be set- htest
Character: e.g. "t.test", "wilcox.test" to compare each box to the first box. If grouped, compare within each group to the first box. If p-value of test is less than
htest.thresh, add asterisk above/ to the side of each box- htest_compare
Integer: 0: Compare all distributions against the first one; 2: Compare every second box to the one before it. Requires
groupto be set- htest_y
Numeric: y coordinate for
htestannotation- htest_annotate
Logical: if TRUE, include htest annotation
- htest_annotate_x
Numeric: x-axis paper coordinate for htest annotation
- htest_annotate_y
Numeric: y-axis paper coordinate for htest annotation
- htest_star_col
Color for htest annotation stars
- htest_bracket_col
Color for htest annotation brackets
- starbracket_pad
Numeric: Padding for htest annotation brackets
- use_plotly_group
If TRUE, use plotly's
grouparg to group boxes.- width
Numeric: Force plot size to this width. Default = NULL, i.e. fill available space
- height
Numeric: Force plot size to this height. Default = NULL, i.e. fill available space
- displayModeBar
Logical: If TRUE, show plotly's modebar
- modeBar_file_format
Character: "svg", "png", "jpeg", "pdf"
- filename
Character: Path to file to save static plot.
- file_width
Integer: File width in pixels for when
filenameis set.- file_height
Integer: File height in pixels for when
filenameis set.- file_scale
Numeric: If saving to file, scale plot by this number
- ...
Additional arguments passed to theme
Details
For multiple box plots, the recommendation is:
x=dat[, columnindex]for multiple variables of a data.framex=list(a=..., b=..., etc.)for multiple variables of potentially different lengthx=split(var, group)for one variable with multiple groups: group names appear below boxplotsx=dat[, columnindex], group = factorfor grouping multiple variables: group names appear in legend
If orientation == "h", xlab is applied to y-axis and vice versa.
Similarly, x.axist.type applies to y-axis - this defaults to
"category" and would not normally need changing.
Examples
if (FALSE) { # \dontrun{
# A.1 Box plot of 4 variables
draw_box(iris[, 1:4])
# A.2 Grouped Box plot
draw_box(iris[, 1:4], group = iris[["Species"]])
draw_box(iris[, 1:4], group = iris[["Species"]], annotate_n = TRUE)
# B. Boxplot binned by time periods
# Synthetic data with an instantenous shift in distributions
set.seed(2021)
dat1 <- data.frame(alpha = rnorm(200, 0), beta = rnorm(200, 2), gamma = rnorm(200, 3))
dat2 <- data.frame(alpha = rnorm(200, 5), beta = rnorm(200, 8), gamma = rnorm(200, -3))
x <- rbind(dat1, dat2)
startDate <- as.Date("2019-12-04")
endDate <- as.Date("2021-03-31")
time <- seq(startDate, endDate, length.out = 400)
draw_box(x[, 1], time, "year", ylab = "alpha")
draw_box(x, time, "year", legend.xy = c(0, 1))
draw_box(x, time, "quarter", legend.xy = c(0, 1))
draw_box(x, time, "month",
legend.orientation = "h",
legend.xy = c(0, 1),
legend.yanchor = "bottom"
)
# (Note how the boxplots widen when the period includes data from both dat1 and dat2)
} # }