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.mdskills/protein-interactions/SKILL.md
GitHubProtein 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.xmlinto 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
- Collect —
--inputaccepts a PLIPreport.xml, a directory containingreport.xmlfiles, or an AlphaFold*.zippackage. Directories are scanned recursively forreport.xml. - Parse —
plip_parser.pywalks the XML withxml.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_ligsuffixed variants). Residue labels are decoded intochain / resname / resnr / atomfields, distinguishing protein residues (A:ARG+102:NE) from ligand atoms (LIG:1:CL1). - Summarise —
summarize_interactionscounts interactions per type; the entry script additionally ranks receptor and ligand residues by participation count to identify hotspots. - Visualise —
interaction_network.pyrenders the Mermaid flowchart (nodes = residues grouped into receptor / ligand subgraphs, edges = individual interactions coloured by type vialinkStyle) and the PyMOL script (select/show sticks/color/label/distancecommands). - Report — writes
interaction_analysis.jsonandinteractions_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;
0records for a non-emptyreport.xmlmeans the schema was not recognised — inspect the file. - Residue label integrity: decoded labels must keep
resnras an integer andresnameas 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.
ARG102engaging 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 > 90is high confidence,70-90is acceptable,< 70marks 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
linkStyleline per edge; a mismatch means edges were dropped during rendering.
References
references/methodology.md— PLIP XML schema, interaction definitions, statistics and renderingreferences/troubleshooting.md— common failures and how to diagnose them