Antibody engineering
Sequence-level analysis for antibodies, nanobodies, and other variable-domain formats: numbering,
CDR annotation, chemical liabilities, and physicochemical properties. All of it runs in seconds
and rules out a surprising fraction of problems before a model or a wet-lab week is spent.
Read references/numbering-schemes.md before quoting any
residue position, references/developability.md before acting on a
liability, references/humanization-and-design.md for
grafting and humanness, and references/tools.md for the wider ecosystem.
A residue number means nothing without its scheme
"Residue 52" is a different residue in IMGT, Kabat, and Chothia numbering, and the CDRs they
define overlap only partially. The same trastuzumab heavy chain:
IMGT CDRH1 GFNIKDTY (8) CDRH2 IYPTNGYT (8) CDRH3 SRWGGDGFYAMDY (13)
Kabat CDRH1 DTYIH (5) CDRH2 RIYPTNGYTRYADSVKG (17) CDRH3 WGGDGFYAMDY (11)
Neither is wrong. Use IMGT by default — one definition for both chains, structurally
principled gaps, and the germline database is IMGT-numbered — and convert to Kabat when matching
legacy literature. State the scheme every time.
python skills/antibody-engineering/scripts/number_antibody.py antibody.fasta
python skills/antibody-engineering/scripts/number_antibody.py antibody.fasta --scheme kabat
python skills/antibody-engineering/scripts/number_antibody.py antibody.fasta \
--format regions --out regions.tsv
# trastuzumab_VH: chain H, closest germline human_H (human), E=3e-60
# variable domain spans input residues 1-120
CDRH1 8 GFNIKDTY
CDRH2 8 IYPTNGYT
CDRH3 13 SRWGGDGFYAMDY
Needs pip install anarci plus HMMER (hmmscan on PATH). Note that ANARCI's species call is
the closest germline, not an annotation — a humanised antibody reports human because its
frameworks are human, which says nothing about its CDRs.
Liabilities, weighted by region
python skills/antibody-engineering/scripts/scan_liabilities.py antibody.fasta \
--regions regions.tsv --min-severity high
# trastuzumab_VH: 120 residues, 3 finding(s)
[critical] deamidation (NG) 'NG' at 55 (CDRH2)
the fastest-deamidating motif; Asn -> iso-Asp/Asp changes charge and can
abolish binding, and it is the usual cause of potency loss on storage
[critical] isomerisation (DG) 'DG' at 102 (CDRH3)
Asp-Gly isomerises to iso-Asp through a succinimide intermediate
Those are trastuzumab's two documented hotspots, found from sequence alone.
Pass --regions. The same NG in framework 3 is usually buried and tolerated; in CDR-H2 it
is a redesign candidate. Without region information every finding is reported at the framework
baseline, and the script says so.
Motifs covered: N-glycosylation sequons (N-X-[ST], X≠P), deamidation (NG ≫ NS/NT/NN/…),
isomerisation (DG ≫ DS/DT/…), acid-labile DP fragmentation, Met and Trp oxidation,
unpaired and extra cysteines, N-terminal pyroglutamate, and the RGD/RYD integrin motifs.
A liability is a question, not a veto. Many approved antibodies carry known liabilities and
manage them with formulation and release specifications. What settles it is a force-degradation
study, not a prediction.
Physicochemical profile
python skills/antibody-engineering/scripts/physchem_profile.py antibody.fasta --combine
# trastuzumab_VH: 120 residues
molecular weight 13164.7 Da
isoelectric point 8.17 (EMBOSS pKa set)
net charge at pH 7.4 +0.89
extinction (280 nm) 35535 /M/cm (cystine)
A280 at 1 mg/mL 2.699
GRAVY -0.305
- pI drives purification and formulation. Formulate at least a unit away from it — near-zero
net charge means poor colloidal stability, and the script warns when the two are close.
- Net charge at pH 7.4 above roughly +6 associates with fast clearance and polyspecificity in
the published developability sets.
- Extinction coefficient is what turns A280 into a concentration; getting it wrong scales
every downstream number including your affinities.
- Different pKa sets shift pI by a few tenths. The script uses EMBOSS and says so; quote the set.
The order that saves time
number_antibody.py --format regions — everything downstream needs regions.scan_liabilities.py --regions — seconds, catches the classics.physchem_profile.py — pI, charge, extinction coefficient.- Model the Fv (ABodyBuilder3, IgFold, or
boltz) — needed for anything conformational.
- Structure-based properties: TAP metrics, hydrophobic and charged patches.
- Humanness, if the molecule is not already human.
- Test: force degradation, SEC, DSF, HIC, AC-SINS, PSR.
Steps 1–3 cost seconds. Do them before spending a GPU hour.
What sequence cannot tell you
Aggregation, viscosity, polyspecificity, and thermal stability are conformational, and none
of them follow from motifs. They need a structure — hydrophobic patch area across the VH/VL
interface predicts aggregation and HIC retention far better than GRAVY does — or an experiment.
Reporting a clean liability scan as "developable" is the mistake this skill is meant to prevent;
say "no sequence liabilities detected, structure-based properties not assessed".
Antibody–antigen complex prediction is also still genuinely hard for every current method,
because the interface is a rearranged loop rather than a conserved surface. Check ipTM before
believing a predicted complex.
Composing with the rest of the bundle
glycoengineering — the sequons this skill flags, in depth: occupancy, glycoform engineering,
effector-function consequences.esm — language-model scoring for affinity maturation and humanness.boltz — antibody–antigen cofolding when you need the complex.uniprot-rcsb — antigen sequence and structure; SAbDab entries are PDB entries.adaptyv — submit designs and get measured binding and thermostability back.open-targets — whether the antigen is validated and accessible to a biologic; its AB
tractability buckets answer exactly that.