tcri 0.14.0

Information-theoretic analysis of paired single-cell RNA + TCR sequencing.

Documentation · Tutorials · Paper · Issues · Contributing

TCRi quantifies how T-cell clonotypes relate to transcriptional phenotypes in paired single-cell data. It fits a hierarchical Bayesian model (on top of scvi-tools / Pyro) that ties each clone's phenotype distribution to gene expression, then reads out information-theoretic summaries — clonotypic and phenotypic entropy, clone↔phenotype mutual information, and phenotypic flux across conditions — over the learned clone × phenotype joint distribution.

It is built on the scverse stack (AnnData, scanpy, scvi-tools) and works on a standard AnnData carrying both a clonotype label and a gene-expression matrix.

Key capabilities

• Joint model of expression + repertoire — a hierarchical VAE (TCRIModel) that learns each clone's phenotype distribution while reconstructing counts with a ZINB decoder.
• Information-theoretic metrics — clonotypic entropy H(c|φ), phenotypic entropy H(φ|c), normalized mutual information I(c;φ), and phenotypic flux between conditions, all in bits over the posterior joint.
• Uncertainty-aware — every metric can be reported as a posterior mean ± HDI by drawing from the fitted Dirichlet posterior (n_samples > 0).
• Group comparisons — paired/unpaired contrasts across cohorts (e.g. disease vs control), with n counting replicates rather than items.
• Diagnostics — posterior-predictive checks, phenotype calibration, and permutation nulls for the metrics.
• Contract-governed — the public API, the generative model, the metric definitions, and the training plan are each frozen by a machine-checked contract.

Installation

TCRi targets Python ≥ 3.12.

pip install tcri

The heavy scientific stack (PyTorch, Pyro, scvi-tools, scanpy) is pulled in automatically. A GPU is optional but speeds up model fitting.

For the development version:

git clone https://github.com/nceglia/tcri.git
cd tcri
pip install -e ".[test,mudata]"

See the installation guide for details.

Quickstart

import tcri

# 1. register clonotype / phenotype / covariate / batch columns on your AnnData
tcri.ml.TCRIModel.setup_anndata(
    adata,
    layer="counts",
    clonotype_key="clone_id",
    phenotype_key="phenotype",
    covariate_key="condition",
    batch_key="patient",
    replicate="patient",
)

# 2. fit the model and write learned quantities back onto the AnnData
model = tcri.ml.TCRIModel(adata)
model.train(max_epochs=200, batch_size=512)
model.to_anndata(adata)

# 3. fit the permutation references, once: every metric is read against one
tcri.null.all(model, adata)

# 4. read out information-theoretic metrics (bits), each with its own floor
#    -> value, null_value, adjusted = value - null_value
mi = tcri.tl.mutual_information(adata, covariate="pre", normalize_mode="average")
ce = tcri.tl.clonotypic_entropy(adata, covariate="pre")
flux = tcri.tl.phenotypic_flux(adata, cov_from="pre", cov_to="post")

# 5. ask the fitted model which genes the phenotype calls rest on
tcri.perturb.gene_importance(model, adata, splitby="disease_status")
tcri.pl.gene_importance(adata)

No paired data yet? tcri.datasets.simulate_cohort() returns a synthetic AnnData with patients as replicates, an ordered condition axis within each, and a disease_status label between them — the basis for the tutorials. tcri.datasets.simulate_tcri() is the single-sample alternative, with a mutual information known in closed form.

Framework

TCRi models the joint distribution of clonotype and phenotype hierarchically: a clonotype-level prior p_c over phenotypes, a covariate-specific p_ct anchored to it, and a per-cell phenotype that fuses a classifier on the latent embedding z with the clone's local prior. The metrics are then pure functions of the learned clone × phenotype joint. The full generative model and its plate diagram are documented under Concepts.

Citation

If you use TCRi in your research, please cite:

An information-theoretic framework for inferring T-cell dynamics from single-cell RNA and T-cell receptor sequencing

Nicholas Ceglia, Sohrab Salehi, et al.

Nature Genetics, In Press 2026.

@article{ceglia2026tcri,
  title   = {An information-theoretic framework for inferring T-cell dynamics from single-cell RNA and T-cell receptor sequencing},
  author  = {Ceglia, Nicholas and Salehi, Sohrab and others},
  journal = {Nature Genetics},
  year    = {2026},
  note    = {In press}
}

License

TCRi is released under the MIT License.