protein-interactions

Analyzes protein-ligand and protein-protein interactions from PLIP XML reports and AlphaFold model packages using a self-contained standard-library XML parser: extracts residue-level salt bridges, hyd

SKILL.md

GitHub

Protein Interaction Analysis

Overview

This skill turns PLIP (Protein-Ligand Interaction Profiler) reports into structured, residue-level interaction records and visualisations. The XML parsing is implemented with the Python standard library (xml.etree.ElementTree) only — no lxml, no Biopython, no network access — so a report produced on a workstation can be analysed anywhere. On top of the parsed records the skill computes per-type and per-residue statistics, renders an interaction network as a Mermaid flowchart with per-interaction-type colouring, and generates a ready-to-run PyMOL script that selects and labels the interacting residues in the 3D structure.

AlphaFold model packages (*.zip from the AlphaFold Protein Structure Database) can be fed in directly: the best model is picked by predicted TM-score confidence (pTM + 0.5 × ipTM) and the per-model confidence JSON is summarised.

When to Use This Skill

  • Parsing a PLIP report.xml into machine-readable residue-level interactions
  • Ranking hotspot residues by interaction count on receptor and ligand sides
  • Detecting salt bridges / hydrogen bonds / π-stacking / water bridges without PLIP
  • Selecting the best AlphaFold model from a multi-model package and reporting pLDDT
  • Generating a Mermaid interaction graph for reports, slides or documentation
  • Generating PyMOL commands that visualise and label the interacting residues

Quick Start

# 解析已有 PLIP 报告
python scripts/analyze_interactions.py --input report.xml --output results/

# 同时生成 Mermaid 网络图与 PyMOL 标注脚本
python scripts/analyze_interactions.py --input report.xml \
    --output results/ --make-mermaid --make-pymol

# 直接运行 PLIP 分析结构(需已安装 plip)
python scripts/analyze_interactions.py --input 1crn.pdb --run-plip \
    --plip-structure 1crn.pdb --output results/

# 分析 AlphaFold 模型包(自动挑选置信度最高的模型)
python scripts/analyze_interactions.py --input AF-P69905-F1-model_v4.zip \
    --output results/ --make-mermaid

Workflow

  1. Collect — --input accepts a PLIP report.xml, a directory containing report.xml files, or an AlphaFold *.zip package. Directories are scanned recursively for report.xml.
  2. Parse — plip_parser.py walks the XML with xml.etree.ElementTree, handling both the modern attribute-style schema (<site ... onf="A:ARG+102:NE"> with child <salt_bridge> elements) and the legacy element-style schema (<resnr>, <restype>, <reschain> with _lig suffixed variants). Residue labels are decoded into chain / resname / resnr / atom fields, distinguishing protein residues (A:ARG+102:NE) from ligand atoms (LIG:1:CL1).
  3. Summarise — summarize_interactions counts interactions per type; the entry script additionally ranks receptor and ligand residues by participation count to identify hotspots.
  4. Visualise — interaction_network.py renders the Mermaid flowchart (nodes = residues grouped into receptor / ligand subgraphs, edges = individual interactions coloured by type via linkStyle) and the PyMOL script (select / show sticks / color / label / distance commands).
  5. Report — writes interaction_analysis.json and interactions_residue_level.csv, one row per interaction.

Parameters

Parameter Default Description
--input required report.xml、包含报告的目录,或 AlphaFold *.zip
--output results/ 输出目录
--run-plip off 对输入结构运行 PLIP
--plip-structure — 传给 PLIP 的结构文件(PDB)
--plip-executable 自动查找 plip PLIP 可执行文件路径
--plip-timeout 600 PLIP 超时秒数
--make-mermaid off 生成 Mermaid 相互作用网络图
--make-pymol off 生成 PyMOL 标注脚本
--format both json / csv / both
--top-residues 10 统计中展示的热门残基数量

Outputs

File Content
interaction_analysis.json 每个报告的完整结果:相互作用记录、按类型统计、热门残基
interactions_residue_level.csv 残基级扁平表(受体残基、配体残基、类型、原子、距离)
*_interaction_network.md Mermaid flowchart 网络图(启用 --make-mermaid)
*_annotation.pml PyMOL 标注脚本(启用 --make-pymol)

Validation

  • Record count sanity: a PLIP report on a ligand with a buried binding site normally yields tens to a few hundred interactions; 0 records for a non-empty report.xml means the schema was not recognised — inspect the file.
  • Residue label integrity: decoded labels must keep resnr as an integer and resname as a three-letter code; protein labels contain a + separator (A:ARG+102), ligand labels do not.
  • Hotspot plausibility: a binding hotspot usually shows ≥ 3 interactions (e.g. ARG102 engaging the ligand in 3 distinct contacts). A flat histogram of one interaction per residue usually means the receptor/ligand roles were swapped or hydrogens were stripped from the input structure.
  • Type cross-check: salt bridges require oppositely charged side chains (ARG/LYS versus ASP/GLU); a salt bridge between two ARG residues is a parsing error, not a result.
  • AlphaFold confidence: pLDDT > 90 is high confidence, 70-90 is acceptable, < 70 marks a disordered or unreliable region; a mean pLDDT below 70 means the model should not be used for interaction analysis at all.
  • Network graph integrity: the Mermaid file must contain one linkStyle line per edge; a mismatch means edges were dropped during rendering.

References

  • references/methodology.md — PLIP XML schema, interaction definitions, statistics and rendering
  • references/troubleshooting.md — common failures and how to diagnose them