cytotrace2-py 1.1.0.4
CytoTRACE 2 is a computational method for predicting cellular potency categories and absolute developmental potential from single-cell RNA-sequencing data.
Requires Python: >=3.9

<p align="center">
  <img width="500" src="https://github.com/digitalcytometry/cytotrace2/raw/main/cytotrace2_python/images_py/logo.jpg"> 
</p>

<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. 

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="https://raw.githubusercontent.com/digitalcytometry/cytotrace2/main/cytotrace2_python/images_py/schematic.png">
</p>



## Installation instructions

<details><summary>Expand section</summary>

Install using pip/pip3:

```bash
pip install cytotrace2-py
```

__Optional:__
For faster data reading, you can optionally install `datatable` (e.g., `pip install datatable` or `conda install -c conda-forge datatable`) if your OS and environment support it. If not installed, the code will default to using `pandas` for reading input files.

</details>


## Input files

<details><summary>Expand section</summary>

By default, CytoTRACE 2 requires only a single-cell gene expression file as input. For output plotting, a cell annotation file is accepted as well. All files should be provided in a tab-delimited tabular input format (.txt) with no double quotations. Further formatting details for each input file are specified below. 

__scRNA-seq gene expression file:__
- The table must be genes (rows) by cells (columns).
- The first row must contain the single cell IDs and the first column must contain the gene names.
- The gene expression data can be represented as raw or normalized counts, as long as normalization preserves relative ranking of input gene values within a cell.  
- No instances of duplicate gene or cell names should be present.

<p align="center">
    <img width="600" src="https://raw.githubusercontent.com/digitalcytometry/cytotrace2/main/cytotrace2_python/images_py/data.png">
</p>

__Cell annotation file:__
- The table should contain two columns, where column 1 contains the single cell IDs corresponding to the columns of the scRNA-seq matrix and column 2 contains the corresponding cell type annotations.
- The columns must have a header. 
- Additional columns beyond the first two will be ignored.

<p align="center">
    <img width="600" src="https://raw.githubusercontent.com/digitalcytometry/cytotrace2/main/cytotrace2_python/images_py/annotation.png">
</p>

</details>

## Running CytoTRACE 2 

<details><summary>Expand section</summary>

After installing the package and its dependencies, the tool is ready to run both from command line and from within a Python script.

**NOTE**: Only during the first run, the script will download remotely hosted underlying models. This is done just once and saved for all future runs. 

For mouse data with default settings, CytoTRACE 2 would be run from command line as: 
 ```bash
 cytotrace2 \
    --input-path /path/to/cell_expression \
    --annotation-path /path/to/cell_annotations \
    --species mouse
```
Or with more condensed parameter names: 
 ```bash
 cytotrace2 \
    -f /path/to/cell_expression \
    -a /path/to/cell_annotations \
    -sp mouse
```

CytoTRACE 2 can also be called from within a Python script after importing the package.

 ```python
from cytotrace2_py.cytotrace2_py import *

input_path = "/path/to/cell_expression.txt"
example_annotation_path = "/path/to/cell_annotations.txt"
example_species = "human"

results =  cytotrace2(input_path,
                      annotation_path=example_annotation_path,
                      species=example_species)
 ```

**NOTE**: When running on computers with less than 16GB memory, we recommend reducing *max_cores* parameter to 1 or 2 to avoid memory issues.
</details>

## Extended usage details

<details><summary>Expand section</summary>

Key notes:

- By default, CytoTRACE 2 expects mouse data. To provide human data, users should specify ```species = "human"```

Required input:

- *input_path*: A filepath to a .txt file containing a single-cell RNA-seq gene expression matrix (rows as genes, columns as cells) 

Optional arguments:

- *annotation_path*: A filepath to a .txt file containing phenotype annotations corresponding to the cells of the scRNA-seq expression matrix
- *species*: String indicating the species name for the gene names in the input data
(options: **"human"** or **"mouse"**, default is **"mouse"**).
- *batch_size*: Integer indicating the number of cells to process at once for the pipeline steps, including subsampling for KNN smoothing (default is **10000**).
- *smooth_batch_size*: Integer indicating the number of cells to subsample further
within the batch_size for the smoothing by diffusion step of the pipeline
(default is **1000**).
- *disable_parallelization*: Flag indicating whether to disable parallelization (default is **FALSE**, or absent for the command line).
- *disable_plotting*: Flag indicating whether to disable plotting (default is **FALSE**, or absent for the command line). To plot results, data are reprocessed following the core CytoTRACE 2 pipeline to produce UMAP embeddings via a standard scanpy pipeline. As this step can be time-consuming, we provide the option to disable it if desired.
- *max_cores*: Integer indicating user-provided restriction on the maximum number of CPU cores to use for parallelization (default is **None**, and the number of cores used will then be determined based on system capacity; when running on computers with less than 16GB memory, we recommend reducing it to 1 or 2 to avoid memory issues.).
- *seed*: Integer specifying the seed for reproducibility in random processes (default is **14**).
- *output_dir*: Path to the directory to which to save CytoTRACE 2 outputs (default is **cytotrace2_results** in the current working directory).

Information about these arguments is also available in the function's manual, which can be accessed by running ```cytotrace2 -h``` from the command line.

</details>

**For more information about the tool, R/Python package documentation, Vignettes, example input files, and more, visit out GitHub page: https://github.com/digitalcytometry/cytotrace2.**

## CytoTRACE 2 web application

An interactive RShiny web application can be accessed at <a href="https://cytotrace2.stanford.edu">cytotrace2.stanford.edu</a>, allowing users to run analyses on their own data, browse results for 33 ground-truth–annotated datasets, explore potency-associated genes and gene-set enrichment across the single-cell potency atlas, download the atlas, and access Python vignettes for model training and custom GSBN architectures.

## Authors

CytoTRACE 2 was developed in the <a href="https://anlab.stanford.edu/" target="_blank">Newman Lab</a> by Minji Kang, Gunsagar Gulati, Erin Brown, Susanna Avagyan, Jose Juan Almagro Armenteros and Rachel Gleyzer.

## Contact

If you have any questions, please contact the CytoTRACE 2 team at cytotrace2team@gmail.com.

## License

Please see the <a href="https://github.com/digitalcytometry/cytotrace2/blob/main/LICENSE">LICENSE</a> file.

## Citation
If you use CytoTRACE 2, please cite: 

**Improved reconstruction of single-cell developmental potential with CytoTRACE 2.** *Nature Methods*, 2025. <br>
Minji Kang<sup>\*</sup>, Gunsagar S. Gulati<sup>\*</sup>, Erin L. Brown<sup>\*</sup>, Zhen Qi<sup>\*</sup>, 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<sup>†</sup>. doi.org/10.1038/s41592-025-02857-2