Molclaw Interaction Visualizer

Interaction Visualizer — Local Analysis & Visualization

Note:

• Local files are not directly accessible by the server. Please upload them to the server using molclaw-file-transfer before execution.
• For PDB file inputs, it is recommended to preprocess them using molclaw-pdbfixer before execution.
• Please refer to skill molclaw-scp-server to complete tool invocation.

> [!NOTE] > This is a local tool — the Python script molclaw_interaction_visualizer.py runs > directly on the compute node. No MCP server connection needed. > Required: numpy, matplotlib. > Optional: rdkit (for 2D ligand diagram + SDF/MOL2/XYZ input), pymol (for 3D rendering), Pillow.

When To Use This Skill

> This is the PRIMARY tool for all single-structure interaction analysis. > ProLIF is only needed for batch docking fingerprint comparison or MD trajectory dynamics.

| Scenario | Use this skill | Use ProLIF instead | |----------|:--------------:|:------------------:| | Single complex structure interaction analysis | ✅ PRIMARY | Only if this tool unavailable | | Peptide or protein-protein interface analysis (single structure) | ✅ PRIMARY | Only if this tool unavailable | | Need Schrödinger-style 2D interaction diagram | ✅ | ❌ | | Need PyMOL 3D multi-angle renderings | ✅ | ❌ | | Need residue role annotations (Hinge/Gatekeeper/DFG) | ✅ | ❌ | | Need decision-ready JSON with top residues + hot sites | ✅ | ❌ | | Need partner_site.csv for ligand atom modification diagnosis | ✅ | ❌ | | Need interaction fingerprint across MD trajectory frames | ❌ | ✅ prolif_md | | Need batch docking pose fingerprint comparison (≥ 2 poses) | ❌ | ✅ prolif_docking | | Need protein-protein trajectory interface profiling | ❌ | ✅ prolif_protein_protein |

Interaction Types Detected

| # | Type | Key Geometry | Default Cutoff | |---|------|-------------|----------------| | 1 | Hydrogen bond | D-H···A angle ≥ 130° | 3.5 Å | | 2 | Hydrophobic contact | C···C distance | 4.5 Å | | 3 | π-π stacking (Face-to-Face) | Ring plane ∠ ≤ 35° | 5.5 Å | | 4 | π-π stacking (Edge-to-Face) | Ring plane ∠ 50°–90° | 6.5 Å | | 5 | Salt bridge | Charge center distance | 5.5 Å | | 6 | Cation-π | Cation-centroid + normal ∠ | 6.0 Å | | 7 | Halogen bond | X···A with A-X-D geometry | 3.5 Å | | 8 | Metal coordination | Metal···coordinating atom | 3.0 Å | | 9 | van der Waals | Sum of VdW radii + tolerance | +0.5 Å |

Three Analysis Modes

• ligand (default): Small-molecule ligand vs protein. Partner identified by HETATM

records or --ligand_resname. Produces 2D diagram + residue bar + partner site CSV.

• peptide: One protein chain as partner peptide. Requires --partner_chain.

Produces interface heatmap + interface network + residue bar.

• protein: Two full protein chains. Requires --chain_a and --chain_b.

Produces interface heatmap + interface network + residue bar.

Input Source Mapping

| Parameter | Source Guidance | |-----------|----------------| | --complex | Pre-merged complex PDB from docking output, Boltz-2/Chai-1 predicted structure, MD extracted frame, or crystal structure | | --receptor | Protein PDB from molclaw-protein-structure-retrieve → molclaw-pdbfixer, or predicted structure | | --ligand | Docking pose file from molclaw-quickvina-docking (.pdbqt), molclaw-diffdock-auto (.sdf), or any .mol/.mol2/.xyz | | --partner_pdb | Partner protein PDB for peptide/protein modes (from molclaw-extract-chains or separate structure) | | --resid_offset | PDB→UniProt offset computed from sequence alignment (L3 Principle 17) | | --residue_roles_json | User-provided or literature-derived residue functional annotations | | --score | Docking affinity from upstream docking tool (kcal/mol) | | --smiles | Ligand SMILES from user input or molecule retrieval |

Setup — Upload Script to Server

