TUF is a lightweight Python package for quantifying uncertainty in single-cell trajectory inference. Rather than inferring trajectories itself, TUF operates downstream of existing trajectory inference methods to identify regions of developmental trajectories exhibiting high temporal uncertainty and directional ambiguity.
The framework introduces two complementary uncertainty metrics:
- Temporal Entropy Score (TES): quantifies local temporal mixing among neighboring cells.
- Trajectory Divergence Score (TDS): measures directional ambiguity and branch divergence within the local neighborhood.
TUF integrates seamlessly with Scanpy workflows and is compatible with any trajectory inference method that stores pseudotime values in an AnnData object.
Trajectory inference methods estimate developmental progression but generally do not quantify the confidence of those estimates. TUF complements existing trajectory inference algorithms by providing local uncertainty measures that help identify
- Transitional cell states
- Regions with mixed temporal identity
- Branch points with ambiguous developmental direction
- Cells where trajectory assignments are less reliable
As a post-hoc analysis framework, TUF can be incorporated into existing trajectory inference workflows without modifying the underlying algorithms.
- Native support for
AnnData - Seamless integration with Scanpy
- Automatic pseudotime detection
- Graph-based uncertainty quantification
- Publication-quality visualization
- Lightweight with minimal dependencies
- Compute TES and TDS individually or together
Currently, TUF can be installed directly from GitHub.
git clone https://github.com/Sizerta/tuf_python.git
cd tuf_python
pip install -e .PyPI support is planned for a future release.
import scanpy as sc
from tuf import compute_tuf, plot_tuf
# Load example dataset
adata = sc.datasets.pbmc3k()
# Standard Scanpy preprocessing
sc.pp.normalize_total(adata)
sc.pp.log1p(adata)
sc.pp.highly_variable_genes(adata)
adata = adata[:, adata.var.highly_variable]
sc.pp.pca(adata)
sc.pp.neighbors(adata)
# Compute pseudotime
sc.tl.diffmap(adata)
sc.tl.dpt(adata)
# Compute trajectory uncertainty
compute_tuf(adata)
# Visualize the results
plot_tuf(adata)from tuf import compute_tes, compute_tds
compute_tes(adata)
compute_tds(adata)Visualize the results
from tuf import plot_tes, plot_tds
plot_tes(adata)
plot_tds(adata)After computation, TUF stores the following quantities in adata.obs.
| Column | Description |
|---|---|
traj_unc_tes |
Temporal Entropy Score (TES) |
traj_unc_tds |
Trajectory Divergence Score (TDS) |
These scores can be used for downstream visualization, statistical analysis, and identification of uncertain or transitional cell populations.
| Function | Description |
|---|---|
compute_tes() |
Compute the Temporal Entropy Score |
compute_tds() |
Compute the Trajectory Divergence Score |
compute_tuf() |
Compute both TES and TDS |
plot_tes() |
Visualize TES on a UMAP embedding |
plot_tds() |
Visualize TDS on a UMAP embedding |
plot_tuf() |
Display TES, TDS, and pseudotime together |
If you work in Julia, you may also be interested in SiCell.jl, a high-performance framework for single-cell RNA-seq analysis featuring preprocessing, quality control, dimensionality reduction, clustering, trajectory inference, differential expression, visualization, and more.
SiCell.jl: https://github.com/Sizerta/SiCell.jl
- Python ≥ 3.10
- NumPy
- Scanpy
- AnnData
- Matplotlib
If you use TUF in your research, please cite the GitHub repository until the accompanying manuscript is published.
Masoud Mahdavifar.
TUF: Trajectory Uncertainty Framework.
GitHub repository.
https://github.com/Sizerta/tuf_python
The manuscript describing the methodology is currently in preparation.
This project is licensed under the MIT License. See the LICENSE file for details.
Contributions, bug reports, feature requests, and pull requests are welcome. If you encounter an issue or have suggestions for improvement, please open an issue on GitHub.
TUF builds upon the excellent scientific Python ecosystem, particularly
- Scanpy
- AnnData
- NumPy
- Matplotlib