% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/guide-axis-plot.R
\name{guide_axis_plot}
\alias{guide_axis_plot}
\title{Side-plot axis}
\usage{
guide_axis_plot(
  plot,
  title = NULL,
  size = unit(2, "cm"),
  reposition = TRUE,
  theme = theme_sub_legend(position = "none"),
  position = waiver()
)
}
\arguments{
\item{plot}{A \verb{<ggplot>} object, subject to limitations listed in the 'Details' section.
Alternatively, a \verb{<function>} that takes the scale as argument and returns
a \verb{<ggplot>} object.}

\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} (default) to not display any title.
\item \code{\link[ggplot2:waiver]{waiver()}} to take the name of the scale
object or the name specified in \code{\link[ggplot2:labs]{labs()}} as the title.
Please note that \code{plot} will still display a title unless instructed
otherwise. To avoid duplicated titles, the default is to have no title for
the guide.
}}

\item{size}{An absolute \code{\link[grid:unit]{<unit>}} to set the size of the \code{plot} panel in
the orthogonal direction.}

\item{reposition}{A \verb{<logical[1]>}. If \code{TRUE} (default) the \code{position} argument of this guide
will be propagated to the position scale bestowed upon the \code{plot} argument.
If \code{FALSE}, that position scale will retain its original \code{position} field.
Setting \code{reposition = TRUE} will generally tend to point axes outwards.}

\item{theme}{A \code{\link[ggplot2:theme]{<theme>}} object to style the guide individually or
differently from the plot's theme settings. The order in which themes are
applies is as follows: (1) the main plot's theme (2) the \code{plot} argument's
theme and (3) this \code{theme} argument. The default \code{theme} argument suppresses
legends.}

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

Displays an axis-sharing plot to the side of the panel.
}
\details{
This guide is subject to the following limitations:
\itemize{
\item The x- or y-scale of the main plot override the corresponding scale in the
\code{plot} argument. This ensures that the scales line up. The \code{plot} argument
should not have the relevant scale.
\item The \code{plot} argument cannot have custom facets. It must use the default
\code{facet_null()}.
\item This guide cannot be used in non-linear coordinate systems of the main plot
and does not support non-linear coordinate systems in the \code{plot} argument.
\item The \code{theme(panel.widths, panel.heights)} setting in the \code{plot} argument
will be ignored in favour of the \code{size} argument.
\item There is no mechanism to accommodate extra space needed by plot components
outside the panel. This applies in the horizontal direction for x-axes and
the vertical direction for y-axes. You may need to manually tweak the
\code{theme(plot.margin)} setting of the main plot to accommodate these
components.
}
\subsection{Styling options}{

This guide has no style options in \code{theme()} on itself. However, the
\code{plot} herein is subject to styling as described under the \code{theme} argument.
}
}
\examples{
# A standard plot
main_plot <- ggplot(mpg, aes(displ, hwy, colour = drv)) +
  geom_point()

# Simple plot sharing the x-variable
x_plot <- ggplot(mpg, aes(displ, fill = drv)) +
  geom_density(alpha = 0.7)

# Simple plot sharing the y-variable
y_plot <- ggplot(mpg, aes(drv, hwy, colour = drv)) +
  geom_boxplot()

# Typical use
main_plot + guides(
  x = guide_axis_plot(x_plot),
  y = guide_axis_plot(y_plot)
)

main_plot + guides(
  # Include `fill` legend by overriding theme
  x = guide_axis_plot(x_plot, theme = NULL),
  # Change the size of the side-plot
  y = guide_axis_plot(y_plot, size = unit(4, "cm"))
)

# Components outside panels may need to be manually acommodated
main_plot +
  guides(y = guide_axis_plot(y_plot + labs(title = "Boxplot"))) +
  theme(plot.margin = margin(25, 5.5, 5.5, 5.5))

# Recursive use of this guide
main_plot + guides(x = guide_axis_plot(
  main_plot + guides(x = guide_axis_plot(x_plot))
))
}
\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_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}
