violinplot: Violin Plots
In r2evans/violinplot: Violin plots for R using base graphics

Description Usage Arguments Details Value Methods (by class) See Also Examples

View source: R/violinplot.R

Produce violin (density) plots of the given (optionally grouped) values. Optionally add slender superimposed boxplots.

violinplot(x, ...)

## S3 method for class 'matrix'
violinplot(x, ...)

## S3 method for class 'data.frame'
violinplot(x, ...)

## S3 method for class 'list'
violinplot(x, ...)

## S3 method for class 'formula'
violinplot(formula, data = NULL, ..., na.action = NULL,
  drop.unused = FALSE)

## Default S3 method:
violinplot(x, ..., at = NULL, width = 1, names = NULL,
  col = NULL, border = 1, groups = NULL, group.spacers = 1,
  group.labels = NULL, group.lines = TRUE, density.auto = TRUE,
  density.scale = TRUE, density.ticks = TRUE, density.args = NULL,
  boxplot.args = TRUE, legend.args = NULL, grid.args = TRUE,
  text.cex = 1, mar = FALSE, add = FALSE)

`x`	for specifying data from which the violin plots (and optionally boxplots) are to be produced. Either a numeric vector, a single list containing such vectors, or a data.frame or matrix (where columns are the vectors to be used). Additional unnamed arguments specify further data as separate vectors (each corresponding to a component violin plot with or without a corresponding boxplot). `NA`s are allowed in the data.
`...`	Unnamed arguments ('default' method only) are additional data vectors; for all other methods, unnamed arguments are ignored. Named arguments are passed through to the 'default' method and optionally to `plot`.
`formula`	a formula, such as `y ~ grp`, where `yh` is a numeric vector of data values to be split into groups according to the grouping variable(s) `grp`. Also supported is `~ grps` and `~ .`, which is analogous to choosing select columns of the data.frame.
`data`	data.frame or list from which the variables in `formula` should be taken.
`na.action`	passed to `model.frame`
`drop.unused`	passed to `model.frame`
`at`	numeric vector giving the locations where the violin plots should be drawn, particularly when `add = TRUE`; defaults to `1:n` for the default, "matrix", and "data.frame" methods, and spaced for the "formula" method (see `spacer.type`).
`width`	numeric, how wide the violin plot can extend where "1" means two neighboring plots may touch but not overlap; greater than 1 and overlap may occur, less than 1 and there will always be space between neighboring violin plots.
`names`	character vector of names to be printed under the plots; if missing, the names will be derived from `groups` (if not null), the column names of a matrix or data.frame (if provided), or variables (if a formula).
`col`	if not `NULL` then it is assumed to contain colors to be used to color the bodies of the violin plots. If the length is less than the number of plots, then the colors will be recycled; in the "formula" method, the length should be the length of the last factor, and it will be recycled "smartly" (taking into account empty plots). Note: this does not affect the boxplots: use `boxplot = list(col = c(...))` to affect them.
`border`	an optional vector of colors for the outlines of the violin plots. As with `col`, the values in `border` are recycled. Note: does not affect boxplots, use `boxplot = list(border = c(...))` to change them.
`groups`	for internal use only (calls between methods), a list for assigning groups and levels of the data. (Internally, the structure is a list of lists, where each element of the top-level list represents a grouping level. Each grouping-level list contains more lists, where each contains contiguous x positions for that group.)
`group.spacers`	numeric, the amount of space to be used for a spacing between groups, defaults to 1 (same width as an individual violin plot). When there are multiple levels ("formula" method), this vector has as many numbers as levels.
`group.labels`	if logical and `TRUE`, plot labels under all plots and groups (under lines, if present). If numeric, then the levels under which to add labels. Defaults to `TRUE`, all groups.
`group.lines`	if logical and `TRUE`, then lines are drawn to visually group plots, for all but the lowest-level; if numeric, indicating which of the levels to apply lines.
`density.auto`	logical, whether to auto-scale the density curves to the maximum density of all curves, default `TRUE`.
`density.scale`	if logical and `TRUE`, include the scale (+/- percentages) for the density scales; if a positive integer, the columns (left-to-right) to show them on; if a negative integer, right-to-left. Default `TRUE` (all).
`density.ticks`	logical or integer, tick marks on each grouping line (lowest level only). Default `TRUE`. This is forced to `TRUE` if `density.scale` is not `FALSE`.
`density.args`	list of arguments to pass to `density`. The parameter `n` has a default value of 32 for simplifying the plots, but it may be overridden with this argument. If not a list, then the actual value is ignored.
`boxplot.args`	list of arguments to pass to `boxplot`. The following parameters have defaults to prevent plotting of the frame, axes, etc as well as for reasonable aesthetic defaults: `pars`, `frame.plot`, `main`, `xlab`, `ylab`, `xaxt`, `yaxt`, `add`. Providing any of these arguments overrides the defaults. If `TRUE`, all defaults are used and boxplots are plotted. If `FALSE` or `NULL`, boxplots are not plotted.
`legend.args`	list of arguments to pass to `legend`. Parameters `xpd` and `horiz` are predefined with defaults. If `TRUE` (the default), a legend is plotted in the top left corner, horizontally. If `FALSE` or `NULL`, no legend is printed.
`grid.args`	list of arguments to pass to `grid`. If `TRUE`, horizontal gray lines are plotted. If `FALSE` or `NULL`, grid is not called.
`text.cex`	numeric, cex to use for group labels; the scale (if `density.scale` is TRUE) is shown at 70% of this.
`mar`	if logical and `TRUE`, calculate the margins based on the presence of `main`, `group.labels`, and `legend`; if numeric, the margins will be assigned to this value. (The calculation does not adjust the side margins if using "left" or "right" for the position of `legend`.) Default is `FALSE`.
`add`	logical, create a new plot or add to the existing device. Default is `FALSE`.

The generic function violinplot currently has a default method (violinplot.default), several helper methods (for "list", "matrix", and "data.frame"), and a "formula" interface (violinplot.formula).

If multiple groups are supplied either as multiple arguments are via a formula, parallel violin plots will be plotted, in the order of the arguments or the order of the levels of the groups.

Missing values are ignored when forming violin plots.

list of various parameters, invisibly

matrix: matrix method:
data.frame: data.frame method:
list: list method:
formula: "formula" method
default: default method:

density which does much of the computation; boxplot for optional overlaid boxplots; legend; model.frame

## Not run: 

# default method
violinplot(mtcars$mpg)
violinplot(mtcars$mpg, col = 2)
violinplot(mtcars$mpg, col = 4, boxplot.args = FALSE)

# matrix method
m <- matrix(runif(99), ncol = 3)
violinplot(m, col = 2:4)
violinplot(m, col = 2:4, width = 1.5)

# data.frame method
violinplot(mtcars[,1:4], col = 2:9) # extra colors are silently discarded

# list method
l <- list(x1 = runif(100), x2 = rnorm(200, mean = 1))
violinplot(l)

# formula method
violinplot(mpg ~ cyl, data = mtcars, col = 2:4)
violinplot(mpg ~ cyl, data = mtcars, col = 2:4,
    legend.args = list(x = "bottomleft", bty = "n"))
violinplot(mpg ~ cyl + vs, data = mtcars, col = 2:4,
    group.labels = 2)
violinplot(mpg ~ cyl + vs, data = mtcars, col = 2:4,
    group.labels = 2, drop.unused = TRUE)

violinplot(~ ., data = mtcars) # same as violinplot(mtcars)


## End(Not run)