% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/densityplot.R
\name{RidgePlotAtomic}
\alias{RidgePlotAtomic}
\title{Atomic ridge plot}
\usage{
RidgePlotAtomic(
  data,
  x = NULL,
  in_form = c("long", "wide"),
  group_by = NULL,
  group_by_sep = "_",
  group_name = NULL,
  add_vline = NULL,
  vline_type = "solid",
  vline_color = TRUE,
  vline_width = 0.5,
  vline_alpha = 1,
  flip = FALSE,
  alpha = 0.8,
  scale = NULL,
  theme = "theme_this",
  theme_args = list(),
  palette = "Paired",
  palcolor = NULL,
  palreverse = FALSE,
  title = NULL,
  subtitle = NULL,
  xlab = NULL,
  ylab = NULL,
  x_text_angle = 90,
  x_min = NULL,
  x_max = NULL,
  keep_na = FALSE,
  keep_empty = FALSE,
  reverse = FALSE,
  facet_by = NULL,
  facet_scales = "fixed",
  facet_ncol = NULL,
  facet_nrow = NULL,
  facet_byrow = TRUE,
  aspect.ratio = 1,
  legend.position = "none",
  legend.direction = "vertical",
  ...
)
}
\arguments{
\item{data}{A data frame. Accepted in two forms:
\itemize{
\item \strong{long} (\code{in_form = "long"}): a numeric column (named by \code{x}) and a
factor column (named by \code{group_by}) whose levels become y-axis ridges.
\item \strong{wide} (\code{in_form = "wide"}): multiple numeric columns listed in
\code{group_by} are gathered into \code{.x} / \code{.group} via \code{tidyr::pivot_longer()}.
}}

\item{x}{A character string specifying the column name for the numeric
values plotted on the x-axis. When \code{in_form = "wide"}, \code{x} should be
\code{NULL}; the gathered values are stored in a synthetic \code{.x} column.}

\item{in_form}{A character string specifying whether \code{data} is in
\code{"long"} (default) or \code{"wide"} format.}

\item{group_by}{A character string specifying the column(s) whose levels
define the individual ridges on the y-axis. Multiple columns are
concatenated with \code{group_by_sep}. In wide mode, these are the column
names to gather.}

\item{group_by_sep}{A character string used to join multiple \code{group_by}
column values into a single factor level. In wide form the columns are
not concatenated (each becomes its own ridge). Default: \code{"_"}.}

\item{group_name}{A character string used as the legend title for the
\code{group_by} fill aesthetic. Defaults to the (concatenated) \code{group_by}
column name.}

\item{add_vline}{A specification for vertical reference lines:
\itemize{
\item \code{NULL} or \code{FALSE}: no lines.
\item \code{TRUE}: draw a line at the mean of each group.
\item A numeric vector: draw the same lines for all groups.
\item A named list of numeric vectors: per-group lines, where names should
match \code{group_by} levels.
}}

\item{vline_type}{A character string specifying the line type for the
vertical reference lines. Passed as \code{linetype} to \code{geom_vline()}.
Default: \code{"solid"}.}

\item{vline_color}{The colour of the vertical reference lines:
\itemize{
\item A literal colour value or vector (recycled): applied directly.
\item \code{TRUE} (default): each line is coloured with a darkened blend of
the corresponding ridge fill colour, computed via
\code{blend_colors(mode = "multiply")}.
}}

\item{vline_width}{A numeric value for the thickness of the vertical
reference lines. Passed as \code{linewidth} to \code{geom_vline()}.
Default: \code{0.5}.}

\item{vline_alpha}{A numeric value in \verb{[0, 1]} for the transparency of
the vertical reference lines. Default: \code{1}.}

\item{flip}{A logical value. If \code{TRUE}, the axes are swapped via
\code{coord_flip()}. X-axis text angle and grid-line placement are adjusted
accordingly.}

\item{alpha}{A numeric value in \verb{[0, 1]} for the transparency of the
ridge fill. Default: \code{0.8}.}

\item{scale}{A numeric value controlling the vertical overlap of ridges.
Passed to \code{ggridges::geom_density_ridges(scale = ...)}. Smaller values
increase overlap. When \code{NULL}, ggridges auto-computes the scale.}

\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{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{x_text_angle}{A numeric value specifying the angle (in degrees) for
x-axis text when \code{flip = TRUE}. Used with \code{calc_just()} to compute
optimal \code{hjust} / \code{vjust}. Default: \code{90}.}

\item{x_min, x_max}{Numeric limits for the x-axis. When \code{NULL} (default),
limits are determined from the data range. Passed to \code{scale_x_continuous(limits = ...)}.}

\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{reverse}{A logical value. If \code{TRUE}, the y-axis group order is
reversed. NA groups are renamed to the literal string \code{"NA"} and
placed at the end.}

\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{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{...}{Additional arguments passed to \code{ggridges::geom_density_ridges()}
(bandwidth, jittered_points, quantile_lines, etc.).}
}
\description{
Core implementation for ridge (joy) plots. Renders overlapping density curves
for each group on the y-axis using \code{ggridges::geom_density_ridges()}, with
optional vertical reference lines and wide-to-long data conversion.

The function accepts data in two forms:
\itemize{
\item \strong{long form} (default) — a numeric \code{x} column plus a \code{group_by} factor
column whose levels become the y-axis ridges.
\item \strong{wide form} — multiple numeric columns named in \code{group_by} are gathered
via \code{tidyr::pivot_longer()} into \code{.x} / \code{.group} columns, then processed
identically to the long form.
}

Vertical reference lines (\code{add_vline}) can be specified as a numeric vector
(same lines for all groups), a named list (per-group values), or \code{TRUE}
(group means). When \code{vline_color = TRUE}, each line is coloured with a
darkened blend of the corresponding ridge fill.
}
\section{Architecture}{

\strong{RidgePlotAtomic} executes the following steps:
\enumerate{
\item \strong{ggplot dispatch} — selects \code{gglogger::ggplot} or \code{ggplot2::ggplot}.
\item \strong{Wide-to-long conversion} — when \code{in_form = "wide"}, calls
\code{tidyr::pivot_longer()} on the \code{group_by} columns, producing \code{.group}
(factor) and \code{.x} (values). \code{x} and \code{group_by} are redirected to these
synthetic columns.
\item \strong{Column resolution} — \code{check_columns()} validates \code{x}, \code{group_by}
(force_factor, allow_multi, concat_multi), and \code{facet_by}.
\item \strong{Default group} — when \code{group_by} is \code{NULL}, a synthetic \code{.group}
factor with a single space character level is created so the fill
pipeline runs uniformly.
\item \strong{Reverse ordering} — if \code{reverse = TRUE}, factor levels of \code{group_by}
are reversed, flipping the y-axis ridge order.
\item \strong{NA / empty handling} — \code{process_keep_na_empty()} filters data. When
\code{reverse = TRUE} and any group value is \code{NA}, the NA level is renamed
to the literal string \code{"NA"} and moved to the end of the factor so
colour mapping and display remain consistent.
\item \strong{Palette resolution} — \code{palette_this()} maps group levels to fill
colours.
\item \strong{Base ggplot} — initialises \code{ggplot(data, aes(x, y, fill))} with
\code{group_by} on the y-axis.
\item \strong{Ridge geometry} — \code{ggridges::geom_density_ridges(alpha, scale)}.
When \code{scale} is \code{NULL}, ggridges auto-computes the overlap factor.
\item \strong{Vertical reference lines} — if \code{add_vline} is not \code{NULL} / \code{FALSE}:
\itemize{
\item \code{add_vline = TRUE} → computes \code{tapply(x, group_by, mean)}.
\item \code{vline_color = TRUE} → resolves per-group line colours by
darkening each fill colour via \code{blend_colors(mode = "multiply")}.
Named list elements are matched to factor levels.
\item Adds \code{geom_vline(xintercept, linetype, linewidth, color, alpha)}.
}
\item \strong{Scales and labels} — \code{scale_y_discrete(drop = !keep_empty_group)},
\code{scale_x_continuous()}, and \code{labs()}.
\item \strong{Fill scale} — \code{scale_fill_manual()}. When \code{keep_empty_group = TRUE},
\code{drop = FALSE}, \code{breaks}, and \code{limits} are set to preserve empty
factor levels.
\item \strong{Flip-aware theme} — when \code{flip = TRUE}:
\itemize{
\item \code{coord_flip()} is applied.
\item x-axis text angle is set from \code{x_text_angle} with computed
\code{hjust} / \code{vjust} via \code{calc_just()}.
\item Major grid lines are drawn on the x-axis.
\item When \code{flip = FALSE}, y-axis text is right-aligned and grid lines
appear on the y-axis.
}
\item \strong{Theme application} — \code{do_call(theme, theme_args)} applies the
resolved theme function, then \code{aspect.ratio} and legend position are
set.
\item \strong{Dimension calculation} — \code{calculate_plot_dimensions(base_height = 1, n_y = nlevels(group_by), y_scale_factor = 1, aspect.ratio, legend, flip)} sets \code{height} / \code{width} attributes. The base height of 1 unit
per ridge keeps individual ridges compact.
\item \strong{Faceting} — \code{facet_plot()} applies \code{facet_grid} / \code{facet_wrap}, with
\code{drop = !keep_empty_facet}.
}
}

\keyword{internal}
