% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/geom-label-pairwise.r, R/geom-text-pairwise.R
\name{geom_label_pairwise}
\alias{geom_label_pairwise}
\alias{geom_text_pairwise}
\title{Label pairwise comparisons}
\usage{
geom_label_pairwise(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  orientation = NA,
  parse = FALSE,
  nudge_x = 0,
  nudge_y = 0,
  default.colour = NULL,
  default.color = default.colour,
  colour.target = "all",
  color.target = colour.target,
  default.alpha = NA,
  alpha.target = "segment",
  label.padding = grid::unit(0.25, "lines"),
  label.r = grid::unit(0.15, "lines"),
  segment.linewidth = 0.5,
  arrow = NULL,
  size.unit = "mm",
  na.rm = FALSE,
  show.legend = FALSE,
  inherit.aes = FALSE
)

geom_text_pairwise(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  orientation = NA,
  parse = FALSE,
  nudge_x = 0,
  nudge_y = 0,
  default.colour = "black",
  default.color = default.colour,
  colour.target = "all",
  color.target = colour.target,
  default.alpha = NA,
  alpha.target = "all",
  segment.linewidth = 0.5,
  arrow = NULL,
  check_overlap = FALSE,
  size.unit = "mm",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = FALSE
)
}
\arguments{
\item{mapping}{Set of aesthetic mappings created by
\code{\link[ggplot2]{aes}}. With \code{inherit.aes = FALSE}
(the default) it is not combined with the default mapping at the top level of
the plot. You always need to supply a \code{mapping} unless you set
\code{inherit.aes = TRUE}.}

\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}{Position adjustment, either as a string, or the result of a
call to a position adjustment function.}

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

  \itemize{ \item Aesthetics: to set an aesthetic to a fixed value, like
  \code{colour = "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. }}

\item{orientation}{character The orientation of the layer. The default
(\code{NA}) automatically determines the orientation from the aesthetic
mapping. In the rare event that this fails it can be given explicitly by
setting orientation to either "x" or "y".}

\item{parse}{If \code{TRUE}, the labels will be parsed into expressions and
displayed as described in \code{?plotmath}.}

\item{nudge_x, nudge_y}{Horizontal and vertical adjustments to nudge the
starting position of each text label. The units for \code{nudge_x} and
\code{nudge_y} are the same as for the data units on the x-axis and y-axis.}

\item{default.colour, default.color}{A colour definition to use for elements
not targeted by the colour aesthetic.}

\item{colour.target, color.target}{A vector of character strings; \code{"all"},
\code{"text"}, \code{"segment"}, \code{"box"}, \code{"box.line"}, and
\code{"box.fill"} or \code{"none"}.}

\item{default.alpha}{numeric in [0..1] A transparency value to use for
elements not targeted by the alpha aesthetic.}

\item{alpha.target}{A vector of character strings; \code{"all"},
\code{"text"}, \code{"segment"}, \code{"box"}, \code{"box.line"}, and
\code{"box.fill"} or \code{"none"}.}

\item{label.padding}{Amount of padding around label. Defaults to 0.25 lines.}

\item{label.r}{Radius of rounded corners. Defaults to 0.15 lines.}

\item{segment.linewidth}{numeric Width of the segments or arrows in mm.}

\item{arrow}{specification for arrow heads, as created by
\code{\link[grid]{arrow}}}

\item{size.unit}{How the `size` aesthetic is interpreted: as millimetres
(`"mm"`, default), points (`"pt"`), centimetres (`"cm"`), inches (`"in"`),
or picas (`"pc"`).}

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

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

\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, rather
than combining them.}

\item{check_overlap}{If \code{TRUE}, text that overlaps previous text in the
same layer will not be plotted. \code{check_overlap} takes place at draw
time and in the order of the data, thus its action depends of the size at
which the plot is drawn.}
}
\value{
A plot layer instance.
}
\description{
Add a plot layer with a text label and a segment connecting two
  values along the \code{x} aesthetic. These are usually two levels of a
  factor mapped to the \code{x} aesthetic when used to report significance or
  highlighting pairwise comparisons.
}
\details{
Geometries \code{geom_text_pairwise()} and
  \code{geom_label_pairwise()} have an interface similar to that of
  \code{\link[ggplot2]{geom_text}} and \code{\link[ggplot2]{geom_label}}, but
  add a segment connecting two values along \code{x}. In the most
  frequent use case they add a segment connecting pairs of levels from a
  grouping factor mapped to the \emph{x} or \emph{y} aesthetic. They can
  also be used to label ranges of values.

  The segment extends from \code{xmin} to \code{xmax}, and the text label is
  located at \code{x} with a default that positions the label at the centre
  of the bar. The ends of the bar can be terminated with arrow heads given
  by parameter \code{arrow}, with a default of a plain segment without
  arrow tips. The text label is located slightly above the segment by the
  default value of \code{vjust} in \code{geom_text_pairwise()} and on top
  of the segment in \code{geom_label_pairwise()}.

  Layer functions \code{geom_text_pairwise()} and
  \code{geom_label_pairwise()} use by default
  \code{\link[ggplot2]{position_nudge}}. Nudging affects both text label and
  bar, and its default of no displacement will very rarely need to be
  changed.

  Differently to \code{geom_text_repel()} and \code{geom_label_repel()},
  \code{geom_text_pairwise()} and \code{geom_label_pairwise()} do not make
  use of additional aesthetics for the segments or boxes, but instead allow
  the choice of which elements are targeted by the usual 'ggplot2' aesthetics
  and which are rendered using a default constant value. In the grammar of
  graphics using the same aesthetic with multiple meanings is not allowed,
  thus, the approach used in package 'ggpp' attempts to enforce this.
}
\section{Under development!}{
 This geometry is still under development
  and its user interface subject to change.
}

