% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/CellWindX_GeneRadar.R
\name{CellWindX_GeneRadar}
\alias{CellWindX_GeneRadar}
\title{Draw gene-level radar plots across annotated cell groups}
\usage{
CellWindX_GeneRadar(
  marker_result,
  genes,
  source_cluster = NULL,
  aggregate_fun = c("mean", "max", "first"),
  palette = c("shanshui", "chongqing_modern", "girlish"),
  scale_avg = TRUE,
  scale_pct = FALSE,
  pct_max = 100,
  avg_scale_method = c("max", "zscore", "none"),
  grid_levels = c(25, 50, 75, 100),
  axis_label_size = 5.2,
  grid_label_size = 3.2,
  facet_title_size = 12,
  line_width = 1.2,
  point_size = 2.8,
  fill_alpha = 0.18,
  facet = TRUE,
  ncol = NULL,
  show_points = TRUE,
  show_fill = TRUE,
  show_grid_label = TRUE,
  output_file = NULL,
  output_width = 11,
  output_height = 5.5,
  dpi = 300
)
}
\arguments{
\item{marker_result}{A result object returned by \code{CellWindX_TopMarkersStats()},
or a data frame containing marker expression statistics. If a data frame is
provided, it must contain the columns \code{source_cluster}, \code{target_cluster},
\code{gene}, \code{pct_expr}, and \code{avg_expr}.}

\item{genes}{Character vector. Gene symbols to visualize.}

\item{source_cluster}{Character vector or \code{NULL}. Optional source-cluster
filter. If provided, only marker statistics from the selected source
cluster(s) are used. Default is \code{NULL}.}

\item{aggregate_fun}{Character string. Method used to aggregate duplicated
gene-cell-group rows. One of \code{"mean"}, \code{"max"}, or \code{"first"}.
Default is \code{"mean"}.}

\item{palette}{Character string. Built-in CellWindX palette. One of
\code{"shanshui"}, \code{"chongqing_modern"}, or \code{"girlish"}.}

\item{scale_avg}{Logical. Whether to scale average expression values before
plotting. Default is \code{TRUE}.}

\item{scale_pct}{Logical. Whether to scale expression percentage values by
gene before plotting. If \code{FALSE}, the raw percentage values are used and
capped by \code{pct_max}. Default is \code{FALSE}.}

\item{pct_max}{Numeric. Maximum value used to cap percentage values when
\code{scale_pct = FALSE}. Default is \code{100}.}

\item{avg_scale_method}{Character string. Scaling method for average
expression. One of \code{"max"}, \code{"zscore"}, or \code{"none"}. \code{"max"} rescales
each gene to a 0-100 range by dividing by its maximum value. \code{"zscore"}
performs gene-wise Z-score scaling and rescales the result to 0-100.
\code{"none"} keeps the original average expression values. Default is \code{"max"}.}

\item{grid_levels}{Numeric vector. Radar grid levels. These values determine
the radius of the straight polygon grid lines. Default is
\code{c(25, 50, 75, 100)}.}

\item{axis_label_size}{Numeric. Font size of cell-group labels placed around
the radar plot. Default is \code{5.2}.}

\item{grid_label_size}{Numeric. Font size of radar grid labels. Default is
\code{3.2}.}

\item{facet_title_size}{Numeric. Font size of facet titles when multiple
genes are plotted. Default is \code{12}.}

\item{line_width}{Numeric. Width of radar polygon lines. Default is \code{1.2}.}

\item{point_size}{Numeric. Size of points on radar axes. Default is \code{2.8}.}

\item{fill_alpha}{Numeric. Transparency of polygon fill. Values should
usually range from 0 to 1. Default is \code{0.18}.}

\item{facet}{Logical. Whether to draw multiple genes as separate facets.
Default is \code{TRUE}.}

\item{ncol}{Integer or \code{NULL}. Number of columns used in facet layout when
\code{facet = TRUE}. Default is \code{NULL}.}

\item{show_points}{Logical. Whether to show points on radar axes.
Default is \code{TRUE}.}

\item{show_fill}{Logical. Whether to fill radar polygons. Default is \code{TRUE}.}

\item{show_grid_label}{Logical. Whether to show numeric grid labels.
Default is \code{TRUE}.}

\item{output_file}{Character string or \code{NULL}. Optional path used to save the
combined radar plot. Supported formats depend on \code{\link[ggplot2:ggsave]{ggplot2::ggsave()}},
such as \code{.pdf}, \code{.png}, \code{.tiff}, or \code{.svg}. Default is \code{NULL}.}

\item{output_width}{Numeric. Width of the saved plot in inches. Default is
\code{11}.}

\item{output_height}{Numeric. Height of the saved plot in inches. Default is
\code{5.5}.}

\item{dpi}{Numeric. Resolution used when saving raster formats. Default is
\code{300}.}
}
\value{
A list with class \code{"CellWindX_GeneRadar"} containing:
\describe{
\item{pct_plot}{A ggplot object showing expression percentage.}
\item{avg_plot}{A ggplot object showing average expression.}
\item{combined_plot}{A patchwork object combining percentage and average expression plots.}
\item{plot_data}{A data frame used for plotting.}
\item{pct_coord}{Radar coordinates for the expression percentage plot.}
\item{avg_coord}{Radar coordinates for the average expression plot.}
\item{palette}{The selected CellWindX palette.}
\item{genes}{Genes used for visualization.}
\item{parameters}{A list of function parameters used in the plot.}
}
}
\description{
\code{CellWindX_GeneRadar()} visualizes the expression pattern of selected genes
across annotated cell groups using straight-line spider radar plots. For each
selected gene, the function generates two radar plots: one for the percentage
of expressing cells and another for average expression.
}
\details{
This function is designed to directly accept the output generated by
\code{CellWindX_TopMarkersStats()}. It uses the \code{marker_expr_by_group} table from
that result object, which should contain gene expression statistics across
cell groups.

Each cell group is represented as one axis of the radar plot. Unlike polar
coordinate radar plots, this function manually calculates polygon coordinates,
resulting in straight polygon grid lines rather than curved circular grid
lines. This style is generally clearer for comparing cell-group-specific
expression patterns.

The function draws two panels:

\itemize{
\item \code{pct_plot}: expression percentage across cell groups.
\item \code{avg_plot}: average expression across cell groups.
}

The expression percentage and average expression panels use intentionally
distinct color sets within the selected CellWindX palette. Three built-in
palettes are available: \code{"shanshui"}, \code{"chongqing_modern"}, and \code{"girlish"}.
}
\examples{
marker_df <- data.frame(
  source_cluster = rep(c("T cell", "B cell"), each = 4),
  target_cluster = rep(c("T cell", "B cell", "Myeloid", "Platelet"), times = 2),
  gene = rep(c("CD3D", "MS4A1"), each = 4),
  pct_expr = c(92, 8, 15, 4, 6, 88, 12, 3),
  avg_expr = c(2.8, 0.2, 0.5, 0.1, 0.1, 2.5, 0.4, 0.1),
  stringsAsFactors = FALSE
)

radar_res <- CellWindX_GeneRadar(
  marker_result = marker_df,
  genes = c("CD3D", "MS4A1"),
  palette = "shanshui",
  scale_avg = TRUE,
  avg_scale_method = "max",
  facet = TRUE,
  ncol = 2
)

radar_res$combined_plot

}
\author{
Xiaofeng Yang, Chongqing Medical University
}
