% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/guide-axis-symbols.R
\name{guide_axis_symbols}
\alias{guide_axis_symbols}
\alias{guide_axis_upset}
\title{Symbol and upset axis guide}
\usage{
guide_axis_symbols(
  key = NULL,
  connect = NULL,
  title = waiver(),
  theme = NULL,
  override.aes = list(),
  position = waiver(),
  direction = NULL,
  call = NULL
)

guide_axis_upset(
  key = "upset",
  connect = "perpendicular",
  title = waiver(),
  theme = NULL,
  override.aes = list(),
  position = waiver(),
  direction = NULL,
  call = NULL
)
}
\arguments{
\item{key}{One of the following:
\itemize{
\item An \link[=key_upset]{upset key} specification. For \code{guide_axis_upset}, specifying
a \verb{<character[n]>} is also passed to the \code{key_upset(order)} argument. An
exception is made when the string is a valid key specification.
\item A \link[=key_symbols]{symbol key} specification.
}}

\item{connect}{One of the following:
\itemize{
\item A \verb{<data.frame>} containing the following columns:
\itemize{
\item \code{value_start}, \code{value_end} Scale break values or \verb{<numeric[n]>} values
connecting along the axis.
\item \code{level_start}, \code{level_end} must be \verb{<integer[n]>} values connecting
perpendicular to the axis.
\item (Optional) columns for graphical parameters: \code{colour}, \code{linewidth}
and \code{linetype}.
}
\item A \verb{<character[1]>} keyword for upset guides or logical symbols:
\itemize{
\item \code{"perpendicular"}: connect \code{TRUE} symbols (set membership for upset)
perpendicular to the axis.
\item \code{"parallel"}: connect \code{TRUE} symbols parallel to the axis. This is
\emph{not} appropriate for upset guides.
}
}}

\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 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{override.aes}{A named \verb{<list>} specifying graphical properties of points to apply to
symbols. Every element must either be length 1 or match the number of symbols
determined by the key. 3 symbols are used in upset guides or for logical
symbolism. Otherwise the number of unique values to the \code{key_symbols(symbol)}
argument determines the number of symbols.}

\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{direction}{A \verb{<character[1]>} indicating the direction of the guide. Can be on of
\code{"horizontal"} or \code{"vertical"}.}

\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]}}

These axis guides can be used for set annotations of discrete categories.
The upset guide displays set intersections in matrix and is can be used
to replace Venn/Euler diagrams. The symbol guide also displays a matrix of
symbols, but requires manually specifying them.
}
\details{
The upset axis does not predetermine the order the categories. If any sorting
based on set size needs to occur, the scale is the correct tool to handle
this task.
\subsection{Styling options}{

Several styling options are provided in the theme, while individualised
styling is discussed below the table.\tabular{lll}{
   \strong{Theme setting} \tab \strong{Type} \tab \strong{Description} \cr
   \code{legendry.axis.subtitle} \tab \code{\link[ggplot2:element_text]{element_text()}} \tab Titles on the side labelling levels. \cr
   \code{legendry.axis.subtitle.position} \tab \verb{<character[1]>} \tab One of \code{"top"}, \code{"right"}, \code{"bottom"} or \code{"left"}. \cr
   \code{legendry.zebra.light} \tab \code{\link[ggplot2:element_rect]{element_rect()}} \tab Row shading. \cr
   \code{legendry.zebra.dark} \tab \code{\link[ggplot2:element_rect]{element_rect()}} \tab Alternate row shading. \cr
   \code{legendry.table.spacing} \tab \code{\link[ggplot2:rel]{rel()}}/\code{\link[=unit]{unit()}} \tab Padding between levels. \cr
   \code{legendry.point} \tab \code{\link[ggplot2:element_point]{element_point()}} \tab Styling of the symbols \cr
   \code{legendry.connector} \tab \code{\link[ggplot2:element_line]{element_line()}} Drawing the \code{connect} lines. \tab  \cr
}


Moreover, styling options \emph{per group} of symbols can be set via the
\code{override.aes} argument. These override theme settings.

Styling options \emph{per symbol} can be set in \code{\link[=key_symbols]{key_symbols()}} via the \code{...}
argument. These override theme settings and 'per group' settings.

Styling options \emph{per line} in line connectors can be set by including
graphical parameters as columns in the \verb{connect = <data.frame>} argument.
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_axis_symbols(theme = theme_guide(
  subtitle = element_line(),
  subtitle.position = "left",
  zebra.light = element_rect(),
  zebra.dark = element_rect(),
  table.spacing = unit(5, "mm"),
  point = element_point(),
  connector = element_line()
))
}\if{html}{\out{</div>}}
}
}
\examples{
# Example plot
p <- ggplot(mpg, aes(paste(drv, year))) +
  geom_bar()

# A standard upset axis might not have right order of levels
p + guides(x = "axis_upset")

# The levels can be manually adjusted to taste
p + guides(x = guide_axis_upset(c("1999", "2008", "4", "f", "r")))

# The connections can be turned off to just show symbols
p + guides(x = guide_axis_upset(connect = NULL))

# The style can be changed per group of symbols.
# We need to give 3 colours to also cover NA-breaks
p + guides(x = guide_axis_upset(
  override.aes = list(colour = c("purple", "orange", NA))
))

# For symbol guides you have to manually specify where you want symbols and
# connection lines appear.
p + guides(x = guide_axis_symbols(
  key_symbols(
    aesthetic = c("4 1999", "4 2008", "r 1999"),
    level = c("Lvl 1", "Lvl 2", "Lvl 3")
  ),
  connect = data.frame(
    value_start = "4 2008", value_end = "r 1999",
    level_start = 2, level_end = 3
  )
))
}
\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_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}
