% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/upsetplot.R
\name{UpsetPlot}
\alias{UpsetPlot}
\title{UpSet Plot}
\usage{
UpsetPlot(
  data,
  in_form = c("auto", "long", "wide", "list", "upset"),
  split_by = NULL,
  split_by_sep = "_",
  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 = "Blues",
  palcolor = NULL,
  palreverse = FALSE,
  alpha = 1,
  specific = TRUE,
  theme = "theme_this",
  theme_args = list(),
  title = NULL,
  subtitle = NULL,
  xlab = NULL,
  ylab = NULL,
  aspect.ratio = 0.6,
  legend.position = "right",
  legend.direction = "vertical",
  combine = TRUE,
  nrow = NULL,
  ncol = NULL,
  byrow = TRUE,
  seed = 8525,
  combmatrix_gap = 6,
  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 from \code{data} structure),
\code{"long"}, \code{"wide"}, \code{"list"}, or \code{"upset"}.}

\item{split_by}{The column(s) to split the data by and produce separate
sub-plots.  Only supported for \code{data.frame} input (list input raises
an error).  Multiple columns 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 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{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{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
(passed to \code{\link[patchwork]{wrap_plots}}).}

\item{byrow}{Logical; fill the combined layout by row.  Default \code{TRUE}
(passed to \code{\link[patchwork]{wrap_plots}}).}

\item{seed}{A numeric seed for reproducibility.  Passed to
\code{\link{validate_common_args}()}.  Default: \code{8525}.}

\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{axes}{A character string specifying how axes should be treated across
the combined layout (passed to \code{\link[patchwork]{wrap_plots}}).}

\item{axis_titles}{A character string specifying how axis titles should be
treated across the combined layout.  Defaults to \code{axes}.}

\item{guides}{A character string specifying how legends should be collected
across panels (passed to \code{\link{combine_plots}()}).}

\item{design}{A custom layout design for the combined plot (passed to
\code{\link{combine_plots}()}).}

\item{...}{Additional arguments.}
}
\value{
A \code{ggplot} object, a \code{patchwork} object, or a named list
of \code{ggplot} objects (when \code{combine = FALSE}), each with
\code{height} and \code{width} attributes in inches.
}
\description{
Draws an UpSet plot visualising set intersections and set sizes.  The plot
comprises:
\itemize{
\item A \strong{horizontal bar chart} showing the size of each
intersection, filled by the intersection count.
\item A \strong{combination matrix} (rows = sets, columns = intersections)
with membership dots and connecting lines.
\item A \strong{set-size bar chart} on the left of the matrix (added
automatically by \code{ggupset}).
}

The function accepts data in four formats:
\itemize{
\item \strong{List} --- a named list of element vectors (one per set).
\item \strong{Long} --- a data frame with one row per (set, element) pair.
\item \strong{Wide} --- a data frame where each row is an element and each
set has its own logical or 0/1 membership column.
\item \strong{UpsetPlotData} --- a pre-processed object from
\code{\link{prepare_upset_data}()}.
}

Supports splitting into sub-plots via \code{split_by}, per-split colour
palettes and legend control, and combining sub-plots via \code{patchwork}.
}
\section{split_by Workflow}{

When \code{split_by} is provided:
\enumerate{
\item \strong{Guard} --- \code{split_by} is only supported for
\code{data.frame} input.  If \code{data} is a list (or other
non-data.frame type) and \code{split_by} is non-\code{NULL}, an
error is raised.
\item \strong{Column validation} --- \code{\link{check_columns}()} resolves
the \code{split_by} column(s) with \code{force_factor = TRUE} and
\code{allow_multi = TRUE}.  Multiple columns are concatenated with
\code{split_by_sep}.
\item \strong{Data splitting} --- empty factor levels in \code{split_by}
are dropped via \code{\link[base]{droplevels}()}, then the data
frame is split by \code{split_by} (level order is preserved).  If
\code{split_by} is \code{NULL}, the data is wrapped in a
single-element list with name \code{"..."}.
\item \strong{Per-split resolution} --- \code{\link{check_palette}()},
\code{\link{check_palcolor}()}, and \code{\link{check_legend}()}
resolve per-split \code{palette}, \code{palcolor},
\code{legend.position}, and \code{legend.direction}.
\item \strong{Atomic dispatch} --- \code{UpsetPlotAtomic} is called for
each split.  If \code{title} is a function, it receives the split
level name and can generate dynamic titles.  When in wide mode
(\code{in_form} is \code{"auto"} or \code{"wide"}) and
\code{group_by} is \code{NULL}, the set columns are auto-detected
as all columns except \code{id_by} and \code{split_by}.
\item \strong{Combination} --- Results are combined via
\code{\link{combine_plots}()} (when \code{combine = TRUE}) or
returned as a named list.
}
}

\examples{
\donttest{
# ---- list input -------------------------------------------------------
data <- list(
    A = 1:5,
    B = 2:6,
    C = 3:7,
    D = 4:8
)
UpsetPlot(data)
UpsetPlot(data, label = FALSE)
UpsetPlot(data, palette = "Reds", specific = FALSE)

# ---- long-format data frame ------------------------------------------
data_long <- data.frame(
    group_by = factor(
         c(rep("A", 5), rep("B", 5), rep("C", 5), rep("D", 5)),
         levels = c("A", "B", "C", "D")
    ),
    id_by = c(1:5, 2:6, 3:7, 4:8)
)
UpsetPlot(data_long, in_form = "long", group_by = "group_by", id_by = "id_by")

# ---- wide-format data frame ------------------------------------------
data <- data.frame(
    id = LETTERS[1:10],
    B = c(1, 0, 1, 1, 0, 0, 1, 0, 1, 0),
    A = c(1, 1, 1, 0, 0, 1, 0, 0, 1, 0),
    D = c(1, 0, 0, 1, 1, 0, 0, 1, 0, 1),
    C = c(0, 1, 1, 0, 1, 0, 1, 0, 1, 0)
)
UpsetPlot(data, in_form = "wide", id_by = "id", n_intersections = 4)
}
}