\section{Plot boundaries and clipping}{
 Note that when you change the scale
  limits for \emph{x} and/or \emph{y} of a plot, text labels stay the same
  size, as determined by the \code{size} aesthetic, given in millimetres. The
  actual size as seen in the plotted output is decided during the rendering
  of the plot to a graphics device. Limits are expanded only to include the
  anchor point of the labels because the "width" and "height" of a text
  element are 0 (as seen by ggplot2). Text labels do have height and width,
  but in grid units, not data units. Either function
  \code{\link[ggplot2]{expand_limits}} or the scale expansion can be used to
  ensure text labels remain within the plotting area.
}

\section{Alignment}{
 You can modify text alignment with the \code{vjust} and
  \code{hjust} aesthetics. These can either be a number between 0
  (right/bottom) and 1 (top/left) or a character (\code{"left"},
  \code{"middle"}, \code{"right"}, \code{"bottom"}, \code{"center"},
  \code{"top"}). Values outside the range 0..1 displace the text label so
  that the anchor point is outside the text label. In addition, you can use
  special alignments for justification including \code{"position"},
  \code{"inward"} and \code{"outward"}. Inward always aligns text towards the
  center of the plotting area, and outward aligns it away from the center of
  the plotting area. If tagged with \code{_mean} or \code{_median} (e.g.,
  \code{"outward_mean"}) the mean or median of the data in the panel along
  the corresponding axis is used as center. If the characters following the
  underscore represent a number (e.g., \code{"outward_10.5"}) the reference
  point will be this value in data units. Position justification is computed
  based on the direction of the displacement of the position of the label so
  that each individual text or label is justified outwards from its original
  position. The default justification is \code{"identity"}.
}

\section{Aesthetics}{
 Layer functions \code{geom_text_pairwise()} and
  \code{geom_label_pairwise()} require aesthetics \code{xmin}, \code{xmax},
  \code{x}, \code{y} and
  \code{label} and support aesthetics: \code{alpha}, \code{colour},
  \code{group}, \code{size} (of text), \code{family}, \code{fontface},
  \code{linewidth}, \code{linetype}, \code{hjust} and \code{vjust}. In addition,
  \code{geom_text_pairwise} supports \code{angle} and \code{geom_label_pairwise} supports
  \code{fill}. See
  \code{\link[ggplot2]{aes_colour_fill_alpha}},
  \code{\link[ggplot2]{aes_linetype_size_shape}},
  \code{\link[ggplot2]{aes_position}}, and
  \code{\link[ggplot2]{aes_group_order}}.

  In 'ggplot2' \code{linewidth} when applied to the border of the box drawn
  by \code{geom_label()} is given in points rather than in mm because of a
  historical error in the code. In other geometries such as
  \code{geom_segment()} \code{linewidth} is given in mm. As in
  \code{geom_label_pairwise()} it is important to remain consistent among
  different \code{linewidth} specifications, mm are used both for the box
  border and linking segment. To imitate the behaviour of \code{geom_label()}
  a correction factor of 0.75 (more exactly 1 pt = 0.7528 mm) can be used for
  the line width of the border of the box.
}

