sc-cytotrace

name	sc-cytotrace
description	Predict cell differentiation potency from scRNA-seq data using gene expression complexity as a proxy for stemness.
version	0.1.0
author	OmicsClaw
license	MIT
tags	["singlecell","scrna","cytotrace","potency","differentiation","stemness"]
metadata	{"omicsclaw":{"domain":"singlecell","allowed_extra_flags":["--method","--n-neighbors","--r-enhanced"],"param_hints":{"cytotrace_simple":"[Truncated]"},"saves_h5ad":true,"requires_preprocessed":true,"legacy_aliases":[]}}

Single-Cell CytoTRACE Potency Prediction

Why This Exists

• Without it: no quick way to estimate which cells are more stem-like vs differentiated.
• With it: a potency score and categorical label for every cell, useful for developmental studies, cancer stem cell analysis, and trajectory interpretation.
• Why OmicsClaw: standardized output contract, gallery, and report following the same conventions as all other scRNA skills.

Core Capabilities

1. cytotrace_simple: lightweight potency prediction using gene expression complexity (number of detected genes per cell) as a proxy for stemness, with KNN smoothing.

Data / State Requirements

• Input: normalized expression or raw counts in X
• Upstream: sc-preprocessing (recommended) or sc-clustering
• Neighbor graph: built automatically if missing; reused if present
• UMAP: computed automatically for visualization if missing

Method Description

cytotrace_simple

The cytotrace_simple method is inspired by CytoTRACE (Gulati et al., Science 2020), which showed that gene expression complexity (number of detected genes) correlates with developmental potential.

Steps:

1. Gene count: count genes detected per cell (expression > 0)
2. Rank normalization: rank-normalize to [0, 1]
3. KNN smoothing: smooth scores using the cell-cell neighbor graph
4. Potency binning: assign cells to 6 potency categories

Category	Score Range	Biological Meaning
Differentiated	0.00 - 0.17	Terminally differentiated
Unipotent	0.17 - 0.33	Can produce one cell type
Oligopotent	0.33 - 0.50	Can produce few cell types
Multipotent	0.50 - 0.67	Can produce many cell types
Pluripotent	0.67 - 0.83	Can produce most cell types
Totipotent	0.83 - 1.00	Can produce all cell types

CLI Reference

# Basic usage
python skills/singlecell/scrna/sc-cytotrace/sc_cytotrace.py \
  --input <preprocessed.h5ad> --output <dir>

# With custom neighbors
python skills/singlecell/scrna/sc-cytotrace/sc_cytotrace.py \
  --input <preprocessed.h5ad> --output <dir> --n-neighbors 50

# Demo mode
python omicsclaw.py run sc-cytotrace --demo --output /tmp/cytotrace_demo

Public Parameters

Parameter	Role	Notes
--method	analysis method	cytotrace_simple (default, only option currently)
--n-neighbors	KNN smoothing neighbors	default 30; higher = smoother scores

Output Contract

Successful runs write:

• processed.h5ad -- with obs['cytotrace_score'], obs['cytotrace_potency'], obs['cytotrace_gene_count']
• figures/potency_umap.png -- UMAP colored by score and potency category
• figures/score_distribution.png -- score histogram
• figures/potency_composition.png -- potency category bar chart
• tables/cytotrace_scores.csv -- per-cell scores
• report.md
• result.json
• reproducibility/commands.sh

Downstream Link

• After potency prediction, consider:
  • sc-pseudotime -- for trajectory / lineage analysis
  • sc-de --groupby cytotrace_potency -- for differential expression between potency levels
  • Overlay potency scores on spatial data if available

Current Limitations

• cytotrace_simple is a heuristic based on gene complexity; it does not use pretrained deep learning models like CytoTRACE 2.
• The method assumes that gene detection count correlates with developmental potential, which holds for most but not all biological systems.
• Very small datasets (<50 cells) may produce unreliable scores.

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 demo data	—
--method	str	cytotrace_simple	Potency method (only cytotrace_simple currently)	fixed choice
--n-neighbors	int	30	KNN neighbors for score smoothing	—
--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_embedding_discrete	r_embedding_discrete.png	cytotrace_embedding.csv	UMAP/embedding colored by cell type labels	ggplot2
plot_embedding_feature	r_embedding_feature.png	cytotrace_embedding.csv	UMAP/embedding colored by CytoTRACE score	ggplot2

Note: The plan listed 1 R renderer (plot_feature_boxplot) for sc-cytotrace, but the actual R_ENHANCED_PLOTS dict contains plot_embedding_discrete and plot_embedding_feature. The cytotrace boxplot renderer (plot_cytotrace_boxplot) is registered in the R registry but not wired into the skill's R_ENHANCED_PLOTS dict.

Workflow Position

Upstream: sc-clustering or sc-cell-annotation Downstream: Terminal analysis. Consider: sc-pseudotime, sc-velocity