% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot.euler.R
\name{plot.euler}
\alias{plot.euler}
\alias{plot.eulerr_venn}
\alias{plot.venn}
\title{Plot Euler and Venn diagrams}
\usage{
\method{plot}{euler}(
  x,
  fills = TRUE,
  patterns = FALSE,
  edges = TRUE,
  legend = FALSE,
  labels = identical(legend, FALSE),
  quantities = FALSE,
  annotations = NULL,
  strips = NULL,
  bg = FALSE,
  main = NULL,
  complement = TRUE,
  rotate = 0,
  n = 200L,
  adjust_labels = TRUE,
  ...
)

\method{plot}{eulerr_venn}(
  x,
  fills = TRUE,
  patterns = FALSE,
  edges = TRUE,
  legend = FALSE,
  labels = identical(legend, FALSE),
  quantities = TRUE,
  strips = NULL,
  bg = FALSE,
  main = NULL,
  complement = TRUE,
  n = 200L,
  adjust_labels = TRUE,
  ...
)

\method{plot}{venn}(...)
}
\arguments{
\item{x}{an object of class \code{'euler'}, generated from \code{\link[=euler]{euler()}}}

\item{fills}{a logical, vector, or list of graphical parameters for the fills
in the diagram. Vectors are assumed to be colors for the fills.
See \code{\link[grid:grid.path]{grid::grid.path()}}. Named fill vectors can be matched in
\code{fills$mode = "disjoint"} (default) or \code{fills$mode = "union"}.}

\item{patterns}{a logical, vector, or list of graphical parameters for
fill patterns in the diagram. Vectors are assumed to be pattern types
(currently \code{"stripes"} or \code{NA}), where \code{NA} means no pattern.
Supported list items are \code{type}, \code{angle}, \code{col}, \code{lwd}, and \code{alpha}.
Named pattern vectors can be matched in
\code{patterns$mode = "disjoint"} (default) or \code{patterns$mode = "union"}.}

\item{edges}{a logical, vector, or list of graphical parameters for the edges
in the diagram. Vectors are assumed to be colors for the edges.
See \code{\link[grid:grid.lines]{grid::grid.polyline()}}.}

\item{legend}{a logical scalar or list. If a list, the item \code{side} can be
used to set the location of the legend and \code{symbol_size} can be used to scale
the legend symbols independently of the text size. See
\code{\link[grid:legendGrob]{grid::grid.legend()}}.}

\item{labels}{a logical, vector, or list. Vectors are assumed to be
text for the labels. See \code{\link[grid:grid.text]{grid::grid.text()}}. In addition to the
\code{grid::gpar()} fields, the following placement controls are
supported (delegated to the \code{eunoia} Rust crate):
\code{labels$placement} (\code{"raycast"} (default), \code{"force_directed"}, or
\code{"elbow"}) selects the strategy used when a label does not fit
inside its region. \code{"raycast"} and \code{"force_directed"} produce
straight leader lines (the former places the label along the
centroid→POI ray, the latter relaxes labels with a polygon-aware
force solver). \code{"elbow"} produces d3-pie style orthogonal leaders,
stacking exterior labels in left/right columns reached by a
three-segment polyline. \code{labels$margin} (numeric) overrides the
per-region margin between an exterior label and the diagram
(default is half the larger of the label's width and height);
\code{labels$tether} (\code{"poi"} (default) or \code{"boundary"}) chooses where
the leader line attaches on the source region; \code{labels$gap}
controls the visible gap between the leader tip and the label box
edge — a bare numeric is interpreted as \code{lines} (font-relative),
a \code{\link[grid:unit]{grid::unit()}} is honored as given, and the default \code{NULL}
tracks \code{eulerr_options()$padding} so the gap matches the spacing
between label and quantity; \code{labels$leader} is a list (\code{col},
\code{alpha}, \code{lwd}, \code{lty}, \code{lex}) styling the leader line drawn from
the tether to the exterior label. Strategy-specific knobs live in
their own sublists: \code{labels$force_directed = list(iterations = ...)}
sets the iteration cap for the force-directed solver, and
\code{labels$elbow = list(min_gap = ...)} sets the minimum vertical
centre-to-centre spacing between stacked label boxes in an elbow
column.}

\item{quantities}{a logical, vector, or list. Vectors are assumed to be
text for the quantities' labels, which by
default are the original values in the input to \code{\link[=euler]{euler()}}. In addition
to plain vectors, \code{quantities$labels} can also be a named vector keyed by
subset names (e.g., \code{"A"}, \code{"B"}, \code{"A&B"}), which is useful for supplying
custom text for overlap regions. If \code{quantities$labels} is \code{NULL},
\code{quantities$format} can be used to control number formatting as a list with
an item \code{fun} (a function such as \code{\link[=signif]{signif()}} or \code{\link[=round]{round()}}) and optional
extra arguments passed to that function (for example,
\code{list(fun = prettyNum, big.mark = ",")}). \code{quantities$total} can be used to
set an external
denominator for percent/fraction quantities (instead of the plotted total).
to arguments that apply to \code{\link[grid:grid.text]{grid::grid.text()}}, an argument \code{type} may
also be used which should be a combination of \code{"counts"}, \code{"percent"},
and \code{"fraction"}. The first item will be printed first and the second
will be printed thereafter inside brackets. The default is
\code{type = "counts"}.
For finer control over the rendered text, set \code{quantities$template} to
a string with \code{{counts}}, \code{{percent}}, and/or \code{{fraction}} placeholders,
for example \code{"{counts}\\n{percent}"} to put the count and percentage on
separate lines or \code{"n={counts} ({percent})"} for arbitrary layout. When
\code{template} is set it overrides \code{type}; the set of placeholders in the
template determines which values are computed.}

\item{annotations}{free-form per-region text rendered as a third
stacked element below the quantity (or below the label when no
quantity is drawn). Accepts a named character vector keyed by
subset name (e.g. \code{c(A = "n = 12", "A&B" = "n = 3")}) as a
shorthand for \verb{list(labels = <vector>)}, or a list with \code{labels}
plus \code{\link[grid:gpar]{grid::gpar()}} fields (\code{col}, \code{alpha}, \code{fontsize}, \code{cex},
\code{fontfamily}, \code{lineheight}, \code{font}, \code{rot}). Regions absent from
\code{labels} are not annotated. The composite tag bbox grows to
include the annotation, so exterior placement and leader lines
adapt automatically. Defaults to slightly smaller text than
\code{labels} / \code{quantities} (\code{cex = 0.8}).}

\item{strips}{a list, ignored unless the \code{'by'} argument
was used in \code{\link[=euler]{euler()}}. In addition to graphical parameters, this
argument can include \code{labels = list(top = ..., left = ...)} for custom
strip labels. Unnamed labels are interpreted in display order. Named
labels are matched by factor levels and then reordered to display order.}

\item{bg}{a logical, character, or list controlling the background grob.
Character values are interpreted as the background fill color.}

\item{main}{a title for the plot in the form of a
character, expression, list or something that can be
sensibly converted to a label via \code{\link[grDevices:as.graphicsAnnot]{grDevices::as.graphicsAnnot()}}. A
list of length one can be provided, in which case its only element
is used as the label. If a list of longer length is provided, an item
named \code{'label'} must be provided (and will be used for the actual text).}

\item{complement}{a logical, character, or list controlling the
container box and complement region for diagrams fit with
\verb{complement =} in \code{\link[=euler]{euler()}}. \code{TRUE} (default) draws the container
with a dashed outline (\code{lty = 2}), no fill, and the complement count
inside the complement region. \code{FALSE} suppresses the container and
its label entirely. A character value is treated as a fill color
shorthand. A list accepts \code{fill}, \code{alpha}, \code{col}, \code{lty}, \code{lwd},
\code{lex} (outline + label gpar), \code{fontsize}, \code{cex}, \code{font}, \code{fontfamily},
\code{lineheight} (label only), and \code{label} (custom text — defaults to the
complement count). Also accepts the same placement controls as
\code{labels} (\code{placement}, \code{margin}, \code{tether}, \code{gap}, \code{leader},
\code{force_directed}, \code{elbow})
for the complement count label. Has no effect if the diagram was
fit without \verb{complement =}. Defaults can be set via
\code{eulerr_options(complement = ...)}.}

\item{rotate}{a numeric value giving the angle in degrees by which to rotate
the entire diagram layout. Positive values rotate counter-clockwise.
Defaults to \code{0} (no rotation).}

\item{n}{number of vertices for the \code{edges} and \code{fills}}

\item{adjust_labels}{a logical. If \code{TRUE}, adjustment will be made to avoid
overlaps or out-of-limits plotting of labels, quantities, and
percentages.}

\item{...}{parameters to update \code{fills} and \code{edges} with and thereby a shortcut
to set these parameters
\code{\link[grid:grid.text]{grid::grid.text()}}.}
}
\value{
Provides an object of class \code{'eulergram'} , which is a
description of the diagram to be drawn. \code{\link[=plot.eulergram]{plot.eulergram()}} does the actual
drawing of the diagram.
}
\description{
Plot diagrams fit with \code{\link[=euler]{euler()}} and \code{\link[=venn]{venn()}} using \code{\link[grid:Grid]{grid::Grid()}} graphics.
This
function sets up all the necessary plot parameters and computes
the geometry of the diagram. \code{\link[=plot.eulergram]{plot.eulergram()}}, meanwhile,
does the actual plotting of the diagram. Please see the \strong{Details} section
to learn about the individual settings for each argument.
}
\details{
The only difference between \code{\link[=plot.euler]{plot.euler()}} and \code{\link[=plot.venn]{plot.venn()}} is that
\code{quantities} is set to \code{TRUE} by default in the latter and \code{FALSE} in
the former.

Most of the arguments to this function accept either a logical, a vector, or
a list where
\itemize{
\item logical values set the attribute on or off,
\item vectors are shortcuts to commonly used options (see the individual
parameters), and
\item lists enable fine-grained control, including graphical
parameters as described in \code{\link[grid:gpar]{grid::gpar()}} and control
arguments that are specific to each argument.
}

The various \code{\link[grid:gpar]{grid::gpar()}} values that are available for each argument
are:

\tabular{lcccccccc}{
\tab fills \tab edges \tab labels \tab quantities  \tab annotations \tab strips \tab legend \tab main \cr
col        \tab       \tab x     \tab x      \tab x           \tab x           \tab x      \tab x      \tab x    \cr
fill       \tab x     \tab       \tab        \tab             \tab             \tab        \tab        \tab      \cr
alpha      \tab x     \tab x     \tab x      \tab x           \tab x           \tab x      \tab x      \tab x    \cr
lty        \tab       \tab x     \tab        \tab             \tab             \tab        \tab        \tab      \cr
lwd        \tab       \tab x     \tab        \tab             \tab             \tab        \tab        \tab      \cr
lex        \tab       \tab x     \tab        \tab             \tab             \tab        \tab        \tab      \cr
fontsize   \tab       \tab       \tab x      \tab x           \tab x           \tab x      \tab x      \tab x    \cr
cex        \tab       \tab       \tab x      \tab x           \tab x           \tab x      \tab x      \tab x    \cr
fontfamily \tab       \tab       \tab x      \tab x           \tab x           \tab x      \tab x      \tab x    \cr
lineheight \tab       \tab       \tab x      \tab x           \tab x           \tab x      \tab x      \tab x    \cr
font       \tab       \tab       \tab x      \tab x           \tab x           \tab x      \tab x      \tab x    \cr
}

Defaults for these values, as well as other parameters of the plots, can
be set globally using \code{\link[=eulerr_options]{eulerr_options()}}.

If the diagram has been fit using the \code{data.frame} or \code{matrix} methods
and using the \code{by} argument, the plot area will be split into panels for
each combination of the one to two factors. The \code{fills}, \code{patterns}, \code{edges},
\code{labels}, \code{quantities}, and \code{annotations} arguments each accept an optional
\code{by_group} entry: a named list of override lists keyed by panel name (the
names of the fitted object). For multi-\code{by} fits the panel name is the
levels joined by \code{.}, e.g. \code{"Male.German"}. Panels not listed in \code{by_group}
use the top-level settings unchanged. Only graphical fields (and \code{rot} for
\code{labels}, \code{quantities}, and \code{annotations}) may be overridden per panel;
structural fields such as \code{quantities$type}, \code{quantities$format},
\code{annotations$labels}, or named-by-subset \code{fills$fill} must be set at the
top level.

For users who are looking to plot their diagram using another package,
all the necessary parameters can be collected if the result of this
function is assigned to a variable (rather than printed to screen).
}
\examples{
fit <- euler(c("A" = 10, "B" = 5, "A&B" = 3))

# Customize colors, remove borders, bump alpha, color labels white
plot(fit,
     fills = list(fill = c("red", "steelblue4"), alpha = 0.5),
     labels = list(col = "white", font = 4))

# Add quantities to the plot
plot(fit, quantities = TRUE)

# Add free-form per-region annotations below the counts
plot(
  fit,
  quantities = TRUE,
  annotations = c(A = "mean = 35", "A&B" = "mean = 41")
)

# Add a custom legend and retain quantities
plot(fit, quantities = TRUE, legend = list(labels = c("foo", "bar")))

# Plot without fills and distinguish sets with border types instead
plot(fit, fills = "transparent", lty = 1:2)

# Save plot parameters to plot using some other method
diagram_description <- plot(fit)

# Plots using 'by' argument
plot(euler(fruits[, 1:4], by = list(sex)), legend = TRUE)

# Per-panel styling with `by_group`
plot(
  venn(fruits[, 1:4], by = list(sex)),
  quantities = list(
    by_group = list(
      male = list(col = "steelblue"),
      female = list(col = "tomato")
    )
  )
)
}
\seealso{
\code{\link[=euler]{euler()}}, \code{\link[=plot.eulergram]{plot.eulergram()}}, \code{\link[grid:gpar]{grid::gpar()}},
\code{\link[grid:grid.lines]{grid::grid.polyline()}}, \code{\link[grid:grid.path]{grid::grid.path()}},
\code{\link[grid:legendGrob]{grid::grid.legend()}}, \code{\link[grid:grid.text]{grid::grid.text()}}
}
