1% Generated by roxygen2: do not edit by hand 2% Please edit documentation in R/geom-violin.r, R/stat-ydensity.r 3\name{geom_violin} 4\alias{geom_violin} 5\alias{stat_ydensity} 6\title{Violin plot} 7\usage{ 8geom_violin( 9 mapping = NULL, 10 data = NULL, 11 stat = "ydensity", 12 position = "dodge", 13 ..., 14 draw_quantiles = NULL, 15 trim = TRUE, 16 scale = "area", 17 na.rm = FALSE, 18 orientation = NA, 19 show.legend = NA, 20 inherit.aes = TRUE 21) 22 23stat_ydensity( 24 mapping = NULL, 25 data = NULL, 26 geom = "violin", 27 position = "dodge", 28 ..., 29 bw = "nrd0", 30 adjust = 1, 31 kernel = "gaussian", 32 trim = TRUE, 33 scale = "area", 34 na.rm = FALSE, 35 orientation = NA, 36 show.legend = NA, 37 inherit.aes = TRUE 38) 39} 40\arguments{ 41\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}} or 42\code{\link[=aes_]{aes_()}}. If specified and \code{inherit.aes = TRUE} (the 43default), it is combined with the default mapping at the top level of the 44plot. You must supply \code{mapping} if there is no plot mapping.} 45 46\item{data}{The data to be displayed in this layer. There are three 47options: 48 49If \code{NULL}, the default, the data is inherited from the plot 50data as specified in the call to \code{\link[=ggplot]{ggplot()}}. 51 52A \code{data.frame}, or other object, will override the plot 53data. All objects will be fortified to produce a data frame. See 54\code{\link[=fortify]{fortify()}} for which variables will be created. 55 56A \code{function} will be called with a single argument, 57the plot data. The return value must be a \code{data.frame}, and 58will be used as the layer data. A \code{function} can be created 59from a \code{formula} (e.g. \code{~ head(.x, 10)}).} 60 61\item{position}{Position adjustment, either as a string, or the result of 62a call to a position adjustment function.} 63 64\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are 65often aesthetics, used to set an aesthetic to a fixed value, like 66\code{colour = "red"} or \code{size = 3}. They may also be parameters 67to the paired geom/stat.} 68 69\item{draw_quantiles}{If \code{not(NULL)} (default), draw horizontal lines 70at the given quantiles of the density estimate.} 71 72\item{trim}{If \code{TRUE} (default), trim the tails of the violins 73to the range of the data. If \code{FALSE}, don't trim the tails.} 74 75\item{scale}{if "area" (default), all violins have the same area (before trimming 76the tails). If "count", areas are scaled proportionally to the number of 77observations. If "width", all violins have the same maximum width.} 78 79\item{na.rm}{If \code{FALSE}, the default, missing values are removed with 80a warning. If \code{TRUE}, missing values are silently removed.} 81 82\item{orientation}{The orientation of the layer. The default (\code{NA}) 83automatically determines the orientation from the aesthetic mapping. In the 84rare event that this fails it can be given explicitly by setting \code{orientation} 85to either \code{"x"} or \code{"y"}. See the \emph{Orientation} section for more detail.} 86 87\item{show.legend}{logical. Should this layer be included in the legends? 88\code{NA}, the default, includes if any aesthetics are mapped. 89\code{FALSE} never includes, and \code{TRUE} always includes. 90It can also be a named logical vector to finely select the aesthetics to 91display.} 92 93\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 94rather than combining with them. This is most useful for helper functions 95that define both data and aesthetics and shouldn't inherit behaviour from 96the default plot specification, e.g. \code{\link[=borders]{borders()}}.} 97 98\item{geom, stat}{Use to override the default connection between 99\code{geom_violin()} and \code{stat_ydensity()}.} 100 101\item{bw}{The smoothing bandwidth to be used. 102If numeric, the standard deviation of the smoothing kernel. 103If character, a rule to choose the bandwidth, as listed in 104\code{\link[stats:bandwidth]{stats::bw.nrd()}}.} 105 106\item{adjust}{A multiplicate bandwidth adjustment. This makes it possible 107to adjust the bandwidth while still using the a bandwidth estimator. 108For example, \code{adjust = 1/2} means use half of the default bandwidth.} 109 110\item{kernel}{Kernel. See list of available kernels in \code{\link[=density]{density()}}.} 111} 112\description{ 113A violin plot is a compact display of a continuous distribution. It is a 114blend of \code{\link[=geom_boxplot]{geom_boxplot()}} and \code{\link[=geom_density]{geom_density()}}: a 115violin plot is a mirrored density plot displayed in the same way as a 116boxplot. 117} 118\section{Orientation}{ 119 120This geom treats each axis differently and, thus, can thus have two orientations. Often the orientation is easy to deduce from a combination of the given mappings and the types of positional scales in use. Thus, ggplot2 will by default try to guess which orientation the layer should have. Under rare circumstances, the orientation is ambiguous and guessing may fail. In that case the orientation can be specified directly using the \code{orientation} parameter, which can be either \code{"x"} or \code{"y"}. The value gives the axis that the geom should run along, \code{"x"} being the default orientation you would expect for the geom. 121} 122 123\section{Aesthetics}{ 124 125\code{geom_violin()} understands the following aesthetics (required aesthetics are in bold): 126\itemize{ 127\item \strong{\code{x}} 128\item \strong{\code{y}} 129\item \code{alpha} 130\item \code{colour} 131\item \code{fill} 132\item \code{group} 133\item \code{linetype} 134\item \code{size} 135\item \code{weight} 136} 137Learn more about setting these aesthetics in \code{vignette("ggplot2-specs")}. 138} 139 140\section{Computed variables}{ 141 142\describe{ 143\item{density}{density estimate} 144\item{scaled}{density estimate, scaled to maximum of 1} 145\item{count}{density * number of points - probably useless for violin plots} 146\item{violinwidth}{density scaled for the violin plot, according to area, counts 147or to a constant maximum width} 148\item{n}{number of points} 149\item{width}{width of violin bounding box} 150} 151} 152 153\examples{ 154p <- ggplot(mtcars, aes(factor(cyl), mpg)) 155p + geom_violin() 156 157# Orientation follows the discrete axis 158ggplot(mtcars, aes(mpg, factor(cyl))) + 159 geom_violin() 160 161\donttest{ 162p + geom_violin() + geom_jitter(height = 0, width = 0.1) 163 164# Scale maximum width proportional to sample size: 165p + geom_violin(scale = "count") 166 167# Scale maximum width to 1 for all violins: 168p + geom_violin(scale = "width") 169 170# Default is to trim violins to the range of the data. To disable: 171p + geom_violin(trim = FALSE) 172 173# Use a smaller bandwidth for closer density fit (default is 1). 174p + geom_violin(adjust = .5) 175 176# Add aesthetic mappings 177# Note that violins are automatically dodged when any aesthetic is 178# a factor 179p + geom_violin(aes(fill = cyl)) 180p + geom_violin(aes(fill = factor(cyl))) 181p + geom_violin(aes(fill = factor(vs))) 182p + geom_violin(aes(fill = factor(am))) 183 184# Set aesthetics to fixed value 185p + geom_violin(fill = "grey80", colour = "#3366FF") 186 187# Show quartiles 188p + geom_violin(draw_quantiles = c(0.25, 0.5, 0.75)) 189 190# Scales vs. coordinate transforms ------- 191if (require("ggplot2movies")) { 192# Scale transformations occur before the density statistics are computed. 193# Coordinate transformations occur afterwards. Observe the effect on the 194# number of outliers. 195m <- ggplot(movies, aes(y = votes, x = rating, group = cut_width(rating, 0.5))) 196m + geom_violin() 197m + 198 geom_violin() + 199 scale_y_log10() 200m + 201 geom_violin() + 202 coord_trans(y = "log10") 203m + 204 geom_violin() + 205 scale_y_log10() + coord_trans(y = "log10") 206 207# Violin plots with continuous x: 208# Use the group aesthetic to group observations in violins 209ggplot(movies, aes(year, budget)) + 210 geom_violin() 211ggplot(movies, aes(year, budget)) + 212 geom_violin(aes(group = cut_width(year, 10)), scale = "width") 213} 214} 215} 216\references{ 217Hintze, J. L., Nelson, R. D. (1998) Violin Plots: A Box 218Plot-Density Trace Synergism. The American Statistician 52, 181-184. 219} 220\seealso{ 221\code{\link[=geom_violin]{geom_violin()}} for examples, and \code{\link[=stat_density]{stat_density()}} 222for examples with data along the x axis. 223} 224