% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/corplot.R
\name{CorPlot}
\alias{CorPlot}
\title{Correlation scatter plot}
\usage{
CorPlot(
  data,
  x,
  y,
  group_by = NULL,
  group_by_sep = "_",
  group_name = NULL,
  split_by = NULL,
  split_by_sep = "_",
  pt_size = 2,
  pt_shape = 16,
  raster = FALSE,
  alpha = 1,
  raster_dpi = c(512, 512),
  highlight = NULL,
  highlight_color = "black",
  highlight_size = 1,
  highlight_alpha = 1,
  highlight_stroke = 0.8,
  anno_items = c("eq", "r2", "p"),
  anno_size = 3,
  anno_fg = "black",
  anno_bg = "white",
  anno_bg_r = 0.1,
  anno_position = c("topleft", "topright", "bottomleft", "bottomright", "tl", "tr", "bl",
    "br"),
  add_smooth = TRUE,
  smooth_color = "red2",
  smooth_width = 1.5,
  smooth_se = FALSE,
  theme = "theme_this",
  theme_args = list(),
  palette = ifelse(is.null(group_by), "Spectral", "Paired"),
  palcolor = NULL,
  palreverse = FALSE,
  title = NULL,
  subtitle = NULL,
  xlab = NULL,
  ylab = NULL,
  facet_by = NULL,
  facet_scales = "fixed",
  facet_ncol = NULL,
  facet_nrow = NULL,
  facet_byrow = TRUE,
  aspect.ratio = 1,
  legend.position = waiver(),
  legend.direction = "vertical",
  seed = 8525,
  combine = TRUE,
  nrow = NULL,
  ncol = NULL,
  byrow = TRUE,
  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{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{group_name}{A character string used as the colour legend title.
When \code{NULL}, the \code{group_by} column name is used.}

\item{split_by}{The column(s) to split the data by and produce separate
sub-plots.  Multiple columns are concatenated with \code{split_by_sep}.}

\item{split_by_sep}{A character string to separate concatenated
\code{split_by} columns.  Default \code{"_"}.}

\item{pt_size}{A numeric value specifying the size of the points.
Default: \code{2}.}

\item{pt_shape}{A numeric value specifying the shape of the points
(see \code{\link[ggplot2]{geom_point}}).  Default: \code{16} (filled
circle).}

\item{raster}{A logical value.  When \code{TRUE}, uses
\code{scattermore::geom_scattermore()} for efficient rendering of
large datasets.  Default: \code{FALSE}.}

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

\item{raster_dpi}{An integer vector of length 1 or 2 specifying the
raster resolution in (width, height) pixels.  When a single value is
provided, it is recycled.  Default: \code{c(512, 512)}.}

\item{highlight}{Specifies which points to emphasise.  Can be:
\itemize{
\item \code{TRUE} — highlight all points.
\item A character expression (e.g. \code{'Species == "setosa"'}) —
evaluated via \code{dplyr::filter}.
\item A character vector — matched against rownames of the data.
\item A numeric vector — treated as row indices.
}
Default: \code{NULL} (no highlighting).}

\item{highlight_color}{A character string specifying the colour of the
highlighted point borders.  Default: \code{"black"}.}

\item{highlight_size}{A numeric value specifying the size of the
highlighted points (the inner fill).  Default: \code{1}.}

\item{highlight_alpha}{A numeric value specifying the alpha transparency
of the highlighted points.  Default: \code{1}.}

\item{highlight_stroke}{A numeric value specifying the stroke width of
the highlighted point borders.  The outer layer size is
\code{highlight_size + highlight_stroke}.  Default: \code{0.8}.}

\item{anno_items}{A character vector specifying which statistics to
display as text annotation.  Available items: \code{"eq"} (regression
equation), \code{"r2"} (R-squared), \code{"p"} (p-value),
\code{"spearman"}, \code{"pearson"}, \code{"kendall"},
\code{"n"} (observation count).  Default: \code{c("eq", "r2", "p")}.}

\item{anno_size}{A numeric value specifying the font size of the
annotation text (scaled by \code{base_size / 12}).  Default: \code{3}.}

\item{anno_fg}{A character string specifying the colour of the
annotation text.  Default: \code{"black"}.}

\item{anno_bg}{A character string specifying the background colour of
the annotation text boxes.  Default: \code{"white"}.}

\item{anno_bg_r}{A numeric value specifying the corner radius of the
annotation text background boxes.  Default: \code{0.1}.}

\item{anno_position}{A character string specifying the corner position
of the annotation text.  One of \code{"topleft"} (alias \code{"tl"}),
\code{"topright"} (\code{"tr"}), \code{"bottomleft"} (\code{"bl"}),
\code{"bottomright"} (\code{"br"}).}

\item{add_smooth}{A logical value.  When \code{TRUE} (default), a linear
regression line (\code{geom_smooth(method = "lm")}) is added.}

\item{smooth_color}{A character string specifying the colour of the
regression line.  Default: \code{"red2"}.}

\item{smooth_width}{A numeric value specifying the linewidth of the
regression line.  Default: \code{1.5}.}

\item{smooth_se}{A logical value.  When \code{TRUE}, a standard error
band is drawn around the regression line.  Default: \code{FALSE}.}

\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{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{seed}{A numeric seed for reproducibility.  Passed to
\code{\link{validate_common_args}()}.}

\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}.}

\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 guides (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 (when \code{split_by} is \code{NULL}),
a \code{patchwork} object (when \code{combine = TRUE}), 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 of two numeric variables with a linear regression
line, optional correlation statistics, and point highlighting.  This is
the public entry point that wraps \code{\link{CorPlotAtomic}} with
\code{split_by} support.

Key features include \strong{group-based colouring} (\code{group_by}),
\strong{point highlighting} by expression, rowname, or index,
\strong{annotation items} (regression equation, R-squared, p-value,
Spearman/Pearson/Kendall rho, N), \strong{raster rendering} for large
datasets, \strong{faceting} (\code{facet_by}), and \strong{splitting}
into separate sub-plots via \code{split_by}.
}
\section{split_by workflow}{

When \code{split_by} is provided:
\enumerate{
\item The \code{split_by} column is validated via
\code{\link{check_columns}()} with \code{force_factor = TRUE}.
Empty levels are dropped (\code{droplevels()}).
\item The data frame is split by \code{split_by} (preserving level
order).  If \code{split_by} is \code{NULL}, the data is wrapped
in a single-element list with name \code{"..."}.
\item Per-split \code{palette}, \code{palcolor},
\code{legend.position}, and \code{legend.direction} are resolved
via \code{\link{check_palette}()}, \code{\link{check_palcolor}()},
and \code{\link{check_legend}()}.
\item \code{\link{CorPlotAtomic}()} is called for each split.  When
\code{title} is a function, it receives the split level name and
can generate dynamic titles.
\item Results are combined via \code{\link{combine_plots}()} (when
\code{combine = TRUE}) or returned as a named list.
}
}

\examples{
\donttest{
data(iris)

# Basic scatter with group colours
CorPlot(iris, "Sepal.Length", "Sepal.Width", group_by = "Species")

# Highlight a specific group with custom stroke
CorPlot(iris, "Sepal.Length", "Sepal.Width", group_by = "Species",
    highlight = 'Species == "setosa"', highlight_stroke = 1.5,
    anno_items = c("eq", "pearson"), anno_position = "bottomright")

# Faceted by species
CorPlot(iris, "Sepal.Length", "Sepal.Width", facet_by = "Species",
    facet_scales = "free")

# Per-split palettes
CorPlot(iris, "Sepal.Length", "Sepal.Width", split_by = "Species",
    palette = c(setosa = "Set1", versicolor = "Dark2", virginica = "Paired"))
}
}
