% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/geom-label-linked.r, R/geom-text-linked.r
\name{geom_label_s}
\alias{geom_label_s}
\alias{geom_text_s}
\title{Linked Text}
\usage{
geom_label_s(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  parse = FALSE,
  nudge_x = 0,
  nudge_y = 0,
  default.colour = NULL,
  default.color = default.colour,
  colour.target = c("text", "box"),
  color.target = colour.target,
  default.alpha = NA,
  alpha.target = "all",
  label.padding = grid::unit(0.25, "lines"),
  label.r = grid::unit(0.15, "lines"),
  segment.linewidth = 0.5,
  add.segments = TRUE,
  box.padding = 1e-06,
  point.padding = 1e-06,
  min.segment.length = 0,
  arrow = NULL,
  size.unit = "mm",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_text_s(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  parse = FALSE,
  nudge_x = 0,
  nudge_y = 0,
  default.colour = NULL,
  default.color = default.colour,
  colour.target = "text",
  color.target = colour.target,
  default.alpha = NA,
  alpha.target = "all",
  add.segments = TRUE,
  box.padding = 0.25,
  point.padding = 1e-06,
  segment.linewidth = 0.5,
  min.segment.length = 0,
  arrow = NULL,
  check_overlap = FALSE,
  size.unit = "mm",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)
}
\arguments{
\item{mapping}{Set of aesthetic mappings created by
\code{\link[ggplot2]{aes}}. If specified and with \code{inherit.aes = TRUE}
(the default), it is combined with the default mapping at the top level of
the plot. You only need to supply \code{mapping} if there isn't a mapping
defined for the plot.}

\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{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{add.segments}{logical Display connecting segments or arrows between
original positions and displaced ones if both are available.}

\item{box.padding, point.padding}{numeric By how much each end of the segments
should shortened in mm.}

\item{min.segment.length}{numeric Segments shorter that the minimum length
are not rendered, 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}, the default, includes a legend if any aesthetics are mapped.
\code{FALSE} never includes it, and \code{TRUE} always includes it.}

\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, rather
than combining them. This is most useful for helper functions that define
both data and aesthetics and shouldn't inherit behaviour from the default
plot specification, e.g., \code{\link[ggplot2]{borders}}.}

\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{
Linked text geometries are most useful for adding data labels to
  plots. `geom_text_s()` and `geom_label_s()` add text to the plot and for
  nudged positions link the original location to the nudged text with a
  segment or arrow.
}
\details{
Geometries \code{geom_text_s()} and \code{geom_label_s()} have an
  interface similar to that of \code{\link[ggplot2]{geom_text}} and
  \code{\link[ggplot2]{geom_label}}, but support additional features.
  Similarly to \code{geom_text_repel()} and \code{geom_label_repel()} when
  used together with position functions defined in package 'ggpp' they draw a
  segment linking the label at a displaced position to the original position,
  usually a point corresponding to an observation to which the label refers.
  Another difference is that they allow control of to which graphical
  elements the mappings to colour and alpha aesthetics are applied.
  Differently to \code{geom_label()}, \code{geom_label_s()} obeys aesthetic
  mappings to \code{linewidth} and \code{linetype} applied to the line at the
  edge of the label box. These features are reflected in the plot key, except
  for the segment, assumed not to be used to display information
  only in coordination with other graphic elements.

  In \code{geom_label_s()} the default \code{fill} is similar to
  \code{"white"} but with its \code{alpha} component set to 0.75. This
  differs from \code{"white"} used in \code{geom_label()}: the default fill
  is semitransparent with the intention that accidental occlusion of
  observations is obvious irrespective of the order in which layers are added
  to the plot.

  Layer functions \code{geom_text_s()} and \code{geom_label_s()} use by
  default \code{\link{position_nudge_keep}} which is backwards compatible
  with \code{\link[ggplot2]{position_nudge}}. In contrast to
  \code{\link[ggplot2]{position_nudge}}, \code{\link{position_nudge_keep}}
  and all other position functions defined in packages 'ggpp' and 'ggrepel'
  keep the original coordinates, thus allowing the plotting of connecting
  segments and arrows.

  Differently to \code{geom_text_repel()} and \code{geom_label_repel()},
  \code{geom_text_s()} and \code{geom_label_s()} do not make use of
  additional aesthetics for the segments or boxes, but instead allow the
  choice of which elements are targeted by the aesthetics and which are
  rendered in a default colour. In the grammar of graphics using the same
  aesthetic with multiple meanings is not allowed, thus, the approach used in
  the geometry layer functions from package 'ggpp' attempts to enforce this.
}
\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.
}

\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"}). 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{"position"}.

  If no position displacement is applied, or a position function defined in
  'ggplot2' is used, these geometries behave similarly to the corresponding
  ones from package 'ggplot2' with a default justification of \code{0.5} and
  no segment drawn.
}

\section{Differences from earlier versions}{

  The user interface is for the most part stable starting from 'ggpp' (==
  0.5.7). In 'ggpp' (== 0.5.0) support for aesthetics related to segments was
  removed, and replaced by parameters and a new mechanism for targeting the
  usual \code{colour} and \code{alpha} aesthetics to text, border, and
  segment.
}

\section{Aesthetics}{
 Layer functions \code{geom_text_s()} and
  \code{geom_label_s()} require aesthetics \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{lineheight}, \code{hjust} and \code{vjust}. In addition,
  \code{geom_text_s} supports \code{angle} and \code{geom_label_s} supports
  \code{fill}, \code{linewidth} and \code{linetype}. 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_s()} 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.
}

