cytotrace2-analysis

CytoTRACE2 Analysis Skill

Predict cellular potency and differentiation states from scRNA-seq data.

Overview

CytoTRACE 2 outputs:

• CytoTRACE2_Score: Continuous (0 = differentiated, 1 = totipotent)
• CytoTRACE2_Potency: Categorical (Differentiated → Totipotent)
• CytoTRACE2_Relative: Normalized relative ordering within dataset

Installation

devtools::install_github("digitalcytometry/cytotrace2", subdir = "cytotrace2_r")

Input Requirements

• Seurat object with raw counts (NOT log-transformed)
• Use slot_type = "counts"
• No duplicate gene names or cell IDs
• Species: "human" or "mouse" (default)

Standard Workflow

Small Datasets (<50K cells)

library(CytoTRACE2)
seurat_obj <- cytotrace2(
  seurat_obj, is_seurat = TRUE, slot_type = "counts",
  species = "human", ncores = 16, batch_size = 10000
)

Large Datasets (Recommended: Split by Sample)

seurat_obj$sample <- paste0(seurat_obj$patient, "_", seurat_obj$condition)
seurat_list <- SplitObject(seurat_obj, split.by = "sample")

for (i in seq_along(seurat_list)) {
  seurat_list[[i]] <- cytotrace2(
    seurat_list[[i]], is_seurat = TRUE, slot_type = "counts",
    species = "human", ncores = 16
  )
}

# Merge and transfer metadata
seurat_merged <- merge(seurat_list[[1]], seurat_list[-1])
seurat_obj <- AddMetaData(seurat_obj, seurat_merged$CytoTRACE2_Score, "CytoTRACE2_Score")
seurat_obj <- AddMetaData(seurat_obj, seurat_merged$CytoTRACE2_Relative, "CytoTRACE2_Relative")
seurat_obj <- AddMetaData(seurat_obj, seurat_merged$CytoTRACE2_Potency, "CytoTRACE2_Potency")

Parameter Guide

Parameter	Default	Notes
species	"mouse"	Use "human" for human data
ncores	1	16 for high-memory systems
batch_size	10000	Reduce to 5000 if memory-limited
slot_type	"counts"	Never use log-transformed

When to split by sample: >100K cells, condition analysis, memory issues, batch effects.

Score Interpretation

Score	Category	Description
0.0-0.167	Differentiated	Terminally differentiated
0.167-0.333	Unipotent	Single lineage
0.333-0.5	Oligopotent	Few lineages
0.5-0.667	Multipotent	Multiple lineages
0.667-0.833	Pluripotent	Most lineages
0.833-1.0	Totipotent	All lineages

Relative vs Absolute: Relative is normalized within dataset; absolute is cross-dataset comparable.

Visualization (Quick Reference)

# Standard colors
colors.cyto <- c(Differentiated = "#9E0142", Unipotent = "#F46D43",
                 Oligopotent = "#FEE08B", Multipotent = "#E6F598",
                 Pluripotent = "#66C2A5", Totipotent = "#5E4FA2")
mycols <- rev(unname(pals::polychrome(32)))

# UMAP with inferno palette
FeaturePlot(seurat_obj, "CytoTRACE2_Score", raster = FALSE) +
  scale_colour_gradientn(colours = c("#000004FF", "#3B0F70FF", "#8C2981FF",
                                     "#DE4968FF", "#FE9F6DFF", "#FCFDBFFF"),
                         limits = c(0, 1)) +
  coord_fixed()

# Violin with potency labels
VlnPlot(seurat_obj, "CytoTRACE2_Score", group.by = "cell_type",
        cols = mycols, sort = TRUE, pt.size = 0) +
  scale_y_continuous(sec.axis = sec_axis(~., breaks = seq(0, 1, by = 1/12),
    labels = c("", "Differentiated", "", "Unipotent", "", "Oligopotent", "",
               "Multipotent", "", "Pluripotent", "", "Totipotent", "")))

See references/visualization.md for complete visualization code.

Troubleshooting

Critical: "rowMeans(): 'x' must be numeric" error on >100K cells is a resource issue, not data quality. Use SBATCH job submission with proper resources.

See references/troubleshooting.md for:

• SBATCH templates with resource guidelines
• Debugging workflow (validate with small subset first)
• Production R script for cluster jobs

Detailed Documentation

• references/troubleshooting.md - SBATCH templates, debugging, resource requirements
• references/visualization.md - Complete visualization code with all plot types
• references/rmd-template.md - Full R Markdown report template

References

• GitHub: https://github.com/digitalcytometry/cytotrace2
• Publication: Gulati et al. (2020) Science
• Example (298K cells): /home/pgueguen/git/paul-scripts/p31662_UM_Aizhan/UM_Atlas/