# Upload the interaction visualizer script to the server
response = await client.session.call_tool(
    "upload_file",
    arguments={"local_path": "/path/to/molclaw_interaction_visualizer.py"}
)
script_path = client.parse_result(response)["remote_path"]

Alternatively, if the script is already present on the server at a known path, skip the upload step.

Usage Patterns

Pattern 1: Single Complex File (Ligand Mode)

For a pre-merged complex PDB containing both protein and ligand:

python molclaw_interaction_visualizer.py \
    --complex complex.pdb \
    --mode ligand \
    --ligand_resname LIG \
    --out_dir viz_out \
    --resid_offset 0 \
    --title "EGFR–Erlotinib" \
    --score -8.3 \
    --smiles "C=Cc1cccc(Nc2ncnc3cc(OCCOC)c(OCCOC)cc23)c1"

Pattern 2: Separate Receptor + Ligand Files (Auto-Merge)

When receptor and ligand come from different upstream tools (e.g., PDBFixer output + docking pose PDBQT/SDF). The script automatically converts the ligand format and merges into a single complex.

python molclaw_interaction_visualizer.py \
    --receptor receptor_fixed.pdb \
    --ligand docking_pose_best.sdf \
    --mode ligand \
    --out_dir viz_out \
    --resid_offset 574 \
    --residue_roles_json roles.json \
    --title "CDK2–Compound_7" \
    --score -9.1 \
    --delta_score -1.2

Supported ligand formats for auto-merge: .sdf, .mol, .mol2, .pdb, .pdbqt, .xyz.

Pattern 3: Peptide–Protein Interface

python molclaw_interaction_visualizer.py \
    --complex complex.pdb \
    --mode peptide \
    --partner_chain B \
    --out_dir viz_out \
    --title "PD1–PeptideBinder"

Pattern 4: Protein–Protein Interface (Separate Files)

python molclaw_interaction_visualizer.py \
    --receptor chain_A.pdb \
    --partner_pdb chain_B.pdb \
    --mode protein \
    --chain_a A \
    --chain_b B \
    --out_dir viz_out \
    --title "IL6–IL6R interface"

Pattern 5: Quick CSV-Only (Skip All Plots)

For agent-only consumption when visualizations are not needed:

python molclaw_interaction_visualizer.py \
    --complex complex.pdb \
    --mode ligand \
    --ligand_resname LIG \
    --out_dir viz_out \
    --skip_diagram2d --skip_bar --skip_heatmap --skip_network --skip_pymol3d

Full Parameter Reference

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | --complex | str | — | Single PDB/PDBQT file containing receptor + partner | | --receptor | str | — | Receptor-only file (used with --ligand or --partner_pdb; alternative to --complex) | | --ligand | str | — | Ligand-only file (.sdf/.mol/.mol2/.pdb/.pdbqt/.xyz); used with --receptor in ligand mode | | --partner_pdb | str | — | Partner protein PDB for peptide/protein modes when receptor and partner are separate files | | --merged_out | str | OUT_DIR/auto_merged.pdb | Path to save the auto-merged complex (when using --receptor + --ligand/--partner_pdb) | | --mode | str | ligand | Analysis mode: ligand, peptide, or protein | | --ligand_resname | str | — | (ligand mode) Restrict partner to a specific HETATM residue name | | --partner_chain | str | — | (peptide mode) Chain ID of the peptide partner | | --chain_a | str | — | (protein mode) Receptor chain ID | | --chain_b | str | — | (protein mode) Partner chain ID | | --out_dir | str | viz_out | Output directory (created if missing) | | --resid_offset | int | 0 | Added to receptor resid in CSV output for PDB→UniProt mapping (L3 Principle 17) | | --title | str | "" | Common title prefix for all figures | | --score | float | — | Docking score (kcal/mol) displayed in 2D diagram header | | --delta_score | float | — | ΔScore vs baseline displayed in 2D diagram header | | --smiles | str | — | Ligand SMILES displayed in 2D diagram footer | | --residue_roles_json | str | — | JSON file mapping residues to functional roles: {"MET769":"Hinge", "THR766":"Gatekeeper", ...} | | --ligand_scale | float | 1.0 | Scale factor for ligand drawing in 2D diagram (0.8=smaller, 1.3=larger) | | --top_n_bar | int | 20 | Number of residues shown in stacked bar chart | | --heatmap_cutoff | float | 4.5 | Atom-pair distance cutoff (Å) for interface heatmap | | --skip_diagram2d | flag | — | Skip 2D interaction diagram generation | | --skip_bar | flag | — | Skip residue stacked bar chart | | --skip_heatmap | flag | — | Skip interface heatmap (peptide/protein modes) | | --skip_network | flag | — | Skip interface network diagram (peptide/protein modes) | | --skip_csv | flag | — | Skip CSV export | | --skip_pymol3d | flag | — | Skip PyMOL 3D rendering | | --pymol_width | int | 1400 | Width of PyMOL ray-traced images | | --pymol_height | int | 1200 | Height of PyMOL ray-traced images |

