tcri 0.9.0

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

Documentation · Tutorials · Paper · Issues

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. responders vs non-responders) with direction probabilities.
• 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.10. Install from source:

git clone https://github.com/nceglia/tcri.git
cd tcri
pip install .

The heavy scientific stack (PyTorch, Pyro, scvi-tools, scanpy) is pulled in automatically. A GPU is optional but speeds up model fitting. 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="timepoint",
    batch_key="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. read out information-theoretic metrics (bits)
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")

No paired data yet? tcri.datasets.simulate_tcri() returns a synthetic AnnData whose true mutual information is known in closed form — the basis for the tutorials.

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.

Governance

The public interface, the generative mathematics, the metric definitions and the training plan are each frozen by a machine-checked contract. A published number only means something if the definition behind it is stable, so a metric cannot be silently redefined and the model the package claims to implement is the model it does implement.

A failing conformance test means stop and decide — never loosen a contract to make it pass. See Governance for what each contract covers, and governance/ in the repository for the contracts themselves.

Related tools

Citation

If you use TCRi in your research, please cite:

TCRi: An Information Theoretic Framework for Paired Single Cell Gene Expression and TCR Sequencing

Nicholas Ceglia, Sohrab Salehi, et al.

bioRxiv 2022. doi: 10.1101/2022.10.01.510457

@article{ceglia2022tcri,
  title   = {TCRi: An Information Theoretic Framework for Paired Single Cell Gene Expression and TCR Sequencing},
  author  = {Ceglia, Nicholas and Salehi, Sohrab and others},
  journal = {bioRxiv},
  year    = {2022},
  doi     = {10.1101/2022.10.01.510457}
}

License

TCRi is released under the MIT License.