Skip to content

docs: fix fabricated API in README + quickstart #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
nceglia wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: fix fabricated API in README + quickstart #28

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
186 changes: 30 additions & 156 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -210,4 +85,3 @@ If you use TCRi in your research, please cite:
year={2022}
}
```

124 changes: 43 additions & 81 deletions docs/usage/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
Loading