# PDBsum-results-visualization

A dependency-light, offline replacement for the parts of the [PDBsum](http://www.ebi.ac.uk/thornton-srv/databases/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](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](index.html) once GitHub Pages is enabled for this repo (Settings -> Pages
-> Deploy from branch -> `main` / root).

## Two modules

### 1. Interface analyzer (`src/pdb_interface_analyzer.py`) -- two (or more) chains

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.

```bash
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/ --batch
```

Results 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.

### 2. Single-chain analyzer (`src/pdbsum_single_chain_analyzer.py`) -- one chain

**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

```bash
# 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.

### 3. Browser-based antibody-antigen viewer (`web/antibody_epitope_visualizer.html`)

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.

## Google Colab

Prefer not to install anything locally? Open
[`notebooks/PDBsum_Interface_Analyzer_Colab.ipynb`](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).

## Chain assignment

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.

## Important caveats

- **Secondary structure** is read straight from the PDB file's `HELIX`/`SHEET` header
  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](http://molprobity.biochem.duke.edu/) 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.

## Repository layout

```
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

[`examples/`](examples/) contains two worked examples:

- PDB entry [1YCR](https://www.rcsb.org/structure/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](https://www.rcsb.org/structure/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`](examples/README.md) for how each was generated and how to
read the output.

## License

MIT -- see [LICENSE](LICENSE). Free to use, modify, and redistribute for research or
any other purpose.

## Citing PDBsum / LIGPLOT concepts

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.