% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/venndiagram.R
\name{VennDiagram}
\alias{VennDiagram}
\title{Venn / Euler diagram}
\usage{
VennDiagram(
  data,
  in_form = c("auto", "long", "wide", "list", "venn"),
  split_by = NULL,
  split_by_sep = "_",
  group_by = NULL,
  group_by_sep = "_",
  id_by = NULL,
  label = "count",
  label_fg = "black",
  label_size = NULL,
  label_bg = "white",
  label_bg_r = 0.1,
  fill_mode = "count",
  palreverse = FALSE,
  fill_name = NULL,
  palette = ifelse(fill_mode == "set", "Paired", "Blues"),
  palcolor = NULL,
  alpha = 1,
  theme = "theme_this",
  theme_args = list(),
  title = NULL,
  subtitle = NULL,
  legend.position = "right",
  legend.direction = "vertical",
  aspect.ratio = 1,
  combine = TRUE,
  nrow = NULL,
  ncol = NULL,
  byrow = TRUE,
  seed = 8525,
  axes = NULL,
  axis_titles = axes,
  guides = NULL,
  design = NULL,
  ...
)
}
\arguments{
\item{data}{A data frame.}

\item{in_form}{A character string specifying the input format.  One of
\code{"auto"} (default; detect automatically via
\code{\link{detect_venn_datatype}()}), \code{"long"}, \code{"wide"},
\code{"list"}, or \code{"venn"}.}

\item{split_by}{The column(s) to split the data by and produce separate
Venn diagrams per subgroup.  Only supported when \code{data} is a data
frame.  Multiple columns are concatenated with \code{split_by_sep}.}

\item{split_by_sep}{A character string to separate concatenated
\code{split_by} columns.  Default \code{"_"}.}

\item{group_by}{Columns to group the data for plotting
For those plotting functions that do not support multiple groups,
They will be concatenated into one column, using \code{group_by_sep} as the separator}

\item{group_by_sep}{The separator for multiple group_by columns. See \code{group_by}}

\item{id_by}{A character string specifying the column name that identifies
individual elements.  Required for long-format data; ignored otherwise.}

\item{label}{A character string or function controlling the text shown in
each intersection region.  One of:
\itemize{
\item \code{"count"} (default) — the raw count of elements in that region.
\item \code{"percent"} — the percentage of the total element count.
\item \code{"both"} — count and percentage on separate lines.
\item \code{"none"} — no region labels are drawn.
\item A \strong{function} — receives a data frame with columns
\code{"id"}, \code{"X"}, \code{"Y"}, \code{"name"}, \code{"item"},
and \code{"count"}, and must return a character vector of labels.
}}

\item{label_fg}{A character string specifying the colour of the label text.}

\item{label_size}{A numeric value specifying the font size of the label
text.  When \code{NULL} (the default), auto-sized at 3.5 for region labels
and 4 for set labels, scaled by \code{base_size / 12}.}

\item{label_bg}{A character string specifying the background colour of the
label text (passed to \code{\link[ggrepel]{geom_text_repel}()} as
\code{bg.color}).  Default \code{"white"}.}

\item{label_bg_r}{A numeric value specifying the corner radius of the label
background rectangle (passed as \code{bg.r}).  Default \code{0.1}.}

\item{fill_mode}{A character string specifying how intersection regions are
coloured.  One of:
\itemize{
\item \code{"count"} — continuous gradient based on element count
(default palette: \code{"Spectral"}).
\item \code{"count_rev"} — continuous gradient with reversed count order.
\item \code{"set"} — discrete blended colours per set combination
(default palette: \code{"Paired"}).  No legend is drawn.
}}

\item{palreverse}{A logical value indicating whether to reverse the palette. Default is FALSE.}

\item{fill_name}{A character string for the colour bar legend title when
\code{fill_mode} is \code{"count"} or \code{"count_rev"}.  Ignored when
\code{fill_mode = "set"}.}

\item{palette}{A character string specifying the palette to use.
A named list or vector can be used to specify the palettes for different \code{split_by} values.}

\item{palcolor}{A character string specifying the color to use in the palette.
A named list can be used to specify the colors for different \code{split_by} values.
If some values are missing, the values from the palette will be used (palcolor will be NULL for those values).}

\item{alpha}{A numeric value specifying the transparency of the plot.}

\item{theme}{A character string or a theme class (i.e. ggplot2::theme_classic) specifying the theme to use.
Default is "theme_this".}

\item{theme_args}{A list of arguments to pass to the theme function.}

\item{title}{A character string specifying the title of the plot.
A function can be used to generate the title based on the default title.
This is useful when split_by is used and the title needs to be dynamic.}

\item{subtitle}{A character string specifying the subtitle of the plot.}

\item{legend.position}{A character string specifying the position of the legend.
if \code{waiver()}, for single groups, the legend will be "none", otherwise "right".}

\item{legend.direction}{A character string specifying the direction of the legend.}

\item{aspect.ratio}{A numeric value specifying the aspect ratio of the plot.}

\item{combine}{Logical; when \code{TRUE} (default), returns a combined
\code{patchwork} object.  When \code{FALSE}, returns a named list of
individual \code{ggplot} objects.}

\item{ncol, nrow}{Integer number of columns / rows for the combined layout
when \code{combine = TRUE}.}

\item{byrow}{Logical; fill the combined layout by row (default \code{TRUE}).}

\item{seed}{A numeric seed for reproducibility.  Default \code{8525}.}

\item{axes, axis_titles}{Character strings specifying how axes and axis
titles are handled across the combined layout.}

\item{guides}{A character string specifying how legends are collected
across panels in the combined layout.}

\item{design}{A custom layout specification for the combined plot.
Passed to \code{\link[patchwork]{wrap_plots}()}.}

\item{...}{Additional arguments.}
}
\value{
A \code{ggplot} object (single split), a \code{patchwork} object
(combined sub-plots), or a named list of \code{ggplot} objects (when
\code{combine = FALSE}), each with \code{height} and \code{width}
attributes in inches.
}
\description{
Draws Venn or Euler diagrams that visualise the overlap relationships among
multiple sets.  Supports four input formats: long (one row per element-set
pair), wide (logical/0-1 columns per set), a named list (element vectors
per set), and a pre-computed \code{VennPlotData} object.

Intersection regions can be filled by a continuous colour gradient encoding
the element count (\code{fill_mode = "count"} / \code{"count_rev"}) or by
blended set colours (\code{fill_mode = "set"}).  Region labels can display
counts, percentages, both, or a custom function.  Set labels always show
the set name and its total element count.

Use \code{split_by} to produce separate Venn diagrams for each level of a
grouping variable.  Note that \code{split_by} is only supported when
\code{data} is a data frame (list and \code{VennPlotData} inputs cannot be
split).
}
\section{split_by Workflow}{

When a non-\code{NULL} \code{split_by} is provided and the input is a
data frame:
\enumerate{
\item \strong{Validation} — an error is raised if \code{data} is not a
data frame (list and \code{VennPlotData} input cannot be split).
\item \strong{Column resolution} — \code{split_by} is validated and
optionally concatenated via \code{\link{check_columns}()} with
\code{force_factor = TRUE} and \code{allow_multi = TRUE}.
\item \strong{Data splitting} — the data frame is split by the unique
levels of the \code{split_by} column, preserving factor level
order.  Empty levels are dropped via \code{droplevels()}.
\item \strong{Per-split colour and legend resolution} —
\code{\link{check_palette}()}, \code{\link{check_palcolor}()},
and \code{\link{check_legend}()} resolve per-split palettes,
custom colours, legend positions, and legend directions.
\item \strong{Atomic dispatch} — \code{\link{VennDiagramAtomic}()} is
called for each subset.  When \code{title} is a function, it
receives the split level name for dynamic title generation.
\item \strong{Combination} — results are passed to
\code{\link{combine_plots}()} which returns a combined
\code{patchwork} object (when \code{combine = TRUE}) or a named
list of individual ggplot objects (when \code{combine = FALSE}).
}
}

\examples{
\donttest{
set.seed(8525)
data <- list(
    A = sort(sample(letters, 8)),
    B = sort(sample(letters, 8)),
    C = sort(sample(letters, 8)),
    D = sort(sample(letters, 8))
)

# Basic Venn diagram with count labels
VennDiagram(data)

# Fill by set membership (blended colours)
VennDiagram(data, fill_mode = "set")

# Show both count and percentage
VennDiagram(data, label = "both")

# Custom label function using set names
VennDiagram(data, label = function(df) df$name)

# Custom palette and transparency
VennDiagram(data, palette = "material-indigo", alpha = 0.6)
}
}
