| name | sc-markers |
| description | Rank cluster marker genes from normalized single-cell AnnData using Scanpy-backed Wilcoxon, t-test, or logistic-regression methods. The wrapper standardizes outputs for downstream annotation and review. |
| version | 0.5.0 |
| author | OmicsClaw |
| license | MIT |
| tags | ["singlecell","markers","cluster-markers","annotation","differential-expression"] |
| metadata | {"omicsclaw":{"domain":"singlecell","allowed_extra_flags":["--groupby","--method","--n-genes","--n-top","--min-in-group-fraction","--min-fold-change","--max-out-group-fraction","--mu","--r-enhanced"],"param_hints":{"wilcoxon":"[Truncated]","t-test":"[Truncated]","logreg":"[Truncated]","cosg":"[Truncated]"},"saves_h5ad":true,"requires_preprocessed":true}} |
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:
wilcoxont-testlogregcosg -- 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.h5adreport.mdresult.jsonfigures/markers_heatmap.pngfigures/markers_dotplot.pngfigures/marker_effect_summary.pngfigures/marker_cluster_summary.pngfigures/marker_fraction_scatter.png when fraction statistics are availabletables/markers_all.csvtables/markers_top.csvtables/cluster_summary.csvfigure_data/
What Users Should Inspect First
report.mdtables/markers_top.csvfigures/markers_dotplot.pngfigures/marker_effect_summary.pngprocessed.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)
