Skip to content

Align residues to SEQRES instead of laying them out by residue number - #351

Open
dww100 wants to merge 1 commit into
openmm:masterfrom
kuano-ai:fix/align-residues-to-seqres
Open

dww100 wants to merge 1 commit into
openmm:masterfrom
kuano-ai:fix/align-residues-to-seqres

Conversation

@dww100

@dww100 dww100 commented Jul 29, 2026

Copy link
Copy Markdown
Contributor

Fixes #219. Fixes #170. Fixes #154.

These three issues have the same root cause, so one change closes all of them.

For transparency all code here was written by Claude but at first glance seemed
close enough to what I was thinking of doing and tests seem sensible. The
wordy description below has the same source.

This maybe overkill and make things more fragile but if this looks promising happy
to follow up.

The problem

findMissingResidues() builds an array indexed by residue number and slides it
against each SEQRES sequence looking for an offset at which every occupied slot
matches. That only works when residue numbers run 1, 2, 3, ….

Kabat and EU numbering for antibodies, IMGT numbering, and other domain-based
conventions deliberately skip numbers without any residue being absent. Each
skipped number becomes a phantom empty slot. Once the array is longer than the
sequence, range(len(sequence.residues) - len(chainWithGaps[chain]) + 1) is an
empty range: the loop body never runs, no alignment is attempted, and the
chain silently drops out of the matching step. missingResidues gets no entries
for it, addMissingAtoms() builds nothing, and findMissingAtoms() then caps the
last observed residue with OXT — so a chain truncated mid-sequence comes out
looking well-formed. No exception, no warning.

1IGT chain B is a good illustration: 444 observed residues and 444 SEQRES entries
that agree residue for residue, but 8 insertion codes and 23 numbering gaps make
the computed span 482, so the offset range is −37 and the chain is never examined.

In #219 the conclusion was that 6RPA's numbering is inconsistent with its SEQRES.
It isn't — IMGT numbering skips numbers by design, and the reporter was right
"the SEQRES represents properly the structure".

The insertion-code shim added in #184 addresses only part of this. Making its
bump conditional on the number not having already advanced — the obvious minim
fix — takes 1IGT chain B from span 482 to 481, not 444. I measured it; it removes
one phantom slot out of 38. The number-indexed layout is the problem, not the

The change

Align the observed residue list to the sequence, and use residue numbers onl
a hint for where to place gaps.

New _alignResiduesToSequence(residues, sequence) returns a strictly increasing
map from residue index to sequence index, or None. Notes on the design:

  • Strict name matching. A residue only matches a sequence element with the
    name, preserving the current a == b semantics. No new tolerance for renamed or
    non-SEQRES residues.
  • Fewest gap blocks. Every residue must map somewhere, so the total number of
    skipped sequence elements is fixed at len(sequence) - len(residues) and on
    their placement is free. A linear gap penalty is therefore a constant and does
    nothing; scoring gap openings prefers a few continuous missing loops over
    scattered single residues.
  • Numbering hint. Opening a gap is cheaper where the deposited numbering i
    discontinuous, since that is where the depositor has told us residues are absent.
    This is what makes the result exact rather than merely plausible: without it
    missing-residue counts are already correct everywhere I tested, but placement
    drifts by one inside runs of repeated residues — 6RPA D and 6RPB F/K/P gave
    [MET, GLY, ARG] where the deposition says [MET, ARG, GLY].
  • Cost. The gap branch is a running maximum, so each row of the DP is a fe
    vectorised numpy operations. 0.05 s for a 2000-residue chain, 0.19 s at 4000.

The sequence-major assignment order is unchanged: sequences are considered in file
order and each is assigned to the first chain it aligns to. That ordering is
load-bearing, since chain IDs are not unique — it is what stops a one-residue
ligand chain from claiming the 212-element sequence of the polymer chain L i
shares an ID with, as happens in 1A0Q.

findMissingResidues() now also warns when a chain contains exactly the residues
one of the sequences lists but still cannot be aligned, rather than doing noth
silently. It stays quiet when the names themselves disagree, since that means the
structure genuinely does not contain what the sequence lists.

chainWithGaps, chainSequence and chainOffset were function-local and nev
reached self, and missingResidues keeps its (chain.index, indexInChain) -> [names] contract, so _addAtomsToTopology, findMissingAtoms, ui.py and
Manual.html are untouched. No public API change, no new dependency.

Structures tested

Compared residue by residue, not just by count, against the deposited
REMARK 465 records. Exact agreement on all 16.

PDB Chains REMARK 465 Before After
1A0Q H / L 12 / 1 0 / 0 12 / 1
1AO7 A / D / E 1 / 89 / 36 1 / 0 / 0 1 / 89 / 36
6RPA A / B / D / E 1 / 1 / 46 / 11 1 / 1 / 0 / 0 1 / 1 / 46 / 11
6RPB A,D,E,F,I,J,K,N,O,P,S,T 6,12,5,3,12,5,18,18,7,6,17,4 only A, F, K, P all 12 correct
5J7S A 35 0 35
4JSV A,B / C,D 116 / 9 116 / 9 116 / 9
1BHL A 16 16 16
5UDC A,B,C,D,E,F,G,H,L 120,10,3,120,8,119,1,11,3 correct correct
1VII, 1UBQ, 3NIR, 2HMI, 1AKE, 4HHB all none none none

