% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/guide-axis-annotation.R
\name{guide_axis_annotation}
\alias{guide_axis_annotation}
\alias{annotate_top}
\alias{annotate_right}
\alias{annotate_bottom}
\alias{annotate_left}
\title{Annotation axis guide}
\usage{
guide_axis_annotation(
  aesthetic,
  label = as.character(aesthetic),
  ...,
  key = NULL,
  arrow = NULL,
  inner = waiver(),
  title = waiver(),
  theme = NULL,
  order = 0L,
  position = waiver(),
  call = NULL
)

annotate_top(..., position = "top")

annotate_right(..., position = "right")

annotate_bottom(..., position = "bottom")

annotate_left(..., position = "left")
}
\arguments{
\item{aesthetic}{A vector of values for the guide to represent.}

\item{label}{A \verb{<character[n]>} or list of expressions to use as labels.}

\item{...}{Additional graphical properties parallel to \code{aesthetic}. Can be
\code{text_colour}, \code{size}, \code{face}, \code{hjust}, \code{vjust}, \code{angle} or \code{lineheight} for
the labels. Can be \code{line_colour}, \code{linewidth} and \code{linetype} for ticks.
Setting \code{colour} will also set \code{text_colour} and \code{line_colour}.
For \code{annotate_top()}, \code{annotate_right()}, \code{annotate_bottom()} and
\code{annotate_left()}, arguments are passed on to \code{guide_axis_annotation()}.}

\item{key}{A \link[=key_standard]{standard key} overriding the \code{aesthetic}, \code{label} and \code{...}
arguments.}

\item{arrow}{A \code{\link[grid:arrow]{grid::arrow()}} specification. Can be \code{NULL} (default) to draw no arrow.}

\item{inner}{A guide that supports the aesthetic to draw the annotation across.
When \code{waiver()} (default), populates a \code{guide_axis_base()} except in the
\code{"top"}, \code{"right"} and \code{"theta.sec"} positions.}

\item{title}{One of the following to indicate the title of the guide:
\itemize{
\item A \verb{<character[1]>} or \verb{<expression[1]>} to set a custom title.
\item \code{NULL} to not display any title.
\item \code{\link[ggplot2:waiver]{waiver()}} (default) to take the name of the scale
object or the name specified in \code{\link[ggplot2:labs]{labs()}} as the title.
}}

\item{theme}{A \code{\link[ggplot2:theme]{<theme>}} object to style the \emph{annotation} part of this
guide differently from the plot's theme settings. The \code{theme} argument
in this guide overrides and is combined with the plot's theme.}

\item{order}{A positive \verb{<integer[1]>} that specifies the order of this guide among
multiple guides. This controls in which order guides are merged if there
are multiple guides for the same position. If \code{0} (default), the order is
determined by a hashing indicative settings of a guide.}

\item{position}{A \verb{<character[1]>} giving the location of the guide. Can be one of \code{"top"},
\code{"bottom"}, \code{"left"} or \code{"right"}.}

\item{call}{A \link[rlang:topic-error-call]{call} to display in messages.}
}
\value{
A \verb{<Guide>} object
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}

This axis guide acts as annotation: it draws labels at specified places.
It also wraps an inner guide, making the behaviour look like one is 'adding'
the annotation on top of the regular guide.
}
\details{
Under the hood, this guide is a hybrid composition guide. The \code{theme()}
options that govern the styling are partially determined by its consituents.
They are linked below so you can find their 'Styling options' sections.

| \strong{Constituent} | \strong{Description} |
| \code{compose_ontop()} | Composes the annotation on top of the \code{inner} guide |
| \code{guide_axis_base()} | The default \code{inner} guide |
| \code{primitive_ticks()} | Display of the annotation ticks |
| \code{primitive_labels()} | Display of the annotation labels |

Styling options \emph{per annotation} can be set via \code{...} as described above.

The context-agnostic alternative to using \code{theme()} is to use
\code{\link[=theme_guide]{theme_guide()}}:

\if{html}{\out{<div class="sourceCode r">}}\preformatted{# Note that `theme` is used *only* for the annotation
guide_axis_annotation(theme = theme_guide(
  text = element_text(),
  ticks = element_line(),
  ticks.length = unit(5, "mm")
))
}\if{html}{\out{</div>}}
}
\examples{
# Basic plot
p <- ggplot(mpg, aes(displ, hwy)) +
  geom_point()

# Typical use
p +
  annotate_top(5, face = "bold") +
  annotate_bottom(c(2.5, 4.5), c("Bottom annotation", "Second label"))

# If you want to combine them with secondary axes, you must
# set the `inner` argument manually.
p +
  scale_y_continuous(
    sec.axis = dup_axis(breaks = c(15, 25, 35))
  ) +
  annotate_right(30, inner = "axis")

# Use in theta axis
p + coord_radial() +
  guides(theta = guide_axis_annotation(4.5, "Theta annotation"))

# Specialised use as part of other guides
# Note that `guide_colbar` imposes white inward ticks
# We can overrule these impositions with a replacement theme
p + aes(colour = cty) +
  guides(colour = guide_colbar(
    second_guide = guide_axis_annotation(22, "This", theme = theme_gray())
  ))
}
\seealso{
Other standalone guides:
\code{\link[=guide_axis_base]{guide_axis_base()}},
\code{\link[=guide_axis_dendro]{guide_axis_dendro()}},
\code{\link[=guide_axis_nested]{guide_axis_nested()}},
\code{\link[=guide_axis_plot]{guide_axis_plot()}},
\code{\link[=guide_axis_symbols]{guide_axis_symbols()}},
\code{\link[=guide_circles]{guide_circles()}},
\code{\link[=guide_colbar]{guide_colbar()}},
\code{\link[=guide_colring]{guide_colring()}},
\code{\link[=guide_colsteps]{guide_colsteps()}},
\code{\link[=guide_legend_base]{guide_legend_base()}},
\code{\link[=guide_legend_cross]{guide_legend_cross()}},
\code{\link[=guide_legend_group]{guide_legend_group()}},
\code{\link[=guide_legend_manual]{guide_legend_manual()}}
}
\concept{standalone guides}
