% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/CellWinX_TopMarkersStats.R
\name{CellWindX_TopMarkersStats}
\alias{CellWindX_TopMarkersStats}
\title{Identify top marker genes and summarize expression statistics}
\usage{
CellWindX_TopMarkersStats(
  object,
  group.by = "seurat_annotations",
  assay = NULL,
  slot = "data",
  top_n = 5,
  only.pos = TRUE,
  min.pct = 0.25,
  logfc.threshold = 0.25,
  test.use = "wilcox",
  min.diff.pct = -Inf,
  expression.threshold = 0,
  exclude.mt = TRUE,
  exclude.ribo = FALSE,
  output_dir = NULL,
  file_prefix = "CellWindX_top_markers",
  seed = 123,
  verbose = TRUE
)
}
\arguments{
\item{object}{A Seurat object.}

\item{group.by}{Character string. Metadata column used as cell-group
annotation for marker detection. Default is \code{"seurat_annotations"}.}

\item{assay}{Character string or \code{NULL}. Assay used for marker detection and
expression summarization. If \code{NULL}, \code{\link[Seurat:reexports]{Seurat::DefaultAssay()}} is used.
Default is \code{NULL}.}

\item{slot}{Character string. Assay slot or layer used to calculate expression
statistics. Common choices are \code{"data"} for normalized expression and
\code{"counts"} for raw counts. Default is \code{"data"}.}

\item{top_n}{Integer. Number of top marker genes selected for each cell group.
Default is \code{5}.}

\item{only.pos}{Logical. Whether to return only positive markers in
\code{\link[Seurat:FindAllMarkers]{Seurat::FindAllMarkers()}}. Default is \code{TRUE}.}

\item{min.pct}{Numeric. Minimum fraction of cells expressing a gene in either
of the two groups tested by \code{\link[Seurat:FindAllMarkers]{Seurat::FindAllMarkers()}}. Default is \code{0.25}.}

\item{logfc.threshold}{Numeric. Log-fold-change threshold used by
\code{\link[Seurat:FindAllMarkers]{Seurat::FindAllMarkers()}}. Default is \code{0.25}.}

\item{test.use}{Character string. Statistical test used by
\code{\link[Seurat:FindAllMarkers]{Seurat::FindAllMarkers()}}. Default is \code{"wilcox"}.}

\item{min.diff.pct}{Numeric. Minimum difference in detection percentage
between the two groups compared by \code{\link[Seurat:FindAllMarkers]{Seurat::FindAllMarkers()}}. Default is
\code{-Inf}.}

\item{expression.threshold}{Numeric. Threshold used to define whether a gene
is expressed in a cell when calculating \code{n_expr_cells} and \code{pct_expr}.
Default is \code{0}.}

\item{exclude.mt}{Logical. Whether to remove mitochondrial genes from selected
top markers. Human mitochondrial genes beginning with \code{"MT-"} and mouse
mitochondrial genes beginning with \code{"mt-"} are removed. Default is \code{TRUE}.}

\item{exclude.ribo}{Logical. Whether to remove ribosomal protein genes
beginning with \code{"RPS"}, \code{"RPL"}, \code{"Rps"}, or \code{"Rpl"}. Default is \code{FALSE}.}

\item{output_dir}{Character string or \code{NULL}. Optional directory for saving
result tables as CSV files. If \code{NULL}, no files are written. Default is
\code{NULL}.}

\item{file_prefix}{Character string. Prefix used for output CSV files when
\code{output_dir} is not \code{NULL}. Default is \code{"CellWindX_top_markers"}.}

\item{seed}{Integer. Random seed set before marker detection. Default is
\code{123}.}

\item{verbose}{Logical. Whether to print progress messages. Default is
\code{TRUE}.}
}
\value{
A list with class \code{"CellWindX_TopMarkersStats"} containing:
\describe{
\item{markers_all}{Complete marker table returned by
\code{\link[Seurat:FindAllMarkers]{Seurat::FindAllMarkers()}}.}
\item{top_markers}{Top marker genes selected for each source cell group.}
\item{top_marker_stats}{Expression statistics of each selected marker gene
within its source cell group.}
\item{marker_expr_by_group}{Expression statistics of selected marker genes
across all target cell groups. This table is used by downstream CellWindX
heatmap and radar functions.}
\item{top_gene_table}{A compact table listing top marker genes for each
cell group.}
\item{parameters}{A list of parameters used in the analysis.}
}
}
\description{
\code{CellWindX_TopMarkersStats()} identifies the top marker genes for each
annotated cell group in a Seurat object and summarizes their expression
percentage and average expression. The output is designed to be directly used
by downstream CellWindX visualization functions, including
\code{CellWindX_MarkerHeatmap()} and \code{CellWindX_GeneRadar()}.
}
\details{
This function first runs \code{\link[Seurat:FindAllMarkers]{Seurat::FindAllMarkers()}} using the cell-group
annotation specified by \code{group.by}. For each group, the top \code{N} marker genes
are selected according to adjusted P value, log-fold change, and detection
percentage.

For each selected marker gene, the function then calculates:

\itemize{
\item \code{n_cells}: number of cells in the target group.
\item \code{n_expr_cells}: number of cells with expression greater than
\code{expression.threshold}.
\item \code{pct_expr}: percentage of expressing cells.
\item \code{avg_expr}: average expression across all cells in the group.
\item \code{avg_expr_positive}: average expression among expressing cells only.
}

The function returns both source-cluster-specific statistics and expression
summaries across all annotated groups. This makes it suitable for marker
inspection, heatmap visualization, dot-plot-style summaries, and radar plots.

The function is compatible with Seurat v4 and v5 by attempting to retrieve
assay data through \code{layer} first and falling back to \code{slot} when needed.
}
\examples{
counts <- matrix(
  c(
    25, 26, 24, 27, 25, 26, 24, 28, 25, 27,
     1,  2,  1,  1,  2,  1,  1,  2,  1,  1,
     1,  1,  2,  1,  1,  2,  1,  1,  2,  1,

     1,  1,  2,  1,  1,  2,  1,  1,  2,  1,
    25, 27, 26, 24, 28, 25, 27, 26, 24, 28,
     1,  2,  1,  1,  2,  1,  1,  2,  1,  1,

     1,  2,  1,  1,  2,  1,  1,  2,  1,  1,
     1,  1,  2,  1,  1,  2,  1,  1,  2,  1,
    25, 26, 28, 24, 27, 25, 26, 28, 24, 27,

     5,  6,  5,  6,  5,  6,  5,  6,  5,  6,
     5,  6,  5,  6,  5,  6,  5,  6,  5,  6,
     5,  6,  5,  6,  5,  6,  5,  6,  5,  6
  ),
  nrow = 4,
  byrow = TRUE
)

rownames(counts) <- c("CD3D", "MS4A1", "LYZ", "ACTB")
colnames(counts) <- paste0("Cell", seq_len(ncol(counts)))

counts <- Matrix::Matrix(counts, sparse = TRUE)

object <- Seurat::CreateSeuratObject(counts = counts)
object$cell_type <- rep(c("T cell", "B cell", "Myeloid"), each = 10)
object <- Seurat::NormalizeData(object, verbose = FALSE)

res_marker <- CellWindX_TopMarkersStats(
  object = object,
  group.by = "cell_type",
  assay = "RNA",
  slot = "data",
  top_n = 1,
  only.pos = TRUE,
  min.pct = 0.10,
  logfc.threshold = 0,
  test.use = "t",
  verbose = FALSE
)

head(res_marker$top_markers)
head(res_marker$top_marker_stats)
head(res_marker$marker_expr_by_group)
res_marker$top_gene_table

}
\author{
Xiaofeng Yang, Chongqing Medical University
}