\examples{

my.cars <- mtcars
my.cars$name <- rownames(my.cars)
p1 <- ggplot(my.cars, aes(x = factor(cyl), y = mpg)) +
       geom_boxplot(width = 0.33)

# With a factor mapped to x, highlight pairs

my.pairs <-
  data.frame(A = 1:2, B = 2:3, bar.height = c(12, 30),
             p.value = c(0.01, 0.05678))
p1 +
  geom_text_pairwise(data = my.pairs,
                     aes(xmin = A, xmax = B,
                         y = bar.height,
                         label = p.value),
                     parse = TRUE)

p1 +
  geom_text_pairwise(data = my.pairs,
                     aes(xmin = A, xmax = B,
                         y = bar.height,
                         label = sprintf("italic(P)~`=`~\%.2f", p.value)),
                     arrow = grid::arrow(angle = 90,
                                         length = unit(1, "mm"),
                                         ends = "both"),
                     parse = TRUE)

p1 +
  geom_text_pairwise(data = my.pairs,
                     aes(xmin = A, xmax = B,
                         y = bar.height,
                         label = sprintf("italic(P)~`=`~\%.2f", p.value)),
                     colour = "red",
                     arrow = grid::arrow(angle = 90,
                                         length = unit(1, "mm"),
                                         ends = "both"),
                     parse = TRUE)

p1 +
  geom_label_pairwise(data = my.pairs,
                      aes(xmin = A, xmax = B,
                          y = bar.height,
                          label = sprintf("italic(P)~`=`~\%.2f", p.value)),
                      colour = "red", size = 2.75,
                      arrow = grid::arrow(angle = 30,
                                          length = unit(1.5, "mm"),
                                          ends = "both"),
                      parse = TRUE)

p1 +
  geom_text_pairwise(data = my.pairs,
                     aes(xmin = A, xmax = B,
                         y = bar.height,
                         label = sprintf("italic(P)~`=`~\%.2f", p.value)),
                     colour = "red", colour.target = "segment",
                     arrow = grid::arrow(angle = 90,
                                         length = unit(1, "mm"),
                                         ends = "both"),
                     parse = TRUE)

p1 +
  geom_text_pairwise(data = my.pairs,
                     aes(xmin = A, xmax = B,
                         y = bar.height,
                         label = sprintf("italic(P)~`=`~\%.2f", p.value)),
                     colour = "red", colour.target = "text",
                     arrow = grid::arrow(angle = 90,
                                         length = unit(1, "mm"),
                                         ends = "both"),
                     parse = TRUE)

# with a numeric vector mapped to x, indicate range

p2 <-
  ggplot(my.cars, aes(disp, mpg)) +
    geom_point()

my.ranges <-
  data.frame(A = c(50, 400),
             B = c(200, 500),
             bar.height = 5,
             text = c("small", "large"))

p2 +
  geom_text_pairwise(data = my.ranges,
                     aes(xmin = A, xmax = B,
                     y = bar.height, label = text))

p2 +
  geom_text_pairwise(data = my.ranges,
                     aes(xmin = A, xmax = B,
                         y = bar.height, label = text),
                     angle = 90, hjust = -0.1)

p2 +
  geom_label_pairwise(data = my.ranges,
                      aes(xmin = A, xmax = B,
                          y = bar.height, label = text),
                     angle = 90, hjust = -0.1)

p2 +
  geom_label_pairwise(data = my.ranges,
                      aes(xmin = A, xmax = B,
                          y = bar.height, label = text))

p2 +
  geom_text_pairwise(data = my.ranges,
                     aes(xmin = A, xmax = B,
                         y = bar.height, label = text),
                     arrow = grid::arrow(ends = "both", length = unit(2, "mm")))

# implicit orientation = "y"
p3 <- ggplot(my.cars, aes(x = mpg, y = factor(cyl))) +
       geom_boxplot(width = 0.33)

p3 +
  geom_text_pairwise(data = my.pairs,
                     aes(ymin = A, ymax = B,
                         x = bar.height,
                         label = p.value))

p3 +
  geom_label_pairwise(data = my.pairs,
                      aes(ymin = A, ymax = B,
                          x = bar.height,
                          label = p.value))

}
\seealso{
\code{\link{geom_text_s}}, \code{\link{geom_label_s}},
  \code{\link[ggplot2]{geom_text}}, \code{\link[ggplot2]{geom_label}} and
  other documentation of package 'ggplot2'.
}
