% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/corplot.R
\name{CorPairsPlot}
\alias{CorPairsPlot}
\title{Correlation pairs (scatterplot matrix)}
\usage{
CorPairsPlot(
  data,
  columns = NULL,
  group_by = NULL,
  group_by_sep = "_",
  group_name = NULL,
  split_by = NULL,
  split_by_sep = "_",
  diag_type = NULL,
  diag_args = list(),
  layout = c(".\\\\", "\\\\.", "/.", "./"),
  cor_method = c("pearson", "spearman", "kendall"),
  cor_palette = "RdBu",
  cor_palcolor = NULL,
  cor_size = 3,
  cor_format = "corr: {round(corr, 2)}",
  cor_fg = "black",
  cor_bg = "white",
  cor_bg_r = 0.1,
  theme = "theme_this",
  theme_args = list(),
  palette = ifelse(is.null(group_by), "Spectral", "Paired"),
  palcolor = NULL,
  palreverse = FALSE,
  title = NULL,
  subtitle = NULL,
  facet_by = NULL,
  legend.position = "right",
  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{columns}{A character vector of column names to include in the
pairs plot.  When \code{NULL} (default), all columns except
\code{group_by} are used.  At least two columns are required.}

\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
in the scatter plots.  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{diag_type}{A character string specifying the plot type for
diagonal cells.  One of \code{"density"}, \code{"violin"},
\code{"histogram"}, \code{"box"}, or \code{"none"} (diagonal line).
Default: \code{"density"} (no \code{group_by}) or \code{"violin"}
(with \code{group_by}).}

\item{diag_args}{A named list of additional arguments passed to the
diagonal plot function (\code{\link{DensityPlot}},
\code{\link{ViolinPlot}}, \code{\link{Histogram}}, or
\code{\link{BoxPlot}}).  Default: \code{list()}.}

\item{layout}{A character string specifying the layout orientation.
One of the following codes (dot = scatter, backslash/slash =
diagonal): \code{.\\}, \code{\\\.}, \code{/.}, \code{./}.
Default: \code{.\\}.}

\item{cor_method}{A character string specifying the correlation method
for the fill tiles.  One of \code{"pearson"}, \code{"spearman"},
\code{"kendall"}.  Default: \code{"pearson"}.}

\item{cor_palette}{A character string specifying the colour palette for
the correlation fill tiles.  Default: \code{"RdBu"}.}

\item{cor_palcolor}{A character vector of custom colours used to create
the correlation tile palette.  When \code{NULL}, the palette's default
colours are used.}

\item{cor_size}{A numeric value specifying the font size of the
correlation text in the fill tiles.  Default: \code{3}.}

\item{cor_format}{A character string specifying a glue template for
formatting the correlation text.  The template is evaluated by
\code{glue::glue()} with access to \code{corr} (the correlation value),
\code{x}, and \code{y} (the column names).  Default:
\code{"corr: \\{round(corr, 2)\\}"}.}

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

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

\item{cor_bg_r}{A numeric value specifying the corner radius of the
correlation text background boxes.  Default: \code{0.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{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{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{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.}

\item{combine}{Logical; when \code{TRUE} (default), returns a combined
\code{patchwork} object.  When \code{FALSE}, returns a named list of
individual \code{patchwork} objects.}

\item{ncol, nrow}{Integer number of columns / rows for the combined
layout.}

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

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

\item{design}{A custom layout design for the combined plot.}

\item{...}{Additional arguments.}
}
\value{
A \code{patchwork} object (when \code{combine = TRUE}) or a
named list of \code{patchwork} objects (when \code{combine = FALSE}),
each with \code{height} and \code{width} attributes in inches.
}
\description{
Draws a grid of pairwise scatter plots for selected numeric columns,
arranged in a scatterplot matrix layout.  The upper or lower triangle
displays correlation tiles while the opposite triangle shows scatter
plots with regression lines.  Diagonal cells can show density plots,
violin plots, histograms, box plots, or a simple diagonal line.

\strong{NOTE:} The \code{facet_by} parameter is \strong{not supported}
in CorPairsPlot (an error is raised if provided).  Use
\code{split_by} instead to create separate correlation pair matrices
per group.

The function supports \strong{four layout orientations} (\code{layout}),
\strong{three correlation methods}, configurable diagonal plots via
other plotthis functions, custom correlation tile formatting, and
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.
\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{"..."}.  The
\code{split_by} column is removed from each split's data before
plotting.
\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{CorPairsPlotAtomic}()} 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{
set.seed(8525)
data <- data.frame(x = rnorm(100))
data$y <- rnorm(100, 10, sd = 0.5)
data$z <- -data$x + data$y + rnorm(100, 20, 1)
data$g <- sample(1:4, 100, replace = TRUE)

# Histogram diagonal, slash layout
CorPairsPlot(data, diag_type = "histogram",
    diag_args = list(bins = 30, palette = "Paired"),
    layout = "/.")

# No diagonal with axis title styling
CorPairsPlot(data, group_by = "g", diag_type = "none", layout = "./",
    theme_args = list(axis.title = element_textbox(
        color = "black", box.color = "grey20", size = 16, halign = 0.5,
        fill = "grey90", linetype = 1,
        width = grid::unit(1, "npc"),
        padding = ggplot2::margin(5, 5, 5, 5))))

# Violin diagonal with custom format
CorPairsPlot(data, group_by = "g", diag_type = "violin", layout = "\\\\.",
    cor_format = "{x}\n{y}\ncorr: {round(corr, 2)}")

# Per-split with bottom legend
CorPairsPlot(data, split_by = "g", diag_type = "none", layout = ".\\\\",
    legend.position = "bottom", legend.direction = "horizontal",
    group_name = "group")

# Per-split with custom palette colours
CorPairsPlot(data, split_by = "g",
    palcolor = list("1" = "red", "2" = "blue", "3" = "green",
                    "4" = "yellow"))
}
}
