Circular Contact Map

What is this tool?

This tool helps you generate a circular ribbon contact map to visualize residue–residue contacts between two protein chains (e.g., nanobody and antigen). It supports two workflows:

From mmCIF: extract sequences and contacts for two chains, then plot.
From edges.csv: directly plot from a Cytoscape-like edges.csv (source,target[,distance]).

Web app (no backend) — Upload and draw

Upload one of the following: edges.csv, edges.json, or .cif. For CIF, choose two chains and cutoff.

Upload file (csv/json/cif)

Choose file No file selected

Chain 1

Chain 2

Cutoff (Å)

Use distance weighting (closer contacts → thicker ribbons)

Show unconnected nodes (hide by setting node width to 0 or making transparent)

Legend:

Node colors: Same color for all nodes in the same chain

Chain 1 (orange) Chain 2 (teal)

Ring colors (unconnected nodes): Different from node colors, but still chain-based

Chain 1 ring (darker orange) Chain 2 ring (darker teal)

Ribbon colors: Based on source node amino acid properties

Cysteine (black) Hydrophobic (orange-red) Polar (light blue) Acidic (red) Basic (purple) Other (gray)

Ribbon thickness: When "Use distance weighting" is enabled, closer contacts contribute more weight; otherwise each contact contributes equally.

Download

Run locally with Python. Requires pandas, holoviews[bokeh], biopython.

View source

File: scripts/circular_ribbon_contact_map.py

Quick start

Install dependencies

pip install pandas holoviews bokeh biopython matplotlib

A) From mmCIF (recommended)

python scripts/circular_ribbon_contact_map.py --cif complex.cif --chain1 H --chain2 L --cutoff 5.0 --output H_L_contact_map.html

Outputs sequences (FASTA), contact pairs (CSV), and an HTML plot (interactive).
Use --output <file.png> to render PNG (requires bokeh + selenium + pillow).

B) From edges.csv

# edges.csv columns: source,target[,distance]
python scripts/circular_ribbon_contact_map.py edges.csv --output contact_map.html

Tips

Residue node naming format: Chain_RES3_Num (e.g., A_ARG_100).
Distance (optional) can control edge width; closer contacts draw thicker ribbons.
Recommended distance cutoff for contacts: 4.5–5.0 Å.

Analytics dashboard

Live Google Analytics 4 metrics rendered via Looker Studio. Use the embedded controls to explore visitors, traffic sources, and geographic distribution.