6RPA, 6RPB, 1AO7 and 5J7S are the structures from #219; 1A0Q is #154; 5UDC and
antibodies generally are #170. 4JSV, 1BHL and 5UDC already worked and are included
to catch regressions — 5UDC appears to have been fixed incidentally by #184, s
its insertion codes happen to land such that the array does not overrun.

1IGT deserves a note: nothing is missing from it, so the reported result is empty
both before and after. What changes is that chains B and D are now aligned to
sequences instead of being skipped, which is what the test asserts.

Also verified directly: non-numeric residue IDs (previously an unguarded
int(r.id)), single-residue chains, chains longer than their sequence, chains
no possible match, and empty chains.

Tests

New pdbfixer/tests/test_find_missing_residues.py, 7 tests. No existing test was
modified. Full suite: 31 passed.

Four tests are offline and use two new fixtures:

  • data/insertion_codes.pdb — a hand-written chain with Kabat-style numbering
    (51, 52, 52A, 52B, 53), a numbering jump from 57 to 60 with nothing absent, and
    one genuine two-residue gap. Asserts the exact missingResidues dict, and t
    building the structure yields the 14 sequence residues and nothing else.
  • data/unalignable_order.pdb — exercises the warning.
  • 4JSV is used to check that heterogens and waters sharing a chain ID with a
    polymer produce no warnings.

None of the five existing fixtures contained a single insertion code (I checke
column 27 of every ATOM record), which is why new ones were needed.

Three parametrized tests download 1IGT, 1A0Q and 1VII from RCSB. I marked them
skipif(os.getenv("GITHUB_ACTION") is not None), following the existing patte
test_cli.py — happy to drop that if you would rather they run in CI, since
test_charge_and_solvate.py already downloads there.

Not addressed here

Related defects in the same family — treating residue.id as a positional ind
that I have deliberately left alone:

  • _addAtomsToTopology derives IDs for newly built residues by arithmetic on
    int(residue.id), which collides or runs backwards on Kabat-numbered chains
    Cosmetic: names, geometry and connectivity are correct, but the output numbering
    of a repaired antibody is not meaningful.
  • applyMutations keys resSeq_to_residue on int(residue.id), collapsing 100
    and 100A onto one key.
  • findNonstandardResidues matches MODRES on (chain.id, residue.id, residue.name)
    with the insertion code dropped on both sides.

One pre-existing behaviour is worth flagging because strict name matching pres
it rather than fixing it (#350): calling applyMutations() before findMissingResidues()
renames a residue in the topology but not in self.sequences, so the chain no
longer matches its sequence and its gaps are silently not filled — the whole chain,
not just the mutated region. On master and on this branch alike:

fixer = PDBFixer(pdbfile=StringIO(PDB))   # SEQRES ALA VAL ASP GLU PHE LYS
fixer.findMissingResidues()               # structure missing ASP 3
# {(0, 2): ['ASP']}

fixer = PDBFixer(pdbfile=StringIO(PDB))
fixer.applyMutations(['VAL-2-GLY'], 'A')
fixer.findMissingResidues()
# {}

Scoring mismatches instead of forbidding them would fix that, with a match-fraction
threshold so a small ligand chain cannot claim a polymer's sequence. I left it
to keep this change to one behaviour, but say the word and I will add it.

findMissingResidues() built an array indexed by residue number and slid it
against each SEQRES sequence looking for an offset where the occupied slots
matched.  Numbering conventions that skip numbers without any residue being
absent, as Kabat, EU and IMGT numbering all do, put a phantom empty slot in
that array for every skipped number.  Once the array grew longer than the
sequence the range of candidate offsets was empty, so no alignment was even
attempted and the chain was silently left with its gaps unfilled.

Replace the layout with a dynamic programming alignment of the residues to
the sequence.  Residue numbers are now only a hint: a gap is cheaper to open
where the numbering is discontinuous, which is where the depositor has told
us residues are absent.  Also warn when a chain contains the residues its
sequence lists but cannot be aligned, rather than doing nothing silently.

Fixes openmm#154, openmm#170, openmm#219.

The missing residues now found agree residue for residue with the REMARK 465
records of 1A0Q, 1AO7, 6RPA, 6RPB, 5J7S, 5UDC, 4JSV and 1BHL, and no missing
residues are reported for 1IGT, 1VII, 1UBQ, 3NIR, 2HMI, 1AKE or 4HHB.  The
first five of those found none at all before this change.
@peastman

Copy link
Copy Markdown
Member

Short answer to this: Claude is wrong. The PDB spec is pretty clear about this:

The sequence implied by ATOM records must be identical to that given in SEQRES, with the exception that residues that have no coordinates, e.g., due to disorder, must appear in SEQRES.

You don't get the use an arbitrary, domain based numbering system. The only reason you're allowed to have a skip is if a residue is present in the molecule but you don't have any coordinates for it. A file that does it differently is incorrect.

PDBx/mmCIF tried to deal with this better by having separate label_seq_id and auth_seq_id fields to distinguish between a strict serial number and an external numbering system. Unfortunately, they then messed it up by using them inconsistently and incorrectly documenting that auth_seq_id should be used as the equivalent of the PDB residue sequence number.

@dww100

dww100 commented Aug 3, 2026

Copy link
Copy Markdown
Contributor Author

I think this is known to be an issue where the files in the PDB disagree with the documentation. I can see why you keep the principled approach though.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

2 participants