Output Files and Download Policy

Ligand Mode Outputs

| Output File | Format | Download Policy | Consumed By | |-------------|--------|-----------------|-------------| | interactions_{label}.csv | CSV | A — MUST download | L2-08 consensus ranking, L2-05 optimization diagnosis | | interactions_{label}_residue_summary.csv | CSV | A — MUST download | Residue-level SAR analysis | | interactions_{label}_partner_site.csv | CSV | A — MUST download | Ligand modification hotspot identification | | diagram2d_{label}.png | PNG | A — MUST download (L3 P15) | Report, user presentation | | residue_bar_{label}.png | PNG | A — MUST download (L3 P15) | Report | | scene_{label}.pml | PML script | B — record path in log | PyMOL manual inspection | | pymol_{label}_{front,side,top}.png | PNG | A — MUST download (if generated) | Report 3D views | | summary_{label}.json | JSON | A — MUST download | Agent decision loop integration |

Peptide / Protein Mode Additional Outputs

| Output File | Format | Download Policy | Consumed By | |-------------|--------|-----------------|-------------| | interface_heatmap_{label}.png | PNG | A — MUST download (L3 P15) | Interface quality evaluation | | interface_network_{label}.png | PNG | A — MUST download (L3 P15) | Interface topology analysis |

CSV Column Specification

interactions_{label}.csv — Per-Interaction Detail

| Column | Description | |--------|-------------| | type | Normalized interaction type (HBond, SaltBridge, PiStacking, CationPi, Halogen, Metal, Hydrophobic, VdW) | | subtype | Direction/variant (LigDonor, ProtDonor, FaceToFace, EdgeToFace, etc.) | | rec_res | Receptor residue label (e.g., MET769A) | | rec_resid_pdb | Receptor residue number in PDB numbering | | rec_resid_mapped | Receptor residue number after applying --resid_offset (for UniProt mapping) | | rec_res_class | Residue classification (hydrophobic, aromatic, polar, positive, negative) | | rec_atom | Receptor atom name(s) involved | | partner_atom | Partner atom name(s) involved | | distance_A | Interaction distance in Ångströms | | angle_deg | Relevant geometry angle in degrees (if applicable) | | strength_hint | Qualitative label: strong / moderate / weak / packing / contact |

*_residue_summary.csv — Per-Residue Rollup

One row per contacting residue, columns for each interaction type count, total count, and minimum distance.

*_partner_site.csv — Ligand Atom Hotspot (Ligand Mode Only)

One row per ligand atom involved in interactions, columns for each interaction type count. Use this to identify:

• Atoms to preserve: high total count → critical pharmacophore points
• Atoms to modify: low or zero count → optimization candidates

Interpreting summary_{label}.json (Agent Decision Integration)

{
  "mode": "ligand",
  "label": "LIG",
  "n_interactions": 42,
  "n_contact_residues": 15,
  "interaction_type_counts": {
    "HBond": 3, "SaltBridge": 1, "PiStacking": 2,
    "CationPi": 0, "Halogen": 0, "Metal": 0,
    "Hydrophobic": 8, "VdW": 15
  },
  "top_residues": [
    {"res": "MET769A", "class": "hydrophobic", "total": 5,
     "by_type": {"HBond": 2, "Hydrophobic": 3}},
    {"res": "LEU694A", "class": "hydrophobic", "total": 4,
     "by_type": {"Hydrophobic": 4}}
  ],
  "hot_partner_sites": [
    {"partner_atom": "N3", "total": 4,
     "by_type": {"HBond": 2, "PiStacking": 2}},
    {"partner_atom": "C15", "total": 1,
     "by_type": {"Hydrophobic": 1}}
  ],
  "outputs": { ... }
}

