Heatmap of Interaction Persistence (% of Sim. Time)

Overview and Methodology

What It Does

This tool generates percentage-based heatmaps that show how often each molecular interaction was present throughout the simulation. The plots display pairwise contact frequencies for hydrogen bonds, salt bridges, hydrophobic contacts, π-stacking, and cation–π interactions.

How It Works

• Objective: Visualize the cumulative persistence of interactions across all frames of the trajectory.
• Process:
  • Loads interaction matrices from the ▶️ (Run First) Extract Pairwise Interaction from Trajectory step.
  • Calculates the percentage of frames in which each interaction was detected.
  • Filters out low-frequency contacts based on a user-defined threshold.
  • Displays the data as a symmetric matrix-style heatmap with annotation options.

---

Configuration and Inputs

Prerequisites

• Requires interaction CSVs generated using the same sel1_name and sel2_name from the extraction step.

Key Configuration Options

• Selection Labels:

  • sel1_name, sel2_name: Must match the labels used during extraction. Used to locate interaction data files.

• Interaction Mode:

  • interaction_mode: Choose to visualize:
    • interchain + intrachain: All interactions.
    • interchain: Only between different chains.
    • intrachain: Only within the same chain.

• Interaction Filtering:

  • pct_hide_threshold: Only show interactions that occurred in at least this percentage of frames.

• Heatmap Layout:

  • pct_fig_width_factor, pct_fig_height_factor: Scale the heatmap size per contact.
  • pct_min_fig_width, pct_min_fig_height: Set the minimum plot dimensions.

---

Output

• Persistence Heatmaps:

  • One matrix-style heatmap per interaction type:
    • Hydrogen Bonds
    • Hydrophobic Contacts
    • Salt Bridges
    • π-Stacking
    • Cation–π
  • Rows and columns = interacting residues.
  • Cell values = percentage of simulation time the interaction was detected.

• Saved Figures:

  • PNG plots saved to the figures/ folder.
    • Example: figures/percentage_Hydrogen_Bonds.png

• Text and CSV Reports:

  • .txt file: List of interaction pairs shown in each plot.
  • *_pct.csv: Raw interaction percentage matrices for each interaction type.
  • top_contacts.csv: Summary of most persistent contacts (≥15%).
  • all_contacts.csv: Full list of all detected contacts and their frequencies.

• Console Output:

  • Displays which interaction type is being plotted.
  • Notifies if a plot is skipped due to lack of qualifying interactions.

---

Interpreting the Results

• High Persistence:

  • Cells with higher percentages indicate interactions that are consistently present across the simulation.

• Low Persistence:

  • Cells with lower percentages reflect weak or transient contacts.

• Filtering Threshold Impact:

  • Raising pct_hide_threshold shows only dominant contacts.
  • Lowering it reveals short-lived or conditional interactions.

• Symmetric Matrix Layout:

  • Contacts are shown between unique residue-residue pairs regardless of interaction direction.

• Sidechain Indicators:

  • Residue labels with * indicate interaction originates from a sidechain atom (inherited from extraction).

---

Example Scenarios

Protein–Ligand Binding Contact Analysis

• Scenario: Quantify how a drug engages its protein binding pocket over time.
• Selections:
  • sel1 = 'protein'
  • sel2 = 'resname LIG', sel2_is_ligand = True
• Observation: Frequent contacts between ligand atoms and specific protein residues, shown as annotated cells with high percentages.
• Interpretation: Highlights residues with strong or persistent interactions. Useful for structure–activity relationships and lead optimization.

Domain–Domain Interaction Mapping

• Scenario: Explore how two protein domains interact dynamically during simulation.
• Selections:
  • sel1 = 'segid PROA'
  • sel2 = 'segid PROB'
• Observation: Salt bridges or hydrophobic contacts between domain residues are present >50% of the time.
• Interpretation: Indicates stable domain–domain interfaces. May support allosteric coupling or coordinated motion.

Dynamic Pocket Closure

• Scenario: Capture a transition in which a protein binding pocket encloses a substrate.
• Selections:
  • sel1 = 'resid 50-90' (binding pocket residues)
  • sel2 = 'resname SUB', sel2_is_ligand = True
• Observation: Pocket contacts with the substrate increase in frequency as the simulation progresses, resulting in high final percentages.
• Interpretation: Suggests ligand-induced conformational changes. Useful for gating mechanism analysis or binding mode validation.

---

Usage Tips

• Annotation Control:

  • Disable pct_annot for large datasets or enable it with a higher pct_hide_threshold for focused visualization.

• Matrix Size Management:

  • Adjust pct_fig_width_factor and pct_fig_height_factor to scale with the number of contacts.

• Cross-reference Reports:

  • Use top_contacts.csv for prioritized contacts or all_contacts.csv for full details.

---