Revert the motif join key change, and record why#199
Merged
Conversation
Reverts ea25a55. Adding mhc.a/mhc.b/mhc.class to the key looked obviously right and was wrong. In both members files mhc.a is constant across every row of a cluster - 0 of 1,123 TCRNET clusters and 0 of 1,929 TCREMP clusters carry more than one - so it is a label on the cluster, not a fact about the member's own VDJdb record, and the two can disagree. CASSMIPDMNTEAFF / TRBV19 / TRBJ1-1 against RPIIRPATL is a member row in TCRNET cluster H.B.RPIIRPATL.1, labelled HLA-B*08:01, and in the TCREMP cluster of the same name labelled HLA-B*07:02, while VDJdb records that rearrangement only under B*08:01 - eight records, no B*07:02 at all. So the key was not conflating two records; the rearrangement really is in both member sets. Joining on MHC dropped it from TCREMP entirely, and with it about 10% of TCREMP and 6% of TCRNET memberships across the database, all of them real memberships whose record carries a different restriction from the cluster label. The measurement that misled me: within each members file the distinct key count is identical with and without MHC. That shows MHC never splits a member key - it does not show the member's MHC agrees with the VDJdb record's, which is the join that actually matters, and it does not. The reasoning is now a comment on motifKey so the next person does not repeat it. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
mikessh
added a commit
that referenced
this pull request
Jul 23, 2026
…gorithm (#200) * Revert "Revert the motif join key change, and record why (#199)" This reverts commit 685b6b9. * Put MHC back in the motif key, and keep the cluster when switching algorithm Reverts the revert in 685b6b9. I removed MHC from the motif join key on the grounds that mhc.a is constant within every cluster and therefore had to be a label on the cluster rather than a fact about the member. It is constant for a different reason, and the removal was wrong. RPIIRPATL is curated in VDJdb under two restrictions - 97 records HLA-B*07:02 and 162 HLA-B*08:01 - and the two tools clustered different halves of it. Every TCREMP cluster for that epitope is B*07:02; the single TCRNET cluster is B*08:01. The cluster ids are even reused across the files: H.B.RPIIRPATL.1 names a B*08:01 cluster in one and a B*07:02 cluster in the other. So mhc.a is constant per cluster because clustering runs per restriction, which makes it part of the member's identity rather than incidental to it, and dropping it collapses two different pMHC complexes onto one key. That is the reported bug: CASSMIPDMNTEAFF / TRBV19 / TRBJ1-1, which VDJdb records only under B*08:01, came back from a "TCREMP only" search as a member of a B*07:02 cluster it has nothing to do with. The member's own MHC agrees with its VDJdb record in 94.7% of TCRNET rows and 90.0% of TCREMP rows, which is the check I should have run the first time instead of counting distinct keys within each file - that only showed MHC never splits a member key, not that it agrees with the record, and the latter is the join that matters. Where the two disagree the members file is describing a record under a restriction VDJdb does not give it; no badge is the honest answer there, and matching it to a differently-restricted record is not. Second bug, same report. A record in both clusterings always linked to TCRNET, because resolveMotif builds the link for the first available method and stops. Switching algorithm on the motif page then dropped the cluster entirely and selected every motif for the epitope, because setMethod re-resolves only the epitope params and cid is method-specific so it cannot be carried across. The badge now puts the clonotype in the link, and the switch re-resolves the cluster for the new method from it, landing on that record's cluster instead of the whole epitope. When the record is a member under one algorithm and not the other the selection falls back to the epitope, which is the true answer rather than a stale cluster. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Reverts #198. Adding
mhc.a/mhc.b/mhc.classto the motif join key looked obviously right and was wrong. I shipped it; this takes it back out.Why it was wrong
mhc.ais a label on the cluster, not a fact about the member's record. It is constant across every row of a cluster in both files:mhc.aSo the members file's MHC and the member's own VDJdb record can disagree — and for the reported case they do.
CASSMIPDMNTEAFF/ TRBV19 / TRBJ1-1 againstRPIIRPATLis a member row in TCRNET clusterH.B.RPIIRPATL.1(labelled HLA-B*08:01) and in the TCREMP cluster of the same name (labelled HLA-B*07:02), while VDJdb records that rearrangement only under B*08:01 — 8 records, no B*07:02 at all.The key was never conflating two records. The rearrangement genuinely is in both member sets. Joining on MHC dropped it from TCREMP entirely, and with it ~10% of TCREMP and ~6% of TCRNET memberships database-wide — all real memberships whose record carries a different restriction from the cluster's label.
The measurement that misled me
Within each members file the distinct-key count is identical with and without MHC (41,432 / 99,572). I read that as "adding MHC costs nothing". It shows only that MHC never splits a member key — it says nothing about whether the member's MHC agrees with the VDJdb record's, which is the join that actually matters. It does not.
What this leaves
The filter is behaving correctly. A rearrangement showing under "TCREMP only" while also being a TCRNET member means the upstream motif data places it in both cluster sets — worth a look on the data side, but not a web bug.
The reasoning is now a comment on
motifKeyso this doesn't get re-fixed.🤖 Generated with Claude Code