Update card
Browse files
README.md
CHANGED
|
@@ -13,156 +13,150 @@ pipeline_tag: feature-extraction
|
|
| 13 |
|
| 14 |
# CLEST-TCRdist
|
| 15 |
|
| 16 |
-
|
| 17 |
-
|
| 18 |
-
|
| 19 |
-
A paired-chain αβ
|
| 20 |
-
|
| 21 |
-
|
| 22 |
-
|
| 23 |
-
|
| 24 |
-
|
| 25 |
-
|
| 26 |
-
batch
|
| 27 |
-
|
| 28 |
-
|
| 29 |
-
|
| 30 |
-
|
| 31 |
-
|
| 32 |
-
|
| 33 |
-
|
| 34 |
-
|
| 35 |
-
|
| 36 |
-
|
| 37 |
-
|
| 38 |
-
|
| 39 |
-
|
| 40 |
-
|
| 41 |
-
|
| 42 |
-
|
| 43 |
-
this is a real shrinkage and not environment drift.
|
| 44 |
-
- **It does not beat TCRdist on accuracy, and we do not claim it does.** Over
|
| 45 |
-
seeds the 1-NN margin changes sign. What the objective buys is measured
|
| 46 |
-
against its own autocontrastive control, and a scoring-rule inversion that is
|
| 47 |
-
itself conditional on the evaluation repertoire (see the paper).
|
| 48 |
-
|
| 49 |
-
- **Architecture:** 6-layer Pre-LN / NormFormer transformer encoder,
|
| 50 |
-
d_model = 128, 8 heads, `CdrSimpleEmbedder` (embedding_dim = 29), CLS-token
|
| 51 |
-
readout. ~1.2 M parameters.
|
| 52 |
-
- **Output:** L2-comparable 128-d embedding per TCR
|
| 53 |
-
(`calc_vector_representations`); pairwise distances via
|
| 54 |
-
`calc_cdist_matrix` / `calc_pdist_vector`.
|
| 55 |
-
- **Inference is epitope-free:** the model sees only the TCR, never the epitope.
|
| 56 |
-
|
| 57 |
-
## How to use
|
| 58 |
|
| 59 |
```python
|
| 60 |
-
|
|
|
|
| 61 |
|
| 62 |
-
model =
|
| 63 |
-
|
| 64 |
-
|
| 65 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 66 |
```
|
| 67 |
|
| 68 |
-
|
| 69 |
-
|
| 70 |
-
|
| 71 |
-
|
| 72 |
-
##
|
| 73 |
-
|
| 74 |
-
|
| 75 |
-
epitope (the reference set) and it scores **any query TCR** for how strongly
|
| 76 |
-
it is specific to that epitope — no epitope sequence and no classifier
|
| 77 |
-
retraining required. It is the epitope-free, learned analogue of TCRMatch and
|
| 78 |
-
tcrdist3 meta-clonotypes. On the paper's fourteen-method slate this
|
| 79 |
-
checkpoint ranks first (NN AUROC@50 = 0.801, prototype AUROC@50 = 0.860), but
|
| 80 |
-
that ranking should be read with two controls attached: the checkpoint was
|
| 81 |
-
selected on the same epitope panel it is scored on (moving selection to six
|
| 82 |
-
held-out epitopes costs 0.013), and it is a single unseeded run that sits above
|
| 83 |
-
all three of its seeded replicates. The margin over TCRdist does not survive
|
| 84 |
-
either control, and does not survive giving TCRdist its own published read-out
|
| 85 |
-
either (Dash et al. score the nearest 10% of the reference set, not the nearest
|
| 86 |
-
one; under each method's own best rule the comparison is a draw, +0.010,
|
| 87 |
-
p = 0.42). The durable comparison is against the matched autocontrastive
|
| 88 |
-
control. Note that the prototype-over-nearest-neighbour gain is **not** specific
|
| 89 |
-
to this objective: once the control is reseeded it gains +0.041 from prototype
|
| 90 |
-
scoring against this model's +0.034, so that inversion is a property of the
|
| 91 |
-
evaluation repertoire rather than of the training target.
|
| 92 |
|
| 93 |
```python
|
| 94 |
-
|
| 95 |
-
from scaled_sceptr.hf_hub import load_champion
|
| 96 |
|
| 97 |
-
|
|
|
|
|
|
|
|
|
|
| 98 |
|
| 99 |
-
|
| 100 |
-
# query = TCRs you want to score (a repertoire, a screen, etc.)
|
| 101 |
-
# both are DataFrames with columns TRAV, CDR3A, TRAJ, TRBV, CDR3B, TRBJ
|
| 102 |
-
cdist = model.calc_cdist_matrix(query, reference) # (n_query, k)
|
| 103 |
|
| 104 |
-
|
| 105 |
-
|
| 106 |
-
|
| 107 |
-
proto_score = -cdist.mean(axis=1) # (n_query,)
|
| 108 |
|
| 109 |
-
|
| 110 |
-
|
| 111 |
-
|
| 112 |
|
| 113 |
-
|
|
|
|
|
|
|
|
|
|
| 114 |
```
|
| 115 |
|
| 116 |
-
|
| 117 |
-
|
| 118 |
-
|
| 119 |
-
|
| 120 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 121 |
|
| 122 |
## Training
|
| 123 |
|
| 124 |
-
|
| 125 |
-
|
| 126 |
-
|
| 127 |
-
|
| 128 |
-
|
| 129 |
-
|
| 130 |
-
|
| 131 |
-
|
| 132 |
-
|
| 133 |
-
|
| 134 |
-
|
| 135 |
-
|
| 136 |
-
|
| 137 |
-
|
| 138 |
-
|
| 139 |
-
|
| 140 |
-
|
| 141 |
-
|
| 142 |
-
1-NN scoring, `--max-neg 5000`, 100 repeats). AUROC, equal-weighted across
|
| 143 |
-
epitopes:
|
| 144 |
-
|
| 145 |
-
| Model | AUROC@50 | AUROC@200 |
|
| 146 |
-
|---|---|---|
|
| 147 |
-
| **CLEST-TCRdist (this model)** | **0.7945** | **0.8138** |
|
| 148 |
-
| TCRdist (reference) | 0.7787 | 0.8020 |
|
| 149 |
-
| SCEPTR (base AC, published) | 0.7360 | 0.7459 |
|
| 150 |
-
| CDR3 Levenshtein | 0.6989 | — |
|
| 151 |
-
|
| 152 |
-
The headline number reproduces exactly (`0.79448`) from the published
|
| 153 |
-
checkpoint with the command in the repo README.
|
| 154 |
-
|
| 155 |
-
**Scope / caveats.**
|
| 156 |
-
- This is a **TCR-to-TCR similarity** model, not an epitope classifier. It
|
| 157 |
-
predicts binding only by retrieval against a labeled reference set.
|
| 158 |
-
- The scaling study found this recipe is **plateaued**: deeper (12L), wider
|
| 159 |
-
(d=256), modern-norm (RMSNorm/SwiGLU/QK-Norm), and larger-corpus variants all
|
| 160 |
-
tie or lose to this 6L Tanno-only recipe.
|
| 161 |
-
- ~8.6% of Tanno CDR3β sequences also appear in VDJdb — the field-standard
|
| 162 |
-
background contamination shared by TCRdist and the published SCEPTR baseline
|
| 163 |
-
alike; a CDR3β-clean leak-free benchmark preserves the same small advantage.
|
| 164 |
|
| 165 |
## Citation
|
| 166 |
|
| 167 |
-
|
| 168 |
-
(
|
|
|
|
|
|
|
|
|
|
|
|
| 13 |
|
| 14 |
# CLEST-TCRdist
|
| 15 |
|
| 16 |
+
Contrastive LEarning with Soft Targets from TCRdist. Checkpoint
|
| 17 |
+
`SCEPTR6L_AC_soft_800k_20ep_bs1024`.
|
| 18 |
+
|
| 19 |
+
A paired-chain αβ T-cell receptor encoder. It maps a TCR to a 128-dimensional vector in
|
| 20 |
+
which receptors that recognise the same peptide sit close together, so retrieval and
|
| 21 |
+
clustering of specificity groups reduce to nearest-neighbour search. The model reads only
|
| 22 |
+
the receptor, never the epitope.
|
| 23 |
+
|
| 24 |
+
It is built on [SCEPTR](https://github.com/yutanagano/sceptr) (Nagano et al. 2025, *Cell
|
| 25 |
+
Systems*) and changes one term of its objective. Autocontrastive pretraining treats every
|
| 26 |
+
other receptor in a batch as a negative. Here each in-batch pair gets a graded target
|
| 27 |
+
`exp(-d_TCRdist / 50)`, zero beyond a TCRdist of 200, computed on the fly with tcrdist3.
|
| 28 |
+
No epitope labels are involved, and nothing is precomputed. Architecture, corpus,
|
| 29 |
+
augmentation and batch size are held fixed against an autocontrastive control trained the
|
| 30 |
+
same way, which is what makes the comparison between them a single-variable one.
|
| 31 |
+
|
| 32 |
+
## Install
|
| 33 |
+
|
| 34 |
+
```bash
|
| 35 |
+
pip install git+https://github.com/20eddibae/CLEST-TCRDist.git
|
| 36 |
+
pip install --no-deps sceptr==1.2.0
|
| 37 |
+
```
|
| 38 |
+
|
| 39 |
+
sceptr goes in with `--no-deps` because its metadata asks for numpy 2 while tcrdist3 needs
|
| 40 |
+
1.26. Everything it actually imports is already installed by the line above.
|
| 41 |
+
|
| 42 |
+
## Use it
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 43 |
|
| 44 |
```python
|
| 45 |
+
import pandas as pd
|
| 46 |
+
from clest_tcrdist import load_pretrained
|
| 47 |
|
| 48 |
+
model = load_pretrained() # pulls ~5 MB here, then caches
|
| 49 |
+
|
| 50 |
+
tcrs = pd.DataFrame({
|
| 51 |
+
"TRAV": ["TRAV35*01"], "CDR3A": ["CAGQLGGGSQGNLIF"], "TRAJ": ["TRAJ42*01"],
|
| 52 |
+
"TRBV": ["TRBV19*01"], "CDR3B": ["CASSIRSSYEQYF"], "TRBJ": ["TRBJ2-7*01"],
|
| 53 |
+
})
|
| 54 |
+
vectors = model.calc_vector_representations(tcrs) # (N, 128)
|
| 55 |
+
distances = model.calc_cdist_matrix(tcrs, tcrs) # (N, N)
|
| 56 |
```
|
| 57 |
|
| 58 |
+
The returned object is a `sceptr.model.Sceptr`, so anything written against the SCEPTR API
|
| 59 |
+
works unchanged. Columns are IMGT symbols and amino-acid junctions. A missing chain or gene
|
| 60 |
+
can be left empty, and single-chain input is accepted.
|
| 61 |
+
|
| 62 |
+
### Few-shot retrieval
|
| 63 |
+
|
| 64 |
+
Given a few known binders for one epitope, rank a repertoire:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 65 |
|
| 66 |
```python
|
| 67 |
+
from clest_tcrdist import read_tcrs, retrieve
|
|
|
|
| 68 |
|
| 69 |
+
repertoire = read_tcrs("repertoire.csv") # any common column naming
|
| 70 |
+
seeds = read_tcrs("known_binders.csv")
|
| 71 |
+
ranked = retrieve(repertoire, seeds, model=model) # sorted best first
|
| 72 |
+
```
|
| 73 |
|
| 74 |
+
or from the shell:
|
|
|
|
|
|
|
|
|
|
| 75 |
|
| 76 |
+
```bash
|
| 77 |
+
python -m clest_tcrdist.retrieve repertoire.csv --seeds known_binders.csv -o ranked.csv
|
| 78 |
+
```
|
|
|
|
| 79 |
|
| 80 |
+
Scoring is distance to the mean seed embedding by default, or to the nearest single seed
|
| 81 |
+
with `--scoring nearest`. Averaging over the seeds is worth about 0.05 AUROC to this model
|
| 82 |
+
and is what the headline number below uses.
|
| 83 |
|
| 84 |
+
### Clustering
|
| 85 |
+
|
| 86 |
+
```bash
|
| 87 |
+
python -m clest_tcrdist.cluster repertoire.csv -o clustered.csv
|
| 88 |
```
|
| 89 |
|
| 90 |
+
Pairs within a radius are linked and connected components become clusters, the same
|
| 91 |
+
construction GIANA and TCRdist use, with the radius measured in this embedding. The radius
|
| 92 |
+
is calibrated from the data unless you set `--threshold`, and it controls a purity against
|
| 93 |
+
retention tradeoff: on 120 TCRs across four epitopes, purity is 1.00 out to 20% retention,
|
| 94 |
+
then 0.88 at 30% and 0.74 at 40%. `--sweep` prints that curve for a labelled file. Compare
|
| 95 |
+
clustering methods at matched retention, never at matched radius.
|
| 96 |
+
|
| 97 |
+
## How it scores
|
| 98 |
+
|
| 99 |
+
Few-shot retrieval on the six-epitope VDJdb backtest of the SCEPTR paper, 100 resamplings
|
| 100 |
+
of the reference set, mean AUROC over epitopes, nearest-neighbour scoring:
|
| 101 |
+
|
| 102 |
+
| Reference TCRs | CLEST-TCRdist | TCRdist | SCEPTR (released) | CDR3 Levenshtein |
|
| 103 |
+
|---|---|---|---|---|
|
| 104 |
+
| 1 | 0.701 | 0.684 | 0.643 | 0.621 |
|
| 105 |
+
| 10 | 0.765 | 0.756 | 0.710 | 0.687 |
|
| 106 |
+
| 50 | 0.794 | 0.779 | 0.737 | 0.699 |
|
| 107 |
+
| 200 | 0.814 | 0.802 | 0.754 | 0.708 |
|
| 108 |
+
|
| 109 |
+
## Read this before quoting a number
|
| 110 |
+
|
| 111 |
+
**These weights are one training run, not an average.** The checkpoint predates seeding in
|
| 112 |
+
our pipeline. Five seeded replicates of the identical configuration average 0.7750 ± 0.0076
|
| 113 |
+
at nearest-neighbour and 0.8104 ± 0.0053 under average-distance scoring, where this run
|
| 114 |
+
gives 0.7945 and 0.8423. It sits above all five in every cell, 2.5 seed standard deviations
|
| 115 |
+
out at nearest-neighbour and 6.0 under averaging. Treat the replicate means as what the
|
| 116 |
+
recipe gives you, and this checkpoint as a lucky draw from it. All five replicates are in
|
| 117 |
+
the paper's supplement.
|
| 118 |
+
|
| 119 |
+
**What the objective is worth is measured against its own control, not against TCRdist.**
|
| 120 |
+
With the full set of replicates the soft-label target buys +0.039 AUROC@50 at
|
| 121 |
+
nearest-neighbour over the matched autocontrastive control (paired over six epitopes,
|
| 122 |
+
p = 0.043, positive on five) and +0.048 under averaging (p = 0.119). Across estimators the
|
| 123 |
+
range is +0.038 to +0.056. That single-variable comparison is the contribution.
|
| 124 |
+
|
| 125 |
+
**It does not reliably beat TCRdist, and we do not claim it does.** The margin in the table
|
| 126 |
+
above does not survive two controls: reselecting hyperparameters on held-out epitopes costs
|
| 127 |
+
about 0.013, and giving TCRdist the read-out from its own publication rather than the 1-NN
|
| 128 |
+
rule inherited here closes the rest. Over seeds the sign of the 1-NN margin changes. What
|
| 129 |
+
holds up is the gap over the control.
|
| 130 |
+
|
| 131 |
+
**It is not an epitope-binding classifier.** There is no peptide or MHC input. It tells you
|
| 132 |
+
which receptors resemble each other in a space shaped by specificity; it cannot tell you
|
| 133 |
+
that a receptor binds a peptide you have not given it examples of.
|
| 134 |
|
| 135 |
## Training
|
| 136 |
|
| 137 |
+
- 6-layer Pre-LN transformer with NormFormer norms, d_model 128, 8 heads, dropout 0.1,
|
| 138 |
+
`CdrSimpleEmbedder` (29-dim token embedding), CLS readout, 1,203,860 parameters.
|
| 139 |
+
- 827,802 unlabeled paired αβ TCRs from Tanno et al. 2022
|
| 140 |
+
([Zenodo 14288119](https://doi.org/10.5281/zenodo.14288119)). No epitope labels anywhere
|
| 141 |
+
in pretraining.
|
| 142 |
+
- 20 epochs, batch 1024, Noam schedule with 2000 warmup steps, contrastive temperature
|
| 143 |
+
0.05, masked-token auxiliary loss with 0.1 label smoothing.
|
| 144 |
+
- Shipped epoch is the one with the lowest validation contrastive loss, epoch 20. The
|
| 145 |
+
repository contains `config.json` and `log.csv` for the whole run.
|
| 146 |
+
|
| 147 |
+
## Also here
|
| 148 |
+
|
| 149 |
+
- [Fine-tuned variant](https://huggingface.co/20eddibae/sceptr-ac-finetuned), for when you
|
| 150 |
+
have epitope labels to train on.
|
| 151 |
+
- [Benchmark data](https://huggingface.co/datasets/20eddibae/sceptr-tcr-benchmark), the
|
| 152 |
+
VDJdb snapshot these numbers come from.
|
| 153 |
+
- [Code](https://github.com/20eddibae/CLEST-TCRDist), including the training configs and
|
| 154 |
+
the benchmark that produced the table.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 155 |
|
| 156 |
## Citation
|
| 157 |
|
| 158 |
+
The manuscript is in preparation; cite the repository until it appears. Please also cite
|
| 159 |
+
SCEPTR (Nagano et al., *Cell Systems* 2025), TCRdist (Dash et al., *Nature* 2017), the
|
| 160 |
+
Tanno et al. 2022 paired repertoire, and VDJdb (Bagaev et al. 2020).
|
| 161 |
+
|
| 162 |
+
MIT licensed.
|