molclaw-prolif-md

name	molclaw-prolif-md
description	ProLIF MD trajectory analysis skill for protein-ligand interaction fingerprints with frame slicing and residue controls.
license	MIT license
metadata	{"skill-author":"PJLab"}

ProLIF MD Interaction Fingerprinting Skill

[!NOTE] Local files are not directly accessible by the server. Please upload them to the server using drugsda-file-transfer before execution. For PDB file inputs, it is recommended to preprocess them using drugsda-fix_pdb before execution.

Task Description

Analyze protein-ligand interaction fingerprints in molecular dynamics (MD) trajectories, with support for frame slicing and residue controls. Use this skill to evaluate whether binding patterns remain stable throughout simulation.

Input Source Mapping

Parameter	Source Guidance
topology_path	Output topology file from MD workflow tools: e.g., protein_openmm_md, prepare_complex, prepare_protein_md, or run_goca_pipeline (.psf/.pdb/.prmtop)
trajectory_path	Output trajectory file from the same MD workflow tools (.dcd/.nc/.xtc)
ligand_selection	User-provided ligand selection string, for example resname LIG or resid 100-101
protein_selection	Defaults to protein; can be customized to narrow protein scope

Usage

Tool: prolif_md

Compute ProLIF fingerprints for an MD trajectory and return standardized summary metrics.
Args:
    topology_path (str): Path to the topology file (e.g., .psf, .pdb, .prmtop).
    trajectory_path (str): Path to the trajectory file to analyze.
    ligand_selection (str): Selection string identifying ligand atoms.
    protein_selection (str): Selection string for protein atoms. Default: 'protein'.
    interactions (List[str]|None): Optional interaction types to compute (e.g., Hydrophobic, HBDonor).
    count (bool): If True, compute interaction counts instead of fingerprints. Default: False.
    vicinity_cutoff (float|None): Optional distance cutoff for vicinity interactions.
    params_json (str|None): Optional JSON parameter file path for ProLIF interaction settings.
    start (int|None): Optional start frame index.
    stop (int|None): Optional stop frame index (exclusive).
    step (int|None): Optional frame stride.
    residues (List[str]|None): Optional explicit residue list to include.
    all_residues (bool): If True, include all residues in analysis. Default: False.
Return:
    status (str): 'success' or 'error'.
    msg (str): Human-readable summary or error message.
    command (str): The executed command label ('md').
    output_dir (str|None): Run-specific directory under tool_result/prolif_result.
    output_file (str|None): Path to the generated CSV file.
    n_frames (int|None): Number of processed frames.
    n_interactions (int|None): Number of interaction columns in output.
    frequent_interactions (List[dict]|None): High-frequency interactions (>30%) with keys 'interaction' and 'frequency'.
    result_summary (dict|None): Full summary dictionary from the wrapper.

How To Use prolif_md

response = await client.session.call_tool(
    "prolif_md",
    arguments={
        "topology_path": "relative/path/to/system.prmtop",
        "trajectory_path": "relative/path/to/md_prod.nc",
        "ligand_selection": "resname LIG",
        "protein_selection": "protein",
        "interactions": ["Hydrophobic", "HBDonor"],
        "start": 0,
        "stop": 100,
        "step": 2
    }
)
result = client.parse_result(response)
key_output = result["output_file"]

Example Parameter Sets

# 1) Main mode
{
    "topology_path": "relative/path/to/system.prmtop",
    "trajectory_path": "relative/path/to/md_prod.nc",
    "ligand_selection": "resname LIG",
    "protein_selection": "protein",
    "interactions": ["Hydrophobic", "HBDonor", "HBAcceptor"],
    "start": 0,
    "stop": 100,
    "step": 2
}

# 2) Variant mode
{
    "topology_path": "relative/path/to/system.prmtop",
    "trajectory_path": "relative/path/to/md_prod.nc",
    "ligand_selection": "resname LIG",
    "count": True,
    "all_residues": True,
    "vicinity_cutoff": 4.5,
    "params_json": "relative/path/to/prolif_params.json"
}

---

⚠ Residue Numbering Warning (L3 Principle 17 — CRITICAL)

ProLIF reports residue identifiers using the numbering of the input PDB file. If the PDB was generated by a prediction tool (ESMFold, Boltz-2, Chai-1), these numbers are tool-internal sequential numbers (1, 2, 3...) — NOT UniProt numbers.

Before interpreting ProLIF results when the task references specific residues (e.g., "confirm Met793 interaction"):

1. Determine which numbering scheme the input PDB uses.
2. If different from the task's reference scheme, run molclaw-residue-mapper to build a mapping table.
3. Translate ProLIF residue IDs to the task's reference scheme before drawing conclusions.

Common catastrophic error: ProLIF reports "HBDonor at MET76" from a Boltz-2 structure. Agent searches for "MET793" in ProLIF output, does not find it, and concludes "Met793 interaction is absent." In reality, MET76 (Boltz-2 internal) IS Met793 (UniProt). Use residue_mapper with query="tool:76" to verify.

⚠ Mandatory Image Download (L3 Principle 15)

After ProLIF analysis, download ALL visualization outputs (interaction heatmaps, frequency barplots, etc.) from the output directory using server_file_to_base64. These are Category A files essential for result communication and user verification.