Plot Ion and Water Occupancy in Selectivity Filter

Overview and Methodology

What It Does

This script analyzes how ions and water occupy, move through, and arrange themselves within the selectivity filter (SF) of an ion channel during molecular dynamics simulations. It calculates:

• Occupancy of each site by ions and water.
• Dwell times of individual ions and waters at each site.
• Binding configurations over time using symbolic representation.

It supports different filter geometries, including:

• Kv filters with 5 binding sites (S0 to S4).
• NaV/CaV filters with 4 residue-defined sites (e.g., DEKA/EEEE).

How It Works

• Binding Sites:

  • Sites are constructed based on either Kv-style midpoint logic or by direct residue positions.
  • Sorted from most intracellular (lowest $z$-coordinate) to extracellular (highest $z$-coordinate).

• Occupancy:

  • An ion or water is considered occupying a site if within a user-defined threshold distance from the site center.
  • Water must also meet symmetry criteria to avoid misclassification.

• Dwell Time:

  • Consecutive frames where the same atom occupies the same site are grouped and counted as a dwell period.
  • Final results are reported in the time units of the trajectory.

• Configuration Frequency:

  • Each frame is converted into a symbolic string:
    • Ion = user-defined symbol (e.g., ●)
    • Water = user-defined symbol (e.g., w)
    • Empty = user-defined symbol (e.g., □)
  • Most frequent configurations are shown as a bar chart.

---

Configuration and Inputs

Prerequisites

• Requires a loaded trajectory.

Key Configuration Options

• Selections:

  • sf_sel: Atom selection defining the SF oxygen atoms.
  • ion_sel, water_sel: Atom selections for ions and water, respectively.

• Site Definition:

  • site_mode: Either 'Kv' for midpoint-based Kv filters or 'Residue' for one-site-per-residue models.

• Distance Thresholds:

  • threshold_distance: Maximum distance from a site center to count an ion or water as occupying it.
  • water_cutoff: Pre-filtering radius for selecting water near the SF.
  • water_symmetry_threshold: Symmetry measure from 0 to 1 used to confirm water is symmetrically placed near all SF chains.

• Symbols:

  • Define which symbols represent ions, water, and empty positions (e.g., ● w □).

• Binding Site Names:

  • Custom labels for binding sites from intracellular to extracellular (e.g., S4 S3 S2 S1 S0).

---

Output

Plots

• Ion Occupancy & Dwell Time

  • File: ion_occupancy_dwell_sf.png
  • Bar plot: Ion occupancy (%) across sites.
  • Boxplot: Ion dwell time distributions at each site.

• Water Occupancy & Dwell Time

  • File: water_occupancy_dwell_sf.png
  • Bar plot: Water occupancy (%) across sites.
  • Boxplot: Water dwell time distributions at each site.

• Configuration Frequency

  • File: sf_configurations.png
  • Top 5 most frequent configurations and their relative frame percentages.

Console Output

• Occupancy Summary:

  • Ion and water occupancy per site.

• Dwell Time Summary:

  • Number of dwell events and mean dwell time for each site.

• Configuration Strings:

  • Most frequent symbolic configurations and their percentages.

---

Interpreting the Results

Ion and Water Occupancy

• High Occupancy:

  • Indicates persistent ion or water binding at that site.

• Low Occupancy:

  • Suggests that the site is transient or unoccupied in current conditions.

Dwell Times

• Long Dwell:

  • Indicates strong interactions or trapping.

• Short Dwell:

  • Suggests transient binding or rapid conduction.

Configuration Symbols

Given user-defined symbols (e.g., ● w □):

• '●●w□□' means:

  • Site 1 (more intracellular): ion
  • Site 2: ion
  • Site 3: water
  • Site 4–5 (more extracellular): empty

• Frequencies indicate how often each configuration appears over the trajectory.

---

Example Scenarios

Kv Channel Selectivity

• Observation: Configuration '●w●w●' is most frequent.
• Interpretation: Alternating ion–water pattern confirms knock-on mechanism.

NaV/CaV Filter Hydration

• Observation: Water occupies multiple sites with high symmetry.
• Interpretation: Channel is water-permeable or partially hydrated.

Filter Collapse

• Observation: All sites are empty or water-filled.
• Interpretation: SF may be in a non-conductive or collapsed state.

---

Usage Tips

• Residue Mapping:

  • Ensure SF selection includes correct atoms (usually oxygens).

• Distance Tuning:

  • Adjust threshold_distance if ions are slightly misaligned.

• Water Filtering:

  • Use water_symmetry_threshold to avoid counting waters outside the SF path.

• Symbol Customization:

  • You can use unicode (e.g., ●, ○, □) or ASCII (e.g., X, W, -) for compatibility.

• Inter-site Patterns:

  • Use configuration frequencies to detect knock-on or concerted motion.

---