% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/type_violin.R
\name{type_violin}
\alias{type_violin}
\title{Violin plot type}
\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
)
}
\arguments{
\item{bw}{the smoothing \code{\link[stats:bw.nrd]{bandwidth}} to be used,
see \code{\link[stats]{density}} for details and options.}

\item{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 \code{"mean"} (the default), \code{"full"},
and \code{"none"}. Also accepts a logical argument, where \code{TRUE} maps to
\code{"mean"} and \code{FALSE} maps to \code{"none"}. See the "Bandwidth selection"
section below for a discussion of practical considerations.}

\item{adjust}{the bandwidth used is actually \code{adjust*bw}.
    This makes it easy to specify values like \sQuote{half the default}
    bandwidth.}

\item{kernel}{a character string giving the smoothing kernel to be used. This
must partially match one of \code{"gaussian"}, \code{"rectangular"}, \code{"triangular"},
\code{"epanechnikov"}, \code{"biweight"}, \code{"cosine"} or \code{"optcosine"}, with default
\code{"gaussian"}, and may be abbreviated to a unique prefix (single letter).

\code{"cosine"} is smoother than \code{"optcosine"}, which is the usual 'cosine'
kernel in the literature and almost MSE-efficient. However, \code{"cosine"} is
the version used by S.}

\item{n}{the number of equally spaced points at which the density is
    to be estimated.  When \code{n > 512}, it is rounded up to a power
    of 2 during the calculations (as \code{\link[stats]{fft}} is used) and the
    final result is interpolated by \code{\link[stats]{approx}}.  So it almost
    always makes sense to specify \code{n} as a power of two.
  }

\item{trim}{logical indicating whether the violins should be trimmed to the
range of the data. Default is \code{FALSE}.}

\item{width}{numeric (ideally in the range \verb{[0, 1]}, although this isn't
enforced) giving the normalized width of the individual violins.}

\item{lighten}{logical. Should the fills use a lighter, opaque tint of the
series colour(s)? Default is \code{TRUE}, which keeps single- and multi-group
displays consistent and lets the fill read cleanly over grid lines. Set to
\code{FALSE} to use the fully-saturated palette colour(s) instead.}
}
\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.
}
\details{
See \code{\link{type_density}} for more details and considerations related to
bandwidth selection and kernel types.
}
\examples{
# "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)
)

}
