Molclaw Interaction Visualizer

Interaction Visualizer — MCP and Local Analysis

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] The current MolClaw server exposes this capability as the MCP tool interaction_visualizer. The bundled molclaw_interaction_visualizer.py remains available as an optional local CLI; it does not need to be uploaded to the server.

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.

Interaction Types Detected

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

MCP Invocation

response = await client.session.call_tool(
    "interaction_visualizer",
    arguments={
        "mode": "ligand",
        "receptor_path": "/server/path/receptor_fixed.pdb",
        "ligand_path": "/server/path/docking_pose.pdbqt",
        "resid_offset": 0,
        "score": -8.3,
        "skip_pymol3d": True
    }
)
result = client.parse_result(response)
output_dir = result["output_dir"]
key_files = result["key_files"]

mode is required and must be one of ligand, peptide, or protein. Input paths must be server-side paths; use molclaw-file-transfer for local input files.

Bundled Local CLI 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

Bundled Local CLI Parameter Reference

Output Files and Download Policy

Ligand Mode Outputs

Peptide / Protein Mode Additional Outputs

CSV Column Specification

interactions_{label}.csv — Per-Interaction Detail

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

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

Integration with Upstream Skills

Integration with Downstream Consumers

Residue Role Annotation JSON Format

The --residue_roles_json file maps residue labels to functional roles. This enables the 2D diagram to annotate each residue bubble with its pharmacological significance.

{
    "MET769": "Hinge",
    "LEU768": "Hinge",
    "THR766": "Gatekeeper",
    "LYS721": "Catalytic",
    "GLU738": "αC-helix",
    "ASP831": "DFG",
    "PHE832": "DFG",
    "VAL702": "P-loop",
    "LEU820": "Hydrophobic",
    "ALA719": "Hydrophobic"
}

Keys are matched by prefix (3-letter resname + resid), so "MET769" matches MET769A, MET769B, etc.

Common role vocabularies by target class:

• Kinases: Hinge, Gatekeeper, DFG, P-loop, αC-helix, Catalytic, Hydrophobic
• GPCRs: TM1-TM7, ECL1-ECL3, ICL1-ICL3, Orthosteric, Allosteric
• Proteases: Catalytic triad, Oxyanion hole, S1-S4 pockets

Dependencies & Installation

Required (typically in base environment):

• numpy — core geometry computation
• matplotlib — all 2D plot generation (diagram, bar, heatmap, network)

Optional (enables additional output types):

Choosing Between This Skill and ProLIF

Rule: This skill is the default for all single-structure interaction analysis. ProLIF is only used when its unique capabilities (batch, trajectory) are required.