Add tcrblosum support to TCRdist

[felixpetschko]

So far, the TCRdist metric used a distance matrix derived from the blosum62 substitution matrix. This PR extends TCRdistDistanceCalculator with a new base_matrix="tcrblosum" option alongside the existing default blosum62 behavior. This way, distance matrices based on the tcrblosum substitution matrices (different matrices for alpha and beta chain) are used for the TCRdist metric calculation.

I try to illustrate how I derived the tcrblosum based distance matrices in this google colab notebook.

The usage of the tcrblosum matrices was already discussed in #591.

[codecov]

Codecov Report

❌ Patch coverage is 29.41176% with 12 lines in your changes missing coverage. Please review.
✅ Project coverage is 19.20%. Comparing base (c0a3947) to head (09da693).

Files with missing lines	Patch %	Lines
src/scirpy/ir_dist/metrics.py	28.57%	10 Missing ⚠️
src/scirpy/ir_dist/__init__.py	33.33%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #685      +/-   ##
==========================================
- Coverage   19.31%   19.20%   -0.12%     
==========================================
  Files          51       51              
  Lines        4633     4645      +12     
==========================================
- Hits          895      892       -3     
- Misses       3738     3753      +15     

Files with missing lines	Coverage Δ
src/scirpy/ir_dist/__init__.py	21.21% <33.33%> (ø)
src/scirpy/ir_dist/metrics.py	13.81% <28.57%> (-0.84%)	⬇️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[grst]

Implementation-wise this looks great!

What's still missing is

• changelog update
• Documentation-update of the user-facing (pp.ir_dist) method. Probably best to add a new metric tcrblosum or tcrdist_tcrblosum.
• Reference to the TCRblosum paper in the documentation
• Maybe tutorial update?

[grst]

Did you make any modifications to the original TCRblosum matrix? e.g. the cap at 4?

[felixpetschko]

First of all, you always have this conversion from the substitution matrix (blosum62, tcrblosum) to a distance matrix.
In the tcrblosum paper , they just menttion "Firstly, we transformed the tcrBLOSUM similarity matrix into a distance matrix according to the rules of TCRdist [12]".

In the original TCRdist paper they write:
"The mismatch distance is defined based on the BLOSUM62 (ref. 37) substitution matrix as follows: distance (a, a)=0; distance (a, b)=min (4, 4-BLOSUM62 (a, b)), where 4 is 1 unit greater than the most favourable BLOSUM62 score for a mismatch, and a and b are amino acids".

Now there would be two options:

1. also use the constant cap 4 like in the original tcrdist paper
2. use a cap that is one unit greater than the most favourable score

However, the most favourable score would be 1 for tcrblosum_alpha and 2 for tcrblosum_beta which would result in a quite low cap (see matrices in notebook). Therefore I just went with the fixed cap of 4 for the transformation formula from substitution matrix to distance matrix of the original tcrdist implementation:
distance(a, a) = 0 and distance(a, b) = min(4, 4 - score)

Unfortunately, I wasn't able to find out how they did it exactly in the tcrblosum paper. Another thing to consider is, that the distance values for alpha and beta chain might be compared later during the clonotype clustering. Therefore having two different caps might cause problems.

What do you think would be the best option?

[grst]

Dear @apostovskaya,

we are working on integrating your tcrBLOSUM matrix into scirpy, which contains a reimplementation of the TCRdist algorithm.

We are unsure how you intended the matrix to be used with TCRdist. Could you please clarify what you mean with

Firstly, we transformed the tcrBLOSUM similarity matrix into a distance matrix according to the rules of TCRdist [12]

in your paper and how you would suggest to set the cap?

[grst]

"The mismatch distance is defined based on the BLOSUM62 (ref. 37) substitution matrix as follows: distance (a, a)=0; distance (a, b)=min (4, 4-BLOSUM62 (a, b)), where 4 is 1 unit greater than the most favourable BLOSUM62 score for a mismatch, and a and b are amino acids".

tbh, I never understood this part about TCRdist. It skews the matrix quite a bit, basically assigning a distance of 4 to all mismatches that have a negative distance in BLOSUM62 (even if it's just -1). So the only way to get a score $1 \leq s \leq 3$ is if you have one of the rare pairs with a positive mismatch score according to BLOSUM62.

Having a cap of 2 with TCRblosum doesn't make sense to me, because then the strong negative effect of mismatches with C would be completely gone which defeats the purpose of TCRblosum. Using 4 is just as arbitrary.