% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/upsetplot.R
\name{UpsetPlotAtomic}
\alias{UpsetPlotAtomic}
\title{Atomic UpSet plot (internal)}
\usage{
UpsetPlotAtomic(
  data,
  in_form = "auto",
  group_by = NULL,
  group_by_sep = "_",
  id_by = NULL,
  label = TRUE,
  label_fg = "black",
  label_size = NULL,
  label_bg = "white",
  label_bg_r = 0.1,
  palette = "material-indigo",
  palcolor = NULL,
  palreverse = FALSE,
  alpha = 1,
  specific = TRUE,
  combmatrix_gap = 6,
  theme = "theme_this",
  theme_args = list(),
  title = NULL,
  subtitle = NULL,
  xlab = NULL,
  ylab = NULL,
  aspect.ratio = 0.6,
  legend.position = "right",
  legend.direction = "vertical",
  levels = NULL,
  ...
)
}
\arguments{
\item{data}{A data frame.}

\item{in_form}{A character string specifying the input format.  One of
\code{"auto"} (default; detect from \code{data} structure),
\code{"long"}, \code{"wide"}, \code{"list"}, or \code{"upset"}.}

\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 for instance
identifiers.  Required for long format; optional for wide format (a
synthetic \code{.id} column is created if omitted).}

\item{label}{A logical value.  When \code{TRUE} (default), count labels are
displayed above each intersection bar via \code{\link[ggrepel]{geom_text_repel}()}.}

\item{label_fg}{A character string specifying the colour of the label text.
Default: \code{"black"}.}

\item{label_size}{A numeric value specifying the size of the label text.
Default: \code{NULL} (computed from \code{base_size / 12 * 3.5}).}

\item{label_bg}{A character string specifying the background fill colour of
the label.  Default: \code{"white"}.}

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

\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{palreverse}{A logical value indicating whether to reverse the palette. Default is FALSE.}

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

\item{specific}{A logical value.  When \code{TRUE} (default), only specific
intersections are returned (elements belonging exclusively to the shown
set combination).  When \code{FALSE}, all overlapping items are included.
See \url{https://github.com/gaospecial/ggVennDiagram/issues/64}.}

\item{combmatrix_gap}{A numeric value specifying the gap between rows of the
combination matrix, measured at \code{base_size = 12}.  The actual gap is
scaled by \code{text_size_scale = base_size / 12}.  Default: \code{6}.}

\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{xlab}{A character string specifying the x-axis label.}

\item{ylab}{A character string specifying the y-axis label.}

\item{aspect.ratio}{A numeric value specifying the aspect ratio 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{levels}{A character vector of set levels to include, in display order.
When \code{NULL} (default), all detected sets are shown.  Accepted for
compatibility but not currently used by the internal implementation.}

\item{...}{Additional arguments passed to \code{\link[ggupset]{scale_x_upset}}.
Useful options include \code{n_sets} and \code{n_intersections} to limit
the number of shown sets / intersections.}
}
\value{
A \code{ggplot} object with \code{height} and \code{width} attributes
(in inches).
}
\description{
Core implementation for drawing a single UpSet plot.  This is the internal
workhorse behind the exported \code{\link{UpsetPlot}} function --- it takes a
\strong{single} data partition (no \code{split_by} support) and returns a
\code{ggplot} object.  The plot comprises three visual components:
\itemize{
\item A \strong{horizontal bar chart} (top) showing the size of each
intersection, with bars filled by a gradient of intersection count.
\item A \strong{set-size bar chart} (left) showing the total number of
elements in each set (added automatically by \code{ggupset}).
\item A \strong{combination matrix} (bottom) where rows are sets, columns
are intersections, and dots indicate set membership.  Connected dots
trace the intersection pattern.
}
}
\section{Architecture}{

\enumerate{
\item \strong{ggplot dispatch} --- selects \code{gglogger::ggplot} or
\code{ggplot2::ggplot} based on
\code{getOption("plotthis.gglogger.enabled")}.
\item \strong{Data preparation} --- \code{\link{prepare_upset_data}()}
converts the input into the internal \code{UpsetPlotData} format
with an \code{Intersection} list-column (set-membership labels per
element) and a \code{"group_order"} attribute for set ordering.
\item \strong{Text scale} --- \code{base_size} from \code{theme_args}
(default 12) drives a \code{text_size_scale} that proportionally
scales the combination-matrix row gap, label sizes, and point sizes.
\item \strong{Bar geom} --- \code{geom_bar()} counts rows per intersection.
Bars are filled by count via \code{scale_fill_gradientn()} with
colours from \code{\link{palette_this}()}.
\item \strong{Bar labels} --- when \code{label = TRUE},
\code{\link[ggrepel]{geom_text_repel}()} places count labels above
each bar, with configurable foreground, background, and size.
\item \strong{Scale x upset} --- \code{ggupset::scale_x_upset(...)} is
called, returning two components: a \code{ScaleUpset} (index \code{[[1]]})
and a \code{CoordCombMatrix} (index \code{[[2]]}).  Only the scale is
applied; the bundled coord is discarded to avoid a "Coordinate
system already present" conflict.
\item \strong{Labels and theme} --- \code{labs()} sets title, subtitle,
and axis text.  \code{do_call(theme, theme_args)} applies the chosen
theme.  Aspect ratio, legend position, legend direction, and grid
lines are configured.
\item \strong{Combination matrix} --- \code{ggupset::axis_combmatrix()}
builds the lower panel via an \code{override_plotting_function}:
\itemize{
\item Reorders rows to match \code{group_order} (reversed for
top-to-bottom set listing).
\item Alternating row backgrounds via \code{geom_rect()} with
white / \code{#F7F7F7} fills.
\item Set-membership dots (\code{geom_point()}) in black for
present and \code{#E0E0E0} for absent.
\item Connecting lines (\code{geom_line()}) through observed
dots to trace the intersection pattern.
}
\item \strong{Matrix theme} --- \code{ggupset::theme_combmatrix()}
applies the combination-matrix appearance with
\code{combmatrix_gap} between rows (scaled by
\code{text_size_scale}).
\item \strong{Dimension calculation} ---
\code{\link{calculate_plot_dimensions}()} computes height from
\code{n_sets} and width from \code{n_intersections}, both passed
via \code{...} (default 99).  \code{aspect.ratio} is used as a
standard H/W coupling with \code{x_scale_factor = 0.6}.  An
additional width adjustment accounts for set-label character width.
}
}

\keyword{internal}
