From 4025c6948c6d050c471815672227ea7cf6ea8da1 Mon Sep 17 00:00:00 2001 From: Nicholas Ceglia Date: Mon, 8 Jun 2026 00:21:49 -0400 Subject: [PATCH] docs: fix fabricated API in README + quickstart Both the README and docs/usage/quickstart.md documented an API that does not exist or is wrong: global_joint_distribution, probability_ternary, polar_plot (deprecation path), register_model phenotype_prob_slot="X_tcri_phenotypes", clonotypic_entropy(adata, cov, "phenotype"), n_latent=10, and more. The README is the PyPI long-description, so it would ship looking authoritative but wrong. Replace both with one accurate, runnable quickstart taken from the test suite (setup_anndata -> TCRIModel -> train -> register_model -> mutual_information / clonotypic_entropy / phenotypic_entropy), and point to the Read the Docs site (real API reference + the D2 concepts page) rather than duplicating a hand-written API in the README. Docs build clean (0 warnings); the fabricated names are gone from the output. Co-Authored-By: Claude Opus 4.8 --- README.md | 186 +++++++-------------------------------- docs/usage/quickstart.md | 124 +++++++++----------------- 2 files changed, 73 insertions(+), 237 deletions(-) diff --git a/README.md b/README.md index 38f0fbe..ad11201 100644 --- a/README.md +++ b/README.md @@ -28,176 +28,51 @@ It provides tools for: - Visualization capabilities - Deep learning model for phenotype prediction -## Core Components - -### 1. Model (`tcri.model`) - -The `TCRIModel` class implements a hierarchical generative Bayesian model for analyzing paired TCR and gene expression data: +## Quick start ```python +import scanpy as sc import tcri +from tcri.model import TCRIModel -# Initialize model -model = tcri.TCRIModel( - adata, - n_latent=10, - n_hidden=128, - global_scale=10.0, - local_scale=5.0, - prior_temperature=1.0, - guide_temperature=1.0, - use_enumeration=False, - device=None -) - -# Train model -model.train( - max_epochs=50, - batch_size=128, - lr=1e-3, - margin_scale=0.0, - margin_value=2.0, - adaptive_margin=False, - reconstruction_loss_scale=1e-2, - n_steps_kl_warmup=1000 -) - -# Get latent representations -latent_z = model.get_latent_representation(adata) -``` - -### 2. Preprocessing (`tcri.preprocessing`) - -Key preprocessing functions: - -```python -# Register model outputs in AnnData -tcri.pp.register_model( - adata, - model, - phenotype_prob_slot="X_tcri_phenotypes", - phenotype_assignment_obs="tcri_phenotype", - latent_slot="X_tcri", - batch_size=256 -) - -# Compute joint distributions -joint_dist = tcri.pp.joint_distribution( - adata, - covariate_label="timepoint", - temperature=1.0, - n_samples=0, - clones=None, - weighted=False -) - -# Global joint distribution -global_dist = tcri.pp.global_joint_distribution( - adata, - temperature=1.0, - n_samples=0 -) -``` - -### 3. Metrics (`tcri.metrics`) - -Information theoretic metrics for analyzing TCR and phenotype relationships: - -```python -# Clonotypic entropy -clonotypic_entropy = tcri.tl.clonotypic_entropy(adata, covariate, phenotype, temperature=1.0) - -# Phenotypic entropy -phenotypic_entropy = tcri.tl.phenotypic_entropy(adata, covariate, clonotype, temperature=1.0) - -# Mutual information -mutual_info = tcri.tl.mutual_information(adata, covariate, temperature=1.0, weighted=False) - -# Clonality -clonality = tcri.tl.clonality(adata) - -# Phenotypic flux -flux = tcri.tl.flux(adata, from_this="T1", to_that="T2", clones=None, temperature=1.0) -``` - -### 4. Plotting (`tcri.plotting`) - -Visualization tools for all metrics: +# AnnData with paired gene expression and, in .obs, columns identifying each +# cell's clonotype, phenotype, covariate (e.g. timepoint), and batch (e.g. patient). +adata = sc.read_h5ad("your_data.h5ad") -```python -# Polar plots -tcri.pl.polar_plot( +# 1. Register the fields and fit the hierarchical model +TCRIModel.setup_anndata( adata, - phenotypes=None, - statistic="distribution", - method="joint_distribution", - splitby=None, - color_dict=None, - temperature=1.0 + clonotype_key="clone_id", # <- your .obs column names + phenotype_key="phenotype", + covariate_key="timepoint", + batch_key="patient", ) +model = TCRIModel(adata) # defaults are sensible; tune n_latent, n_hidden, ... +model.train(max_epochs=200, batch_size=128) -# Ternary plots -tcri.pl.probability_ternary( - adata, - phenotype_names, - splitby=None, - conditions=None, - top_n=None -) +# 2. Write learned distributions, latent embedding, and per-cell phenotype +# posteriors back onto the AnnData (.uns / .obsm / .obs) +tcri.pp.register_model(adata, model, clonotype_key="clone_id") -# Mutual information plots -tcri.pl.mutual_information( - adata, - splitby=None, - temperature=1.0, - n_samples=0, - normalized=True, - palette=None, - save=None, - legend_fontsize=6, - bbox_to_anchor=(1.15,1.), - figsize=(8,4), - rotation=90, - weighted=True, - return_plot=True -) +# 3. Information-theoretic metrics at a covariate value +covariate = adata.uns["tcri_covariate_categories"][0] -# Clonality plots -tcri.pl.clonality( - adata, - groupby=None, - splitby=None, - s=10, - order=None, - figsize=(12,5), - palette=None -) +mi = tcri.tl.mutual_information(adata, covariate) # clone–phenotype coupling (float) +ce = tcri.tl.clonotypic_entropy(adata, covariate, n_samples=50) # Series over phenotypes +pe = tcri.tl.phenotypic_entropy(adata, covariate, n_samples=50) # Series over clones ``` -## Example Usage - -```python -import tcri -import scanpy as sc - -# Load data -adata = sc.read_h5ad("your_data.h5ad") - -# Setup model -model = tcri.TCRIModel(adata) -model.train() +Plotting helpers live under `tcri.pl` — phenotype-flux Sankey diagrams +(`plot_pheno_sankey`), per-cell phenotype probabilities, mutual-information +summaries, and more. See the API reference for the full set. -# Register model outputs -tcri.pp.register_model(adata, model) +## Documentation -# Compute metrics -mi = tcri.tl.mutual_information(adata, "timepoint") -entropy = tcri.tl.clonotypic_entropy(adata, "timepoint", "phenotype") +Full documentation — a conceptual overview of the data model plus the complete +API reference — lives on [Read the Docs](https://tcri.readthedocs.io): -# Visualize results -tcri.pl.mutual_information(adata, splitby="timepoint") -tcri.pl.polar_plot(adata, statistic="entropy") -``` +- **Concepts:** the hierarchical model and the objects `register_model` writes onto your AnnData +- **API reference:** `tcri.model`, `tcri.pp`, `tcri.tl`, `tcri.pl`, `tcri.ut` ## Citation @@ -210,4 +85,3 @@ If you use TCRi in your research, please cite: year={2022} } ``` - diff --git a/docs/usage/quickstart.md b/docs/usage/quickstart.md index 8062b5d..7de7f96 100644 --- a/docs/usage/quickstart.md +++ b/docs/usage/quickstart.md @@ -1,117 +1,79 @@ # Quickstart -This guide will help you get started with TCRi by walking through a basic analysis workflow using sample data. +A minimal end-to-end TCRi workflow. For the concepts behind these objects see +[Data model & concepts](../concepts/data-model.md); for full signatures see the +API reference. -## Loading Data +## Loading data -TCRi works with AnnData objects that contain both gene expression and TCR information. Here's how to load and set up your data: +TCRi works on an `AnnData` with paired gene expression and TCR information. The +`.obs` table needs columns identifying each cell's **clonotype**, **phenotype**, +**covariate** (e.g. timepoint), and **batch** (e.g. patient). ```python -import tcri import scanpy as sc +import tcri +from tcri.model import TCRIModel -# Load your data adata = sc.read_h5ad("your_data.h5ad") - -# Make sure your AnnData object has the right fields for TCR information -# Typically, TCR information should be in obs under 'clone_id' or similar ``` -## Setting up the Model +## Setting up and training the model ```python -# Initialize the model -model = tcri.TCRIModel( +TCRIModel.setup_anndata( adata, - n_latent=10, # Dimension of latent space - n_hidden=128, # Size of hidden layers - global_scale=10.0, - local_scale=5.0 + clonotype_key="clone_id", # your .obs column names + phenotype_key="phenotype", + covariate_key="timepoint", + batch_key="patient", ) -# Train the model -model.train( - max_epochs=50, - batch_size=128, - lr=1e-3, - reconstruction_loss_scale=1e-2 -) - -# Get latent representations -latent_z = model.get_latent_representation(adata) +model = TCRIModel(adata) # defaults are sensible; tune n_latent, n_hidden, ... +model.train(max_epochs=200, batch_size=128) ``` -## Preprocessing +## Registering model outputs -```python -# Register model outputs back to the AnnData object -tcri.pp.register_model( - adata, - model, - phenotype_prob_slot="X_tcri_phenotypes", - phenotype_assignment_obs="tcri_phenotype", - latent_slot="X_tcri" -) +`register_model` writes the learned distributions, latent embedding, per-cell +phenotype posteriors, and indexing arrays back onto the `AnnData` +(`.uns` / `.obsm` / `.obs`) so the metric and plotting functions can read them. -# Compute joint distributions -joint_dist = tcri.pp.joint_distribution( - adata, - covariate_label="timepoint" # Replace with your covariate of interest -) +```python +tcri.pp.register_model(adata, model, clonotype_key="clone_id") ``` -## Computing Metrics +## Computing metrics ```python -# Calculate mutual information -mi = tcri.tl.mutual_information( - adata, - "timepoint", # Replace with your covariate of interest - temperature=1.0 -) +covariate = adata.uns["tcri_covariate_categories"][0] -# Calculate clonotypic entropy -entropy = tcri.tl.clonotypic_entropy( - adata, - "timepoint", # Covariate - "phenotype" # Phenotype field -) +# Mutual information between clonotype and phenotype (point estimate -> float) +mi = tcri.tl.mutual_information(adata, covariate) + +# Clonotypic entropy: a value per phenotype (Series). n_samples > 0 draws from +# the posterior; phenotypic_entropy is the per-clone analogue. +ce = tcri.tl.clonotypic_entropy(adata, covariate, n_samples=50) +pe = tcri.tl.phenotypic_entropy(adata, covariate, n_samples=50) -# Calculate clonality +# Clonality per phenotype clonality = tcri.tl.clonality(adata) ``` ## Visualization -```python -# Mutual information plot -tcri.pl.mutual_information( - adata, - splitby="timepoint", # Replace with your covariate - temperature=1.0, - figsize=(8,4) -) - -# Polar plot of phenotype distributions -tcri.pl.polar_plot( - adata, - statistic="distribution", - method="joint_distribution" -) +Plotting helpers live under `tcri.pl`: -# Phenotype probability ternary plot -tcri.pl.probability_ternary( - adata, - ["Phenotype1", "Phenotype2", "Phenotype3"], # Replace with your phenotype names - splitby="condition" # Optional: split by a condition -) +```python +# Mutual-information summary across covariate groups +tcri.pl.mutual_information(adata, splitby=covariate) ``` -## Next Steps +Other helpers — phenotype-flux Sankey diagrams (`plot_pheno_sankey`), per-cell +phenotype probabilities, and more — are documented in the +[Plotting API](../api/plotting.md). -Explore the API documentation for more detailed information on each function and additional functionality: +## Next steps -- [Model API](../api/model.md) -- [Preprocessing API](../api/preprocessing.md) -- [Metrics API](../api/metrics.md) -- [Plotting API](../api/plotting.md) +- [Data model & concepts](../concepts/data-model.md) — how the model and objects fit together +- [Model API](../api/model.md) · [Preprocessing API](../api/preprocessing.md) · [Metrics API](../api/metrics.md) · [Plotting API](../api/plotting.md)