% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/create_tesselation_plots.R
\name{create_tesselation_plots}
\alias{create_tesselation_plots}
\title{Create Tesselation Visualization Plots}
\usage{
create_tesselation_plots(
  data,
  class_column = NULL,
  alternative_class_column = NULL,
  coordinate_columns = NULL,
  case_labels = NULL,
  coord_names = c("Dim1", "Dim2"),
  title = NULL,
  show_labels = FALSE,
  ellipse_alpha = 0.1,
  voronoi_alpha = 0.3,
  point_size = 2,
  legend_position = "bottom",
  color_palette = NULL,
  add_grid_lines = FALSE,
  color_points = "primary",
  fill_voronoi = "primary",
  point_shape = "none",
  label_fontface = "plain",
  label_size = 3.88,
  show_island_count = FALSE,
  label_islands_only = FALSE
)
}
\arguments{
\item{data}{A data frame containing projected data. Must have at least 2 numeric columns.
If more than 2 columns are provided, the first 2 are used as coordinates.}

\item{class_column}{Character string specifying the column name containing class labels,
or a vector of class labels. If NULL, all observations are treated as a single class.
Default: NULL.}

\item{alternative_class_column}{Character string specifying the column name containing
alternative class labels, or a vector of alternative class labels. If NULL, uses
class_column. Default: NULL.}

\item{coordinate_columns}{Character vector of length 2 specifying the column names
to use as coordinates. If NULL, uses the first two numeric columns. Default: NULL.}

\item{case_labels}{Character vector of case labels for individual observations.
If NULL, row numbers are used. Default: NULL.}

\item{coord_names}{Character vector of length 2 specifying names for the coordinate axes.
Default: c("Dim1", "Dim2").}

\item{title}{Character string for plot title. If NULL, no title is added. Default: NULL.}

\item{show_labels}{Logical indicating whether to show case labels on plots. Default: FALSE.}

\item{ellipse_alpha}{Numeric value (0-1) for ellipse transparency. Default: 0.1.}

\item{voronoi_alpha}{Numeric value (0-1) for Voronoi polygon transparency. Default: 0.3.}

\item{point_size}{Numeric value for point size. Default: 2.}

\item{legend_position}{Character string or numeric vector specifying legend position.
Default: "bottom".}

\item{color_palette}{Function or character vector for color palette. If NULL, uses
ggplot2 default colors. Default: NULL.}

\item{add_grid_lines}{Logical indicating whether to add dashed grid lines at origin.
Default: FALSE.}

\item{color_points}{Character string specifying which classification to use for point colors.
Either "primary" (uses class_column) or "alternative" (uses alternative_class_column).
Default: "primary".}

\item{fill_voronoi}{Character string specifying which classification to use for Voronoi fill.
Either "primary" (uses class_column) or "alternative" (uses alternative_class_column).
Default: "primary".}

\item{point_shape}{Character string specifying which classification to use for point shapes.
Either "primary" (uses class_column), "alternative" (uses alternative_class_column),
or "none" (no shape differentiation). Default: "none".}

\item{label_fontface}{Character string specifying the font face for text labels.
Options include "plain", "bold", "italic", "bold.italic". Default: "plain".}

\item{label_size}{Numeric value specifying the size of text labels. Default: 3.88.}

\item{show_island_count}{Logical indicating whether to display the Voronoi island
count as a subtitle on the Voronoi-based plots (\code{voronoi_plot} and
\code{voronoi_plot_plus_ellipse}). A Voronoi island is a data point whose cell
is entirely surrounded by cells belonging to a different class. The count and
rate (proportion of all cells that are islands) are shown as a subtitle when
TRUE. The \code{ellipse_plot} is unaffected as it contains no tessellation.
The island count is always computed using the primary class labels
(class_column), regardless of the fill_voronoi setting. Default: FALSE.}

\item{label_islands_only}{Logical indicating whether to show case labels on plots 
only for Voronoi islands. Default: FALSE.}
}
\value{
A list containing three ggplot objects:
\item{ellipse_plot}{Plot with confidence ellipses for each class. Unaffected
by \code{show_island_count}.}
\item{voronoi_plot}{Plot with Voronoi tessellation regions. If
\code{show_island_count = TRUE}, the subtitle displays the number of Voronoi
islands and the island rate (proportion of all cells that are islands).}
\item{voronoi_plot_plus_ellipse}{Combined plot with both Voronoi regions and
confidence ellipses. If \code{show_island_count = TRUE}, the subtitle displays
the same island count and rate as \code{voronoi_plot}.}
}
\description{
Creates three types of visualization plots for 2D data: ellipse plots,
Voronoi diagram plots, and combined ellipse-Voronoi plots. The function is designed
to visualize class separation in raw or dimensionally reduced data.
}
\details{
The function creates visualizations for 2D (raw or projected) data, particularly useful
for displaying results from dimensionality reduction techniques like PCA, PLS-DA, or UMAP.

Voronoi tessellation divides the plot space into regions based on proximity to data points,
providing an intuitive visualization of class boundaries and decision regions.

Confidence ellipses show the distribution spread and correlation structure within each class.

The Voronoi island count is a visualization-intrinsic metric with no equivalent
in confidence ellipse approaches. Neighbor relationships are determined from the
Delaunay triangulation (the \code{dirsgs} component of the \code{deldir} output),
which is the geometric dual of the Voronoi tessellation: two cells share an edge
if and only if their corresponding points are connected by a Delaunay edge. A cell
is classified as an island if all its Voronoi neighbors belong to a different class.
Island detection requires no additional computation beyond the tessellation itself.
The Delaunay triangulation is computed once and reused for both the tessellation
plot and the island count, so enabling \code{show_island_count} incurs no
additional computational cost.
}
\examples{
# Basic usage with iris dataset
data <- iris[, c("Sepal.Length", "Petal.Length", "Species")]
plots <- create_tesselation_plots(
  data = data,
  class_column = "Species",
  legend_position = "bottom",
  add_grid_lines = FALSE
)

# With Voronoi island count displayed as subtitle on Voronoi-based plots
plots <- create_tesselation_plots(
  data = data,
  class_column = "Species",
  legend_position = "bottom",
  add_grid_lines = FALSE,
  show_island_count = TRUE
)

# With Voronoi island count displayed as subtitle on Voronoi-based plots
# Label only islands
plots <- create_tesselation_plots(
  data = data,
  class_column = "Species",
  legend_position = "bottom",
  add_grid_lines = FALSE,
  show_island_count = TRUE,
  label_islands_only = FALSE
)
}
