Cytotrace2

<p align="center"> <img width="500" src="images/logo.jpg"> </p> <h2> <p align="center"> CytoTRACE 2 - Version 1.1.0 Released </p> </h2>

We are thrilled to introduce CytoTRACE 2 version 1.1.0, published in Nature Methods and packed with significant performance enhancements to elevate your single-cell transcriptomic analyses. Here's what's new in this release:

<details><summary>Major Updates and Enhancements 🔍</summary>

• Retrained CytoTRACE 2 Framework
  The CytoTRACE 2 model has been retrained, yielding additional performance gains in granular potency prediction and enhancing cross-platform robustness.

• Expanded Ensemble Model
  The ensemble now comprises 19 models instead of 17, improving the predictive power and stability of the framework.

• Background Expression Matrix
  Introduced a background expression matrix generated during training for improved regularization.

• Enhanced Data Representations
  Added Log2-adjusted representation of the input expression data to be used for prediction on top of ranked expression profiles, to capture detailed transcriptomic signals. This changes the requirement for the input expression data to contain only raw or CPM/TPM normalized counts.

• Adaptive Nearest Neighbor Smoothing
  Modified the KNN smoothing step to employ an adaptive nearest neighbor smoothing strategy.

</details> <details><summary>Codebase and Distribution Updates 💻</summary>

• Codebase Updates

  • Updated both R and Python package codebases to reflect all the above changes.
  • Optimized for time and memory efficiency, ensuring faster computations and scalability.

• Enhanced Python Package Distribution
  The Python version of CytoTRACE 2 is now available on PyPI, making installation easier for Python users.

</details> <details><summary>Documentation and Guides 📚</summary>

• Updated Vignettes to align with the new model features and usage instructions.
• Refreshed README with new information, detailed explanations, and FAQ items tailored to the new framework.

</details>

We deeply appreciate the contributions from our community that made this release possible. Thank you for your continued support! 🙏

---

<h2> <p align="center"> Prediction of absolute developmental potential <br> using single-cell expression data </p> </h2>

CytoTRACE 2 is a computational method for predicting cellular potency categories and absolute developmental potential from single-cell RNA-sequencing data (Kang et al., Nature Methods 2025).

Potency categories in the context of CytoTRACE 2 classify cells based on their developmental potential, ranging from totipotent and pluripotent cells with broad differentiation potential to lineage-restricted oligopotent, multipotent and unipotent cells capable of producing varying numbers of downstream cell types, and finally, differentiated cells, ranging from mature to terminally differentiated phenotypes.

The predicted potency scores additionally provide a continuous measure of developmental potential, ranging from 0 (differentiated) to 1 (totipotent).

Underlying this method is a novel, interpretable deep learning framework trained and validated across 34 human and mouse scRNA-seq datasets encompassing 24 tissue types, collectively spanning the developmental spectrum.

This framework learns multivariate gene expression programs for each potency category and calibrates outputs across the full range of cellular ontogeny, facilitating direct cross-dataset comparison of developmental potential in an absolute space.

<p align="center"> <img width="900" src="images/schematic.png"> </p>

This documentation page details the R package for applying CytoTRACE 2. <strong> For the python package, see <a href="/cytotrace2_python" target="_blank">CytoTRACE 2 Python</a>.</strong>

Citation

If you use CytoTRACE 2, please cite:

Improved reconstruction of single-cell developmental potential with CytoTRACE 2. Nature Methods, 2025. <br> Minji Kang^*, Gunsagar S. Gulati^*, Erin L. Brown^*, Zhen Qi^*, Susanna Avagyan, Jose Juan Almagro Armenteros, Rachel Gleyzer, Wubing Zhang, Chloé B. Steen, Jeremy Philip D’Silva, Janella Schwab, Michael F. Clarke, Aadel A. Chaudhuri, and Aaron M. Newman^†. doi.org/10.1038/s41592-025-02857-2

<!-- ## Preprint Mapping single-cell developmental potential in health and disease with interpretable deep learning. bioRxiv 2024.03.19.585637; <br> doi: https://doi.org/10.1101/2024.03.19.585637 -->

Installation

We recommend installing the CytoTRACE 2 package using the devtools package from the R console. If you do not have devtools installed, you can install it by running install.packages("devtools") in the R console.

  devtools::install_github("digitalcytometry/cytotrace2", subdir = "cytotrace2_r") #installing
  library(CytoTRACE2) #loading