Agent decision rules:

• top_residues → Verify expected key contacts match the task requirements (e.g., "confirm hinge interaction with Met793").
• hot_partner_sites → Atoms with high total and strong interaction types (HBond, SaltBridge) should be preserved during optimization. Atoms with low total are safe modification candidates.
• interaction_type_counts → A molecule with 0 HBonds to the hinge region is likely a poor kinase inhibitor candidate; flag for re-evaluation.

Residue Numbering Reconciliation (L3 Principle 17 — MANDATORY)

Use --resid_offset N where N = UniProt_number − PDB_number for the protein.

Example: If PDB 1M17 has Met at position 769, but UniProt numbering is Met793, then --resid_offset 24.

All CSV outputs include a rec_resid_mapped column with the offset applied. When reporting results:

• CORRECT: "Interaction visualizer detected HBond at MET769 (PDB) = Met793 (UniProt, offset +24). This confirms the expected hinge interaction."
• WRONG: "Interaction visualizer did not find Met793." (False negative from numbering mismatch.)

For Boltz-2/Chai-1 predicted structures where the offset is non-trivial, compute the offset from sequence alignment BEFORE running this tool.

Strength Hints (Qualitative — NOT Quantitative Energies)

| Type | "strong" | "moderate" | "weak" / "packing" / "contact" | |------|----------|------------|--------------------------------| | HBond | d ≤ 2.9 Å and ∠ ≥ 150° | d ≤ 3.2 Å and ∠ ≥ 130° | otherwise | | SaltBridge | d ≤ 4.0 Å | d > 4.0 Å | — | | PiStacking | d ≤ 4.5 Å | d > 4.5 Å | — | | Hydrophobic | — | — | "packing" (always) | | VdW | — | — | "contact" (always) |

These are qualitative drug-chemist-style labels. They are NOT quantitative binding energy estimates. Do not use them as substitutes for MM-PBSA or FEP calculations.

Common Failures & Recovery

| Failure | Likely Cause | Recovery | |---------|-------------|----------| | No atoms parsed from {path} | Wrong file format, empty file, or binary format given as text | Verify file is valid PDB/PDBQT; check encoding | | Partner atom list empty | Ligand resname not found in PDB, or wrong --partner_chain | Check --ligand_resname matches actual HETATM resname in PDB; verify chain IDs | | RDKit failed to build ligand mol | Bond perception or sanitization issue with ligand | 2D diagram skipped; CSV and all other outputs still produced. Install/upgrade rdkit if needed | | 2D diagram PNG not generated | RDKit not installed | pip install rdkit; or accept CSV-only output and use --skip_diagram2d | | PyMOL images not generated | PyMOL not on system PATH | Install PyMOL (conda install -c conda-forge pymol-open-source); or use --skip_pymol3d | | 0 interactions detected | Ligand not in binding pocket (bad docking pose) or atoms too far apart | Verify docking pose quality upstream; re-dock with larger box | | Auto-merge PDBQT fails | PDBQT has non-standard formatting | Convert PDBQT → PDB first using OpenBabel, then use --ligand pose.pdb | | AssertionError: --partner_chain required | Peptide mode invoked without chain specification | Inspect PDB chain IDs and provide --partner_chain |

Integration with Upstream Skills

| Upstream Skill | Provides | This Skill Uses As | |----------------|----------|--------------------| | molclaw-quickvina-docking | PDBQT docking pose + affinity score | --ligand (PDBQT) + --score | | molclaw-diffdock-auto | SDF docking pose + confidence | --ligand (SDF) + --score | | molclaw-karmadock-tool | SDF docking pose + score | --ligand (SDF) + --score | | molclaw-pdbfixer | Cleaned receptor P

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: InternScience
• Source: InternScience/MolClaw
• License: MIT

Install and usage instructions live in the source repository linked above.