SAbR

SAbR assigns antibody residue numbers from backbone coordinates. It accepts PDB and mmCIF structures, preserves the input object, and supports IMGT, Chothia, Kabat, Martin, AHo, and Wolfguy numbering.

Installation

SAbR requires Python 3.11 or newer.

pip install sabr-kit

Command line

Renumber chain H using the default IMGT scheme and automatic heavy, kappa, or lambda reference selection:

sabr -i antibody.pdb -c H -o numbered.pdb

Select a numbering scheme and chain type explicitly:

sabr -i antibody.cif -c light_chain -o numbered.cif \
  --scheme chothia --chain-type K

Use the complete SoftAlign parameter set (encoder, reference embeddings, and gap penalties):

sabr -i antibody.pdb -c H -o numbered.pdb --mode softalign

Renumber only residues whose source PDB numbers are 1 through 130:

sabr -i antibody.pdb -c H -o numbered.pdb \
  --residue-range 1 130

Insertion-coded residues are included when their numeric component falls in the range. Existing files are protected unless --overwrite is supplied.

The complete interface is:

sabr -i INPUT -c CHAIN -o OUTPUT
     [-n imgt|chothia|kabat|martin|aho|wolfguy]
     [-t auto|H|K|L]
     [--noise-level 0.0|0.2|0.5|1.0|2.0]
     [-m sabr|softalign]
     [--residue-range START END]
     [--scfv]
     [--no-mmcif]
     [--overwrite] [-v]

The defaults are IMGT, automatic chain selection, noise level 0.0, and sabr mode. SoftAlign mode uses its own fixed references, so noise_level is ignored in that mode. Normal output contains only warnings and errors. Use --verbose to show the JAX backend, chain-selection scores, and a traceback on failure.

For a single chain containing two linked variable domains, pass --scfv. This adds H:K, H:L, K:H, and L:H concatenated references to the normal H, K, and L candidates. SAbR offsets the second domain's assigned numbers by 128 to keep residue IDs unique and numbers the linker as insertions after domain one. scFv mode requires the default automatic chain type because each composite reference already specifies both domain types. Composite references use the selected parameter mode, so --scfv can be combined with --mode softalign. Gap-open and gap-extension penalties are disabled for query linker residues aligned at the boundary between the two references. All other internal gap transitions retain the selected parameter mode's normal penalties.

When candidates are compared, SAbR applies the normal affine gap-open and gap-extension costs to unaligned query and reference termini of composite representations. This post-hoc selection penalty does not change the computed alignments or their raw scores.

Python API

renumber_structure accepts a Biopython Structure, returns a new Biopython Structure, and does not mutate its input.

from Bio.PDB import PDBParser
from sabr import renumber_structure

structure = PDBParser(QUIET=True).get_structure("antibody", "antibody.pdb")
numbered = renumber_structure(
    structure,
    chain="H",
    scheme="imgt",
    chain_type="auto",
)

The function signature is:

renumber_structure(
    structure,
    chain: str,
    scheme: str = "imgt",
    chain_type: str = "auto",
    noise_level: float = 0.0,
    residue_range: tuple[int, int] | None = None,
    mode: str = "sabr",
    scfv: bool = False,
)

mode="softalign" selects the SoftAlign encoder weights, reference embeddings, and exact gap penalties stored in softalign_gap.npz. The default mode="sabr" preserves existing behavior.

Non-target chains, waters, ligands, metadata represented by the input object, and residues outside the selected range are preserved in the returned clone. Only single-model structures are supported.

PDB and mmCIF output

Use mmCIF when a structure has:

• a chain ID longer than one character;
• multi-character insertion codes;
• residue numbers outside the PDB range -999 through 9999; or
• more than 99,999 atoms.

For exceptionally long CDR insertions, use mmCIF output.

CLI conversion preserves atomic structure content but does not preserve every non-atomic mmCIF category.

Structural gaps and modified residues

A C–N distance above 2.66 Å is treated as a structural gap. If a gap crosses a CDR or the DE loop between IMGT anchors 79 and 85, SAbR warns and retains the learned alignment for that region while continuing corrections elsewhere. Otherwise, DE-loop residues fill 80 first, then 84 back through 81; additional residues are inserted after 82.

Supported modified peptide residues are translated to their canonical parent only for sequence generation. Original residue names and atoms are preserved. Unknown or ambiguous polymer chemistry is rejected rather than converted to X.

Experimental TCR use

T-cell receptors are not an officially supported SAbR target. Experimental users of the low-level alignment and numbering modules should align TCRs against the K reference because it includes IMGT position 10, as TCRs do. Pass the actual TCR chain type (A, B, G, or D) only to the ANARCI conversion step, together with ref_type="K". This workaround supports IMGT and AHo numbering only; Chothia, Kabat, Martin, and Wolfguy are antibody-specific.

Errors

Common errors include:

• selecting a missing chain;
• selecting more than one structural model;
• residues missing N, CA, or C atoms;
• a range containing multiple or discontinuous domains;
• output that cannot be represented in PDB format; and
• selections above the 1,024-residue safety limit.

For long or multi-domain chains, pass --residue-range on the command line or residue_range=(start, end) in Python.