PDBsum-results-visualization — offline protein & interface analysis

01 What it computes

Contact types & structural metrics

Every calculation uses exact geometric criteria extracted directly from the atomic coordinates in your PDB file.

Hydrogen bonds

Polar atom pairs (N/O/S) positioned close enough to plausibly hydrogen-bond.

2.4–3.5 Å

Salt bridges

Oppositely charged side-chain atoms (Asp/Glu against Lys/Arg/His) within range.

≤ 4.0 Å

Hydrophobic contacts

Non-polar carbon atoms from hydrophobic residues packed against each other.

≤ 4.0 Å

Single-Chain Analysis Module

Standalone Protein Characterization

When evaluating a single protein chain in isolation, run pdbsum_single_chain_analyzer.py. Shown below are the 5 core diagnostic figures generated for Ubiquitin (1UBQ), detailing sequence composition, secondary structure topology, disulfide connectivity, and backbone dihedrals.

Residue composition bar chart for Ubiquitin — **Residue Composition**Amino acid breakdown grouped by chemical classification (Aliphatic, Polar, Positive, etc.)

Secondary structure track for Ubiquitin — **Secondary Structure Track**Helix, sheet, and coil assignment track mapped sequentially along the chain

Secondary structure wiring diagram for Ubiquitin — **Structure Wiring Diagram**PDBsum-style schematic layout highlighting motif connections across residues

Disulfide bond connectivity diagram for Ubiquitin — **Disulfide Bond Connectivity**Cysteine S-S bond network graph (detected automatically via geometry)

Ramachandran plot for Ubiquitin — **Ramachandran Plot**Backbone phi (φ) / psi (ψ) angle distribution across favored and allowed regions

Command: python src/pdbsum_single_chain_analyzer.py examples/data/1UBQ_ubiquitin.pdb --chain A. Includes a detailed Chain_Structure_Report.txt report.

Two-Chain Interface Case

Receptor-Ligand / Peptide-Protein Complexes

Generated by running the interface analyzer on PDB entry 1YCR — MDM2's binding domain (chain A) with a 15-residue p53 peptide (chain B) docked into it.

Bubble summary of interface contact counts — **Summary bubble**At-a-glance bond counts per chain

Residue-to-residue interaction network diagram — **Interaction network**Every contacting residue pair, PDBsum-ligplot style

Contact density heatmap between interface residues — **Contact heatmap**Density of contact across residue pairs

Static 3D backbone trace of the docked complex — **3D backbone trace**Static snapshot; an interactive HTML version ships alongside it

Secondary structure track showing helix, sheet and coil regions — **Secondary structure**Helix / sheet / coil, read from the PDB header

Ramachandran plot of backbone phi and psi angles — **Ramachandran plot**Backbone phi/psi angles per chain

Includes full text reports and interactive docked_complex_3d.html 3D viewers — see examples/ for complete sample outputs.

Multi-Chain Case

Antibody Heavy + Light vs. Epitope

One side of an interface can consist of multiple chains — such as an antibody's Heavy (H) and Light (L) chains binding an antigen epitope (A). Pass --receptor-chain H,L and every plot disambiguates residues by chain automatically.

Three-bubble summary for antibody heavy chain, light chain, and epitope — **Three bubbles, not two**H, L, and A each get their own bubble and connection counts

Interaction network for antibody heavy and light chains vs epitope, with a chain divider — **H vs. L, disambiguated**Dashed divider separates chain-H contacts from chain-L contacts

Contact heatmap for antibody vs epitope with a chain boundary line — **Contact heatmap**Solid line marks the H/L chain boundary

03 Get started

Four ways in, pick whichever fits you

New to the command line

Guided, no flags

Download the project, install two requirements (numpy, matplotlib), then answer simple prompts.

python src/easy_start.py Read the full walkthrough →

Nothing to install

Google Colab

Fetch a structure by PDB ID or upload your own, run everything in the browser, and download a zip of results.

Open notebooks/PDBsum_Interface_Analyzer_Colab.ipynb Launch in Colab →

Command Line Interface (Complexes)

Interface CLI

Full control over multi-chain analysis, custom labels, and distance thresholds.

python src/pdb_interface_analyzer.py complex.pdb \
  --ligand-chain A --receptor-chain H,L

See all interface options →

Command Line Interface (Single Chain)

Single-Chain CLI

Analyze individual protein chains for secondary structure, composition, and Ramachandran regions.

python src/pdbsum_single_chain_analyzer.py protein.pdb \
  --chain A

See single-chain options →

04 Repository layout

Where everything lives

src/pdb_interface_analyzer.py # two-(or-more)-chain interface analyzer — CLI src/pdbsum_single_chain_analyzer.py # single-chain analyzer: composition, secondary structure, Ramachandran, disulfides src/easy_start.py # question-and-answer wizard for beginners web/antibody_epitope_visualizer.html# zero-install browser tool for antibody H+L vs epitope A notebooks/ # Google Colab notebook examples/data/ # sample inputs: Ubiquitin, 1YCR peptide complex, Antibody H/L/A complex examples/output/ # sample multi-chain interface analyzer outputs examples/output_single_chain/ # sample single-chain analyzer outputs (Ubiquitin, Heavy chain) GETTING_STARTED.md # plain-English walkthrough README.md requirements.txt LICENSE # MIT

05 Read before you cite

What this is — and isn't

Secondary structure comes straight from the PDB file's HELIX/SHEET header records. Raw docking output usually has no header at all, so it will show as coil — that's expected, not a bug.
Ramachandran "favored regions" shown here are a simplified, illustrative guide for an at-a-glance check, not a validated statistical potential. For publication-grade validation, cross-check with MolProbity or the structure's wwPDB validation report.
Distance thresholds are the same geometry-only heuristics PDBsum/LIGPLOT use — they don't model hydrogen positions or electrostatics, so treat borderline contacts as candidates worth a closer look, not certainties.