draw_box: Interactive Boxplots & Violin plots

In egenn/rtemis: Machine Learning and Visualization

Interactive Boxplots & Violin plots

Description

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 = choose_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	Theme object.
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 margins
automargin_y	Logical: If TRUE, automatically set y-axis margins
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 htest and htest_compare. Requires group to 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 group to be set
htest_y	Numeric: y coordinate for htest annotation
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 group arg 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 filename is set.
file_height	Integer: File height in pixels for when filename is set.
file_scale	Numeric: If saving to file, scale plot by this number

Details

For multiple box plots, the recommendation is:

• x=dat[, columnindex] for multiple variables of a data.frame

• x=list(a=..., b=..., etc.) for multiple variables of potentially different length

• x=split(var, group) for one variable with multiple groups: group names appear below boxplots

• ⁠x=dat[, columnindex], group = factor⁠ for 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.

Value

plotly object.

Author(s)

EDG

Examples

## Not run: 
# 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)

## End(Not run)

egenn/rtemis documentation built on June 14, 2025, 11:54 p.m.