% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/venndiagram.R
\name{VennDiagramAtomic}
\alias{VennDiagramAtomic}
\title{Atomic Venn / Euler diagram (internal)}
\usage{
VennDiagramAtomic(
  data,
  in_form = "auto",
  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,
  aspect.ratio = 1,
  palette = ifelse(fill_mode == "set", "Paired", "Spectral"),
  palcolor = NULL,
  alpha = 1,
  theme = "theme_this",
  theme_args = list(),
  title = NULL,
  subtitle = NULL,
  legend.position = "right",
  legend.direction = "vertical",
  ...
)
}
\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{group_by}{A character string (or vector) specifying the column name(s)
that define the set membership.  For \code{in_form = "long"}, this is the
grouping column; for \code{in_form = "wide"}, these are the set columns
(must be logical or 0/1); when \code{NULL} and \code{data} is a data
frame, all columns are treated as sets (wide format).}

\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{aspect.ratio}{A numeric value specifying the aspect ratio of the plot.}

\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{...}{Additional arguments.}
}
\value{
A \code{ggplot} object with \code{height} and \code{width}
attributes (in inches) attached.
}
\description{
Core implementation for drawing a Venn or Euler diagram that visualises
the overlap relationships among multiple sets.  Supports four input formats
(long, wide, list, and pre-computed \code{VennPlotData}) which are
normalised by \code{\link{prepare_venn_data}()} into the internal
\code{VennPlotData} representation used by \pkg{ggVennDiagram}.

Intersection regions can be filled either by a continuous colour gradient
based on the element count (\code{fill_mode = "count"} or \code{"count_rev"})
or by blended set colours (\code{fill_mode = "set"}).  Region labels can
display the raw count, the percentage of total elements, both, nothing, or
a custom function result.  Set labels always show the set name and its
total element count.
}
\section{Architecture}{

\enumerate{
\item \strong{Data type detection} — \code{\link{detect_venn_datatype}()}
identifies whether \code{data} is in long, wide, list, or
\code{VennPlotData} format.
\item \strong{Data preparation} — \code{\link{prepare_venn_data}()}
converts the input into a \code{VennPlotData} object suitable for
rendering by \pkg{ggVennDiagram}.
\item \strong{Geometry extraction} — \pkg{ggVennDiagram} utilities
(\code{venn_regionedge()}, \code{venn_setedge()},
\code{venn_regionlabel()}, \code{venn_setlabel()}) compute polygon
vertices and label positions for all sets and their intersections.
\item \strong{Fill resolution} — When \code{fill_mode = "set"},
\code{\link{palette_this}()} assigns colours to each set; the
\code{blend_colors()} helper blends the colours of overlapping sets
for each intersection region.  When \code{fill_mode = "count"} or
\code{"count_rev"}, a continuous gradient is applied across regions
via \code{scale_fill_gradientn()} with a colour bar legend.
\item \strong{Label computation} — Region labels are formatted per the
\code{label} parameter: raw count, percentage, both, none, or a
custom function that receives a data frame with columns
\code{"id"}, \code{"X"}, \code{"Y"}, \code{"name"}, \code{"item"},
and \code{"count"}.  Set labels are formatted as
\code{"setName\\n(count)"}.
\item \strong{Plot assembly} — \code{geom_polygon()} draws filled
regions; \code{geom_path()} draws set outlines; two
\code{\link[ggrepel]{geom_text_repel}()} layers add region labels
and set labels.  For \code{fill_mode = "set"}, colours are mapped
directly (no aesthetic mapping, no legend); for count modes, a
\code{scale_fill_gradientn()} continuous scale is used.
\item \strong{Theme and coordinate system} — \code{coord_equal()}
enforces a square aspect ratio.  The theme removes all axis text,
ticks, titles, grid lines, and panel borders.  The x-axis
expansion is widened to accommodate set label text width.
\item \strong{Dimension calculation} —
\code{\link{calculate_plot_dimensions}()} computes \code{height}
and \code{width} attributes (in inches) from \code{base_height},
\code{aspect.ratio}, and legend metrics.  When
\code{fill_mode = "set"}, the legend position is forced to
\code{"none"}.
}
}

\keyword{internal}
