geom_dotplot.Rd

% Generated by roxygen2 (4.1.1): do not edit by hand
% Please edit documentation in R/geom-dotplot.r
\name{geom_dotplot}
\alias{geom_dotplot}
\title{Dot plot}
\usage{
geom_dotplot(mapping = NULL, data = NULL, stat = "bindot",
  position = "identity", na.rm = FALSE, binwidth = NULL, binaxis = "x",
  method = "dotdensity", binpositions = "bygroup", stackdir = "up",
  stackratio = 1, dotsize = 1, stackgroups = FALSE, show_guide = NA,
  ...)
}
\arguments{
\item{mapping}{The aesthetic mapping, usually constructed with
\code{\link{aes}} or \code{\link{aes_string}}. Only needs to be set
at the layer level if you are overriding the plot defaults.}

\item{data}{A data frame. If specified, overrides the default data frame
defined at the top level of the plot.}

\item{stat}{The statistical transformation to use on the data for this
layer, as a string.}

\item{position}{Postion adjustment, either as a string, or the result of
a call to a position adjustment function.}

\item{na.rm}{If \code{FALSE} (the default), removes missing values with
a warning.  If \code{TRUE} silently removes missing values.}

\item{binwidth}{When \code{method} is "dotdensity", this specifies maximum bin width.
 When method is "histodot", this specifies bin width.
Defaults to 1/30 of the range of the data}

\item{binaxis}{which axis to bin along "x" (default) or "y"}

\item{method}{"dotdensity" (default) for dot-density binning, or
"histodot" for fixed bin widths (like stat_bin)}

\item{binpositions}{When \code{method} is "dotdensity", "bygroup" (default)
determines positions of the bins for each group separately. "all" determines
positions of the bins with all the data taken together; this is used for
aligning dot stacks across multiple groups.}

\item{stackdir}{which direction to stack the dots. "up" (default),
"down", "center", "centerwhole" (centered, but with dots aligned)}

\item{stackratio}{how close to stack the dots. Default is 1, where dots just
just touch. Use smaller values for closer, overlapping dots.}

\item{dotsize}{The diameter of the dots relative to \code{binwidth}, default 1.}

\item{stackgroups}{should dots be stacked across groups? This has the effect
that \code{position = "stack"} should have, but can't (because this geom has
some odd properties).}

\item{show_guide}{logical. Should this layer be included in the legends?
\code{NA}, the default, includes if any aesthetics are mapped.
\code{FALSE} never includes, and \code{TRUE} always includes.}

\item{...}{other arguments passed on to \code{\link{layer}}. There are
  three types of arguments you can use here:

  \itemize{
  \item Aesthetics: to set an aesthetic to a fixed value, like
     \code{color = "red"} or \code{size = 3}.
  \item Other arguments to the layer, for example you override the
    default \code{stat} associated with the layer.
  \item Other arguments passed on to the stat.
  }}
}
\description{
In a dot plot, the width of a dot corresponds to the bin width
(or maximum width, depending on the binning algorithm), and dots are
stacked, with each dot representing one observation.
}
\details{
With dot-density binning, the bin positions are determined by the data and
\code{binwidth}, which is the maximum width of each bin. See Wilkinson
(1999) for details on the dot-density binning algorithm.

With histodot binning, the bins have fixed positions and fixed widths, much
like a histogram.

When binning along the x axis and stacking along the y axis, the numbers on
y axis are not meaningful, due to technical limitations of ggplot2. You can
hide the y axis, as in one of the examples, or manually scale it
to match the number of dots.
}
\section{Aesthetics}{

\Sexpr[results=rd,stage=build]{ggplot2:::rd_aesthetics("geom", "dotplot")}
}
\examples{
ggplot(mtcars, aes(x = mpg)) + geom_dotplot()
ggplot(mtcars, aes(x = mpg)) + geom_dotplot(binwidth = 1.5)

# Use fixed-width bins
ggplot(mtcars, aes(x = mpg)) +
  geom_dotplot(method="histodot", binwidth = 1.5)

# Some other stacking methods
ggplot(mtcars, aes(x = mpg)) +
  geom_dotplot(binwidth = 1.5, stackdir = "center")
ggplot(mtcars, aes(x = mpg)) +
  geom_dotplot(binwidth = 1.5, stackdir = "centerwhole")

# y axis isn't really meaningful, so hide it
ggplot(mtcars, aes(x = mpg)) + geom_dotplot(binwidth = 1.5) +
  scale_y_continuous(name = "", breaks = NULL)

# Overlap dots vertically
ggplot(mtcars, aes(x = mpg)) + geom_dotplot(binwidth = 1.5, stackratio = .7)

# Expand dot diameter
ggplot(mtcars, aes(x  =mpg)) + geom_dotplot(binwidth = 1.5, dotsize = 1.25)


# Examples with stacking along y axis instead of x
ggplot(mtcars, aes(x = 1, y = mpg)) +
  geom_dotplot(binaxis = "y", stackdir = "center")

ggplot(mtcars, aes(x = factor(cyl), y = mpg)) +
  geom_dotplot(binaxis = "y", stackdir = "center")

ggplot(mtcars, aes(x = factor(cyl), y = mpg)) +
  geom_dotplot(binaxis = "y", stackdir = "centerwhole")

ggplot(mtcars, aes(x = factor(vs), fill = factor(cyl), y = mpg)) +
  geom_dotplot(binaxis = "y", stackdir = "center", position = "dodge")

# binpositions="all" ensures that the bins are aligned between groups
ggplot(mtcars, aes(x = factor(am), y = mpg)) +
  geom_dotplot(binaxis = "y", stackdir = "center", binpositions="all")

# Stacking multiple groups, with different fill
ggplot(mtcars, aes(x = mpg, fill = factor(cyl))) +
  geom_dotplot(stackgroups = TRUE, binwidth = 1, binpositions = "all")

ggplot(mtcars, aes(x = mpg, fill = factor(cyl))) +
  geom_dotplot(stackgroups = TRUE, binwidth = 1, method = "histodot")

ggplot(mtcars, aes(x = 1, y = mpg, fill = factor(cyl))) +
  geom_dotplot(binaxis = "y", stackgroups = TRUE, binwidth = 1, method = "histodot")
}
\references{
Wilkinson, L. (1999) Dot plots. The American Statistician,
   53(3), 276-281.
}