Single-Cell Markers

Why This Exists

• Without it: users jump straight from clusters to labels without a stable marker evidence layer.
• With it: OmicsClaw exports cluster-level marker tables, summary figures, and a downstream-ready processed.h5ad.
• Why OmicsClaw: it keeps marker ranking separate from replicate-aware condition DE.

Scope Boundary

Implemented methods:

1. wilcoxon
2. t-test
3. logreg
4. cosg -- COSG cosine-similarity specificity scoring (fast, no p-values)

This skill is for cluster or label marker ranking. For treated-vs-control or replicate-aware DE, use sc-de.

Input Expectations

• Expected state: normalized expression in adata.X
• Typical upstream step: sc-clustering
• Typical downstream step: sc-cell-annotation
• Required metadata: an existing grouping column such as leiden, louvain, or cell_type

Public Parameters

• --groupby
• --method
• --n-genes
• --n-top
• --min-in-group-fraction
• --min-fold-change
• --max-out-group-fraction

Output Contract

Successful runs write:

• processed.h5ad
• report.md
• result.json
• figures/markers_heatmap.png
• figures/markers_dotplot.png
• figures/marker_effect_summary.png
• figures/marker_cluster_summary.png
• figures/marker_fraction_scatter.png when fraction statistics are available
• tables/markers_all.csv
• tables/markers_top.csv
• tables/cluster_summary.csv
• figure_data/

What Users Should Inspect First

1. report.md
2. tables/markers_top.csv
3. figures/markers_dotplot.png
4. figures/marker_effect_summary.png
5. processed.h5ad

Guardrails

• Treat groupby as the main scientific parameter.
• Do not present cluster markers as replicate-aware condition DE.
• Use normalized expression, not raw counts, for the public marker workflow.
• After marker review, the usual next step is sc-cell-annotation.

For concise execution rules, see knowledge_base/knowhows/KH-sc-markers-guardrails.md. For longer interpretation guidance, see knowledge_base/skill-guides/singlecell/sc-markers.md.

CLI Parameters

Flag	Type	Default	Description	Validation
--input	str	—	Input .h5ad file	required unless --demo
--output	str	—	Output directory	required
--demo	flag	off	Run with bundled PBMC3k data	—
--groupby	str	None	Grouping column in obs	auto-detected from leiden/louvain/cell_type if omitted
--method	str	wilcoxon	Ranking method: wilcoxon, t-test, logreg, cosg	validated against METHOD_REGISTRY
--n-genes	int	None (all)	Total genes to test per group	—
--n-top	int	10	Top genes to export per group	—
--min-in-group-fraction	float	0.25	Minimum fraction of cells expressing the gene in the group	—
--min-fold-change	float	0.25	Minimum log fold-change threshold	—
--max-out-group-fraction	float	0.5	Maximum fraction of cells expressing the gene outside the group	—
--mu	float	1.0	COSG specificity penalty (0–1); higher = more specific	COSG only
--r-enhanced	flag	off	Also render R Enhanced ggplot2 figures	—

R Enhanced Plots

Activated by --r-enhanced. Files written to figures/r_enhanced/.

Renderer	Output file	figure_data CSV	Plot description	Required R packages
plot_marker_heatmap	r_marker_heatmap.png	marker_top_genes.csv	Heatmap of top marker genes per cluster	ggplot2, ComplexHeatmap
plot_feature_violin	r_feature_violin.png	feature_expression.csv	Violin plots of top marker expression per group	ggplot2

Workflow Position

Upstream: sc-clustering or sc-cell-annotation Downstream: sc-de (formal DE testing), sc-enrichment (pathway enrichment on markers)