See alternative installation and package management methods (including an easy-to-use conda environment that precisely solves all dependencies) in the Advanced options section below.

The installation of the CytoTRACE 2 package itself typically takes about one minute on a standard computer. Optional installation of the provided conda environment generally takes 5-10 minutes but can vary substantially, sometimes requiring up to an hour depending on system and conda version.

NOTE: We recommend using Seurat v4 or later for full compatibility with CytoTRACE 2 package. If you don't have Seurat installed, you can install it by running install.packages("Seurat") in the R console prior to installing CytoTRACE 2 or use the provided conda environment.

<details><summary>Dependencies</summary>

The following list includes the versions of packages used during the development of CytoTRACE 2. While CytoTRACE 2 is compatible with various (older and newer) versions of these packages, it's important to acknowledge that specific combinations of dependency versions can lead to conflicts. The only such conflict known at this time happens when using Seurat v4 in conjunction with Matrix v1.6. This issue can be resolved by either upgrading Seurat or downgrading Matrix.

    R (4.2.3)
    data.table (1.14.8)
    doParallel (1.0.17)
    dplyr (1.1.3)
    ggplot2 (3.4.4)
    HiClimR (2.2.1)
    magrittr (2.0.3)
    Matrix (1.5-4.1)
    parallel (4.2.3)
    plyr (1.8.9)
    RANN (2.6.1)
    Rfast (2.0.8)
    RSpectra (0.16.1)
    Seurat (4.3.0.1)
    SeuratObject (4.1.3)
    stringr (1.5.1)

</details>

Running CytoTRACE 2

Running CytoTRACE 2 is easy and straightforward. After loading the library, simply execute the cytotrace2() function, with one required input, expression data, to obtain potency score and potency category predictions. Subsequently, running plotData will generate informative visualizations based on the predicted values, and external annotations, if available. Below, find two vignettes showcasing the application on a mouse dataset and a human dataset.

<details open><summary><span style="font-size: 15px;"><strong>Vignette 1: Development of mouse pancreatic epithelial cells (data table input, ~2 minutes)</strong></span></summary>

To illustrate use of CytoTRACE 2 with a mouse dataset, we will use the dataset Pancreas_10x_downsampled.rds, originally from Bastidas-Ponce et al., 2019, filtered to cells with known ground truth developmental potential and downsampled, available to download here, containing 2 objects:

• expression_data: gene expression matrix for a scRNA-seq (10x Chromium) dataset encompassing 2850 cells from murine pancreatic epithelium
• annotation: phenotype annotations for the scRNA-seq dataset above.

After downloading the .rds file, we apply CytoTRACE 2 to this dataset as follows:

# load the CytoTRACE 2 package
library(CytoTRACE2) 

# download the .rds file (this will download the file to your working directory)
download.file("https://drive.google.com/uc?export=download&id=1TYdQsMoDIJjoeuiTD5EO_kZgNJUyfRY2", "Pancreas_10x_downsampled.rds")

# load rds
data <- readRDS("Pancreas_10x_downsampled.rds")

# extract expression data
expression_data <- data$expression_data

# running CytoTRACE 2 main function - cytotrace2 - with default parameters
cytotrace2_result <- cytotrace2(expression_data)

# extract annotation data
annotation <- data$annotation

# generate prediction and phenotype association plots with plotData function
plots <- plotData(cytotrace2_result = cytotrace2_result, 
                  annotation = annotation,
                  expression_data = expression_data
                  )

Expected prediction output, dataframe cytotrace2_result looks as shown below (can be downloaded from here):

<p align="center"> <img width="600" src="images/Vignette1_predictions.png"> </p> <br>

This dataset contains cells from 4 different embryonic stages of a murine pancreas, and has the following cell types present:

• Multipotent pancreatic progenitors
• Endocrine progenitors and precursors
• Immature endocrine cells
• Alpha, Beta, Delta, and Epsilon cells

<p align="center"> <img width="600" src="images/Vignette1_phenotype_umap.png"> </p>

Each of these cell types is at a different stage of development, with progenitors and precursors having varying potential to differentiate into other cell types, and mature cells having no potential for further development. We use CytoTRACE 2 to predict the absolute developmental potential of each cell, whic