nblib

Two scripts that build a structural nanobody library from scratch: mine the PDB for every nanobody / VHH / single-domain antibody entry, split each structure into its nanobody and antigen chains, then superpose the nanobody chains onto a common frame with consistent residue numbering.

The output is a directory of single-chain PDB files that are directly usable as input for structure-based design (RFdiffusion, ProteinMPNN, ESM-IF) or for statistics on CDR loop conformations.

Scripts

nb_dl.py — mine and split

1. Queries the RCSB search API (v2) for entries whose struct_keywords or struct.title contain nanobody, vhh, or single domain antibody.
2. Downloads each hit as PDB format.
3. Reads the COMPND header to find which chains are annotated as the nanobody — header annotation, not a length heuristic, so it survives structures with multiple nanobodies or fusion constructs.
4. Treats any non-nanobody chain with > 160 unique residues as the antigen. The cutoff filters out the short peptides, tags, and crystallization chaperones that would otherwise pollute the antigen set.
5. Writes each chain to its own PDB file, stripping waters, as {pdb_id}_{chain}.pdb.

python nb_dl.py
# -> nanobody_chains/7abc_A.pdb, antigen_chains/7abc_B.pdb, ...

Chains are separated into nanobody_chains/ and antigen_chains/, so you can use the pair for interface work or the nanobody alone for framework analysis.

align_nb.py — renumber and superpose

Runs headless PyMOL (pymol -cq) over nanobody_chains/:

1. Takes the first PDB file as the reference.
2. Renumbers every structure's residues to a clean consecutive series starting at 1 — this is what makes the set comparable, since deposited nanobodies carry wildly inconsistent numbering (IMGT, Kabat, sequential, insertion codes).
3. cmd.aligns each remaining structure to the reference and prints the RMSD and aligned-atom count per structure.
4. Saves results to aligned_nanobody_chains/{name}_aligned.pdb.

python align_nb.py

The per-structure RMSD in the log is a useful sanity filter — a nanobody that aligns at 3 Å+ over few atoms is usually a truncated or misannotated chain worth excluding.

Setup

conda env create -f environment.yml
conda activate nanobody_env

The environment is deliberately minimal: requests for the PDB API and pymol-open-source for alignment.

Notes

• Downloaded and aligned structures aren't committed — the full RCSB sweep is ~1 GB across a few thousand chains. Run nb_dl.py to regenerate; it's reproducible from the query.
• The scripts read and write fixed relative directory names (nanobody_chains, antigen_chains, aligned_nanobody_chains), so run them from the repo root.
• nb_dl.py requests entries serially with no rate limiting. It's polite enough for RCSB but a full sweep takes a while; the [INFO]/[DEBUG] logging makes it easy to resume by hand if it dies partway.
• Only PDB-format entries are handled. Very large structures that exist only as mmCIF are skipped when the .pdb download 404s.

License

MIT — see LICENSE.