\section{Position functions}{
 Many layer functions from package 'ggpp' are
  designed to work seamlessly with position functions that keep, rather than
  discard, the original \code{x} and \code{y} positions in \code{data} when
  computing a new displaced position. See \code{\link{position_nudge_keep}},
  \code{\link{position_dodge_keep}}, \code{\link{position_jitter_keep}},
  \code{\link{position_nudge_center}}, \code{\link{position_nudge_line}},
  \code{\link{position_nudge_to}}, \code{\link{position_dodgenudge}},
  \code{\link{position_jitternudge}}, and \code{\link{position_stacknudge}}
  for examples and details of their use.
}

\examples{

my.cars <- mtcars[c(TRUE, FALSE, FALSE, FALSE), ]
my.cars$name <- rownames(my.cars)

# no nudging
ggplot(my.cars, aes(wt, mpg, label = name)) +
  geom_text_s() +
  expand_limits(x = c(2, 6))

# base plot
p <- ggplot(my.cars, aes(wt, mpg, label = name)) +
       geom_point()

# Using nudging
p +
  geom_text_s(nudge_x = 0.12) +
  expand_limits(x = 6.2)
p +
  geom_text_s(nudge_x = -0.12) +
  expand_limits(x = 1.5)
p +
  geom_text_s(nudge_x = 0.12,
              arrow = arrow(length = grid::unit(1.5, "mm")),
              point.padding = 0.4) +
  expand_limits(x = 6.2)
p +
  geom_text_s(nudge_y = 0.1, nudge_x = 0.07) +
  expand_limits(x = 6.2)
p +
  geom_text_s(nudge_y = 1, angle = 90) +
  expand_limits(y = 30)
p +
  geom_text_s(angle = 90, nudge_y = 1,
              arrow = arrow(length = grid::unit(1.5, "mm")),
              colour.target = "segment", colour = "red") +
  expand_limits(y = 30)
p +
  geom_text_s(aes(colour = factor(cyl)),
              angle = 90, nudge_y = 1,
              arrow = arrow(length = grid::unit(1.5, "mm")),
              alpha.target = "segment", alpha = 0.3) +
  expand_limits(y = 30)

p +
  geom_label_s(nudge_x = 0.12) +
  expand_limits(x = 6.2)
p +
  geom_label_s(nudge_x = 0.12, linetype = "dotted", linewidth = 0.3) +
  expand_limits(x = 6.2)
p +
  geom_label_s(aes(colour = factor(cyl)),
               nudge_x = 0.12,
               colour.target = "box",
               linewidth = 0.5,
               label.r = unit(0, "lines")) +
  expand_limits(x = 6.2)
p +
  geom_label_s(nudge_x = 0.12, linewidth = 0) +
  expand_limits(x = 6.2)

# No segments
p +
  geom_label_s(nudge_x = 0.05, segment.linewidth = 0) +
  expand_limits(x = 6.2)

# Nudging away from arbitrary point
p +
  geom_label_s(hjust = "outward_1", nudge_x = 0.12) +
  expand_limits(x = 6.2)
p +
  geom_label_s(hjust = "inward_3", nudge_y = 0.4)

p +
  geom_label_s(nudge_y = 1, angle = 90) +
  expand_limits(y = 30)

# Add aesthetic mappings and adjust arrows
p +
  geom_text_s(aes(colour = factor(cyl)),
              angle = 90,
              nudge_y = 1,
              arrow = arrow(angle = 20,
                            length = grid::unit(1.5, "mm"),
                            ends = "first",
                            type = "closed")) +
  scale_colour_discrete(l = 40) + # luminance, make colours darker
  expand_limits(y = 27)

p +
  geom_text_s(aes(colour = factor(cyl)),
              angle = 90,
              nudge_y = 1,
              arrow = arrow(angle = 20,
                            length = grid::unit(1.5, "mm"),
                            ends = "first",
                            type = "closed")) +
  scale_colour_discrete(l = 40) + # luminance, make colours darker
  expand_limits(y = 27)

p +
  geom_label_s(aes(colour = factor(cyl)),
              colour.target = c("box", "text"),
              nudge_x = 0.3,
              arrow = arrow(angle = 20,
                            length = grid::unit(1/3, "lines"))) +
  scale_colour_discrete(l = 40) + # luminance, make colours darker
  expand_limits(x = 7)

p +
  geom_label_s(aes(colour = factor(cyl)),
              nudge_x = 0.3,
              colour.target = c("box", "segment"),
              linewidth = 0.5,
              arrow = arrow(angle = 20,
                            length = grid::unit(1/3, "lines"))) +
  scale_colour_discrete(l = 40) + # luminance, make colours darker
  expand_limits(x = 7)

p +
  geom_label_s(aes(colour = factor(cyl), fill = factor(cyl)),
              nudge_x = 0.3,
              alpha.target = "box",
              alpha = 0.1,
              linewidth = 0.5,
              arrow = arrow(angle = 20,
                            length = grid::unit(1/3, "lines"))) +
  scale_colour_discrete(l = 40) + # luminance, make colours darker
  expand_limits(x = 7)#' # Scale height of text, rather than sqrt(height)

p +
  geom_text_s(aes(size = wt), nudge_x = -0.1) +
  scale_radius(range = c(3,6)) + # override scale_area()
    expand_limits(x = c(1.8, 5.5))

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