wasimap 0.1.1

A Python tool for identifying and mapping persistent water-sites from molecular dynamics (MD) simulations of biomolecular complexes

WaSiMap

WaSiMap is a Python tool for identifying and mapping persistent water-sites from molecular dynamics (MD) simulations of biomolecular complexes.

The software detects regions where solvent molecules repeatedly occupy similar spatial positions across simulation frames and clusters them into water-sites, enabling comparative analysis across multiple simulations.

---

Overview

Water molecules frequently mediate hydrogen bonding and stabilize interaction patterns that extend beyond direct residue–residue contacts in biomolecular recognition. Identifying solvent-mediated interactions is particularly important in protein–protein and protein–DNA interfaces, where conserved water-sites may contribute to binding specificity and stability.

WaSiMap analyzes explicitly solvated MD simulations to:

• Detect water molecules with increased interfacial persistence
• Determine the heavy atoms contacted by these waters
• Cluster water positions into spatial water-site centroids
• Enable visual comparison of water-sites across many closely related MD simulations

The tool is designed to facilitate post-processing of MD-based HTP mutational series, allowing researchers to investigate how solvent-mediated interactions evolve across closely related molecular systems.

---

Features

• Detection of persistent water molecules at biomolecular interfaces
• Identification of contacted heavy atoms for each water molecule
• Clustering of water coordinates into water-site centroids
• Aggregation of results from multiple MD simulations
• Generation of an interactive HTML visualization interface
• Compatible with multiple MD trajectory formats (based on MDTraj)

---

Installation

The installation of WaSiMap is straightforward.

Install directly from PIP:

pip install wasimap

Or install from source:

git clone https://github.com/pisabarro-group/WaSiMap
cd wasimap
pip install .

Example usage (with test data)

The following commands download three (3) MD simulations into the current folder (~320 Mb) and perform a WaSiMap analysis on all simulations.

wasimap --testdata
wasimap --gui

Upon completion of the wasimap routines, the WaSiMap viewer should open automatically in your default browser.

To exit the program, use CTRL-C.

Basic Usage

WaSiMap scans for MD trajectory files and topologies in the folder where it is executed. Trajectories and their corresponding topologies must have the same filename (i.e: an AMBER trajectory called SIM1 must exist as SIM1.mdcrd and SIM1.prmtop). H5 trajectories include their topology as metadata and come as a single file. WaSiMap tries to match trajectories and topologies autonatically.

Standard wasimap usage syntax:

wasimap --flag --flag ... [input]

For a fully automated execution, use:

wasimap --gui

To process a single trajectory, use:

wasimap --gui <<trajectory_filename>> (name only, no extension)

The command "wasimap" can be executed with several flags, described as follows:

-c --cuttoff H-bonding distance cutoff (default: 0.35 nm) -r --persistence Minimum percentage of frames to consider water as resident (default: 5) --gui Start the WaSiMap explorer after execution --onlygui Do not process anything. Show GUI for existing results. --testdata Download test MD simulations to the current folder -h --help Displays help -v --version Displays current version

Navigating Results

WaSiMap automatically creates a folder called ./wasimap_outputs and stores:

• A PDB file of each MD trajectory (first frame)
• A collection of water-site data, centroid coordinates and water ids in file wasimap.json
• A copy of the HTML viewer wasimap.html

A small web server is initiated and binds to all interfaces (port 8080) upon completion, and the viewer is launched on the default browser. This web application embeds a 3D viewer (based on NGLViewer) that superposes all structures. Water-sites are shown as spheres. The size of each sphere is proportional to the residence time of all waters in the water-site.

• Each structure is assigned a color for ease of identification
• Interfacial residues involved in water-sites are displayed as "ball+sticks"
• Molecular backbones are displayed as ribbons
• An intuitive menu (left panel) allows toggling structures and water-sites on/off
• The stage can be conveniently navigated with the mouse (see NGL documentation)
• Clicking on a water-site sphere shows the water-site table for the given structure.
• The table displays one water-site per row, and also its resident waters.
• Each water shows its internal AtomID
• Hovering the mouse over waters highlights its occurence around other residues.

Citation

If you use this software in academic work, please cite us. (DOI PENDING)

Contributing

Contributions, bug reports, and feature requests are welcome. Please open an issue or submit a pull request.