Violin plot type

Description

Type function for violin plots, which are an alternative to box plots for visualizing continuous distributions (by group) in the form of mirrored densities.

Usage

type_violin(
  bw = "nrd0",
  joint.bw = c("mean", "full", "none"),
  adjust = 1,
  kernel = c("gaussian", "epanechnikov", "rectangular", "triangular", "biweight",
    "cosine", "optcosine"),
  n = 512,
  trim = FALSE,
  width = 0.9,
  lighten = TRUE,
  singletons = c("warn", "drop", "none")
)

Arguments

bw	the smoothing bandwidth to be used, see density for details and options.
joint.bw	character string indicating whether (and how) the smoothing bandwidth should be computed from the joint data distribution when there are multiple subgroups. The options are “mean” (the default), “full”, and “none”. Also accepts a logical argument, where TRUE maps to “mean” and FALSE maps to “none”. See the "Bandwidth selection" section below for a discussion of practical considerations.
adjust	the bandwidth used is actually adjust*bw. This makes it easy to specify values like ‘half the default’ bandwidth.
kernel	a character string giving the smoothing kernel to be used. This must partially match one of “gaussian”, “rectangular”, “triangular”, “epanechnikov”, “biweight”, “cosine” or “optcosine”, with default “gaussian”, and may be abbreviated to a unique prefix (single letter). “cosine” is smoother than “optcosine”, which is the usual ‘cosine’ kernel in the literature and almost MSE-efficient. However, “cosine” is the version used by S.
n	the number of equally spaced points at which the density is to be estimated. When n > 512, it is rounded up to a power of 2 during the calculations (as fft is used) and the final result is interpolated by approx. So it almost always makes sense to specify n as a power of two.
trim	logical indicating whether the violins should be trimmed to the range of the data. Default is FALSE.
width	numeric (ideally in the range [0, 1], although this isn’t enforced) giving the normalized width of the individual violins.
lighten	logical. Should the fills use a lighter, opaque tint of the series colour(s)? Default is TRUE, which keeps single- and multi-group displays consistent and lets the fill read cleanly over grid lines. Set to FALSE to use the fully-saturated palette colour(s) instead.
singletons	character string indicating what to do with singleton groups, i.e. combinations of x, by, and facet that consist of only 1 row. The default “warn” option removes any singleton cases and emits a warning reporting how many there were. “drop” does the same thing, but quietly. In either case the dropped groups may still be represented as empty violins or facets in your plot. Finally, “none” skips all singleton checks and retains the affected groups; possibly leading to an error. Note that singletons require a numeric bw, since the data-driven bandwidth rules need at least 2 observations.

Details

See type_density for more details and considerations related to bandwidth selection and kernel types.

Examples

library("tinyplot")

# "violin" type convenience string
tinyplot(weight ~ feed, data = chickwts, type = "violin")

# to match the defaults of `ggplot2::geom_violin()`, use `trim = TRUE` and
# `joint.bw = FALSE`
tinyplot(
  weight ~ feed, data = chickwts,
  # type = type_violin(trim = TRUE, joint.bw = FALSE) # same but see final ex.
  type = "violin", trim = TRUE, joint.bw = FALSE
)

# For flipped violin plots, it's usually better to use a dynamic theme to
# accommodate (horizontal) y-axis labels
tinyplot(
  weight ~ feed, data = chickwts, type = "violin", flip = TRUE,
  theme = "dynamic" # or "clean(2)", "classic", "minimal", etc.
)

# you can group by the x var to add colour (here with the original orientation)
tinyplot(weight ~ feed | feed, data = chickwts, type = "violin", legend = FALSE)

# dodged grouped violin plot example (different dataset)
tinyplot(len ~ dose | supp, data = ToothGrowth, type = "violin")

# note: above we relied on `...` argument passing alongside the "violin"
# type convenience string. But this won't work for `width`, since it will
# clash with the top-level `tinyplot(..., width = <width>)` arg. To ensure
# correct arg passing, it's safer to use the functional `type_violin()` type.
tinyplot(
  len ~ dose | supp, data = ToothGrowth,
  type = type_violin(width = 0.75)
)