% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/barplot.R
\name{SplitBarPlotAtomic}
\alias{SplitBarPlotAtomic}
\title{Atomic split bar plot (internal)}
\usage{
SplitBarPlotAtomic(
  data,
  x,
  y,
  y_sep = "_",
  flip = FALSE,
  alpha_by = NULL,
  alpha_reverse = FALSE,
  alpha_name = NULL,
  order_y = list(`+` = c("x_desc", "alpha_desc"), `-` = c("x_desc", "alpha_asc")),
  bar_height = 0.9,
  lineheight = 0.5,
  max_charwidth = 80,
  fill_by = NULL,
  fill_by_sep = "_",
  fill_name = NULL,
  direction_name = "direction",
  direction_pos_name = "positive",
  direction_neg_name = "negative",
  theme = "theme_this",
  theme_args = list(),
  palette = "Spectral",
  palcolor = NULL,
  palreverse = FALSE,
  lower_quantile = 0,
  upper_quantile = 0.99,
  lower_cutoff = NULL,
  upper_cutoff = NULL,
  facet_by = NULL,
  facet_scales = "free_y",
  facet_nrow = NULL,
  facet_ncol = NULL,
  facet_byrow = TRUE,
  aspect.ratio = 1,
  x_min = NULL,
  x_max = NULL,
  legend.position = "right",
  legend.direction = "vertical",
  title = NULL,
  subtitle = NULL,
  xlab = NULL,
  ylab = NULL,
  keep_empty = FALSE,
  keep_na = FALSE,
  ...
)
}
\arguments{
\item{data}{A data frame.}

\item{x}{A character string specifying the numeric column for the
x-axis.  Values determine bar direction: positive → right, negative →
left.}

\item{y}{A character string (or vector) specifying the column(s) for the
category axis.  Each unique value becomes a bar.  Multiple columns are
concatenated with \code{y_sep}.}

\item{y_sep}{A character string to join multiple \code{y} columns.
Default \code{"_"}.}

\item{flip}{Logical; if \code{TRUE}, swap the x and y axes (bars become
vertical rather than horizontal).}

\item{alpha_by}{A character string naming a numeric column to encode as
bar opacity.  Default \code{NULL} (all bars fully opaque).}

\item{alpha_reverse}{Logical; if \code{TRUE}, reverse the alpha scale
direction (solid for low values, transparent for high).}

\item{alpha_name}{A character string for the alpha legend title.}

\item{order_y}{A named list controlling the vertical ordering of bars.
Keys are \code{"+"} (positive bars), \code{"-"} (negative bars), or
\code{"*"} (all bars).  Values are character vectors of ordering
criteria: \code{"x_asc"}, \code{"x_desc"}, \code{"alpha_asc"},
\code{"alpha_desc"}.  Default orders positive bars by descending x and
descending alpha; negative bars by descending x and ascending alpha.}

\item{bar_height}{A numeric value (0–1) specifying the bar height as a
fraction of the available category slot.}

\item{lineheight}{A numeric value controlling the line height of wrapped
category labels.}

\item{max_charwidth}{An integer specifying the maximum character width
for wrapping category labels.}

\item{fill_by}{A character string (or vector) naming the column(s) for
bar fill colour.  If \code{NULL}, the direction (positive/negative) is
used.  Can be categorical or numeric.}

\item{fill_by_sep}{A character string to join multiple \code{fill_by}
columns.  Default \code{"_"}.}

\item{fill_name}{A character string for the fill legend title.}

\item{direction_name}{A character string naming the internal direction
column (used in legends).  Default \code{"direction"}.}

\item{direction_pos_name}{A character string labelling the positive
direction in the legend.  Default \code{"positive"}.}

\item{direction_neg_name}{A character string labelling the negative
direction in the legend.  Default \code{"negative"}.}

\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{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{lower_quantile, upper_quantile}{Lower and upper quantiles for the continuous color/fill scale.
The actual cutoffs are determined by these quantiles when \code{lower_cutoff} and
\code{upper_cutoff} are \code{NULL}. Defaults: \code{lower_quantile = 0}, \code{upper_quantile = 0.99}.}

\item{lower_cutoff, upper_cutoff}{Explicit lower and upper cutoffs for the continuous color/fill scale.
When \code{NULL} (the default), the cutoffs are determined by \code{lower_quantile} and
\code{upper_quantile} via \code{\link[stats]{quantile}}. Values outside the
\code{[lower_cutoff, upper_cutoff]} range are clamped (winsorized) to the nearest cutoff value.}

\item{facet_by}{A character string specifying the column name of the data frame to facet the plot.
Otherwise, the data will be split by \code{split_by} and generate multiple plots
and combine them into one using \code{patchwork::wrap_plots}}

\item{facet_scales}{Whether to scale the axes of facets. Default is "fixed"
Other options are "free", "free_x", "free_y". See \code{ggplot2::facet_wrap}}

\item{facet_nrow}{A numeric value specifying the number of rows in the facet.
When facet_by is a single column and facet_wrap is used.}

\item{facet_ncol}{A numeric value specifying the number of columns in the facet.
When facet_by is a single column and facet_wrap is used.}

\item{facet_byrow}{A logical value indicating whether to fill the plots by row. Default is TRUE.}

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

\item{x_min, x_max}{Numeric limits for the x-axis.  When \code{NULL},
symmetric limits are computed from the maximum absolute x-value.}

\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{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{keep_empty}{One of FALSE, TRUE and "level". It can also take a named list to specify
different behavior for different columns. Without a named list, the behavior applies to the
categorical/character columns used on the plot, for example, the \code{x}, \code{group_by}, \code{fill_by}, etc.
\itemize{
\item{\code{FALSE} (default): Drop empty factor levels from the data before plotting.}
\item{\code{TRUE}: Keep empty factor levels and show them as a separate category in the plot.}
\item{\code{"level"}: Keep empty factor levels, but do not show them in the plot.
But they will be assigned colors from the palette to maintain consistency across multiple plots.
Alias: \code{levels}}
}}

\item{keep_na}{A logical value or a character to replace the NA values in the data.
It can also take a named list to specify different behavior for different columns.
If TRUE or NA, NA values will be replaced with NA.
If FALSE, NA values will be removed from the data before plotting.
If a character string is provided, NA values will be replaced with the provided string.
If a named vector/list is provided, the names should be the column names to apply the behavior to,
and the values should be one of TRUE, FALSE, or a character string.
Without a named vector/list, the behavior applies to categorical/character columns used on the plot,
for example, the \code{x}, \code{group_by}, \code{fill_by}, etc.}

\item{...}{Additional arguments.}
}
\value{
A \code{ggplot} object, possibly faceted, with \code{height}
and \code{width} attributes (in inches) attached.
}
\description{
Core implementation for drawing a split (divergent / waterfall-style) bar
plot.  Bars extend left (negative values) and right (positive values) from
a central zero line, with the y-axis listing categories.  Bars can be
coloured by a categorical or continuous fill variable, and their opacity
can encode an additional numeric variable via \code{alpha_by}.

This is the workhorse behind the exported \code{\link{SplitBarPlot}}
(also aliased as \code{\link{WaterfallPlot}}).
}
\section{Architecture}{

\enumerate{
\item \strong{Column resolution} — \code{x}, \code{y}, \code{fill_by},
\code{alpha_by}, and \code{facet_by} are validated via
\code{\link{check_columns}}.  Multi-column \code{y} and
\code{fill_by} are concatenated with their respective separators.
\item \strong{Direction assignment} — a \code{direction_name} column
is created from the sign of \code{x}, assigning each row to the
positive or negative group (customisable via
\code{direction_pos_name} / \code{direction_neg_name}).
\item \strong{Fill resolution} — if \code{fill_by} is \code{NULL},
the direction column is used as the fill (two-colour palette).
Categorical fills use a discrete colour scale; numeric fills use
\code{\link{prepare_continuous_color_scale}()} with quantile /
cutoff clamping and \code{scale_fill_gradientn()}.
\item \strong{Alpha by} — when \code{alpha_by} is provided, bar
opacity encodes an additional numeric variable via
\code{scale_alpha_continuous()}.
\item \strong{Ordering} — \code{order_y} is a named list controlling
the vertical ordering of bars.  The keys \code{"+"} and \code{"-"}
specify separate orderings for positive and negative bars; key
\code{"*"} applies a single ordering to all bars.  Values are
character vectors of ordering criteria: \code{"x_asc"},
\code{"x_desc"}, \code{"alpha_asc"}, \code{"alpha_desc"}.
\item \strong{Empty level padding} — when \code{keep_empty_y = TRUE},
missing y-levels are padded per facet (or globally) with
zero-height bars so they still appear on the axis.
\item \strong{Text labels} — category names are drawn beside the bars
via \code{geom_text()} at the zero line.  When flipped, labels are
rotated 90°.  Long labels are wrapped via
\code{\link[stringr]{str_wrap}()} using \code{max_charwidth}.
\item \strong{Plot assembly} — the ggplot is built with
\code{geom_vline(xintercept = 0)} for the centre line,
\code{geom_col()} for bars, and the appropriate fill / alpha
scales.
\item \strong{Dimension calculation} — \code{calculate_plot_dimensions()}
computes dimensions from the number of y categories, scaled by
\code{bar_height / 4}.  Flipping adjusts the aspect ratio.
\item \strong{Faceting} — \code{\link{facet_plot}()} wraps the result,
defaulting to \code{facet_scales = "free_y"}.
}
}

\keyword{internal}
