% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ggboxplot.R
\name{ggboxplot}
\alias{ggboxplot}
\title{Box plot}
\usage{
ggboxplot(
  data,
  x,
  y,
  combine = FALSE,
  merge = FALSE,
  color = "black",
  fill = "white",
  palette = NULL,
  title = NULL,
  xlab = NULL,
  ylab = NULL,
  bxp.errorbar = FALSE,
  bxp.errorbar.width = 0.4,
  facet.by = NULL,
  panel.labs = NULL,
  short.panel.labs = TRUE,
  linetype = "solid",
  size = NULL,
  linewidth = NULL,
  width = 0.7,
  notch = FALSE,
  outliers = TRUE,
  outlier.shape = 19,
  select = NULL,
  remove = NULL,
  order = NULL,
  add = "none",
  add.params = list(),
  error.plot = "pointrange",
  label = NULL,
  font.label = list(size = 11, color = "black"),
  label.select = NULL,
  repel = FALSE,
  label.rectangle = FALSE,
  position = position_dodge(0.8),
  ggtheme = theme_pubr(),
  show.n = FALSE,
  ...
)
}
\arguments{
\item{data}{a data frame}

\item{x}{character string containing the name of x variable.}

\item{y}{character vector containing one or more variables to plot}

\item{combine}{logical value. Default is FALSE. Used only when y is a vector
containing multiple variables to plot. If TRUE, create a multi-panel plot by
combining the plot of y variables.}

\item{merge}{logical or character value. Default is FALSE. Used only when y is
a vector containing multiple variables to plot. If TRUE, merge multiple y
variables in the same plotting area. Allowed values include also "asis"
(TRUE) and "flip". If merge = "flip", then y variables are used as x tick
labels and the x variable is used as grouping variable.}

\item{color}{outline color.}

\item{fill}{fill color.}

\item{palette}{the color palette to be used for coloring or filling by groups.
Allowed values include "grey" for grey color palettes; brewer palettes e.g.
"RdBu", "Blues", ...; or custom color palette e.g. c("blue", "red"); and
scientific journal palettes from ggsci R package, e.g.: "npg", "aaas",
"lancet", "jco", "ucscgb", "uchicago", "simpsons" and "rickandmorty".}

\item{title}{plot main title.}

\item{xlab}{character vector specifying x axis labels. Use xlab = FALSE to
hide xlab.}

\item{ylab}{character vector specifying y axis labels. Use ylab = FALSE to
hide ylab.}

\item{bxp.errorbar}{logical value. If TRUE, shows error bars of box plots.}

\item{bxp.errorbar.width}{numeric value specifying the width of box plot error
bars. Default is 0.4.}

\item{facet.by}{character vector, of length 1 or 2, specifying grouping
variables for faceting the plot into multiple panels. Should be in the data.}

\item{panel.labs}{a list of one or two character vectors to modify facet panel
labels. For example, panel.labs = list(sex = c("Male", "Female")) specifies
the labels for the "sex" variable. For two grouping variables, you can use
for example panel.labs = list(sex = c("Male", "Female"), rx = c("Obs",
"Lev", "Lev2") ).}

\item{short.panel.labs}{logical value. Default is TRUE. If TRUE, create short
labels for panels by omitting variable names; in other words panels will be
labelled only by variable grouping levels.}

\item{linetype}{line types.}

\item{size}{Numeric value (e.g.: size = 1). change the size of points and
outlines.}

\item{linewidth}{constant value specifying the line width.}

\item{width}{numeric value between 0 and 1 specifying the width of the plot elements.}

\item{notch}{If \code{FALSE} (default) make a standard box plot. If
\code{TRUE}, make a notched box plot. Notches are used to compare groups;
if the notches of two boxes do not overlap, this suggests that the medians
are significantly different.}

\item{outliers}{Whether to display (\code{TRUE}) or discard (\code{FALSE}) outliers
from the plot. Hiding or discarding outliers can be useful when, for
example, raw data points need to be displayed on top of the boxplot.
By discarding outliers, the axis limits will adapt to the box and whiskers
only, not the full data range. If outliers need to be hidden and the axes
needs to show the full data range, please use \code{outlier.shape = NA} instead.}

\item{outlier.shape}{point shape of outlier. Default is 19. To hide outlier,
specify \code{outlier.shape = NA}. When jitter is added, then outliers will
be automatically hidden.}

\item{select}{character vector specifying which items to display.}

\item{remove}{character vector specifying which items to remove from the plot.}

\item{order}{character vector specifying the order of items.}

\item{add}{character vector for adding another plot element (e.g.: dot plot or
error bars). Allowed values are one or the combination of: "none",
"dotplot", "jitter", "boxplot", "point", "mean", "mean_se", "mean_sd",
"mean_ci", "mean_range", "median", "median_iqr", "median_hilow",
"median_q1q3", "median_mad", "median_range"; see ?desc_statby for more
details.}

\item{add.params}{parameters (color, shape, size, fill, linetype) for the
argument 'add'; e.g.: add.params = list(color = "red").}

\item{error.plot}{plot type used to visualize error. Allowed values are one of
c("pointrange", "linerange", "crossbar", "errorbar", "upper_errorbar",
"lower_errorbar", "upper_pointrange", "lower_pointrange", "upper_linerange",
"lower_linerange"). Default value is "pointrange" or "errorbar". Used only
when add != "none" and add contains one "mean_*" or "med_*" where "*" = sd,
se, ....}

\item{label}{the name of the column containing point labels. Can be also a
character vector with length = nrow(data).}

\item{font.label}{a list which can contain the combination of the following
elements: the size (e.g.: 14), the style (e.g.: "plain", "bold", "italic",
"bold.italic") and the color (e.g.: "red") of labels. For example font.label
= list(size = 14, face = "bold", color ="red"). To specify only the size and
the style, use font.label = list(size = 14, face = "plain").}

\item{label.select}{can be of two formats: \itemize{ \item a character vector
specifying some labels to show. \item a list containing one or the
combination of the following components: \itemize{ \item \code{top.up} and
\code{top.down}: to display the labels  of the top up/down points. For
example, \code{label.select = list(top.up = 10, top.down = 4)}. \item
\code{criteria}: to filter, for example, by x and y variables values, use
this: \code{label.select = list(criteria = "`y` > 2 & `y` < 5 & `x` \%in\%
c('A', 'B')")}. } }}

\item{repel}{a logical value, whether to use ggrepel to avoid overplotting
text labels or not.}

\item{label.rectangle}{logical value. If TRUE, add rectangle underneath the
text, making it easier to read.}

\item{position}{position adjustment, either as a string, or the result of a
call to a position adjustment function (e.g. \code{position_dodge(0.8)}).
Used to control the spacing between grouped elements.}

\item{ggtheme}{function, ggplot2 theme name. Default value is theme_pubr(). Set ggtheme = NULL to skip applying a ggpubr theme, so the plot keeps ggplot2 default theme or the theme set globally via theme_set().
Allowed values include ggplot2 official themes: theme_gray(), theme_bw(),
theme_minimal(), theme_classic(), theme_void(), ....}

\item{show.n}{logical. If TRUE, displays the number of observations
(\code{"n = <count>"}) at the top of each group. Off by default. When the
groups are dodged (a \code{color}/\code{fill} grouping with a dodging
\code{position}), one count is shown per group; otherwise a single count is
shown per x-axis tick. Counts respect \code{select}/\code{remove} and are
computed per facet.}

\item{...}{other arguments to be passed to
\code{\link[ggplot2]{geom_boxplot}}, \code{\link{ggpar}} and
\code{\link{facet}}.}
}
\description{
Create a box plot with points. Box plots display a group of
 numerical data through their quartiles.
}
\details{
The plot can be easily customized using the function ggpar(). Read
 ?ggpar for changing: \itemize{ \item main title and axis labels: main, xlab,
 ylab \item axis limits: xlim, ylim (e.g.: ylim = c(0, 30)) \item axis
 scales: xscale, yscale (e.g.: yscale = "log2") \item color palettes: palette
 = "Dark2" or palette = c("gray", "blue", "red") \item legend title, labels
 and position: legend = "right" \item plot orientation : orientation =
 c("vertical", "horizontal", "reverse") }
}
\section{Suggestions for the argument "add"}{
 Suggested values are one of
 c("dotplot", "jitter").
}

\examples{
# Load data
data("ToothGrowth")
df <- ToothGrowth

# Basic plot
# +++++++++++++++++++++++++++
# width: change box plots width
ggboxplot(df, x = "dose", y = "len", width = 0.8)

# Change orientation: horizontal
ggboxplot(df, "dose", "len", orientation = "horizontal")

# Notched box plot
ggboxplot(df,
  x = "dose", y = "len",
  notch = TRUE
)

# Add dots
# ++++++++++++++++++++++++++
ggboxplot(df,
  x = "dose", y = "len",
  add = "dotplot"
)

# Add jitter points and change the shape by groups
ggboxplot(df,
  x = "dose", y = "len",
  add = "jitter", shape = "dose"
)


# Select and order items
# ++++++++++++++++++++++++++++++

# Select which items to display: "0.5" and "2"
ggboxplot(df, "dose", "len",
  select = c("0.5", "2")
)

# Change the default order of items
ggboxplot(df, "dose", "len",
  order = c("2", "1", "0.5")
)


# Change colors
# +++++++++++++++++++++++++++
# Change outline and fill colors
ggboxplot(df, "dose", "len",
  color = "black", fill = "gray"
)

# Change outline colors by groups: dose
# Use custom color palette
# Add jitter points and change the shape by groups
ggboxplot(df, "dose", "len",
  color = "dose", palette = c("#00AFBB", "#E7B800", "#FC4E07"),
  add = "jitter", shape = "dose"
)

# Change fill color by groups: dose
ggboxplot(df, "dose", "len",
  fill = "dose", palette = c("#00AFBB", "#E7B800", "#FC4E07")
)


# Box plot with multiple groups
# +++++++++++++++++++++
# fill or color box plot by a second group : "supp"
ggboxplot(df, "dose", "len",
  color = "supp",
  palette = c("#00AFBB", "#E7B800")
)

}
\seealso{
\code{\link{ggpar}}, \code{\link{ggviolin}}, \code{\link{ggdotplot}}
 and \code{\link{ggstripchart}}.
}
