% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dotplot.R
\name{DotPlotAtomic}
\alias{DotPlotAtomic}
\title{Atomic dot/lollipop plot}
\usage{
DotPlotAtomic(
  data,
  x,
  y,
  x_sep = "_",
  y_sep = "_",
  flip = FALSE,
  lollipop = FALSE,
  size_by = NULL,
  fill_by = NULL,
  fill_cutoff = NULL,
  palreverse = FALSE,
  size_name = NULL,
  fill_name = NULL,
  fill_cutoff_name = NULL,
  size_min = 1,
  size_max = 10,
  theme = "theme_this",
  theme_args = list(),
  palette = "Spectral",
  palcolor = NULL,
  alpha = 1,
  border_color = "black",
  border_size = 0.5,
  border_alpha = 1,
  lower_quantile = 0,
  upper_quantile = 0.99,
  lower_cutoff = NULL,
  upper_cutoff = NULL,
  facet_by = NULL,
  facet_scales = "fixed",
  facet_ncol = NULL,
  facet_nrow = NULL,
  facet_byrow = TRUE,
  x_text_angle = 0,
  aspect.ratio = 1,
  legend.position = "right",
  legend.direction = "vertical",
  add_bg = FALSE,
  bg_palette = "stripe",
  bg_palcolor = NULL,
  bg_alpha = 0.2,
  bg_direction = c("vertical", "horizontal", "v", "h"),
  title = NULL,
  subtitle = NULL,
  xlab = NULL,
  ylab = NULL,
  keep_na = FALSE,
  keep_empty = FALSE,
  ...
)
}
\arguments{
\item{data}{A data frame.}

\item{x}{A character vector specifying the column(s) to use for the x-axis.
Can be numeric (for scatter/lollipop mode) or factor/character (for dot
matrix mode). When multiple columns are provided for a non-numeric axis,
they are concatenated with \code{x_sep} as the separator.}

\item{y}{A character vector specifying the column(s) to use for the y-axis.
Can be numeric (for scatter mode) or factor/character (for dot matrix or
lollipop mode). When multiple columns are provided for a non-numeric axis,
they are concatenated with \code{y_sep} as the separator.}

\item{x_sep}{A character string used to join multiple \code{x} column values
into a single factor level. Only used when x is non-numeric and multiple
columns are provided. Default: \code{"_"}.}

\item{y_sep}{A character string used to join multiple \code{y} column values
into a single factor level. Only used when y is non-numeric and multiple
columns are provided. Default: \code{"_"}.}

\item{flip}{A logical value. If \code{TRUE}, the x and y axes are swapped via
\code{coord_flip()}. Dimension calculation accounts for the flip.
Default: \code{FALSE}.}

\item{lollipop}{A logical value. If \code{TRUE}, renders a lollipop plot
with bars extending from x = 0 to each data point, capped by filled dots.
Requires \code{x} to be numeric and \code{y} to be factor/character.
Default: \code{FALSE}.}

\item{size_by}{A character string naming a numeric column whose values
control dot size. When \code{NULL} (the default), the per-combination
observation count is computed automatically (via \code{dplyr::summarise(n =
  n())}) and used as the size variable. If \code{fill_by} is also present,
the first value of \code{fill_by} per combination is retained with a
warning. A single numeric value is also accepted and sets a constant dot
size (used by \code{ScatterPlot}).}

\item{fill_by}{A character string naming a numeric column whose values
control the fill colour of the dots (and lollipop inner bars). A
continuous gradient from \code{palette} is applied via
\code{scale_fill_gradientn()}. When \code{NULL} (the default), all dots
are filled with a single constant colour from the middle of the palette.}

\item{fill_cutoff}{A string expression specifying which values of
\code{fill_by} to grey out. Format: an operator followed by a number,
e.g. \code{"< 18"}, \code{"<= 18"}, \code{"> 18"}, or \code{">= 18"}.
Values matching the condition are set to \code{NA} and rendered in grey
(\code{"grey80"}), while the rest are coloured by the fill gradient. The
operator determines which side of the threshold is greyed out,
independent of \code{palreverse}. A numeric value is also accepted as
shorthand for \code{"<"} (e.g. \code{18} is equivalent to
\code{"< 18"}). Requires \code{fill_by} to be set.}

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

\item{size_name}{A character string for the size legend title. When
\code{NULL} (the default), the \code{size_by} column name is used.}

\item{fill_name}{A character string for the fill colour-bar legend title.
When \code{NULL} (the default), the \code{fill_by} column name is used.}

\item{fill_cutoff_name}{A character string for the fill cutoff legend title
(shown when \code{fill_cutoff} is active). Defaults to
\code{"<fill_by> <fill_cutoff>"}, e.g. \code{"mpg < 18"}.}

\item{size_min}{A numeric value for the smallest dot size in the
\code{scale_size(range = c(size_min, size_max))} range.
Default: \code{1}.}

\item{size_max}{A numeric value for the largest dot size in the
\code{scale_size(range = c(size_min, size_max))} range.
Default: \code{10}.}

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

\item{border_color}{Controls the dot border colour and lollipop outer-shadow
appearance:
\itemize{
\item \code{TRUE} — dot borders and lollipop inner bars follow the
\code{fill_by} gradient via \code{scale_color_gradientn()}; lollipop
outer shadow is black.
\item \code{"black"} (default) — constant black borders on dots and
black outer shadow on lollipop bars.
\item A colour string (e.g. \code{"red"}, \code{"#FF0000"}) — constant
colour for both dot borders and lollipop outer shadows.
\item \code{FALSE} — no dot borders and no lollipop outer shadow (the
inner coloured bars remain visible in lollipop mode).
}}

\item{border_size}{A numeric value for the stroke width of dot borders and
the base linewidth of lollipop bars. In lollipop mode, the outer shadow
uses \code{border_size * 4} and the inner bar uses \code{border_size * 2}.
Default: \code{0.5}.}

\item{border_alpha}{A numeric value in \code{[0, 1]} controlling the
transparency of dot borders and lollipop bar segments.
Default: \code{1}.}

\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_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_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_byrow}{A logical value indicating whether to fill the plots by row. Default is TRUE.}

