sabr-kit 0.3.4

Structure-based Antibody Renumbering

Structure-based Antibody Renumbering

SAbR (Structure-based Antibody Renumbering) renumbers antibody PDB files using the 3D coordinate of backbone atoms. It uses custom forked versions of SoftAlign and ANARCI to align structures to SAbDaB-derived consensus embeddings and renumber to various antibody schemes, respectively.

Documentation

Full API documentation is available at sabr.readthedocs.io.

Installation and use

Requirements: Python 3.11 or higher

1. SAbR can be installed into a virtual environment via pip:

# Latest release
pip install sabr-kit

# Most recent version from Github
git clone --recursive https://github.com/delalamo/SAbR.git
cd SAbR/
pip install -e .

It can then be run using the sabr command (see below).

2. Alternatively, SAbR can be directly run with the latest docker container:

docker run --rm ghcr.io/delalamo/sabr:latest -i input.pdb -o output.pdb -c CHAIN_ID

Running SAbR

Practical considerations:

• Heavy and light chain structures are similar enough that chain type should be manually declared with --chain-type if possible (leave blank if uncertain).
• It is recommended for now to truncate the query structure to contain only the Fv when running SAbR, as it will sometimes align variable region beta-strands to those in the constant region.
• When running scFvs, it is recommended to run each variable domain independently.

If running on a Mac with apple silicon, set the environmental variable JAX_PLATFORMS to cpu.

Usage: sabr [OPTIONS]

  Structure-based Antibody Renumbering (SAbR) renumbers antibody structure
  files using the 3D coordinates of backbone atoms. Supports both PDB and
  mmCIF input formats.

Options:
  -i, --input-pdb FILE            Input structure file (PDB or mmCIF format).
                                  [required]
  -c, --input-chain TEXT          Chain identifier to renumber (single
                                  character).  [required]
  -o, --output FILE               Destination structure file. Use .pdb
                                  extension for PDB format or .cif extension
                                  for mmCIF format. mmCIF is required for
                                  antibodies with extended insertion codes
                                  (e.g., very long CDR loops).  [required]
  -n, --numbering-scheme [imgt|chothia|kabat|martin|aho|wolfguy]
                                  Numbering scheme.  [default: IMGT]
  --overwrite                     Overwrite the output file if it already
                                  exists.
  -v, --verbose                   Enable verbose logging.
  --residue-range START END       Range of residues to process in PDB
                                  numbering (inclusive). Use '0 0' (default)
                                  to process all residues. Example:
                                  --residue-range 1 120 processes residues
                                  1-120.
  --disable-deterministic-renumbering
                                  Disable deterministic renumbering corrections
                                  for loop regions. By default, corrections are
                                  applied for FR1, DE loop, and CDR loops.
  -t, --chain-type [H|K|L|heavy|kappa|lambda|auto]
                                  Chain type for ANARCI numbering.
                                  H/heavy=heavy chain, K/kappa=kappa light,
                                  L/lambda=lambda light. Use 'auto' (default)
                                  to detect from DE loop occupancy.
                                  [default: auto]
  -h, --help                      Show this message and exit.

Python API

SAbR can also be used programmatically to renumber BioPython Structure objects directly in memory:

from Bio.PDB import PDBParser, PDBIO
from sabr import renumber

# Load a structure
parser = PDBParser(QUIET=True)
structure = parser.get_structure("antibody", "input.pdb")

# Renumber the structure (returns a new BioPython Structure)
renumbered = renumber.renumber_structure(
    structure,
    chain="H",                      # Chain identifier
    numbering_scheme="imgt",        # imgt, chothia, kabat, martin, aho, wolfguy
    chain_type="auto",              # H, K, L, or auto
)

# Optionally specify a residue range
renumbered = renumber.renumber_structure(
    structure,
    chain="H",
    res_start=1,                    # Start at residue 1
    res_end=128,                    # End at residue 128
)

# Save the renumbered structure
io = PDBIO()
io.set_structure(renumbered)
io.save("output.pdb")

Known issues

• SAbR currently struggles with scFvs for two reasons. First, it is unclear how to assign canonical numbering to multiple domains within a single chain, unless we accept a spacer (e.g., starting chain #2 at 201 instead of 1). Second, it will sometimes align across both chains, introducing a massive insertion in between. It is unclear how to prevent this; please see issue #2 for details.
• SAbR sometimes mistakenly includes sheets from the Fab in the VH.
• The algorithm for renumbering CDRs, which is the same as the one for IMGT, does not account for unassigned residues. So if a residue is missing due to heterogeneity, the CDR numbering algorithm will misnumber other residues in the CDR.