% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/scatterplot.R
\name{ScatterPlot}
\alias{ScatterPlot}
\title{Scatter Plot}
\usage{
ScatterPlot(
  data,
  x,
  y,
  size_by = 2,
  size_name = NULL,
  color_by = NULL,
  color_name = NULL,
  lower_quantile = 0,
  upper_quantile = 0.99,
  lower_cutoff = NULL,
  upper_cutoff = NULL,
  palreverse = FALSE,
  split_by = NULL,
  split_by_sep = "_",
  shape = 21,
  alpha = ifelse(shape \%in\% 21:25, 0.65, 1),
  border_color = "black",
  border_size = 0.5,
  highlight = NULL,
  highlight_shape = 16,
  highlight_size = 3,
  highlight_color = "red",
  highlight_alpha = 1,
  theme = "theme_this",
  theme_args = list(),
  palette = ifelse(!is.null(color_by) && !is.numeric(data[[color_by]]), "Paired",
    "Spectral"),
  palcolor = NULL,
  facet_by = NULL,
  facet_scales = "fixed",
  facet_ncol = NULL,
  facet_nrow = NULL,
  facet_byrow = TRUE,
  aspect.ratio = 1,
  legend.position = "right",
  legend.direction = "vertical",
  title = NULL,
  subtitle = NULL,
  xlab = NULL,
  ylab = NULL,
  combine = TRUE,
  nrow = NULL,
  ncol = NULL,
  byrow = TRUE,
  seed = 8525,
  axes = NULL,
  axis_titles = axes,
  guides = NULL,
  design = NULL,
  ...
)
}
\arguments{
\item{data}{A data frame.}

\item{x}{A character string specifying the column name of the data frame to plot for the x-axis.}

\item{y}{A character string specifying the column name of the data frame to plot for the y-axis.}

\item{size_by}{Either a numeric constant (uniform dot size) or a character
string naming a numeric column whose values control dot size via
\code{scale_size_area(max_size = 6)}. Default: \code{2}.}

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

\item{color_by}{A character string naming a column whose values control
dot colour. Can be numeric (continuous gradient via
\code{scale_fill_gradientn()} / \code{scale_color_gradientn()}) or
factor/character (discrete palette via
\code{scale_fill_manual()} / \code{scale_color_manual()}). For shapes
21--25, the colour is applied to the fill aesthetic. When \code{NULL}
(default), all dots are rendered in a single colour derived from the
palette.}

\item{color_name}{A character string for the colour legend title. When
\code{NULL} (default), the \code{color_by} column name is used.}

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

\item{split_by}{The column(s) to split data by and generate separate scatter
plots for each level. The split column is processed before splitting;
multiple columns are concatenated with \code{split_by_sep}.}

\item{split_by_sep}{A character string used to concatenate multiple
\code{split_by} column values. Default: \code{"_"}.}

\item{shape}{A numeric value specifying the point shape. Default: \code{21}
(filled circle with border). Shapes 21--25 support separate fill and border
colour aesthetics; all other shapes use a single colour aesthetic.}

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

\item{border_color}{Controls the point border colour. For shapes 21--25:
\itemize{
\item \code{"black"} (default) -- constant black border.
\item A colour string (e.g. \code{"red"}, \code{"#FF0000"}) -- constant
colour border.
\item \code{TRUE} -- border colour tracks the \code{color_by} gradient
/ palette via \code{scale_color_gradientn()} /
\code{scale_color_manual()}.
}
For shapes without a fill aesthetic (not 21--25), this parameter has no
effect.}

\item{border_size}{A numeric value specifying the point border size. Default: \code{0.5}.}

\item{highlight}{Specifies which points to highlight with an overlaid
\code{geom_point()} layer. Accepted values:
\itemize{
\item \code{NULL} (default) -- no highlighting.
\item \code{TRUE} -- all points are highlighted.
\item A numeric vector -- row indices of points to highlight.
\item A single character string -- an R expression (e.g.
\code{"x > 0"}) that is parsed with \code{rlang::parse_expr()} and
evaluated via \code{\link[dplyr]{filter}()} to select rows.
\item A character vector -- rownames of points to highlight. An error
is thrown if the data has no rownames.
}}

\item{highlight_shape}{A numeric value specifying the point shape for
highlighted points. Default: \code{16} (filled circle). Shapes 21--25
use the \code{fill} aesthetic; other shapes use \code{color}.}

\item{highlight_size}{A numeric value specifying the size of highlighted
points. Default: \code{3}.}

\item{highlight_color}{A character string specifying the colour of
highlighted points. Default: \code{"red"}.}

\item{highlight_alpha}{A numeric value in \code{[0, 1]} specifying the
transparency of highlighted points. Default: \code{1}.}

\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{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{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{combine}{A logical value. If \code{TRUE} (the default), the list of
per-split plots is combined into a single \code{patchwork} object via
\code{\link{combine_plots}()}. If \code{FALSE}, returns the raw list of
\code{ggplot} objects.}

\item{nrow, ncol, byrow}{Integers controlling the layout of combined plots via
\code{\link{combine_plots}()}. \code{byrow = TRUE} (default) fills the
layout row-wise.}

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

\item{axes, axis_titles}{Strings controlling how axes and axis titles are
handled across combined plots. Passed to \code{\link{combine_plots}()}.
See \code{?patchwork::wrap_plots} for options (\code{"keep"},
\code{"collect"}, \code{"collect_x"}, \code{"collect_y"}).}

\item{guides}{A string controlling guide collection across combined plots.
Passed to \code{\link{combine_plots}()}.}

\item{design}{A custom layout specification for combined plots. Passed to
\code{\link{combine_plots}()}. When specified, \code{nrow}, \code{ncol},
and \code{byrow} are ignored.}

\item{...}{Additional arguments.}
}
\value{
A \code{ggplot} object (single plot), a \code{patchwork} object
(when \code{combine = TRUE} with \code{split_by}), or a named list of
\code{ggplot} objects (when \code{combine = FALSE}), each with
\code{height} and \code{width} attributes in inches.
}
\description{
Draws a scatter plot with optional size encoding, colour encoding
(continuous gradient or discrete palette), point highlighting, and axis
transformations. This is the user-facing wrapper around
\code{\link{ScatterPlotAtomic}} that adds \code{split_by} support
(generating separate sub-plots per group) and combines them via
\code{patchwork}.

Key features:
\itemize{
\item \strong{Variable point size} -- \code{size_by} accepts either a
numeric constant or a column name.
\item \strong{Colour modes} -- numeric \code{color_by} produces a
continuous gradient; factor/character \code{color_by} produces a discrete
palette.
\item \strong{Colour scale trimming} -- \code{lower_quantile} /
\code{upper_quantile} (or explicit \code{lower_cutoff} /
\code{upper_cutoff}) trim/clamp continuous colour scale extremes.
\item \strong{Border modes} -- \code{border_color} can be a constant
colour, \code{TRUE} (track the fill gradient), or omitted.
\item \strong{Point highlighting} -- \code{highlight} accepts indices,
rownames, logical \code{TRUE}, or a string expression.
\item \strong{Axis transformation} -- \code{xtrans} / \code{ytrans}
support log, sqrt, and other scale transformations.
\item \strong{Split sub-plots} -- \code{split_by} produces one scatter
plot per group level, combined into a single \code{patchwork} layout.
}
}
\section{split_by Workflow}{

When \code{split_by} is provided:
\enumerate{
\item \strong{Seed validation} -- \code{\link{validate_common_args}()}
sets the random seed for reproducibility.
\item \strong{Theme resolution} -- \code{\link{process_theme}()} resolves
the \code{theme} string or function.
\item \strong{Split column resolution} -- \code{\link{check_columns}()}
validates \code{split_by} (force_factor, allow_multi, concat_multi).
\item \strong{Data splitting} -- unused factor levels are dropped and the
data is split into a named list (preserving factor level order). When
\code{split_by = NULL}, a single-element list named \code{"..."} is used.
\item \strong{Per-split palette / colour} -- \code{\link{check_palette}()}
and \code{\link{check_palcolor}()} resolve per-split palette and colour
overrides.
\item \strong{Per-split legend} -- \code{\link{check_legend}()} resolves
\code{legend.position} and \code{legend.direction} per split.
\item \strong{Per-split title} -- when \code{title} is a function, it
receives the default title (the split level name) and can return a custom
string; otherwise \code{title \%||\% split_level} is used.
\item \strong{Dispatch} -- each split subset is passed to
\code{\link{ScatterPlotAtomic}()}.
\item \strong{Combination} -- \code{\link{combine_plots}()} assembles the
list of plots via \code{patchwork::wrap_plots}, honouring
\code{nrow}/\code{ncol}/\code{byrow}/\code{design}.
}
}

\examples{
set.seed(8525)

data <- data.frame(
   x = rnorm(20),
   y = rnorm(20),
   w = abs(rnorm(20)),
   t = sample(c("A", "B"), 20, replace = TRUE)
)

# --- Basic scatter plot ---
ScatterPlot(data, x = "x", y = "y")

# --- Highlight points ---
ScatterPlot(data, x = "x", y = "y", highlight = 'x > 0')

# --- Size encoding (column name) ---
ScatterPlot(data, x = "x", y = "y", size_by = "w")

# --- Colour encoding (numeric gradient) ---
ScatterPlot(data, x = "x", y = "y", color_by = "w")

# --- Colour encoding (categorical) with border ---
ScatterPlot(data, x = "x", y = "y", size_by = "w", color_by = "t",
 border_color = "red")

# --- Border colour tracks fill gradient ---
ScatterPlot(data, x = "x", y = "y", size_by = "w", color_by = "t",
 border_color = TRUE)

# --- Shape without fill (single colour aesthetic) ---
ScatterPlot(data, x = "x", y = "y", size_by = "w", color_by = "t",
 shape = 1, palette = "Set1")

# --- split_by with per-split palcolor ---
ScatterPlot(data, x = "x", y = "y", split_by = "t",
            palcolor = list(A = "blue", B = "red"))

# --- Colour scale limits (quantile-based) ---
ScatterPlot(data, x = "x", y = "y", color_by = "w",
            lower_quantile = 0.1, upper_quantile = 0.9)

# --- Colour scale limits (explicit cutoffs) ---
ScatterPlot(data, x = "x", y = "y", color_by = "w",
            lower_cutoff = 0, upper_cutoff = 1)
}
