Kompot

Kompot is a Python package for differential abundance and gene expression analysis using Gaussian Process models with JAX backend.

Overview

Kompot implements methodologies from the Mellon package for computing differential abundance and gene expression, with a focus on using Mahalanobis distance as a measure of differential expression significance. It leverages JAX for efficient computations and provides a scikit-learn like API with .fit() and .predict() methods.

Key features:

• Computation of differential abundance between conditions

• Gene expression smoothing and uncertainty estimation

• Mahalanobis distance calculation for differential expression significance

• Weighted log fold change analysis with density difference weighting

• Support for covariance matrices and optional landmarks

• JAX-accelerated computations

• Empirical variance estimation

• Resource estimation and dry run for planning large analyses

• Disk-backed covariance storage for sample variance estimation (see Planning Memory and Disk)

• Visualization tools (volcano plots, heatmaps, expression plots)

• Full scverse compatibility with direct AnnData integration

• Command-line interface for pipeline integration and batch processing

Use Cases

Kompot is particularly useful for:

• Comparing cell type abundances across different samples

• Identifying differentially expressed genes between conditions

• Integrating multi-sample or multi-batch variability

• Handling large covariance tensors during sample variance estimation via disk-backed storage

• Creating visualizations of differential analysis results

Installation

Install from PyPI:

pip install kompot

Or via conda/mamba:

conda install -c bioconda kompot

For optional dependencies and JAX GPU support, see the installation guide.

Quick Start

import kompot

# Minimal call — uses sensible defaults
kompot.de(adata, "condition", "Young", "Old")

# Differential abundance
kompot.da(adata, "condition", "Young", "Old")

# Customize GP and FDR settings
kompot.de(
    adata, "condition", "Young", "Old",
    gp=kompot.GPSettings(sigma=0.5, use_empirical_variance=True),
    fdr=kompot.FDRSettings(threshold=0.01),
)

See AnnData Interface for the full API and all available settings.

Warning

Adding sample_col turns on sample variance, which gives every gene its own landmark covariance matrix and its own Cholesky factorisation. At default settings that is roughly 0.37 GiB and ~2 s per gene, so it belongs in a second pass over a restricted gene list rather than a whole-transcriptome run. Read Planning Memory and Disk before your first sample-variance run.

New to Kompot? Start with the Getting Started tutorial: differential expression, end to end, with rich visualizations.

Ready for more? Explore advanced topics:

• Advanced Differential Expression - Parameter tuning, multiple comparisons, run tracking, and resource planning

• DE with Sample Variance - Replicate-aware significance in multi-sample studies

• Differential Abundance - Cell-state frequency changes, including its sample-variance treatment

• Smoothing Expression - The expression function underneath DE: reading its two uncertainties, and fitting on some cells to predict on others

• Planning Memory and Disk - What sample variance costs, the two-pass workflow, and pricing a run with dry_run=True

Command-Line Interface

For pipeline integration and batch processing, use the Command-Line Interface:

# Compute diffusion maps (preprocessing)
kompot dm input.h5ad -o input_dm.h5ad --pca-key X_pca

# Run differential expression
kompot de input_dm.h5ad -o results.h5ad \
  --groupby condition --condition1 control --condition2 treatment \
  --obsm-key DM_EigenVectors

See the CLI documentation for complete usage and examples.

Citation

If you use Kompot in your research, please cite:

Otto, D. J., Arriaga-Gomez, E., Thieme, E., Yang, R., Lee, S. C., & Setty, M. (2025). Comparing phenotypic manifolds with Kompot: Detecting differential abundance and gene expression at single-cell resolution. bioRxiv. https://doi.org/10.1101/2025.06.03.657769

BibTeX:

@article{Otto2025.06.03.657769,
    author = {Otto, Dominik J. and Arriaga-Gomez, Erica and Thieme, Elana and Yang, Ruijin and Lee, Stanley C. and Setty, Manu},
    title = {Comparing phenotypic manifolds with Kompot: Detecting differential abundance and gene expression at single-cell resolution},
    year = {2025},
    doi = {10.1101/2025.06.03.657769},
    publisher = {Cold Spring Harbor Laboratory},
    journal = {bioRxiv},
    URL = {https://www.biorxiv.org/content/10.1101/2025.06.03.657769}
}

Index

• Index