20eddibae/CLEST-TCRdist-finetuned

CLEST-TCRdist, supervised fine-tune

Checkpoint CLEST_TCRdist_finetuned_full: CLEST-TCRdist fine-tuned on labelled VDJdb. Same architecture as CLEST-TCRdist, 6 layers and d_model 128. Positives during fine-tuning are receptors annotated to the same epitope, so the embedding is pulled tight around the specificities present in the training labels.

Use this when you have epitope labels and want the strongest retrieval you can get on those epitopes. Use CLEST-TCRdist when you do not have labels, or when you need a number that is comparable to label-free methods.

Use it

from clest_tcrdist import load_model
from huggingface_hub import snapshot_download

model = load_model(snapshot_download("20eddibae/CLEST-TCRdist-finetuned"))
vectors = model.calc_vector_representations(tcrs)          # (N, 128)
distances = model.calc_cdist_matrix(queries, references)   # min or mean gives a score

Retrieval and clustering work exactly as on the zero-shot model:

python -m clest_tcrdist.retrieve repertoire.csv --seeds binders.csv --model-dir <snapshot dir>

How it scores, and why the number is not comparable

Leak-free benchmark: positives drawn from the valid_filtered.csv split that was held out of fine-tuning, six epitopes, nearest-neighbour scoring, 100 repeats per reference size.

References	This model	Same fine-tune from the autocontrastive control	CLEST-TCRdist, no fine-tune	TCRdist
1	0.976	0.979	0.711	0.673
5	0.982	0.982	0.774	0.746
20	0.976	0.975	0.796	0.726
50	0.959	0.948	0.723	0.722

From 50 references up only two epitopes (GILGFVFTL, NLVPMVATV) have enough held-out binders, so those rows average two epitopes, not six.

Starting the fine-tune from CLEST-TCRdist instead of the autocontrastive checkpoint makes no measurable difference. Paired over epitopes, the gap is within ±0.004 AUROC from 1 to 20 references (p > 0.2 at every size), and the larger gaps at 50 references and above rest on two epitopes (p ≥ 0.5). Once labels are available, the label-free pretraining is not what sets the result.

These numbers are much higher than any label-free method here and they are not a like-for-like comparison. The model has been trained on epitope labels, including the epitopes it is evaluated on. It has learned where these specificity groups live; it has not demonstrated that it can find a group it was never shown.

• Do not put this number next to CLEST-TCRdist, TCRdist or GIANA figures. They answer a different question.
• Evaluate any fine-tune on a pool held out of fine-tuning. The standard benchmark pool in this project draws positives from the same table the fine-tune trained on, which inflates the result. In the repository's benchmark that is --protocol leakfree.

Expect it to degrade on epitopes outside its training labels. We have not characterised that falloff, so treat it as a model for the specificities in VDJdb rather than a general one.

Training

• Base: CLEST-TCRdist (SCEPTR6L_AC_soft_800k_20ep_bs1024, epoch 20), pretrained label-free on unlabelled Tanno et al. TCRs with TCRdist soft labels.
• Fine-tune: supervised contrastive loss with same-epitope positives plus the masked-token auxiliary loss, on the labelled VDJdb training split (train_filtered.csv, ~42k paired receptors). 20 epochs, batch size 512. The recipe is identical to the comparison fine-tune in the table, which starts from the autocontrastive control (SCEPTR6L_AC); only the starting checkpoint differs.
• Shipped epoch: 1, the epoch with the lowest validation contrastive loss on the held-out split (log.csv). Validation loss rises after it, and load_model applies the same rule, so the weights here are the ones the table scores.
• Architecture unchanged from the base: 6 layers, d_model 128, 8 heads, dropout 0.1.

Also here

• CLEST-TCRdist, the label-free model.
• Benchmark data.
• Code.

Citation

Built on SCEPTR (Nagano et al., Cell Systems 2025) and TCRdist (Dash et al., Nature 2017). Fine-tuning labels from VDJdb (Bagaev et al. 2020). MIT licensed.