% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/guide-colring.R
\name{guide_colring}
\alias{guide_colring}
\title{Colour rings and arcs}
\usage{
guide_colring(
  title = waiver(),
  key = "auto",
  start = 0,
  end = NULL,
  outer_guide = "axis_base",
  inner_guide = "axis_base",
  nbin = 300L,
  reverse = FALSE,
  show_labels = "outer",
  theme = NULL,
  vanilla = TRUE,
  position = waiver(),
  available_aes = c("colour", "fill"),
  ...
)
}
\arguments{
\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{key}{A \link[=key_standard]{standard key} specification. Defaults to
\code{\link[=key_auto]{key_auto()}}.}

\item{start, end}{A \verb{<numeric[1]>} in radians specifying the offset of the
starting and end points from 12 o'clock. The \code{NULL} default for \code{end},
internally defaults to \code{start + 2 * pi}.}

\item{outer_guide, inner_guide}{Guides to display on the outside and inside
of the colour ring. Each guide can be specified using one of the following:
\itemize{
\item A \verb{<Guide>} class object.
\item A \verb{<function>} that returns a \verb{<Guide>} class object.
\item A \verb{<character>} naming such function, without the \code{guide_} or
\code{primitive_} prefix.
}}

\item{nbin}{A positive \verb{<integer[1]>} determining how many colours to display.}

\item{reverse}{A \verb{<logical[1]>} whether to reverse continuous guides.
If \code{TRUE}, guides like colour bars are flipped. If \code{FALSE} (default),
the original order is maintained.}

\item{show_labels}{A \verb{<character[1]>} indicating for which guide labels
should be shown. Can be one of \code{"outer"} (default), \code{"inner"}, \code{"both"} or
\code{"none"}. Note that labels can only be omitted if the related guide
has a label suppression mechanism.}

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

\item{vanilla}{A \verb{<logical[1]>} whether to have the default style match
the vanilla \code{guide_colourbar()} (\code{TRUE}) or take the theme
verbatim (\code{FALSE}).}

\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{available_aes}{A \verb{<character>} vector listing the aesthetics for which this guide can
be build.}

\item{...}{Arguments forwarded to the \code{outer_guide} and \code{inner_guide} if
provided as functions or strings.}
}
\value{
A \verb{<Guide>} object.
}
\description{
Similar to \code{\link[ggplot2:guide_colourbar]{guide_colourbar()}}, this guide
displays continuous \code{colour} or \code{fill} aesthetics. Instead of a bar, the
gradient in shown in a ring or arc, which can be convenient for cyclical
palettes such as some provided in the \pkg{scico} package.
}
\details{
\subsection{Styling options}{

This guide is a hybrid composition guide, where the \link[ggplot2:theme]{theme}
settings apply both this guide itself and the constituents it manages.
The constituents are linked below so you can find their 'Styling options'
sections. Note that \code{guide_axis_base()} is just a default that can be
swapped out.\tabular{ll}{
   \strong{Constituent} \tab \strong{Description} \cr
   \code{\link[=guide_axis_base]{guide_axis_base()}} \tab Makes up the tick marks and labels at inner and outer rings. \cr
}


In addition to the constituent's theme setting, it also has the following
settings:\tabular{lll}{
   \strong{Theme setting} \tab \strong{Type} \tab \strong{Description} \cr
   \code{legend.background} \tab \code{\link[ggplot2:element_rect]{element_rect()}} \tab Background of the legend. \cr
   \code{legend.margin} \tab \code{\link[ggplot2:margin]{margin()}} \tab Padding around the legend. \cr
   \code{legend.key.width} \tab \code{\link[=unit]{unit()}} \tab Radial thickness of the donut ring. \cr
   \code{legend.key.size} \tab \code{\link[=unit]{unit()}} \tab Size of the legend. Multiplied by 5 to roughly match dimensions of colour bar guides. \cr
   \code{legend.frame} \tab \code{\link[ggplot2:element_rect]{element_rect()}} \tab Outline of the donut. The \code{fill} setting is ignored. \cr
   \code{legend.title} \tab \code{\link[ggplot2:element_text]{element_text()}} \tab Title of the legend. \cr
   \code{legend.title.position} \tab \verb{<character[1]>} \tab One of \code{"top"}, \code{"right"}, \code{"bottom"} or \code{"left"}. \cr
}


Styling options \emph{per break} can be set in the \link[=key_standard]{standard key}.
These override theme settings.

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{guide_colring(theme = theme_guide(
  # Ring settings
  title = element_text(),
  title.position = "top",
  margin = margin(5),
  background = element_rect(),
  frame = element_rect(),
  key.size = unit(1, "cm"),
  key.width = unit(5, "mm"),

  # Common options for `guide_axis_base()`
  line = element_line(),
  text = element_text(),
  ticks = element_line(),
  ticks.length = unit(5, "mm"),
))
}\if{html}{\out{</div>}}
}
}
\examples{
# Rings works best with a cyclical palette
my_pal <- c("black", "tomato", "white", "dodgerblue", "black")

p <- ggplot(mpg, aes(displ, hwy, colour = cty)) +
  geom_point() +
  scale_colour_gradientn(colours = my_pal)

# Standard colour ring
p + guides(colour = "colring")

# As an arc
p + guides(colour = guide_colring(
  start = 1.25 * pi, end = 2.75 * pi
))

# Removing the inner tick marks
p + guides(colour = guide_colring(inner_guide = "none"))

# Include labels on the inner axis
p + guides(colour = guide_colring(show_labels = "both"))

# Passing an argument to inner/outer guides
p + guides(colour = guide_colring(angle = 0))
}
\seealso{
Other standalone guides:
\code{\link[=guide_axis_annotation]{guide_axis_annotation()}},
\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_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}