\item{x_text_angle}{A numeric value specifying the angle of the x-axis text.}

\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{add_bg}{A logical value. If \code{TRUE}, alternating background
stripes are drawn behind the points via \code{\link{bg_layer}()}. The
striped axis is determined by \code{bg_direction}. Requires the striped
axis to be non-numeric. Default: \code{FALSE}.}

\item{bg_palette}{A character string specifying the palette for the
background stripe colours. Passed to \code{\link{bg_layer}()}.
Default: \code{"stripe"}.}

\item{bg_palcolor}{A character vector of colours for the background stripes.
Passed to \code{\link{bg_layer}()}. When \code{NULL} (default), colours
are derived from \code{bg_palette}.}

\item{bg_alpha}{A numeric value in \code{[0, 1]} for the transparency of
the background stripes. Default: \code{0.2}.}

\item{bg_direction}{A character string specifying which axis receives the
alternating background stripes. \code{"vertical"} (default) stripes by x
levels; \code{"horizontal"} stripes by y levels. Abbreviations \code{"v"}
and \code{"h"} are also accepted.}

\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_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{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{...}{Additional arguments.}
}
\value{
A \code{ggplot} object with \code{height} and \code{width}
attributes.
}
\description{
Core implementation for dot plots and lollipop plots. This is the internal
workhorse dispatched by both \code{DotPlot()} and \code{LollipopPlot()}. It
renders a matrix of points where dot size encodes one variable and dot fill
colour encodes another, with optional background stripes and a lollipop
(bar + dot) display mode.
}
\details{
The function supports two display modes:
\itemize{
\item \strong{Dot plot} (\code{lollipop = FALSE}, the default) — renders
\code{ggplot2::geom_point()} with \code{shape = 21} (filled circle). Either
or both axes can be numeric (producing a scatter plot) or factor (producing
a dot matrix). Dot size scales by \code{size_by} (or the per-combination
observation count when \code{size_by} is \code{NULL}) via
\code{scale_size(range = c(size_min, size_max))}. Dot fill follows the
\code{fill_by} column via \code{scale_fill_gradientn()}.
\item \strong{Lollipop plot} (\code{lollipop = TRUE}) — expects a numeric
\code{x} and a factor/character \code{y}. Renders a two-layer bar:
an outer shadow segment followed by an inner coloured segment, each capped
by a filled dot. The outer shadow is black (or a custom colour when
\code{border_color} is a string), and the inner segment + dot fill follow
\code{fill_by}.
}

When \code{add_bg = TRUE}, alternating background stripes are drawn via
\code{\link{bg_layer}()} along the discrete axis (vertical stripes for
factor \code{x}, horizontal stripes for factor \code{y}). The fill colour
scale is prepared via \code{\link{prepare_continuous_color_scale}()} and
can be trimmed with \code{lower_quantile}/\code{upper_quantile} or
\code{lower_cutoff}/\code{upper_cutoff}.

When \code{fill_cutoff} is set (e.g. \code{"< 18"}), values of
\code{fill_by} matching the condition are set to \code{NA} and rendered in
grey ("grey80"), with a separate legend entry documenting the cutoff.

\strong{Border colour modes:}
\itemize{
\item \code{border_color = TRUE} — dot borders and lollipop inner bar
colour track the \code{fill_by} gradient via
\code{scale_color_gradientn()}; lollipop outer shadow is black.
\item \code{border_color = "black"} (default) — constant black borders on
dots and a black outer shadow on lollipop bars.
\item \code{border_color = FALSE} — no dot borders, no lollipop outer
shadow (the inner coloured segment remains).
}
}
\section{Architecture}{


\strong{DotPlotAtomic} executes the following steps:
\enumerate{
\item \strong{ggplot dispatch} — selects \code{gglogger::ggplot} or
\code{ggplot2::ggplot} based on
\code{getOption("plotthis.gglogger.enabled")}.
\item \strong{bg_direction normalisation} — \code{match.arg()} resolves
\code{"v"}/\code{"h"} abbreviations to \code{"vertical"}/\code{"horizontal"}.
\item \strong{Axis type detection} — determines whether \code{x} (resp.
\code{y}) is numeric by checking that the column is a single name and the
data column is neither character nor factor.
\item \strong{Column resolution} — non-numeric x and y are processed via
\code{check_columns()} with \code{force_factor = TRUE, allow_multi = TRUE,
  concat_multi = TRUE} using \code{x_sep}/\code{y_sep}. \code{fill_by} and
\code{facet_by} are also validated.
\item \strong{NA / empty handling} — \code{process_keep_na_empty()} filters
data and extracts \code{keep_empty} settings for x, y, and facet_by.
\item \strong{Multi-facet keep_empty guard} — when \code{facet_by} has more
than one column, the \code{keep_empty} values must be identical for all
facet columns (consistent drop behaviour).
\item \strong{fill_cutoff guard} — errors if \code{fill_cutoff} is set but
\code{fill_by} is \code{NULL}.
\item \strong{Size-by resolution} — when \code{size_by = NULL}:
\itemize{
\item Groups data by the unique combination of x, y, and facet_by
columns and counts rows per combination into \code{.size}.
\item If \code{fill_by} is present, \code{summarise()} also takes the
first value of \code{fill_by} per group (with a warning that only the
first value is used).
\item Factor levels of x, y, and facet_by are preserved post-summary.
\item Sets \code{size_by <- ".size"}.
}
\item \strong{fill_cutoff parsing} — if \code{fill_cutoff} is set:
\itemize{
\item Numeric shorthand (e.g. \code{18}) is converted to \code{"< 18"}.
\item The string is parsed with regex \code{^(<=?|>=?)\\\\s*(-?[0-9.]+)$}
to extract operator and numeric threshold.
\item A \code{switch()} on the operator NAs-out matching values in
\code{fill_by} (e.g. \code{"<"} sets values \emph{below} the threshold
to \code{NA}).
\item A label \code{"<fill_by> <fill_cutoff>"} is generated for the
legend.
}
\item \strong{Default fill_by} — when \code{fill_by = NULL}, a synthetic
\code{.fill_by} column (constant \code{1}) is created and the fill legend
is suppressed.
\item \strong{Continuous colour scale preparation} — when \code{fill_by}
is numeric, \code{\link{prepare_continuous_color_scale}()} computes
\code{feat_colors_value} (the range endpoints after optional quantile
trimming or cutoff clamping).
\item \strong{Base ggplot} — initialises \code{ggplot(data, aes(x, y))}.
\item \strong{Background layer} — if \code{add_bg = TRUE}:
\itemize{
\item Vertical stripes (\code{bg_direction = "vertical"}) require a
non-numeric x-axis; horizontal stripes require a non-numeric y-axis.
\item Calls \code{\link{bg_layer}()} with the relevant discrete column
and stripe styling.
}
\item \strong{Discrete axis scales} — \code{scale_x_discrete()} /
\code{scale_y_discrete()} with \code{drop = !isTRUE(keep_empty_*)} for
non-numeric axes.
\item \strong{Lollipop branch} (\code{lollipop = TRUE}):
\itemize{
\item Sets x-axis expansion to \code{c(0, 0, 0.05, 0)} (bars start at
x = 0 with a 5\\% right pad).
\item \strong{Outer shadow} — \code{geom_segment()} from x = 0 to the
data value, coloured black (or \code{border_color} when a string),
with linewidth \code{border_size * 4}. Skipped when
\code{border_color = FALSE}.
\item \strong{Inner coloured bar} — \code{geom_segment()} mapped to
the \code{fill_by} gradient via \code{scale_color_gradientn()}, with
linewidth \code{border_size * 2}.
\item \code{ggnewscale::new_scale_color()} resets the colour scale for
the subsequent point layer.
}
\item \strong{Point layer} — \code{geom_point(shape = 21)} (filled circle
with border) with four dispatch paths:
\itemize{
\item \emph{Numeric size + gradient border}: \code{aes(fill, color)}
both mapped to \code{fill_by}; \code{size = size_by} constant.
\item \emph{Numeric size + constant/no border}: \code{aes(fill,
      color = "")} with a constant colour string.
\item \emph{Column size + gradient border}: \code{aes(size, fill,
      color)} with \code{scale_size(range = c(size_min, size_max))} and a
size legend (title = \code{size_name}, order = 1).
\item \emph{Column size + constant/no border}: \code{aes(size, fill,
      color = "")} with the same size scale.
}
\item \strong{Fill scale} — \code{scale_fill_gradientn()} with
\code{palette_this()}, \code{feat_colors_value} for rescaled colour
mapping, \code{na.value = "grey80"}, and a colour-bar legend (title =
\code{fill_name}, order = 2) or \code{guide_none()} when no
\code{fill_by} was provided.
\item \strong{Labels} — \code{labs(title, subtitle, x, y)} with fallback
to column names via \code{\%||\%}.
\item \strong{Theme} — \code{do_call(theme, theme_args)} plus
\code{panel.grid.major} (grey80 dashed) and rotated x-axis text via
\code{calc_just(x_text_angle)}.
\item \strong{Colour (border) scale}:
\itemize{
\item \code{border_color = TRUE} — \code{scale_color_gradientn()}
following the \code{fill_by} gradient (with border_alpha), guide
suppressed (the fill colour-bar serves both).
\item \code{border_color = FALSE} — \code{scale_color_manual()} with
\code{"transparent"}, guide suppressed.
\item Constant string — \code{scale_color_manual()} with the
alpha-adjusted colour, guide suppressed.
}
\item \strong{fill_cutoff legend} — when \code{fill_cutoff} is active and
there are NA values in \code{fill_by}, a \code{guide_legend()} (order = 3)
is added showing the cutoff label with a grey fill and the border colour.
\item \strong{Flip} — optional \code{coord_flip()} swaps x and y axes.
\item \strong{Dimension calculation} — \code{calculate_plot_dimensions()}
with \code{base_height = 4.5}, \code{aspect.ratio = NULL}, and per-axis
scale factors (0.9 for the categorical axis driving width, 0.6 for the
categorical axis driving height). Legend width, y-axis label length, and
minimum dimensions (width \eqn{\ge} 5, height \eqn{\ge} 4) are factored in. A fallback
manual calculation is used when \code{calculate_plot_dimensions()} returns
\code{NULL}.
\item \strong{Faceting} — \code{facet_plot()} applies
\code{facet_grid}/\code{facet_wrap} with \code{drop = !isTRUE(keep_empty_facet)}.
}
}

\keyword{internal}
