A dependency-light, offline replacement for the parts of the PDBsum web server that generate ligand-plots, single-structure summaries, and interface diagnostics -- built because the PDBsum web interface has been unreliable / down for extended stretches.
No Biopython required -- just numpy and matplotlib.
New to the command line? Skip straight to GETTING_STARTED.md
for a no-jargon, step-by-step walkthrough, and run python src/easy_start.py instead
of the CLI below -- it just asks plain questions instead of requiring flags.
A browsable project page (with the example gallery) is also available via
index.html once GitHub Pages is enabled for this repo (Settings -> Pages
-> Deploy from branch -> main / root).
Given a PDB file with two interacting sides, computes:
- Hydrogen bonds (polar-polar atom pairs, 2.4-3.5 A)
- Salt bridges (charged side-chain atom pairs, <= 4.0 A)
- Hydrophobic / non-bonded contacts (<= 4.0 A)
- Per-residue interface catalogs for both sides
- Secondary structure (from HELIX/SHEET header records, when present)
- Ramachandran (phi/psi) backbone geometry, with a simplified favored/outlier summary
...and renders everything as a text report plus six figures (five static PNGs and one standalone interactive 3D HTML viewer).
Supports a multi-chain side -- e.g. an antibody's Heavy (H) and Light (L) chains
both binding one epitope (A). Pass the group as comma-separated chain letters
(--receptor-chain H,L) and every output (report, plots, interactive viewer)
disambiguates residues by chain automatically, since H and L routinely reuse the same
residue numbers.
pip install -r requirements.txt
# Peptide vs. target, chains given explicitly (recommended when known)
python src/pdb_interface_analyzer.py path/to/complex.pdb \
--ligand-chain B --receptor-chain A \
--ligand-label p53_peptide --receptor-label MDM2
# Antibody (Heavy + Light) vs. epitope
python src/pdb_interface_analyzer.py path/to/complex.pdb \
--ligand-chain A --receptor-chain H,L \
--ligand-label Epitope --receptor-label Antibody
# Auto-detect which chain is the (smaller) ligand vs. (larger) receptor
python src/pdb_interface_analyzer.py path/to/complex.pdb
# Batch mode: every .pdb file in a folder
python src/pdb_interface_analyzer.py path/to/folder/ --batchResults land in ./interface_results/<complex_name>/ by default (override with
--output), each folder containing:
| File | Contents |
|---|---|
Complex_Interface_Report.txt |
Full text report: stats, contact lists, residue catalog |
interface_summary_bubble.png |
Proportional bubble summary -- one bubble per chain (e.g. 3 bubbles for antibody H+L vs epitope A), with per-chain-pair bond counts |
interface_interactions_network.png |
Residue-to-residue Bezier contact network |
interface_contact_heatmap.png |
Contact-density heatmap between interface residues |
docked_complex_3d_static.png |
Static 3D backbone trace, interface highlighted |
docked_complex_3d.html |
Standalone interactive 3Dmol.js viewer (open in any browser) |
secondary_structure.png |
Per-chain helix/sheet/coil track along the sequence |
ramachandran_plot.png |
Phi/psi scatter plot per chain |
Ramachandran_Summary.txt |
Favored-region / outlier residue counts per chain |
In batch mode you additionally get a Summary_All_Complexes.txt comparing every
complex processed in that run.
Note: the interface analyzer above already computes secondary structure and a Ramachandran plot for every chain involved (e.g. all three of Epitope/Heavy/Light in an antibody case) -- so you don't need this module just to get those two if you already ran the interface analyzer. This module's actual unique value is disulfide bond detection and the residue composition breakdown, neither of which the interface analyzer computes. Use it when: you have a chain with nothing to compare it against, or you specifically want disulfides/composition for a chain you've already interface-analyzed.
For when there's no second chain to compare against -- a designed construct, a modeled antigen, or one subunit pulled out of a bigger file. Emulates the other half of PDBsum's single-structure summary page:
- Secondary structure breakdown (helix/sheet/coil %, from HELIX/SHEET records)
- Ramachandran plot and favored/outlier summary
- Disulfide bonds, tiered by distance: Formed (<2.5 A), Candidate (2.5-4.5 A -- close enough to flag, e.g. an engineered disulfide that hasn't fully formed in a model), or Far
- Residue composition by physicochemical class (aliphatic/aromatic/polar/+/-/Pro-Gly)
- Two secondary-structure pictures: a to-scale linear track, and an authentic PDBsum-style "wiring diagram" -- sequence spelled out letter by letter with sinusoidal purple helix ribbons, strand arrows, beta/gamma turn markers, and disulfide-bond arcs connecting cysteines, labeled with their SG...SG distance
# Auto-detects the chain if the file has only one
python src/pdbsum_single_chain_analyzer.py path/to/structure.pdb
# Pick a specific chain out of a multi-chain file
python src/pdbsum_single_chain_analyzer.py path/to/structure.pdb --chain H --label "Antibody Heavy Chain"Results land in ./single_chain_results/<name>/:
| File | Contents |
|---|---|
Chain_Structure_Report.txt |
Stats, secondary structure %, tiered disulfide/candidate pairs, Ramachandran summary, composition, FASTA sequence |
secondary_structure.png |
Helix/sheet/coil track, to scale |
secondary_structure_wiring.png |
Schematic topology diagram (shapes in sequence order, not to scale) |
secondary_structure_disulfides.svg |
Authentic PDBsum-style wiring diagram: sequence + helix ribbons/strand arrows + turn markers + disulfide arcs |
ramachandran_plot.png |
Phi/psi scatter plot |
residue_composition.png |
Bar chart of residue-type composition |
If a file has no HELIX/SHEET header records at all (typical docking/homology-model
output), secondary_structure_disulfides.svg falls back to an approximate phi/psi-based
H/E guess so the diagram isn't blank -- and says so directly on the image. The strict,
header-only view (secondary_structure.png and the report's percentages) is unaffected
by that fallback.
This module reuses the PDB parser and math from pdb_interface_analyzer.py --
keep both files in src/ together.
A zero-install, single-file HTML app specifically for the Heavy+Light-vs-epitope case:
drag-and-drop a PDB, get an interactive 3D viewer, a PDBsum-style wiring diagram,
a contact heatmap, and downloadable figures/reports, entirely in your browser (no
Python required). Open it directly, or via GitHub Pages at
.../web/antibody_epitope_visualizer.html. It assumes chains are named exactly
H, L, and A -- for anything else, use the Python module above instead.
Its "non-bonded contact" count is intentionally broader than the Python module's
(any close atom pair, not just hydrophobic carbon-carbon), so the two tools'
non-bonded numbers won't match exactly -- H-bond and salt-bridge counts do.
Prefer not to install anything locally? Open
notebooks/PDBsum_Interface_Analyzer_Colab.ipynb
in Colab. It covers both single-complex and batch analysis, displays every figure
inline, and lets you download the results as a zip. It can fetch a structure directly
from RCSB by PDB ID, or you can upload your own .pdb file(s).
If --ligand-chain/--receptor-chain (single-file mode) or a --chain-map JSON file
(batch mode) aren't given, the interface analyzer auto-detects: whichever protein chain
has fewer residues is treated as the ligand (e.g. a short peptide), and the largest
remaining chain as the receptor. Auto-detect only ever picks one chain per side --
a multi-chain side (antibody H+L) must always be given explicitly.
- Secondary structure is read straight from the PDB file's
HELIX/SHEETheader records. Raw docking/homology-model output frequently has no header at all -- in that case the plot will show the whole chain as coil and say so explicitly. This is expected, not a bug. - Ramachandran "favored regions" shown here are a simplified, illustrative guide (rough alpha/beta/left-handed-helix boxes) meant for an at-a-glance sanity check -- not a validated statistical potential. For publication-grade validation, cross-check with MolProbity or the structure's wwPDB validation report.
- Distance thresholds (2.4-3.5 A for H-bonds, 4.0 A for salt bridges/hydrophobic contacts) are geometry-only heuristics, the same kind PDBsum/LIGPLOT use -- they don't account for hydrogen positions or electrostatics, so treat borderline contacts as candidates worth a closer look rather than certainties.
- If your PDB file includes explicit hydrogen atoms (some antibody homology models do), the Python modules exclude them from contact geometry automatically -- heavy-atom distances only, consistent with the thresholds above.
src/pdb_interface_analyzer.py - two-(or-more)-chain interface analyzer (CLI)
src/pdbsum_single_chain_analyzer.py - single-chain structural analyzer (CLI)
src/easy_start.py - question-and-answer version for beginners
web/antibody_epitope_visualizer.html- zero-install browser tool for antibody H+L vs epitope A
notebooks/ - Google Colab notebook
examples/data/ - example inputs (see below)
examples/output/ - example interface-analyzer output
examples/output_single_chain/ - example single-chain-analyzer output
GETTING_STARTED.md - plain-English walkthrough for first-time users
index.html - browsable project page (enable GitHub Pages to view)
requirements.txt
LICENSE
examples/ contains two worked examples:
- PDB entry 1YCR (MDM2 bound to a 15-residue p53 peptide) -- a simple two-chain peptide-vs-target case.
- An antibody-epitope complex (chains H, L, A) -- the multi-chain case, run both through
the interface analyzer (
--receptor-chain H,L) and the single-chain analyzer (chain H alone, which also has two real disulfide bonds to detect). - PDB entry 1UBQ (ubiquitin) through the single-chain analyzer -- picked specifically because it has real HELIX/SHEET header records (one alpha helix, a five-stranded beta sheet), so the wiring diagrams show actual secondary structure rather than all-coil.
See examples/README.md for how each was generated and how to
read the output.
MIT -- see LICENSE. Free to use, modify, and redistribute for research or any other purpose.
This tool is an independent reimplementation inspired by the type of diagram PDBsum and LIGPLOT popularized; it is not affiliated with, and does not reuse code from, either project. If your work also benefits from the original concepts, consider citing:
Laskowski, R.A. (2001) PDBsum: summaries and analyses of PDB structures. Nucleic Acids Research, 29, 221-222.